Add clippy::doc_markdown (#346)

src/ciphersuite.rs

@@ -6,7 +6,7 @@
 // of this source tree. You may select, at your option, one of the above-listed
 // licenses.
 
-//! Defines the CipherSuite trait to specify the underlying primitives for
+//! Defines the [`CipherSuite`] trait to specify the underlying primitives for
 //! OPAQUE
 
 use digest::core_api::{BlockSizeUser, CoreProxy};

src/hash.rs

@@ -32,9 +32,9 @@ where
 {
 }
 
-/// Trait inheriting the requirements from digest::Digest for compatibility with
-/// HKDF and HMAC Associated types could be simplified when they are made as
-/// defaults: <https://github.com/rust-lang/rust/issues/29661>
+/// Trait inheriting the requirements from [`digest::Digest`] for compatibility
+/// with HKDF and HMAC Associated types could be simplified when they are made
+/// as defaults: <https://github.com/rust-lang/rust/issues/29661>
 pub trait Hash:
     Default
     + HashMarker

src/key_exchange/group/mod.rs

@@ -6,7 +6,7 @@
 // of this source tree. You may select, at your option, one of the above-listed
 // licenses.
 
-//! Includes the KeGroup trait and definitions for the key exchange groups
+//! Includes the [`KeGroup`] trait and definitions for the key exchange groups
 
 #[cfg(feature = "curve25519")]
 pub mod curve25519;
@@ -56,12 +56,13 @@ pub trait KeGroup {
         H: BlockSizeUser + Default + FixedOutput + HashMarker,
         H::OutputSize: IsLess<U256> + IsLessOrEqual<H::BlockSize>;
 
-    /// Corresponds to the DeriveAuthKeyPair() function defined in
+    /// Corresponds to the `DeriveAuthKeyPair()` function defined in
     /// <https://www.ietf.org/archive/id/draft-irtf-cfrg-opaque-08.html#section-6.4.2>
     ///
     /// Note that we cannot call the voprf crate directly since we need to
-    /// ensure that the KeGroup is used for the hash_to_scalar operation (as
-    /// opposed to the OprfGroup).
+    /// ensure that the [`KeGroup`] is used for the
+    /// [`hash_to_scalar`](Self::hash_to_scalar) operation (as opposed to
+    /// the [`OprfGroup`](voprf::Group)).
     fn derive_auth_keypair<CS: voprf::CipherSuite>(
         seed: GenericArray<u8, Self::SkLen>,
     ) -> Result<Self::Sk, InternalError>

src/keypair.rs

@@ -47,12 +47,12 @@ impl<KG: KeGroup, S: SecretKey<KG>> KeyPair<KG, S> {
         &self.sk
     }
 
-    /// Obtains a KeyPair from a slice representing the private key
+    /// Obtains a [`KeyPair`] from a slice representing the private key
     pub fn from_private_key_slice(input: &[u8]) -> Result<Self, ProtocolError<S::Error>> {
         Self::from_private_key(S::deserialize(input)?)
     }
 
-    /// Obtains a KeyPair from a private key
+    /// Obtains a [`KeyPair`] from a private key
     pub fn from_private_key(private_key: S) -> Result<Self, ProtocolError<S::Error>> {
         let pk = private_key.public_key()?;
         Ok(Self {
@@ -90,7 +90,7 @@ where
     KG::Sk: std::fmt::Debug,
 {
     /// Test-only strategy returning a proptest Strategy based on
-    /// generate_random
+    /// [`Self::generate_random`]
     fn uniform_keypair_strategy<CS: voprf::CipherSuite>() -> proptest::prelude::BoxedStrategy<Self>
     where
         <CS::Hash as OutputSizeUser>::OutputSize:

src/lib.rs

@@ -77,35 +77,35 @@
 //! let server_setup = ServerSetup::<Default>::new(&mut rng);
 //! # Ok::<(), ProtocolError>(())
 //! ```
-//! The server must persist an instance of [ServerSetup] for the registration
-//! and login steps, and can use [ServerSetup::serialize] and
-//! [ServerSetup::deserialize] to save and restore the instance.
+//! The server must persist an instance of [`ServerSetup`] for the registration
+//! and login steps, and can use [`ServerSetup::serialize`] and
+//! [`ServerSetup::deserialize`] to save and restore the instance.
 //!
 //! ## Registration
 //! The registration protocol between the client and server consists of four
-//! steps along with three messages: [RegistrationRequest],
-//! [RegistrationResponse], and [RegistrationUpload]. A successful execution of
-//! the registration protocol results in the server producing a password file
+//! steps along with three messages: [`RegistrationRequest`],
+//! [`RegistrationResponse`], and [`RegistrationUpload`]. A successful execution
+//! of the registration protocol results in the server producing a password file
 //! corresponding to a server-side identifier for the client, along with the
 //! password provided by the client. This password file is typically stored in a
 //! key-value database, where the keys consist of these server-side identifiers
 //! for each client, and the values consist of their corresponding password
 //! files, to be retrieved upon future login attempts made by the client.
 //! It is your responsibility to ensure that the identifier used to form the
-//! initial [RegistrationRequest], typically supplied by the client, matches
-//! the database key used in the final [RegistrationUpload] step.
+//! initial [`RegistrationRequest`], typically supplied by the client, matches
+//! the database key used in the final [`RegistrationUpload`] step.
 //!
-//! Note that the [RegistrationUpload] message contains sensitive information
+//! Note that the [`RegistrationUpload`] message contains sensitive information
 //! (about as sensitive as a hash of the password), and hence should be
 //! protected with confidentiality guarantees by the consumer of this library.
 //!
 //! ### Client Registration Start
 //! In the first step of registration, the client chooses as input a
-//! registration password. The client runs [ClientRegistration::start] to
-//! produce a [ClientRegistrationStartResult], which consists of a
-//! [RegistrationRequest] to be sent to the server and a [ClientRegistration]
-//! which must be persisted on the client for the final step of client
-//! registration.
+//! registration password. The client runs [`ClientRegistration::start`] to
+//! produce a [`ClientRegistrationStartResult`], which consists of a
+//! [`RegistrationRequest`] to be sent to the server and a
+//! [`ClientRegistration`] which must be persisted on the client for the final
+//! step of client registration.
 //! ```
 //! # use opaque_ke::{
 //! #   errors::ProtocolError,
@@ -139,10 +139,11 @@
 //!
 //! ### Server Registration Start
 //! In the second step of registration, the server takes as input a persisted
-//! instance of [ServerSetup], a [RegistrationRequest] from the client, and a
-//! server-side identifier for the client. The server runs
-//! [ServerRegistration::start] to produce a [ServerRegistrationStartResult],
-//! which consists of a [RegistrationResponse] to be returned to the client.
+//! instance of [`ServerSetup`], a [`RegistrationRequest`] from the client, and
+//! a server-side identifier for the client. The server runs
+//! [`ServerRegistration::start`] to produce a
+//! [`ServerRegistrationStartResult`], which consists of a
+//! [`RegistrationResponse`] to be returned to the client.
 //! ```
 //! # use opaque_ke::{
 //! #   errors::ProtocolError,
@@ -185,10 +186,11 @@
 //!
 //! ### Client Registration Finish
 //! In the third step of registration, the client takes as input a
-//! [RegistrationResponse] from the server, and a [ClientRegistration] from the
-//! first step of registration. The client runs [ClientRegistration::finish] to
-//! produce a [ClientRegistrationFinishResult], which consists of a
-//! [RegistrationUpload] to be sent to the server and an `export_key` field
+//! [`RegistrationResponse`] from the server, and a [`ClientRegistration`] from
+//! the first step of registration. The client runs
+//! [`ClientRegistration::finish`] to
+//! produce a [`ClientRegistrationFinishResult`], which consists of a
+//! [`RegistrationUpload`] to be sent to the server and an `export_key` field
 //! which can be used optionally as described in the [Export Key](#export-key)
 //! section.
 //! ```
@@ -233,11 +235,11 @@
 //!
 //! ### Server Registration Finish
 //! In the fourth step of registration, the server takes as input a
-//! [RegistrationUpload] from the client, and a [ServerRegistration] from the
-//! second step. The server runs [ServerRegistration::finish] to produce a
-//! finalized [ServerRegistration]. At this point, the client can be considered
-//! as successfully registered, and the server can invoke
-//! [ServerRegistration::serialize] to store the password file for use during
+//! [`RegistrationUpload`] from the client, and a [`ServerRegistration`] from
+//! the second step. The server runs [`ServerRegistration::finish`] to produce a
+//! finalized [`ServerRegistration`]. At this point, the client can be
+//! considered as successfully registered, and the server can invoke
+//! [`ServerRegistration::serialize`] to store the password file for use during
 //! the login protocol.
 //! ```
 //! # use opaque_ke::{
@@ -279,8 +281,8 @@
 //!
 //! ## Login
 //! The login protocol between a client and server also consists of four steps
-//! along with three messages: [CredentialRequest], [CredentialResponse],
-//! [CredentialFinalization]. The server is expected to have access to the
+//! along with three messages: [`CredentialRequest`], [`CredentialResponse`],
+//! [`CredentialFinalization`]. The server is expected to have access to the
 //! password file corresponding to an output of the registration phase (see
 //! [Dummy Server Login](#dummy-server-login) for handling the scenario where no
 //! password file is available). The login protocol will execute successfully
@@ -289,9 +291,9 @@
 //!
 //! ### Client Login Start
 //! In the first step of login, the client chooses as input a login password.
-//! The client runs [ClientLogin::start] to produce an output consisting of a
-//! [CredentialRequest] to be sent to the server, and a [ClientLogin] which must
-//! be persisted on the client for the final step of client login.
+//! The client runs [`ClientLogin::start`] to produce an output consisting of a
+//! [`CredentialRequest`] to be sent to the server, and a [`ClientLogin`] which
+//! must be persisted on the client for the final step of client login.
 //! ```
 //! # use opaque_ke::{
 //! #   errors::ProtocolError,
@@ -323,12 +325,12 @@
 //!
 //! ### Server Login Start
 //! In the second step of login, the server takes as input a persisted instance
-//! of [ServerSetup], the password file output from registration, a
-//! [CredentialRequest] from the client, and a server-side identifier for the
-//! client. The server runs [ServerLogin::start] to produce an output consisting
-//! of a [CredentialResponse] which is returned to the client, and a
-//! [ServerLogin] which must be persisted on the server for the final step of
-//! login.
+//! of [`ServerSetup`], the password file output from registration, a
+//! [`CredentialRequest`] from the client, and a server-side identifier for the
+//! client. The server runs [`ServerLogin::start`] to produce an output
+//! consisting of a [`CredentialResponse`] which is returned to the client, and
+//! a [`ServerLogin`] which must be persisted on the server for the final step
+//! of login.
 //! ```
 //! # use opaque_ke::{
 //! #   errors::ProtocolError,
@@ -381,17 +383,18 @@
 //! ```
 //! Note that if there is no corresponding password file found for the user, the
 //! server can use `None` in place of `Some(password_file)` in order to generate
-//! a [CredentialResponse] that is indistinguishable from a valid
-//! [CredentialResponse] returned for a registered client. This allows the
+//! a [`CredentialResponse`] that is indistinguishable from a valid
+//! [`CredentialResponse`] returned for a registered client. This allows the
 //! server to prevent leaking information about whether or not a client has
 //! previously registered with the server.
 //!
 //! ### Client Login Finish
-//! In the third step of login, the client takes as input a [CredentialResponse]
-//! from the server. The client runs [ClientLogin::finish] and produces an
-//! output consisting of a [CredentialFinalization] to be sent to the server to
-//! complete the protocol, the `session_key` sequence of bytes which will match
-//! the server's session key upon a successful login.
+//! In the third step of login, the client takes as input a
+//! [`CredentialResponse`] from the server. The client runs
+//! [`ClientLogin::finish`] and produces an output consisting of a
+//! [`CredentialFinalization`] to be sent to the server to complete the
+//! protocol, the `session_key` sequence of bytes which will match the server's
+//! session key upon a successful login.
 //! ```
 //! # use opaque_ke::{
 //! #   errors::ProtocolError,
@@ -445,8 +448,8 @@
 //!
 //! ### Server Login Finish
 //! In the fourth step of login, the server takes as input a
-//! [CredentialFinalization] from the client and runs [ServerLogin::finish] to
-//! produce an output consisting of the `session_key` sequence of bytes which
+//! [`CredentialFinalization`] from the client and runs [`ServerLogin::finish`]
+//! to produce an output consisting of the `session_key` sequence of bytes which
 //! will match the client's session key upon a successful login.
 //! ```
 //! # use opaque_ke::{
@@ -510,8 +513,8 @@
 //! `server_login_finish_result.session_key` which is guaranteed to match
 //! `client_login_finish_result.session_key` (see the [Session
 //! Key](#session-key) section). Otherwise, on failure, the
-//! [ServerLogin::finish] algorithm outputs the error
-//! [InvalidLoginError](errors::ProtocolError::InvalidLoginError).
+//! [`ServerLogin::finish`] algorithm outputs the error
+//! [`InvalidLoginError`](errors::ProtocolError::InvalidLoginError).
 //!
 //! # Advanced Usage
 //!
@@ -525,26 +528,26 @@
 //! Upon a successful completion of the OPAQUE protocol (the client runs login
 //! with the same password used during registration), the client and server have
 //! access to a session key, which is a pseudorandomly distributed byte
-//! string (of length equal to the output size of [voprf::CipherSuite::Hash])
+//! string (of length equal to the output size of [`voprf::CipherSuite::Hash`])
 //! which only the client and server know. Multiple login runs using the
 //! same password for the same client will produce different session keys,
 //! distributed as uniformly random strings. Thus, the session key can be used
 //! to establish a secure channel between the client and server.
 //!
 //! The session key can be accessed from the `session_key` field of
-//! [ClientLoginFinishResult] and [ServerLoginFinishResult]. See the combination
-//! of [Client Login Finish](#client-login-finish) and [Server Login
+//! [`ClientLoginFinishResult`] and [`ServerLoginFinishResult`]. See the
+//! combination of [Client Login Finish](#client-login-finish) and [Server Login
 //! Finish](#server-login-finish) for example usage.
 //!
 //! ## Checking Server Consistency
 //!
-//! A [ClientLoginFinishResult] contains the `server_s_pk` field, which is
+//! A [`ClientLoginFinishResult`] contains the `server_s_pk` field, which is
 //! represents the static public key of the server that is established during
 //! the setup phase. This can be used by the client to verify the authenticity
 //! of the server it engages with during the login phase. In particular, the
 //! client can check that the static public key of the server supplied during
 //! registration (with the `server_s_pk` field of
-//! [ClientRegistrationFinishResult]) matches this field during login.
+//! [`ClientRegistrationFinishResult`]) matches this field during login.
 //! ```
 //! # use opaque_ke::{
 //! #   errors::ProtocolError,
@@ -623,11 +626,11 @@
 //! ## Export Key
 //!
 //! The export key is a pseudorandomly distributed byte string
-//! (of length equal to the output size of [voprf::CipherSuite::Hash]) output by
-//! both the [Client Registration Finish](#client-registration-finish) and
+//! (of length equal to the output size of [`voprf::CipherSuite::Hash`]) output
+//! by both the [Client Registration Finish](#client-registration-finish) and
 //! [Client Login Finish](#client-login-finish) steps. The same export key
 //! string will be output by both functions only if the exact same password is
-//! passed to [ClientRegistration::start] and [ClientLogin::start].
+//! passed to [`ClientRegistration::start`] and [`ClientLogin::start`].
 //!
 //! The export key retains as much secrecy as the password itself, and is
 //! similarly derived through an evaluation of the key stretching function.
@@ -642,7 +645,7 @@
 //! for a working example).
 //!
 //! You can access the export key from the `export_key` field of
-//! [ClientRegistrationFinishResult] and [ClientLoginFinishResult].
+//! [`ClientRegistrationFinishResult`] and [`ClientLoginFinishResult`].
 //! ```
 //! # use opaque_ke::{
 //! #   errors::ProtocolError,
@@ -722,7 +725,7 @@
 //! But, for applications that wish to cryptographically bind these identities
 //! to the registered password file as well as the session key output by the
 //! login phase, these custom identifiers can be specified through
-//! [ClientRegistrationFinishParameters] in [Client Registration
+//! [`ClientRegistrationFinishParameters`] in [Client Registration
 //! Finish](#client-registration-finish):
 //! ```
 //! # use opaque_ke::{
@@ -771,7 +774,7 @@
 //! ```
 //!
 //! The same identifiers must also be supplied using
-//! [ServerLoginStartParameters] in [Server Login Start](#server-login-start):
+//! [`ServerLoginStartParameters`] in [Server Login Start](#server-login-start):
 //! ```
 //! # use opaque_ke::{
 //! #   errors::ProtocolError,
@@ -829,7 +832,7 @@
 //! # Ok::<(), ProtocolError>(())
 //! ```
 //!
-//! as well as [ClientLoginFinishParameters] in [Client Login
+//! as well as [`ClientLoginFinishParameters`] in [Client Login
 //! Finish](#client-login-finish):
 //! ```
 //! # use opaque_ke::{
@@ -903,9 +906,9 @@
 //! configuration parameters to the security of the key exchange. During the
 //! login phase, the client and server can specify this context using:
 //! - The second login message, where the server can populate
-//!   [ServerLoginStartParameters], and
+//!   [`ServerLoginStartParameters`], and
 //! - The third login message, where the client can populate
-//!   [ClientLoginFinishParameters].
+//!   [`ClientLoginFinishParameters`].
 //!
 //! For both of these messages, the `WithContextAndIdentifiers` variant can be
 //! used to specify these fields in addition to [custom
@@ -920,8 +923,8 @@
 //! a "dummy" credential response message to the client for an unregistered
 //! client, which is indistinguishable from the normal credential response
 //! message that the server would return for a registered client. The dummy
-//! message is created by passing a `None` to the password_file parameter for
-//! [ServerLogin::start].
+//! message is created by passing a `None` to the `password_file` parameter for
+//! [`ServerLogin::start`].
 //!
 //! ## Remote Private Keys
 //!
@@ -1093,7 +1096,7 @@
 //!   and implements the `Ksf` trait for `Argon2` with a set of default parameters.
 //!   In general, secure instantiations should choose to invoke a memory-hard password
 //!   hashing function when the client's password is expected to have low entropy,
-//!   instead of relying on [ksf::Identity] as done in the above example. The
+//!   instead of relying on [`ksf::Identity`] as done in the above example. The
 //!   more computationally intensive the `Ksf` function is, the more resistant
 //!   the server's password file records will be against offline dictionary and precomputation
 //!   attacks; see [the OPAQUE paper](https://eprint.iacr.org/2018/163.pdf) for
@@ -1121,7 +1124,7 @@
 #![no_std]
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![cfg_attr(not(test), deny(unsafe_code))]
-#![warn(clippy::cargo, missing_docs)]
+#![warn(clippy::cargo, clippy::doc_markdown, missing_docs, rustdoc::all)]
 #![cfg_attr(not(test), warn(unused_crate_dependencies))]
 #![allow(type_alias_bounds)]