Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add clippy::doc_markdown #346

Merged
merged 1 commit into from
Oct 8, 2023
Merged

Add clippy::doc_markdown #346

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/ciphersuite.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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};
Expand Down
6 changes: 3 additions & 3 deletions src/hash.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 5 additions & 4 deletions src/key_exchange/group/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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>
Expand Down
6 changes: 3 additions & 3 deletions src/keypair.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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:
Expand Down
137 changes: 70 additions & 67 deletions src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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.
//! ```
Expand Down Expand Up @@ -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::{
Expand Down Expand Up @@ -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
Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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::{
Expand Down Expand Up @@ -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
//!
Expand All @@ -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,
Expand Down Expand Up @@ -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.
Expand All @@ -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,
Expand Down Expand Up @@ -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::{
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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::{
Expand Down Expand Up @@ -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
Expand All @@ -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
//!
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)]

Expand Down
Loading
Loading