From 937990d3cb424ef1eca7a63a6d285d6547bd865b 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 +++++++-------- 3 files changed, 62 insertions(+), 59 deletions(-) diff --git a/protocols/v2/noise-sv2/src/aed_cipher.rs b/protocols/v2/noise-sv2/src/aed_cipher.rs index 63336027d2..02b8474169 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 0a1cc34d0f..61553cdf05 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 65bfb7bf3b..fa91b4c62b 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());