srp: rename and deprecate legacy implementation (#237)

Attempts to steer people towards the new RFC5054-compatible
implementation by adding `*_legacy` and `Legacy*` to methods and types
for the `srp` v0.6-and-earlier compatible implementation.

Ideally it can be removed in the next breaking release after this one,
and we can only support RFC5054. But for now, this makes a migration
possible.

Author: tarcieri

srp/src/client.rs

@@ -40,7 +40,7 @@
 //! # let b_pub = b"b_pub";
 //!
 //! let private_key = (username, password, salt);
-//! let verifier = client.process_reply(&a, username, password, salt, b_pub);
+//! let verifier = client.process_reply_legacy(&a, username, password, salt, b_pub);
 //! ```
 //!
 //! Finally verify the server: first generate user proof,
@@ -61,7 +61,7 @@
 //! key using `key()` method.
 //! ```rust
 //! # let client = srp::Client::<srp::G2048, sha2::Sha256>::new();
-//! # let verifier = client.process_reply(b"", b"", b"", b"", b"1").unwrap();
+//! # let verifier = client.process_reply_legacy(b"", b"", b"", b"", b"1").unwrap();
 //!
 //! verifier.key();
 //! ```
@@ -200,18 +200,20 @@ impl<G: Group, D: Digest> Client<G, D> {
             .into()
     }
 
-    /// Process server reply to the handshake.
+    /// Process server reply to the handshake according to RFC 5054.
+    ///
+    /// # Params
     /// `a` is a random value,
     /// `username`, `password` is supplied by the user
     /// `salt` and `b_pub` come from the server
-    pub fn process_reply(
+    pub fn process_reply_rfc5054(
         &self,
         a: &[u8],
         username: &[u8],
         password: &[u8],
         salt: &[u8],
         b_pub: &[u8],
-    ) -> Result<ClientVerifier<D>, AuthError> {
+    ) -> Result<ClientVerifierRfc5054<D>, AuthError> {
         let a = BoxedUint::from_be_slice_vartime(a);
         let a_pub = self.compute_g_x(&a);
         let b_pub = BoxedUint::from_be_slice_vartime(b_pub);
@@ -227,39 +229,57 @@ impl<G: Group, D: Digest> Client<G, D> {
         let identity_hash = Self::compute_identity_hash(self.identity_username(username), password);
         let x = Self::compute_x(identity_hash.as_slice(), salt);
 
-        let key = self.compute_premaster_secret(&b_pub, &k, &x, &a, &u);
+        let premaster_secret = self
+            .compute_premaster_secret(&b_pub, &k, &x, &a, &u)
+            .to_be_bytes_trimmed_vartime();
 
-        let m1 = compute_m1::<D>(
+        let session_key = compute_hash::<D>(&premaster_secret);
+
+        let m1 = compute_m1_rfc5054::<D>(
+            &self.g,
+            username,
+            salt,
             &a_pub.to_be_bytes_trimmed_vartime(),
             &b_pub.to_be_bytes_trimmed_vartime(),
-            &key.to_be_bytes_trimmed_vartime(),
+            session_key.as_slice(),
         );
 
         let m2 = compute_m2::<D>(
             &a_pub.to_be_bytes_trimmed_vartime(),
             &m1,
-            &key.to_be_bytes_trimmed_vartime(),
+            session_key.as_slice(),
         );
 
-        Ok(ClientVerifier {
+        Ok(ClientVerifierRfc5054 {
             m1,
             m2,
-            key: key.to_be_bytes_trimmed_vartime().to_vec(),
+            key: premaster_secret.to_vec(),
+            session_key: session_key.to_vec(),
         })
     }
 
-    /// Process server reply to the handshake according to RFC 5054.
-    /// `a` is a random value,
-    /// `username`, `password` is supplied by the user
-    /// `salt` and `b_pub` come from the server
-    pub fn process_reply_rfc5054(
+    /// Process server reply to the handshake using the legacy implementation.
+    ///
+    /// This implementation is compatible with `srp` v0.6 and earlier. Note the default
+    /// implementation is now RFC5054 compatible.
+    ///
+    /// # Params
+    /// - `a` is a random value,
+    /// - `username`, `password` is supplied by the user
+    /// - `salt` and `b_pub` come from the server
+    #[deprecated(
+        since = "0.7.0",
+        note = "please switch to `Client::process_reply_rfc5054`"
+    )]
+    #[allow(deprecated)]
+    pub fn process_reply_legacy(
         &self,
         a: &[u8],
         username: &[u8],
         password: &[u8],
         salt: &[u8],
         b_pub: &[u8],
-    ) -> Result<ClientVerifierRfc5054<D>, AuthError> {
+    ) -> Result<LegacyClientVerifier<D>, AuthError> {
         let a = BoxedUint::from_be_slice_vartime(a);
         let a_pub = self.compute_g_x(&a);
         let b_pub = BoxedUint::from_be_slice_vartime(b_pub);
@@ -275,32 +295,24 @@ impl<G: Group, D: Digest> Client<G, D> {
         let identity_hash = Self::compute_identity_hash(self.identity_username(username), password);
         let x = Self::compute_x(identity_hash.as_slice(), salt);
 
-        let premaster_secret = self
-            .compute_premaster_secret(&b_pub, &k, &x, &a, &u)
-            .to_be_bytes_trimmed_vartime();
-
-        let session_key = compute_hash::<D>(&premaster_secret);
+        let key = self.compute_premaster_secret(&b_pub, &k, &x, &a, &u);
 
-        let m1 = compute_m1_rfc5054::<D>(
-            &self.g,
-            username,
-            salt,
+        let m1 = compute_m1::<D>(
             &a_pub.to_be_bytes_trimmed_vartime(),
             &b_pub.to_be_bytes_trimmed_vartime(),
-            session_key.as_slice(),
+            &key.to_be_bytes_trimmed_vartime(),
         );
 
         let m2 = compute_m2::<D>(
             &a_pub.to_be_bytes_trimmed_vartime(),
             &m1,
-            session_key.as_slice(),
+            &key.to_be_bytes_trimmed_vartime(),
         );
 
-        Ok(ClientVerifierRfc5054 {
+        Ok(LegacyClientVerifier {
             m1,
             m2,
-            key: premaster_secret.to_vec(),
-            session_key: session_key.to_vec(),
+            key: key.to_be_bytes_trimmed_vartime().to_vec(),
         })
     }
 
@@ -338,14 +350,15 @@ impl<G: Group, D: Digest> Default for Client<G, D> {
     }
 }
 
-/// SRP client state after handshake with the server.
-pub struct ClientVerifier<D: Digest> {
+/// RFC 5054 SRP client state after handshake with the server.
+pub struct ClientVerifierRfc5054<D: Digest> {
     m1: Output<D>,
     m2: Output<D>,
     key: Vec<u8>,
+    session_key: Vec<u8>,
 }
 
-impl<D: Digest> ClientVerifier<D> {
+impl<D: Digest> ClientVerifierRfc5054<D> {
     /// Get shared secret key without authenticating server, e.g. for using with
     /// authenticated encryption modes. DO NOT USE this method without
     /// some kind of secure authentication
@@ -358,25 +371,26 @@ impl<D: Digest> ClientVerifier<D> {
         self.m1.as_slice()
     }
 
-    /// Verify server reply to verification data.
-    pub fn verify_server(&self, reply: &[u8]) -> Result<(), AuthError> {
+    /// Verify server reply to verification data and return shared session key.
+    pub fn verify_server(&self, reply: &[u8]) -> Result<&[u8], AuthError> {
         if self.m2.ct_eq(reply).unwrap_u8() == 1 {
-            Ok(())
+            Ok(self.session_key.as_slice())
         } else {
             Err(AuthError::BadRecordMac { peer: "server" })
         }
     }
 }
 
-/// RFC 5054 SRP client state after handshake with the server.
-pub struct ClientVerifierRfc5054<D: Digest> {
+/// Legacy SRP client state after handshake with the server, compatible with `srp` v0.6 and earlier.
+#[deprecated(since = "0.7.0", note = "please switch to `ClientVerifierRfc5054`")]
+pub struct LegacyClientVerifier<D: Digest> {
     m1: Output<D>,
     m2: Output<D>,
     key: Vec<u8>,
-    session_key: Vec<u8>,
 }
 
-impl<D: Digest> ClientVerifierRfc5054<D> {
+#[allow(deprecated)]
+impl<D: Digest> LegacyClientVerifier<D> {
     /// Get shared secret key without authenticating server, e.g. for using with
     /// authenticated encryption modes. DO NOT USE this method without
     /// some kind of secure authentication
@@ -389,10 +403,10 @@ impl<D: Digest> ClientVerifierRfc5054<D> {
         self.m1.as_slice()
     }
 
-    /// Verify server reply to verification data and return shared session key.
-    pub fn verify_server(&self, reply: &[u8]) -> Result<&[u8], AuthError> {
+    /// Verify server reply to verification data.
+    pub fn verify_server(&self, reply: &[u8]) -> Result<(), AuthError> {
         if self.m2.ct_eq(reply).unwrap_u8() == 1 {
-            Ok(self.session_key.as_slice())
+            Ok(())
         } else {
             Err(AuthError::BadRecordMac { peer: "server" })
         }