diff --git a/protocols/v2/noise-sv2/src/initiator.rs b/protocols/v2/noise-sv2/src/initiator.rs index e813be774a..3a0e3f29d0 100644 --- a/protocols/v2/noise-sv2/src/initiator.rs +++ b/protocols/v2/noise-sv2/src/initiator.rs @@ -176,11 +176,11 @@ impl Initiator { /// Creates a new [`Initiator`] instance with an optional responder public key and a custom /// random number generator. /// - /// 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 - /// ephemeral key pair and handshake hash. + /// See [`Self::new`] for more details. /// - /// The custom random number generator is used to generate the ephemeral key pair. + /// The custom random number generator is used to generate the ephemeral key pair. It should be + /// provided in order to not implicitely rely on `std` and allow `no_std` environments to + /// provide a hardware random number generator for example. #[inline] pub fn new_with_rng( pk: Option, @@ -216,13 +216,11 @@ impl Initiator { /// Creates a new [`Initiator`] instance using a raw 32-byte public key and a custom random /// number generator. /// - /// Constructs a [`XOnlyPublicKey`] from the provided raw key slice and initializes a new - /// [`Initiator`] with the derived public key and the custom random number generator. If the - /// provided key cannot be converted into a valid [`XOnlyPublicKey`], an - /// [`Error::InvalidRawPublicKey`] error is returned. + /// See [`Self::from_raw_k`] for more details. /// - /// Typically used when the initiator is aware of the responder's public key in advance and - /// wants to use a custom random number generator. + /// The custom random number generator should be provided in order to not implicitely rely on + /// `std` and allow `no_std` environments to provide a hardware random number generator for + /// example. #[inline] pub fn from_raw_k_with_rng( key: [u8; 32], @@ -246,12 +244,11 @@ impl Initiator { /// Creates a new [`Initiator`] instance without a responder's public key and using a custom /// random number generator. /// - /// This function initializes an [`Initiator`] with a default empty state, without requiring the - /// responder's authority public key, ideal for scenarios where both parties are within the same - /// network. The custom random number generator is used to generate the ephemeral key pair, - /// ensuring unique and secure cryptographic materials for the handshake process. The - /// connection remains encrypted, even though the initiator does not validate the - /// responder's static key from a certificate. Returns an error if the initialization fails. + /// See [`Self::without_pk`] for more details. + /// + /// The custom random number generator should be provided in order to not implicitely rely on + /// `std` and allow `no_std` environments to provide a hardware random number generator for + /// example. #[inline] pub fn without_pk_with_rng(rng: &mut R) -> Result, Error> { Ok(Self::new_with_rng(None, rng)) @@ -307,6 +304,14 @@ impl Initiator { .as_secs() as u32; self.step_2_with_now(message, now) } + + /// Processes the second step of the Noise NX protocol handshake for the initiator given the + /// current system time. + /// + /// See [`Self::step_2`] for more details. + /// + /// The current system time should be provided to avoid relying on `std` and allow `no_std` + /// environments to use another source of time. pub fn step_2_with_now( &mut self, message: [u8; INITIATOR_EXPECTED_HANDSHAKE_MESSAGE_SIZE], diff --git a/protocols/v2/noise-sv2/src/responder.rs b/protocols/v2/noise-sv2/src/responder.rs index 74fdbfa32b..c35c851917 100644 --- a/protocols/v2/noise-sv2/src/responder.rs +++ b/protocols/v2/noise-sv2/src/responder.rs @@ -184,12 +184,11 @@ impl Responder { /// Creates a new [`Responder`] instance with the provided authority keypair, certificate /// validity, and a custom random number generator. /// - /// Constructs a new [`Responder`] with the necessary cryptographic state for the Noise NX - /// protocol handshake. It generates ephemeral and static key pairs for the responder and - /// prepares the handshake state. The authority keypair, certificate validity period, and - /// custom random number generator are also configured. The custom random number generator - /// is used to generate the ephemeral key pair for the handshake process. Returns an error if - /// the initialization fails. + /// See [`Self::new`] for more details. + /// + /// The custom random number generator should be provided in order to not implicitely rely on + /// `std` and allow `no_std` environments to provide a hardware random number generator for + /// example. #[inline] pub fn new_with_rng( a: Keypair, @@ -231,12 +230,11 @@ impl Responder { /// Creates a new [`Responder`] instance with the provided 32-byte authority key pair and a /// custom random number generator. /// - /// Constructs a new [`Responder`] with a given public and private key pair, which represents - /// the responder's authority credentials. It verifies that the provided public key matches the - /// corresponding private key, ensuring the authenticity of the authority key pair. The - /// certificate validity duration is also set here. The custom random number generator is used - /// to generate the ephemeral key pair for the handshake process. Fails if the key pair is - /// mismatched or if the initialization fails. + /// See [`Self::from_authority_kp`] for more details. + /// + /// The custom random number generator should be provided in order to not implicitely rely on + /// `std` and allow `no_std` environments to provide a hardware random number generator for + /// example. #[inline] pub fn from_authority_kp_with_rng( public: &[u8; 32], @@ -287,18 +285,14 @@ impl Responder { ) } - /// Executes the first step of the Noise NX protocol handshake for the responder with - /// the current time and a custom RNG. + /// Executes the first step of the Noise NX protocol handshake for the responder given + /// the current time and a custom random number generator. /// - /// This method handles the initial processing of the initiator's message by interpreting - /// the provided ephemeral public key, deriving shared secrets, and setting up the session - /// ciphers. It performs operations such as mixing the handshake hash, decrypting, and hashing - /// the ephemeral public key, and encrypting and hashing the static public key. Additionally, - /// it generates a signature noise message and encrypts it to be included in the response. + /// See [`Self::step_1`] for more details. /// - /// The method finalizes by configuring the session ciphers for secure communication, returning - /// both the response message and a `NoiseCodec` instance for further message encryption and - /// decryption. On failure, it returns an error if decryption or encryption operations fail. + /// The current time and the custom random number generatorshould be provided in order to not + /// implicitely rely on `std` and allow `no_std` environments to provide a hardware random + /// number generator for example. #[inline] pub fn step_1_with_now_rng( &mut self, diff --git a/protocols/v2/noise-sv2/src/signature_message.rs b/protocols/v2/noise-sv2/src/signature_message.rs index 529d1ffa36..b020056452 100644 --- a/protocols/v2/noise-sv2/src/signature_message.rs +++ b/protocols/v2/noise-sv2/src/signature_message.rs @@ -82,21 +82,11 @@ impl SignatureNoiseMessage { /// Verifies the validity and authenticity of the `SignatureNoiseMessage` at a given timestamp. /// - /// This method checks that the message is within its validity period defined by `valid_from` - /// and `not_valid_after`, and verifies the Schnorr signature using the provided public keys. - /// It computes the message hash using SHA-256 over the message components concatenated with - /// the public key serialization. If `authority_pk` is provided, the signature is verified - /// against it; otherwise, the message is assumed valid. + /// See [`Self::verify`] for more details. /// - /// # Parameters - /// - `pk`: A reference to the `XOnlyPublicKey` of the responder. - /// - `authority_pk`: An optional reference to the `XOnlyPublicKey` of the authority, used for - /// signature verification. - /// - `now`: The current time as a Unix timestamp, used to check the validity period. - /// - /// # Returns - /// Returns `true` if the message is valid and the signature is successfully verified, `false` - /// otherwise. + /// The current system time should be provided to avoid relying on `std` and allow `no_std` + /// environments to use another source of time. + #[inline] pub fn verify_with_now( self, @@ -134,12 +124,14 @@ impl SignatureNoiseMessage { Self::sign_with_rng(msg, static_pk, kp, &mut rand::thread_rng()); } - /// Creates a Schnorr signature for the message, combining the version, validity period, and - /// the static public key of the server (`static_pk`). The resulting signature is then written - /// into the provided message buffer (`msg`). + /// Signs a [`SignatureNoiseMessage`] using the provided keypair (`kp`) and a custom random + /// number generator. + /// + /// See [`Self::sign`] for more details. /// - /// This function takes a random number generator (`R`) to generate the random number used in - /// the signature generation. + /// The random number generator is used in the signature generation. It should be provided in + /// order to not implicitely rely on `std` and allow `no_std` environments to provide a + /// hardware random number generator for example. #[inline] pub fn sign_with_rng( msg: &mut [u8; 74],