srp/src/client.rs

   1 //! SRP client implementation.
   2 //!
   3 //! # Usage
   4 //! First create SRP client struct by passing to it SRP parameters (shared
   5 //! between client and server) and randomly generated `a`:
   6 //!
   7 //! ```ignore
   8 //! use srp::groups::G_2048;
   9 //! use sha2::Sha256;
  10 //!
  11 //! let mut a = [0u8; 64];
  12 //! rng.fill_bytes(&mut a);
  13 //! let client = SrpClient::<Sha256>::new(&a, &G_2048);
  14 //! ```
  15 //!
  16 //! Next send handshake data (username and `a_pub`) to the server and receive
  17 //! `salt` and `b_pub`:
  18 //!
  19 //! ```ignore
  20 //! let a_pub = client.get_a_pub();
  21 //! let (salt, b_pub) = conn.send_handshake(username, a_pub);
  22 //! ```
  23 //!
  24 //! Compute private key using `salt` with any password hashing function.
  25 //! You can use method from SRP-6a, but it's recommended to use specialized
  26 //! password hashing algorithm instead (e.g. PBKDF2, argon2 or scrypt).
  27 //! Next create verifier instance, note that `get_verifier` consumes client and
  28 //! can return error in case of malicious `b_pub`.
  29 //!
  30 //! ```ignore
  31 //! let private_key = srp_private_key::<Sha256>(username, password, salt);
  32 //! let verifier = client.get_verifier(&private_key, &b_pub)?;
  33 //! ```
  34 //!
  35 //! Finally verify the server: first generate user proof,
  36 //! send it to the server and verify server proof in the reply. Note that
  37 //! `verify_server` method will return error in case of incorrect server reply.
  38 //!
  39 //! ```ignore
  40 //! let user_proof = verifier.get_proof();
  41 //! let server_proof = conn.send_proof(user_proof);
  42 //! let key = verifier.verify_server(server_proof)?;
  43 //! ```
  44 //!
  45 //! `key` contains shared secret key between user and the server. Alternatively
  46 //! you can directly extract shared secret key using `get_key()` method and
  47 //! handle authentification through different (secure!) means (e.g. by using
  48 //! authentificated cipher mode).
  49 //!
  50 //! For user registration on the server first generate salt (e.g. 32 bytes long)
  51 //! and get password verifier which depends on private key. Send useranme, salt
  52 //! and password verifier over protected channel to protect against
  53 //! Man-in-the-middle (MITM) attack for registration.
  54 //!
  55 //! ```ignore
  56 //! let pwd_verifier = client.get_password_verifier(&private_key);
  57 //! conn.send_registration_data(username, salt, pwd_verifier);
  58 //! ```
  59 use std::marker::PhantomData;
  60
  61 use digest::Digest;
  62 use generic_array::GenericArray;
  63 use num::{BigUint, Zero};
  64
  65 use tools::powm;
  66 use types::{SrpAuthError, SrpGroup};
  67
  68 /// SRP client state before handshake with the server.
  69 pub struct SrpClient<'a, D: Digest> {
  70     params: &'a SrpGroup,
  71
  72     a: BigUint,
  73     a_pub: BigUint,
  74
  75     d: PhantomData<D>,
  76 }
  77
  78 /// SRP client state after handshake with the server.
  79 pub struct SrpClientVerifier<D: Digest> {
  80     proof: GenericArray<u8, D::OutputSize>,
  81     server_proof: GenericArray<u8, D::OutputSize>,
  82     key: GenericArray<u8, D::OutputSize>,
  83 }
  84
  85 /// Compute user private key as described in the RFC 5054. Consider using proper
  86 /// password hashing algorithm instead.
  87 pub fn srp_private_key<D: Digest>(
  88     username: &[u8],
  89     password: &[u8],
  90     salt: &[u8],
  91 ) -> GenericArray<u8, D::OutputSize> {
  92     let p = {
  93         let mut d = D::new();
  94         d.input(username);
  95         d.input(b":");
  96         d.input(password);
  97         d.result()
  98     };
  99     let mut d = D::new();
 100     d.input(salt);
 101     d.input(&p);
 102     d.result()
 103 }
 104
 105 impl<'a, D: Digest> SrpClient<'a, D> {
 106     /// Create new SRP client instance.
 107     pub fn new(a: &[u8], params: &'a SrpGroup) -> Self {
 108         let a = BigUint::from_bytes_be(a);
 109         let a_pub = params.powm(&a);
 110
 111         Self {
 112             params,
 113             a,
 114             a_pub,
 115             d: Default::default(),
 116         }
 117     }
 118
 119     /// Get password verfier for user registration on the server
 120     pub fn get_password_verifier(&self, private_key: &[u8]) -> Vec<u8> {
 121         let x = BigUint::from_bytes_be(private_key);
 122         let v = self.params.powm(&x);
 123         v.to_bytes_be()
 124     }
 125
 126     fn calc_key(
 127         &self,
 128         b_pub: &BigUint,
 129         x: &BigUint,
 130         u: &BigUint,
 131     ) -> GenericArray<u8, D::OutputSize> {
 132         let n = &self.params.n;
 133         let k = self.params.compute_k::<D>();
 134         let interm = (k * self.params.powm(x)) % n;
 135         // Because we do operation in modulo N we can get: (kv + g^b) < kv
 136         let v = if *b_pub > interm {
 137             (b_pub - &interm) % n
 138         } else {
 139             (n + b_pub - &interm) % n
 140         };
 141         // S = |B - kg^x| ^ (a + ux)
 142         let s = powm(&v, &(&self.a + (u * x) % n), n);
 143         D::digest(&s.to_bytes_be())
 144     }
 145
 146     /// Process server reply to the handshake.
 147     pub fn process_reply(
 148         self,
 149         private_key: &[u8],
 150         b_pub: &[u8],
 151     ) -> Result<SrpClientVerifier<D>, SrpAuthError> {
 152         let u = {
 153             let mut d = D::new();
 154             d.input(&self.a_pub.to_bytes_be());
 155             d.input(b_pub);
 156             BigUint::from_bytes_be(&d.result())
 157         };
 158
 159         let b_pub = BigUint::from_bytes_be(b_pub);
 160
 161         // Safeguard against malicious B
 162         if &b_pub % &self.params.n == BigUint::zero() {
 163             return Err(SrpAuthError {
 164                 description: "Malicious b_pub value",
 165             });
 166         }
 167
 168         let x = BigUint::from_bytes_be(private_key);
 169         let key = self.calc_key(&b_pub, &x, &u);
 170         // M1 = H(A, B, K)
 171         let proof = {
 172             let mut d = D::new();
 173             d.input(&self.a_pub.to_bytes_be());
 174             d.input(&b_pub.to_bytes_be());
 175             d.input(&key);
 176             d.result()
 177         };
 178
 179         // M2 = H(A, M1, K)
 180         let server_proof = {
 181             let mut d = D::new();
 182             d.input(&self.a_pub.to_bytes_be());
 183             d.input(&proof);
 184             d.input(&key);
 185             d.result()
 186         };
 187
 188         Ok(SrpClientVerifier {
 189             proof,
 190             server_proof,
 191             key,
 192         })
 193     }
 194
 195     /// Get public ephemeral value for handshaking with the server.
 196     pub fn get_a_pub(&self) -> Vec<u8> {
 197         self.a_pub.to_bytes_be()
 198     }
 199 }
 200
 201 impl<D: Digest> SrpClientVerifier<D> {
 202     /// Get shared secret key without authenticating server, e.g. for using with
 203     /// authenticated encryption modes. DO NOT USE this method without
 204     /// some kind of secure authentification.
 205     pub fn get_key(self) -> GenericArray<u8, D::OutputSize> {
 206         self.key
 207     }
 208
 209     /// Verification data for sending to the server.
 210     pub fn get_proof(&self) -> GenericArray<u8, D::OutputSize> {
 211         self.proof.clone()
 212     }
 213
 214     /// Verify server reply to verification data. It will return shared secret
 215     /// key in case of success.
 216     pub fn verify_server(
 217         self,
 218         reply: &[u8],
 219     ) -> Result<GenericArray<u8, D::OutputSize>, SrpAuthError> {
 220         if self.server_proof.as_slice() != reply {
 221             Err(SrpAuthError {
 222                 description: "Incorrect server proof",
 223             })
 224         } else {
 225             Ok(self.key)
 226         }
 227     }
 228 }