From 69ead888a159d5085f608a914817227337037003 Mon Sep 17 00:00:00 2001 From: daxpedda Date: Thu, 5 Oct 2023 12:31:23 +0200 Subject: [PATCH] Add `clippy::doc_markdown` --- src/ciphersuite.rs | 2 +- src/hash.rs | 6 +- src/key_exchange/group/mod.rs | 9 ++- src/keypair.rs | 6 +- src/lib.rs | 137 +++++++++++++++++----------------- src/opaque.rs | 14 ++-- src/tests/opaque_vectors.rs | 2 +- 7 files changed, 90 insertions(+), 86 deletions(-) diff --git a/src/ciphersuite.rs b/src/ciphersuite.rs index b686cb11..1cfa92e9 100644 --- a/src/ciphersuite.rs +++ b/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}; diff --git a/src/hash.rs b/src/hash.rs index d7b7210c..2c51e77d 100644 --- a/src/hash.rs +++ b/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: +/// Trait inheriting the requirements from [`digest::Digest`] for compatibility +/// with HKDF and HMAC Associated types could be simplified when they are made +/// as defaults: pub trait Hash: Default + HashMarker diff --git a/src/key_exchange/group/mod.rs b/src/key_exchange/group/mod.rs index d0f43a95..12c6de45 100644 --- a/src/key_exchange/group/mod.rs +++ b/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 + IsLessOrEqual; - /// Corresponds to the DeriveAuthKeyPair() function defined in + /// Corresponds to the `DeriveAuthKeyPair()` function defined in /// /// /// 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( seed: GenericArray, ) -> Result diff --git a/src/keypair.rs b/src/keypair.rs index 08e0103b..c189c8ab 100644 --- a/src/keypair.rs +++ b/src/keypair.rs @@ -47,12 +47,12 @@ impl> KeyPair { &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::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> { 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() -> proptest::prelude::BoxedStrategy where ::OutputSize: diff --git a/src/lib.rs b/src/lib.rs index 3507eed2..9a2113c8 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -77,35 +77,35 @@ //! let server_setup = ServerSetup::::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)] diff --git a/src/opaque.rs b/src/opaque.rs index 63a132a0..2d3cad48 100644 --- a/src/opaque.rs +++ b/src/opaque.rs @@ -226,8 +226,8 @@ where /// Create [`ServerSetup`] with the given keypair /// /// This function should not be used to restore a previously-existing - /// instance of [ServerSetup]. Instead, use [ServerSetup::serialize] and - /// [ServerSetup::deserialize] for this purpose. + /// instance of [`ServerSetup`]. Instead, use [`ServerSetup::serialize`] and + /// [`ServerSetup::deserialize`] for this purpose. pub fn new_with_key( rng: &mut R, keypair: KeyPair, @@ -328,7 +328,7 @@ where } /// Returns an initial "blinded" request to send to the server, as well as a - /// ClientRegistration + /// [`ClientRegistration`] pub fn start( blinding_factor_rng: &mut R, password: &[u8], @@ -438,7 +438,7 @@ where } /// From the client's "blinded" password, returns a response to be sent back - /// to the client, as well as a ServerRegistration + /// to the client, as well as a [`ServerRegistration`] pub fn start>( server_setup: &ServerSetup, message: RegistrationRequest, @@ -461,7 +461,7 @@ where } /// From the client's cryptographic identifiers, fully populates and returns - /// a ServerRegistration + /// a [`ServerRegistration`] pub fn finish(message: RegistrationUpload) -> Self { Self(message) } @@ -540,7 +540,7 @@ where Le<< as CoreProxy>::Core as BlockSizeUser>::BlockSize, U256>: NonZero, { /// Returns an initial "blinded" password request to send to the server, as - /// well as a ClientLogin + /// well as a [`ClientLogin`] pub fn start( rng: &mut R, password: &[u8], @@ -691,7 +691,7 @@ where } /// From the client's "blinded" password, returns a challenge to be sent - /// back to the client, as well as a ServerLogin + /// back to the client, as well as a [`ServerLogin`] pub fn start>( rng: &mut R, server_setup: &ServerSetup, diff --git a/src/tests/opaque_vectors.rs b/src/tests/opaque_vectors.rs index d02347e3..73028402 100644 --- a/src/tests/opaque_vectors.rs +++ b/src/tests/opaque_vectors.rs @@ -7,7 +7,7 @@ // licenses. //! The OPAQUE test vectors taken from -//! https://github.com/cfrg/draft-irtf-cfrg-opaque/blob/727b9acb908dce296e15bc14a53a7d04ba9604d0/poc/vectors/formatted.txt +//! pub(crate) static VECTORS: &str = r#" ## Real Test Vectors {#real-vectors}