Rust docs noise_sv2

protocols/v2/noise-sv2/src/aed_cipher.rs

@@ -1,16 +1,60 @@
+//! # AEAD Cipher Trait
+//!
+//! 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.
+//!
+//! ## Overview
+//!
+//! AEAD ciphers provide both confidentiality and integrity by encrypting data and creating an
+//! authentication tag in a single step. The integrity of additional associated data (AAD) can also
+//! be verified without including it in the encrypted output.
+//!
+//! ## Usage
+//!
+//! 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
+/// 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
+/// [`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
+/// decryption.
 pub trait AeadCipher {
+    /// Creates a new instance of the cipher from a 32-byte key.
+    ///
+    /// Initializes the AEAD cipher with the provided key (`k`), preparing it for
+    /// encryption and decryption operations.
     fn from_key(k: [u8; 32]) -> Self;
 
+    /// Encrypts the data in place using the provided 12-byte `nonce` and AAD (`ad`).
+    ///
+    /// Performs authenticated encryption on the provided mutable data buffer (`data`), modifying
+    /// it in place to contain the ciphertext. The encryption is performed using the provided nonce
+    /// and AAD, which ensures that the data has not been tampered with during transit.
     fn encrypt<T: Buffer>(
         &mut self,
         nonce: &[u8; 12],
         ad: &[u8],
         data: &mut T,
     ) -> Result<(), aes_gcm::Error>;
 
+    /// Decrypts the data in place using the provided 12-byte nonce (`n`) and AAD (`ad`).
+    ///
+    /// Performs authenticated decryption on the provided mutable data buffer, modifying it in
+    /// place to contain the plaintext. The decryption is performed using the provided nonce and
+    /// AAD, ensuring that the data has not been tampered with during transit.
     fn decrypt<T: Buffer>(
         &mut self,
         nonce: &[u8; 12],
@@ -47,6 +91,7 @@ impl AeadCipher for Aes256Gcm {
     fn from_key(k: [u8; 32]) -> Self {
         Aes256Gcm::new(&k.into())
     }
+
     fn encrypt<T: Buffer>(
         &mut self,
         nonce: &[u8; 12],
@@ -55,6 +100,7 @@ impl AeadCipher for Aes256Gcm {
     ) -> Result<(), aes_gcm::Error> {
         self.encrypt_in_place(nonce.into(), ad, data)
     }
+
     fn decrypt<T: Buffer>(
         &mut self,
         nonce: &[u8; 12],

protocols/v2/noise-sv2/src/cipher_state.rs

@@ -1,19 +1,79 @@
+//! # AEAD Cipher Management
+//!
+//! The [`CipherState`] trait manages the state and operations of Authenticated Encryption with
+//! Associated Data (AEAD) ciphers within cryptographic protocols.
+//!
+//! ## Overview
+//!
+//! Details of key management, nonce generation, and encryption/decryption are abstracted away,
+//! 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
+//! cipher implementations in a generic manner.
+//!
+//! ## Usage
+//!
+//! 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 [`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;
 
 use crate::aed_cipher::AeadCipher;
 use aes_gcm::Aes256Gcm;
 use chacha20poly1305::{aead::Buffer, ChaCha20Poly1305};
 
+/// Manages the state and operations of an AEAD cipher.
+///
+/// Provides methods for managing the cryptographic state of an AEAD cipher, including the
+/// 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.
 pub trait CipherState<Cipher_: AeadCipher>
 where
     Self: Sized,
 {
+    /// Retrieves a mutable reference to the 32-byte encryption key (`k`).
     fn get_k(&mut self) -> &mut Option<[u8; 32]>;
+
+    /// Sets the 32-byte encryption key to the optionally provided value (`k`).
+    ///
+    /// Allows the encryption key to be explicitly set, typically after it has been derived or
+    /// initialized during the handshake process. If `None`, the encryption key is unset.
     fn set_k(&mut self, k: Option<[u8; 32]>);
+
+    /// Retrieves the current nonce (`n`) used for encryption.
+    ///
+    /// The nonce is a counter that is incremented with each encryption/decryption operations to
+    /// ensure that each encryption operation with the same key produces a unique ciphertext.
     fn get_n(&self) -> u64;
+
+    /// Sets the nonce (`n`) to the provided value.
+    ///
+    /// Allows the nonce to be explicitly set, typically after it has been initialized, incremented
+    /// during the encryption process, or reset.
     fn set_n(&mut self, n: u64);
+
+    /// Retrieves a mutable reference to the optional cipher instance.
+    ///
+    /// Provides access to the underlying AEAD cipher instance used for encryption and decryption
+    /// operations.
     fn get_cipher(&mut self) -> &mut Option<Cipher_>;
 
+    /// Converts the current 64-bit nonce value (`n`) to a 12-byte array.
+    ///
+    /// Converts the 64-bit nonce value  to a 12-byte array suitable for use with AEAD ciphers,
+    /// which typically expect a 96-bit (12-byte) nonce. The result is a correctly formatted nonce
+    /// for use in encryption and decryption operations.
     fn nonce_to_bytes(&self) -> [u8; 12] {
         let mut res = [0u8; 12];
         let n = self.get_n();
@@ -37,6 +97,11 @@ where
         Some(Cipher::from_cipher(c))
     }
 
+    /// Encrypts the provided `data` in place using the cipher and AAD (`ad`).
+    ///
+    /// Performs authenticated encryption on the provided `data` buffer, modifying it in place to
+    /// contain the ciphertext. The encryption is performed using the current nonce and the AAD.
+    /// The nonce is incremented after each successful encryption.
     fn encrypt_with_ad<T: Buffer>(
         &mut self,
         ad: &[u8],
@@ -58,6 +123,11 @@ where
         }
     }
 
+    /// Decrypts the data in place using the cipher and AAD (`ad`).
+    ///
+    /// Performs authenticated decryption on the provided `data` buffer, modifying it in place to
+    /// contain the plaintext. The decryption is performed using the current nonce and the provided
+    /// AAD. The nonce is incremented after each successful decryption.
     fn decrypt_with_ad<T: Buffer>(
         &mut self,
         ad: &[u8],
@@ -80,6 +150,17 @@ 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.
+///
+/// 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.
 #[allow(clippy::large_enum_variant)]
 pub enum GenericCipher {
     ChaCha20Poly1305(Cipher<ChaCha20Poly1305>),
@@ -88,24 +169,45 @@ pub enum GenericCipher {
 }
 
 impl Drop for GenericCipher {
+    /// Securely erases the encryption key when the [`GenericCipher`] is dropped.
+    ///
+    /// 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();
     }
 }
 
 impl GenericCipher {
+    /// Encrypts the data (`msg`) in place using the underlying cipher.
+    ///
+    /// Performs authenticated encryption on the provided data buffer, modifying it in place to
+    /// contain the ciphertext. The encryption is performed using the current nonce and an empty
+    /// additional associated data (AAD) buffer.
     pub fn encrypt<T: Buffer>(&mut self, msg: &mut T) -> Result<(), aes_gcm::Error> {
         match self {
             GenericCipher::ChaCha20Poly1305(c) => c.encrypt_with_ad(&[], msg),
             GenericCipher::Aes256Gcm(c) => c.encrypt_with_ad(&[], msg),
         }
     }
+
+    /// Decrypts the data (`msg`) in place using the underlying cipher.
+    ///
+    /// Performs authenticated decryption on the provided data buffer, modifying it in place to
+    /// contain the plaintext. The decryption is performed using the current nonce and an empty
+    /// additional associated data (AAD) buffer.
     pub fn decrypt<T: Buffer>(&mut self, msg: &mut T) -> Result<(), aes_gcm::Error> {
         match self {
             GenericCipher::ChaCha20Poly1305(c) => c.decrypt_with_ad(&[], msg),
             GenericCipher::Aes256Gcm(c) => c.decrypt_with_ad(&[], msg),
         }
     }
+
+    /// 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
+    /// no longer needed.
     pub fn erase_k(&mut self) {
         match self {
             GenericCipher::ChaCha20Poly1305(c) => {
@@ -180,9 +282,19 @@ impl CipherState<Aes256Gcm> for GenericCipher {
     }
 }
 
+/// Represents the state of an AEAD cipher, including the optional 32-byte encryption key (`k`),
+/// nonce (`n`), and optional cipher instance (`cipher`).
+///
+/// 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.
 pub struct Cipher<C: AeadCipher> {
+    /// Optional 32-byte encryption key.
     k: Option<[u8; 32]>,
+    /// Nonce value.
     n: u64,
+    /// Optional cipher instance.
     cipher: Option<C>,
 }
 
@@ -191,7 +303,6 @@ pub struct Cipher<C: AeadCipher> {
 // anymore it
 //impl<C: AeadCipher> !Sync for Cipher<C> {}
 //impl<C: AeadCipher> !Copy for Cipher<C> {}
-
 impl<C: AeadCipher> Cipher<C> {
     /// Internal use only, we need k for handshake
     pub fn from_key_and_cipher(k: [u8; 32], c: C) -> Self {

protocols/v2/noise-sv2/src/error.rs

@@ -1,18 +1,47 @@
+//! # Noise Sv2 Error Handling
+//!
+//! [`Error`] defines the set of possible errors that may arise during the Noise protocol
+//! handshake, cipher selection, and encryption/decryption processes.
+
 use aes_gcm::Error as AesGcm;
 
+/// Noise protocol error handling.
 #[derive(Debug, PartialEq, Eq)]
 pub enum Error {
+    /// The handshake has not been completed when a finalization step is executed.
     HandshakeNotFinalized,
+
+    /// Error on an empty cipher list is provided where one is required.
     CipherListMustBeNonEmpty,
+
+    /// Error on unsupported ciphers.
     UnsupportedCiphers(Vec<u8>),
+
+    /// Provided cipher list is invalid or malformed.
     InvalidCipherList(Vec<u8>),
+
+    /// Chosen cipher is invalid or unsupported.
     InvalidCipherChosed(Vec<u8>),
+
+    /// Wraps AES-GCM errors during encryption/decryption.
     AesGcm(AesGcm),
+
+    /// Cipher is in an invalid state during encryption/decryption operations.
     InvalidCipherState,
+
+    /// Provided certificate is invalid or cannot be verified.
     InvalidCertificate([u8; 74]),
+
+    /// A raw public key is invalid or cannot be parsed.
     InvalidRawPublicKey,
+
+    /// A raw private key is invalid or cannot be parsed.
     InvalidRawPrivateKey,
+
+    /// An incoming handshake message is expected but not received.
     ExpectedIncomingHandshakeMessage,
+
+    /// A message has an incorrect or unexpected length.
     InvalidMessageLength,
 }