Data type links in doc cmts

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.

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<Cipher_: AeadCipher>
 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<ChaCha20Poly1305>),
@@ -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<Aes256Gcm> for GenericCipher {
     fn get_k(&mut self) -> &mut Option<[u8; 32]> {
         match self {
@@ -294,8 +295,8 @@ impl CipherState<Aes256Gcm> 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<C: AeadCipher> {
     /// Optional 32-byte encryption key.
     k: Option<[u8; 32]>,

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<ChaCha20Poly1305> for Initiator {
@@ -112,11 +113,11 @@ pub trait HandshakeOp<Cipher: AeadCipher>: CipherState<Cipher> {
         *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());