From 2ead83f9d82a8ca73e6e058fbaf793ab3f4adf8f Mon Sep 17 00:00:00 2001 From: Luca BRUNO Date: Mon, 19 Aug 2024 14:59:21 +0200 Subject: [PATCH] docs: add details for client login final step This tweaks the documentation on the main module, in order to add some details on the outcome of the client login final step. In particular, it clarifies the result of `ClientLogin::finish()` both on success and on errors and it adds some intra-crate links to the relevant structures and fields. --- src/lib.rs | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 2599a52..e00c8ff 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -390,11 +390,18 @@ //! //! ### 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. +//! [`CredentialResponse`] from the server and runs [`ClientLogin::finish`] +//! on it. +//! If the authentication is successful, then the client obtains a +//! [`ClientLoginFinishResult`]. Otherwise, on failure, the +//! algorithm outputs an +//! [`InvalidLoginError`](errors::ProtocolError::InvalidLoginError) error. +//! +//! The resulting [`ClientLoginFinishResult`] obtained by client in this step +//! contains, among other things, a [`CredentialFinalization`] to be sent to the +//! server to complete the protocol, and a +//! [`session_key`](struct.ClientLoginFinishResult.html#structfield.session_key) +//! which will match the server's session key upon a successful login. //! ``` //! # use opaque_ke::{ //! # errors::ProtocolError, @@ -1108,8 +1115,8 @@ //! and `OprfCs`. To select a specific backend see the [curve25519-dalek] //! documentation. //! -//! - The `curve25519` feature enables [`Curve25519`] as a `KeGroup`. To select -//! a specific backend see the [curve25519-dalek] documentation. +//! - The `curve25519` feature enables Curve25519 as a `KeGroup`. To select a +//! specific backend see the [curve25519-dalek] documentation. //! //! - The `p256` feature enables the use of [`p256::NistP256`] as a `KeGroup` //! and a `OprfCs` for `CipherSuite`.