srp: improve rustdoc (#242)

Adds the `missing_docs` lint

Author: tarcieri

srp/src/client.rs

@@ -122,6 +122,9 @@ impl<G: Group, D: Digest> Client<G, D> {
         Self::new_with_options(true)
     }
 
+    /// Create a new SRP client instance, with the ability to override username inclusion in `x`.
+    ///
+    /// Set `username_in_x` to false for e.g. compatibility with Apple implementations of SRP.
     #[must_use]
     pub fn new_with_options(username_in_x: bool) -> Self {
         Self {
@@ -131,13 +134,23 @@ impl<G: Group, D: Digest> Client<G, D> {
         }
     }
 
-    // v = g^x % N
+    /// Compute `g^x % N`, which can be used when computing e.g. `v`.
     #[must_use]
     pub fn compute_g_x(&self, x: &BoxedUint) -> BoxedUint {
         self.g.pow(x).retrieve()
     }
 
-    //  H(<username> | ":" | <raw password>)
+    /// Get public ephemeral value for handshaking with the server: `g^a % N`.
+    ///
+    /// This returns a big endian byte serialization stripped of leading zeros.
+    #[must_use]
+    pub fn compute_public_ephemeral(&self, a: &[u8]) -> Vec<u8> {
+        self.compute_g_x(&BoxedUint::from_be_slice_vartime(a))
+            .to_be_bytes_trimmed_vartime()
+            .into()
+    }
+
+    /// Compute the identity hash: `H(<username> | ":" | <raw password>)`.
     #[must_use]
     pub fn compute_identity_hash(username: &[u8], password: &[u8]) -> Output<D> {
         let mut d = D::new();
@@ -147,7 +160,7 @@ impl<G: Group, D: Digest> Client<G, D> {
         d.finalize()
     }
 
-    // x = H(<salt> | H(<username> | ":" | <raw password>))
+    /// Compute `x = H(<salt> | H(<username> | ":" | <raw password>))`.
     #[must_use]
     pub fn compute_x(identity_hash: &[u8], salt: &[u8]) -> BoxedUint {
         let mut x = D::new();
@@ -156,7 +169,7 @@ impl<G: Group, D: Digest> Client<G, D> {
         BoxedUint::from_be_slice_vartime(&x.finalize())
     }
 
-    // (B - (k * g^x)) ^ (a + (u * x)) % N
+    /// Compute the premaster secret: `(B - (k * g^x)) ^ (a + (u * x)) % N`.
     #[must_use]
     pub fn compute_premaster_secret(
         &self,
@@ -179,29 +192,22 @@ impl<G: Group, D: Digest> Client<G, D> {
         base.pow(&exp).retrieve()
     }
 
-    /// Get password verifier (v in RFC5054) for user registration on the server.
+    /// Get password verifier (`v` in RFC5054) for user registration on the server.
     #[must_use]
     pub fn compute_verifier(&self, username: &[u8], password: &[u8], salt: &[u8]) -> Vec<u8> {
         let identity_hash = Self::compute_identity_hash(self.identity_username(username), password);
         let x = Self::compute_x(identity_hash.as_slice(), salt);
         self.compute_g_x(&x).to_be_bytes_trimmed_vartime().into()
     }
 
-    /// Get public ephemeral value for handshaking with the server.
-    /// g^a % N
-    #[must_use]
-    pub fn compute_public_ephemeral(&self, a: &[u8]) -> Vec<u8> {
-        self.compute_g_x(&BoxedUint::from_be_slice_vartime(a))
-            .to_be_bytes_trimmed_vartime()
-            .into()
-    }
-
-    /// Process server reply to the handshake according to RFC 5054.
+    /// Process server reply to the handshake according to [RFC5054].
     ///
     /// # Params
     /// - `a` is a random value,
     /// - `username`, `password` is supplied by the user
     /// - `salt` and `b_pub` come from the server
+    ///
+    /// [RFC5054]: https://datatracker.ietf.org/doc/html/rfc5054
     pub fn process_reply(
         &self,
         a: &[u8],
@@ -325,7 +331,9 @@ impl<G: Group, D: Digest> Default for Client<G, D> {
     }
 }
 
-/// RFC 5054 SRP client state after handshake with the server.
+/// [RFC5054]-compatible SRP client state after handshake with the server.
+///
+/// [RFC5054]: https://datatracker.ietf.org/doc/html/rfc5054
 pub struct ClientVerifier<D: Digest> {
     m1: Output<D>,
     m2: Output<D>,

srp/src/errors.rs

@@ -5,10 +5,12 @@ use core::{error, fmt};
 /// SRP authentication error.
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub enum AuthError {
+    /// Parameter with the given `name` is illegal.
     IllegalParameter {
         /// Parameter name
         name: &'static str,
     },
+    /// Invalid MAC when computing proof for the given peer.
     BadRecordMac {
         /// Which peer's proof is invalid
         peer: &'static str,

srp/src/lib.rs

@@ -5,6 +5,8 @@
     html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg"
 )]
 #![allow(clippy::many_single_char_names)]
+#![forbid(unsafe_code)]
+#![warn(missing_docs, rust_2018_idioms, unused_qualifications)]
 
 //! # Usage
 //! See [`Client`] and [`Server`] types for usage information.

srp/src/server.rs

@@ -102,15 +102,15 @@ impl<G: Group, D: Digest> Server<G, D> {
         }
     }
 
-    //  k*v + g^b % N
+    /// Compute the server's public ephemeral: `k*v + g^b % N`.
     #[must_use]
     pub fn compute_b_pub(&self, b: &BoxedUint, k: &BoxedUint, v: &BoxedUint) -> BoxedUint {
         let k = self.monty_form(k);
         let v = self.monty_form(v);
         (k * v + self.g.pow(b)).retrieve()
     }
 
-    // <premaster secret> = (A * v^u) ^ b % N
+    /// Compute the premaster secret: `(A * v^u) ^ b % N`.
     #[must_use]
     pub fn compute_premaster_secret(
         &self,
@@ -138,11 +138,13 @@ impl<G: Group, D: Digest> Server<G, D> {
         .into()
     }
 
-    /// Process client reply to the handshake according to RFC 5054.
+    /// Process client reply to the handshake according to [RFC5054].
     ///
     /// # Params
     /// - `b` is a random value,
     /// - `v` is the provided during initial user registration
+    ///
+    /// [RFC5054]: https://datatracker.ietf.org/doc/html/rfc5054
     pub fn process_reply(
         &self,
         username: &[u8],
@@ -265,7 +267,9 @@ impl<G: Group, D: Digest> Default for Server<G, D> {
     }
 }
 
-/// RFC 5054 SRP server state after handshake with the client.
+/// [RFC5054] SRP server state after handshake with the client.
+///
+/// [RFC5054]: https://datatracker.ietf.org/doc/html/rfc5054
 pub struct ServerVerifier<D: Digest> {
     m1: Output<D>,
     m2: Output<D>,