From 5596727787298ea3b4cc5d36115c8b43ccaf036e Mon Sep 17 00:00:00 2001 From: RJ Rybarczyk Date: Thu, 12 Sep 2024 14:22:09 -0400 Subject: [PATCH] Data type links in doc cmts --- protocols/v2/noise-sv2/src/aed_cipher.rs | 21 +++--- protocols/v2/noise-sv2/src/cipher_state.rs | 59 +++++++-------- protocols/v2/noise-sv2/src/handshake.rs | 41 ++++++----- protocols/v2/noise-sv2/src/initiator.rs | 85 +++++++++++----------- 4 files changed, 105 insertions(+), 101 deletions(-) diff --git a/protocols/v2/noise-sv2/src/aed_cipher.rs b/protocols/v2/noise-sv2/src/aed_cipher.rs index 63336027d..02b847416 100644 --- a/protocols/v2/noise-sv2/src/aed_cipher.rs +++ b/protocols/v2/noise-sv2/src/aed_cipher.rs @@ -1,9 +1,9 @@ //! # AEAD Cipher Trait //! -//! Defines the `AeadCipher` trait which standardizes the interface for Authenticated Encryption +//! Defines the [`AeadCipher`] trait which standardizes the interface for Authenticated Encryption //! with Associated Data (AEAD) ciphers used within the Noise protocol implementation. The trait is -//! implemented for two common cipher, `ChaCha20Poly1305` and `Aes256Gcm`, providing encryption and -//! decryption functionality with authenticated data. +//! implemented for two common cipher, [`ChaCha20Poly1305`] and [`Aes256Gcm`], providing encryption +//! and decryption functionality with authenticated data. //! //! ## Overview //! @@ -13,22 +13,23 @@ //! //! ## Usage //! -//! The `AeadCipher` trait is used by the `HandshakeOp` trait to perform cryptographic operations -//! during the Noise protocol handshake, ensuring secure communication between parties. +//! The [`AeadCipher`] trait is used by the [`crate::handshake::HandshakeOp`] trait to perform +//! cryptographic operations during the Noise protocol handshake, ensuring secure communication +//! between parties. use aes_gcm::Aes256Gcm; use chacha20poly1305::{aead::Buffer, AeadInPlace, ChaCha20Poly1305, ChaChaPoly1305, KeyInit}; /// Defines the interface for AEAD ciphers. /// -/// The `AeadCipher` trait provides a standard interface for initializing AEAD ciphers, and for +/// The [`AeadCipher`] trait provides a standard interface for initializing AEAD ciphers, and for /// performing encryption and decryption operations with additional AAD. This trait is implemented -/// by either the `ChaCha20Poly1305` or `Aes256Gcm` specific cipher types, allowing them to be used -/// interchangeably in cryptographic protocols. It is utilized by the `HandshakeOp` trait to secure -/// the handshake process. +/// by either the [`ChaCha20Poly1305`] or [`Aes256Gcm`] specific cipher types, allowing them to be +/// used interchangeably in cryptographic protocols. It is utilized by the +/// [`crate::handshake::HandshakeOp`] trait to secure the handshake process. /// /// The `T: Buffer` represents the data buffer to be encrypted or decrypted. The buffer must -/// implement the `Buffer` trait, which provides necessary operations for in-place encryption and +/// implement the [`Buffer`] trait, which provides necessary operations for in-place encryption and /// decryption. pub trait AeadCipher { /// Creates a new instance of the cipher from a 32-byte key. diff --git a/protocols/v2/noise-sv2/src/cipher_state.rs b/protocols/v2/noise-sv2/src/cipher_state.rs index 0a1cc34d0..61553cdf0 100644 --- a/protocols/v2/noise-sv2/src/cipher_state.rs +++ b/protocols/v2/noise-sv2/src/cipher_state.rs @@ -1,6 +1,6 @@ //! # AEAD Cipher Management //! -//! The `CipherState` trait manages the state and operations of Authenticated Encryption with +//! The [`CipherState`] trait manages the state and operations of Authenticated Encryption with //! Associated Data (AEAD) ciphers within cryptographic protocols. //! //! ## Overview @@ -9,19 +9,19 @@ //! ensuring the underlying cryptographic details are consistently handled across different cipher //! implementations. //! -//! The module also includes the `GenericCipher` enum, which allows for the use of different AEAD +//! The module also includes the [`GenericCipher`] enum, which allows for the use of different AEAD //! cipher implementations in a generic manner. //! //! ## Usage //! -//! The `CipherState` trait is used by the `HandshakeOp` trait to handle the stateful encryption -//! and decryption tasks required during the Noise protocol handshake. By implementing -//! `CipherState`, handshake operations securely manage cryptographic material and perform -//! necessary transformations on messages exchanged between the initiator and responder. +//! The [`CipherState`] trait is used by the [`crate::handshake::HandshakeOp`] trait to handle the +//! stateful encryption and decryption tasks required during the Noise protocol handshake. By +//! implementing [`CipherState`], handshake operations securely manage cryptographic material and +//! perform necessary transformations on messages exchanged between the initiator and responder. //! -//! The `Initiator` and `Responder` structs use `GenericCipher` instances (`c1` and `c2`) to -//! perform symmetric encryption and decryption once the Noise handshake is complete. These -//! ciphers, initialized and managed through the `CipherState` trait, ensure that ongoing +//! The [`crate::Initiator`] and [`crate::Responder`] structs use [`GenericCipher`] instances (`c1` +//! and `c2`) to perform symmetric encryption and decryption once the Noise handshake is complete. +//! These ciphers, initialized and managed through the [`CipherState`] trait, ensure that ongoing //! communication remains confidential and authenticated. use std::ptr; @@ -36,8 +36,8 @@ use chacha20poly1305::{aead::Buffer, ChaCha20Poly1305}; /// encryption key (`k`), nonce (`n`), and the cipher instance itself. It also provides methods for /// encrypting and decrypting data with additional associated data (AAD) using the managed cipher. /// -/// `CipherState` is typically implemented by structs that need to manage cipher state as part of a -/// the Noise protocol handshake. +/// [`CipherState`] is typically implemented by structs that need to manage cipher state as part of +/// a the Noise protocol handshake. pub trait CipherState where Self: Sized, @@ -152,15 +152,15 @@ where /// An enum representing a generic cipher state. /// -/// `GenericCipher` abstracts over different AEAD cipher implementations, allowing -/// for flexible use of either `ChaCha20Poly1305` or `Aes256Gcm`. It provides methods -/// for encryption, decryption, and key erasure. +/// [`GenericCipher`] abstracts over different AEAD cipher implementations, allowing for flexible +/// use of either [`ChaCha20Poly1305`] or [`Aes256Gcm`]. It provides methods for encryption, +/// decryption, and key erasure. /// -/// A generic cipher that can be either `ChaCha20Poly1305` or `Aes256Gcm`. +/// A generic cipher that can be either [`ChaCha20Poly1305`] or [`Aes256Gcm`]. /// -/// The `GenericCipher` enum allows for flexibility in choosing between different AEAD ciphers. It -/// provides methods for encrypting, decrypting, and securely erasing the encryption key, ensuring -/// that sensitive cryptographic material is handled correctly. +/// The [`GenericCipher`] enum allows for flexibility in choosing between different AEAD ciphers. +/// It provides methods for encrypting, decrypting, and securely erasing the encryption key, +/// ensuring that sensitive cryptographic material is handled correctly. #[allow(clippy::large_enum_variant)] pub enum GenericCipher { ChaCha20Poly1305(Cipher), @@ -169,9 +169,9 @@ pub enum GenericCipher { } impl Drop for GenericCipher { - /// Securely erases the encryption key when the `GenericCipher` is dropped. + /// Securely erases the encryption key when the [`GenericCipher`] is dropped. /// - /// Ensures that the encryption key is securely erased from memory when the `GenericCipher` + /// Ensures that the encryption key is securely erased from memory when the [`GenericCipher`] /// instance is dropped, preventing any potential leakage of sensitive cryptographic material. fn drop(&mut self) { self.erase_k(); @@ -205,8 +205,8 @@ impl GenericCipher { /// Securely erases the encryption key (`k`) from memory. /// - /// Overwrites the encryption key stored within the `GenericCipher` with zeros and sets it to - /// `None`, ensuring that the key cannot be recovered after the `GenericCipher` is dropped or + /// Overwrites the encryption key stored within the [`GenericCipher`] with zeros and sets it to + /// `None`, ensuring that the key cannot be recovered after the [`GenericCipher`] is dropped or /// no longer needed. pub fn erase_k(&mut self) { match self { @@ -245,13 +245,14 @@ impl GenericCipher { } } -/// Represents the state of an AEAD cipher when using `Aes256Gcm`, including the encryption key and -/// nonce. +/// Represents the state of an AEAD cipher when using [`Aes256Gcm`], including the encryption key +/// and nonce. /// -/// The `Cipher` struct manages the cryptographic state required to perform AEAD encryption and +/// The [`Cipher`] struct manages the cryptographic state required to perform AEAD encryption and /// decryption operations. It stores the optional 32-byte encryption key (`k`), the nonce (`n`), -/// and the optional cipher instance itself. The `CipherState` trait is implemented for this struct -/// to provide a consistent interface for managing cipher state across different AEAD ciphers. +/// and the optional cipher instance itself. The [`CipherState`] trait is implemented for this +/// struct to provide a consistent interface for managing cipher state across different AEAD +/// ciphers. impl CipherState for GenericCipher { fn get_k(&mut self) -> &mut Option<[u8; 32]> { match self { @@ -294,8 +295,8 @@ impl CipherState for GenericCipher { /// /// Manages the cryptographic state required to perform AEAD encryption and decryption operations. /// It stores the optional encryption key, the nonce, and the optional cipher instance itself. The -/// `CipherState` trait is implemented to provide a consistent interface for managing cipher state -/// across different AEAD ciphers. +/// [`CipherState`] trait is implemented to provide a consistent interface for managing cipher +/// state across different AEAD ciphers. pub struct Cipher { /// Optional 32-byte encryption key. k: Option<[u8; 32]>, diff --git a/protocols/v2/noise-sv2/src/handshake.rs b/protocols/v2/noise-sv2/src/handshake.rs index 65bfb7bf3..fa91b4c62 100644 --- a/protocols/v2/noise-sv2/src/handshake.rs +++ b/protocols/v2/noise-sv2/src/handshake.rs @@ -1,31 +1,31 @@ //! # Noise Protocol Handshake Operations //! -//! The `HandshakeOp` trait defines the essential operations required for executing the Noise +//! The [`HandshakeOp`] trait defines the essential operations required for executing the Noise //! protocol handshake, a cryptographic procedure used to establish secure communication channels. //! //! ## Overview //! -//! The trait abstracts away the complexities of key management, encryption, and hashing, -//! ensuring consistent and secure operations across different handshake implementations. +//! The trait abstracts away the complexities of key management, encryption, and hashing, ensuring +//! consistent and secure operations across different handshake implementations. //! -//! The `HandshakeOp` trait is central to managing the cryptographic state during the handshake, +//! The [`HandshakeOp`] trait is central to managing the cryptographic state during the handshake, //! including the handling of keys, nonces, and encryption tasks necessary to authenticate and //! secure the communication between parties. //! //! ## Usage //! -//! The `HandshakeOp` trait is typically implemented by roles in the Noise protocol handshake, -//! such as the `Initiator` and `Responder`. These roles leverage the trait to securely manage -//! cryptographic material and perform operations like mixing hashes, encrypting/decrypting -//! messages, and deriving new keys as the handshake progresses. +//! The [`HandshakeOp`] trait is typically implemented by roles in the Noise protocol handshake, +//! such as the [`crate::Initiator`] and [`crate::Responder`]. These roles leverage the trait to +//! securely manage cryptographic material and perform operations like mixing hashes, +//! encrypting/decrypting messages, and deriving new keys as the handshake progresses. //! -//! Implementation of `HandshakeOp` handles the updating of the handshake hash (`h`), the +//! Implementation of [`HandshakeOp`] handles the updating of the handshake hash (`h`), the //! chaining key (`ck`), and the encryption key (`k`), ensuring that the cryptographic state //! remains consistent and secure throughout the handshake process. //! -//! For example, an `Initiator` and `Responder` would use `HandshakeOp` implementations to perform -//! the necessary steps of the handshake, including the encryption and decryption of messages, -//! while maintaining the integrity and confidentiality of the exchange. +//! For example, an [`crate::Initiator`] and [`crate::Responder`] would use [`HandshakeOp`] +//! implementations to perform the necessary steps of the handshake, including the encryption and +//! decryption of messages, while maintaining the integrity and confidentiality of the exchange. //! use crate::{aed_cipher::AeadCipher, cipher_state::CipherState, NOISE_HASHED_PROTOCOL_NAME_CHACHA}; @@ -38,20 +38,21 @@ use secp256k1::{ /// Represents the operations needed during a Noise protocol handshake. /// -/// The `HandshakeOp` trait defines the necessary functions for managing the state and +/// The [`HandshakeOp`] trait defines the necessary functions for managing the state and /// cryptographic operations required during the Noise protocol handshake. It provides methods for /// key generation, hash mixing, encryption, decryption, and key derivation, ensuring that the /// handshake process is secure and consistent. /// /// ## Associated Types /// -/// * `Cipher: AeadCipher`: Represents the cipher used during the handshake, typically an -/// authenticated encryption with associated data (AEAD) cipher like `ChaCha20Poly1305`. +/// * [`crate::cipher_state::Cipher`]: [`AeadCipher`]: Represents the cipher used during the +/// handshake, typically an authenticated encryption with associated data (AEAD) cipher like +/// [`ChaCha20Poly1305`]. /// /// ## Example /// -/// This trait is implemented for both the `Initiator` and `Responder` structs, allowing them -/// to perform their respective roles in the Noise protocol handshake. +/// This trait is implemented for both the [`crate::Initiator`] and [`crate::Responder`] structs, +/// allowing them to perform their respective roles in the Noise protocol handshake. /// /// ```rs /// impl HandshakeOp for Initiator { @@ -112,11 +113,11 @@ pub trait HandshakeOp: CipherState { *h = Sha256Hash::hash(&to_hash).to_byte_array(); } - /// Generates a new cryptographic key pair using the Secp256k1 curve. + /// Generates a new cryptographic key pair using the [`Secp256k1`] curve. /// /// Generates a fresh key pair, consisting of a secret key and a corresponding public key, - /// using the Secp256k1 elliptic curve. If the generated public key does not match the expected - /// parity, a new key pair is generated to ensure consistency. + /// using the [`Secp256k1`] elliptic curve. If the generated public key does not match the + /// expected parity, a new key pair is generated to ensure consistency. fn generate_key() -> Keypair { let secp = Secp256k1::new(); let (secret_key, _) = secp.generate_keypair(&mut rand::thread_rng()); diff --git a/protocols/v2/noise-sv2/src/initiator.rs b/protocols/v2/noise-sv2/src/initiator.rs index 005070edc..2190a2966 100644 --- a/protocols/v2/noise-sv2/src/initiator.rs +++ b/protocols/v2/noise-sv2/src/initiator.rs @@ -1,34 +1,35 @@ //! # Noise NX Protocol Initiator //! -//! This module manages the state and operations of the initiator within the Noise NX -//! protocol. This struct plays a crucial role in the cryptographic handshake, establishing a -//! secure communication channel with the responder by performing key exchanges, deriving shared -//! secrets, and encrypting/decrypting handshake messages. +//! This module manages the state and operations of the initiator within the Noise NX protocol. +//! This struct plays a crucial role in the cryptographic handshake, establishing a secure +//! communication channel with the responder by performing key exchanges, deriving shared secrets, +//! and encrypting/decrypting handshake messages. //! //! ## Overview //! -//! The `Initiator` is responsible for generating and managing the necessary cryptographic keys, +//! The [`Initiator`] is responsible for generating and managing the necessary cryptographic keys, //! including ephemeral and optional static keys, as well as maintaining the state of the handshake //! process. It interacts with the responder to derive shared secrets and set up secure cipher -//! states that protect subsequent communication. The struct implements the `CipherState` and -//! `HandshakeOp` traits to manage the cryptographic state and operations throughout the handshake. +//! states that protect subsequent communication. The struct implements the +//! [`crate::cipher_state::CipherState`] and [`crate::handshake::HandshakeOp`] traits to manage the +//! cryptographic state and operations throughout the handshake. //! -//! The module utilizes cryptographic components such as ChaCha20Poly1305 for encryption, Elligator -//! Swift for key obfuscation, and Secp256k1 for key generation, ensuring that the handshake is -//! both secure and efficient. +//! The module utilizes cryptographic components such as [`ChaCha20Poly1305`] for encryption, +//! Elligator Swift for key obfuscation, and Secp256k1 for key generation, ensuring that the +//! handshake is both secure and efficient. //! //! ## Usage //! -//! The `Initiator` can be instantiated with or without knowledge of the responder's public key. +//! The [`Initiator`] can be instantiated with or without knowledge of the responder's public key. //! The handshake process is executed in multiple steps, starting with the generation of an //! ephemeral keypair and encoding the public key, followed by processing messages exchanged with //! the responder to derive shared secrets and authenticate the responder. Upon successful -//! completion of the handshake, the `Initiator` sets up cipher states that are used for encrypted +//! completion of the handshake, the [`Initiator`] sets up cipher states that are used for encrypted //! communication with the responder. //! //! ### Example //! -//! This example demonstrates how to initialize an `Initiator`, perform the first step of the +//! This example demonstrates how to initialize an [`Initiator`], perform the first step of the //! Noise NX handshake, and handle the responder's reply. //! //! ```rust @@ -59,12 +60,12 @@ //! //! ## Secure Data Erasure //! -//! The `Initiator` includes methods to securely erase sensitive cryptographic material, +//! The [`Initiator`] includes methods to securely erase sensitive cryptographic material, //! preventing any accidental leakage or misuse. This functionality is essential when the instance //! is no longer needed or is being deallocated. //! -//! The `Drop` trait is implemented to ensure that this erasure happens automatically when the -//! `Initiator` goes out of scope. +//! The [`Drop`] trait is implemented to ensure that this erasure happens automatically when the +//! [`Initiator`] goes out of scope. use std::{convert::TryInto, ptr}; @@ -115,11 +116,11 @@ pub struct Initiator { /// handshake. #[allow(unused)] responder_authority_pk: Option, - /// First `CipherState` used for encrypting messages from the initiator to the responder after - /// the handshake is complete. + /// First [`crate::cipher_state::CipherState`] used for encrypting messages from the initiator + /// to the responder after the handshake is complete. c1: Option, - /// Second `CipherState` used for encrypting messages from the responder to the initiator after - /// the handshake is complete. + /// Second [`crate::cipher_state::CipherState`] used for encrypting messages from the responder + /// to the initiator after the handshake is complete. c2: Option, } @@ -129,8 +130,8 @@ impl std::fmt::Debug for Initiator { } } -// Make sure that Initiator is not sync so we do not need to worry about what other memory accessor see -// after that we zeroize k is send cause if we send it the original thread can not access +// Make sure that Initiator is not sync so we do not need to worry about what other memory accessor +// see after that we zeroize k is send cause if we send it the original thread can not access // anymore it //impl !Sync for Initiator {} //impl !Copy for Initiator {} @@ -184,7 +185,7 @@ impl HandshakeOp for Initiator { } impl Initiator { - /// Creates a new `Initiator` instance with an optional responder public key. + /// Creates a new [`Initiator`] instance with an optional responder public key. /// /// If the responder public key is provided, the initiator uses this key to authenticate the /// responder during the handshake. The initial initiator state is instantiated with the @@ -205,11 +206,11 @@ impl Initiator { Box::new(self_) } - /// Creates a new `Initiator` instance using a raw 32-byte public key. + /// Creates a new [`Initiator`] instance using a raw 32-byte public key. /// - /// Constructs a `XOnlyPublicKey` from the provided raw key slice and initializes a new - /// `Initiator` with the derived public key. If the provided key cannot be converted into a - /// valid `XOnlyPublicKey`, an `InvalidRawPublicKey` error is returned. + /// Constructs a [`XOnlyPublicKey`] from the provided raw key slice and initializes a new + /// [`Initiator`] with the derived public key. If the provided key cannot be converted into a + /// valid [`XOnlyPublicKey`], an [`Error::InvalidRawPublicKey`] error is returned. /// /// Typically used when the initiator is aware of the responder's public key in advance. pub fn from_raw_k(key: [u8; 32]) -> Result, Error> { @@ -218,8 +219,8 @@ impl Initiator { Ok(Self::new(Some(pk))) } - /// Creates a new `Initiator` without specifying a responder's public key. - /// This function initializes the `Initiator` with a default empty state. + /// Creates a new [`Initiator`] without specifying a responder's public key. + /// This function initializes the [`Initiator`] with a default empty state. pub fn without_pk() -> Result, Error> { Ok(Self::new(None)) } @@ -234,7 +235,7 @@ impl Initiator { /// the responder. /// /// On success, the function returns a 64-byte array containing the encoded public key. - /// If an error occurs during encryption, it returns an `aes_gcm::Error`. + /// If an error occurs during encryption, it returns an [`aes_gcm::Error`]. pub fn step_0(&mut self) -> Result<[u8; ELLSWIFT_ENCODING_SIZE], aes_gcm::Error> { let elliswift_enc_pubkey = ElligatorSwift::from_pubkey(self.e.public_key()).to_array(); self.mix_hash(&elliswift_enc_pubkey); @@ -247,11 +248,11 @@ impl Initiator { /// Processes the second step of the Noise NX protocol handshake for the initiator. /// - /// This method handles the responder's reply in the Noise NX protocol handshake, processing the - /// message to derive shared secrets and authenticate the responder. It interprets the first 64 - /// bytes of the message as the responder's ephemeral public key, decodes it, and mixes it into the - /// handshake state. It then derives a shared secret from the ephemeral keys and updates the state - /// accordingly. + /// This method handles the responder's reply in the Noise NX protocol handshake, processing + /// the message to derive shared secrets and authenticate the responder. It interprets the + /// first 64 bytes of the message as the responder's ephemeral public key, decodes it, and + /// mixes it into the handshake state. It then derives a shared secret from the ephemeral keys + /// and updates the state accordingly. /// /// The next 80 bytes of the message contain the responder's static public key, encrypted and /// authenticated. The method decrypts this segment and derives another shared secret using the @@ -259,10 +260,10 @@ impl Initiator { /// decrypts and verifies the signature included in the message to ensure the responder's /// authenticity. /// - /// On success, this method returns a `NoiseCodec` instance initialized with session ciphers for - /// secure communication. If the provided `message` has an incorrect length, it returns an - /// `Error::InvalidMessageLength`. If decryption or signature verification fails, it returns an - /// `Error::InvalidCertificate`. + /// On success, this method returns a [`NoiseCodec`] instance initialized with session ciphers + /// for secure communication. If the provided `message` has an incorrect length, it returns an + /// [`Error::InvalidMessageLength`]. If decryption or signature verification fails, it returns + /// an [`Error::InvalidCertificate`]. pub fn step_2( &mut self, message: [u8; INITIATOR_EXPECTED_HANDSHAKE_MESSAGE_SIZE], @@ -354,10 +355,10 @@ impl Initiator { /// Securely erases sensitive data in the initiator's memory. /// - /// Clears all sensitive cryptographic material within the `Initiator` to prevent any + /// Clears all sensitive cryptographic material within the [`Initiator`] to prevent any /// accidental leakage or misuse. It overwrites the stored keys, chaining key, handshake hash, /// and session ciphers with zeros or other non-sensitive values. This method is typically - /// called when the `Initiator` instance is no longer needed or before deallocation. + /// called when the [`Initiator`] instance is no longer needed or before deallocation. fn erase(&mut self) { if let Some(k) = self.k.as_mut() { for b in k { @@ -380,7 +381,7 @@ impl Initiator { } } impl Drop for Initiator { - /// Ensures that sensitive data is securely erased when the `Initiator` instance is dropped, + /// Ensures that sensitive data is securely erased when the [`Initiator`] instance is dropped, /// preventing any potential leakage of cryptographic material. fn drop(&mut self) { self.erase();