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

Co-authored-by: RJ Rybarczyk <[email protected]>

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

@@ -1,28 +1,37 @@
-// # AEAD Cipher Management
+// # Cipher State Management
 //
-// The [`CipherState`] trait manages the state and operations of Authenticated Encryption with
-// Associated Data (AEAD) ciphers within cryptographic protocols.
+// Defines the [`CipherState`] trait and the [`GenericCipher`] enum, which manage the state of
+// AEAD ciphers used in the Noise protocol. This includes managing the encryption key, nonce, and
+// the cipher instance itself, facilitating secure encryption and decryption during communication.
 //
-// ## Overview
+// The [`CipherState`] trait abstracts the management of core elements for AEAD ciphers:
+// - Manages the encryption key lifecycle used by the AEAD cipher.
+// - Generates and tracks unique nonces for each encryption operation, preventing replay attacks.
+// - Initializes the appropriate cipher (e.g., [`ChaCha20Poly1305`] or [`Aes256Gcm`]) for secure
+//   communication.
 //
-// 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 trait provides methods for encrypting and decrypting data using additional associated data
+// (AAD) and securely erasing sensitive cryptographic material when no longer needed.
 //
-// The module also includes the [`GenericCipher`] enum, which allows for the use of different AEAD
-// cipher implementations in a generic manner.
+// The [`GenericCipher`] enum enables flexible use of either [`ChaCha20Poly1305`] or [`Aes256Gcm`]
+// ciphers. It abstracts away the specific cipher being used while ensuring consistent handling of
+// cryptographic operations (e.g., encryption, decryption, key erasure) across both ciphers.
 //
 // ## 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 [`CipherState`] trait is used by the [`crate::handshake::HandshakeOp`] trait to manage
+// stateful encryption and decryption tasks during the Noise protocol handshake. By implementing
+// [`CipherState`], the handshake process securely manages cryptographic material and transforms
+// 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
+// Once the Noise handshake is complete, the [`crate::Initiator`] and [`crate::Responder`] use
+// [`GenericCipher`] instances (`c1` and `c2`) to perform symmetric encryption and decryption.
+// These ciphers, initialized and managed through the [`CipherState`] trait, ensure ongoing
 // communication remains confidential and authenticated.
+//
+// The [`CipherState`] trait and [`GenericCipher`] enum are essential for managing AEAD ciphers
+// within the Noise protocol, ensuring secure data handling, key management, and nonce tracking
+// throughout the communication session.
 
 use std::ptr;