Add docs for signature_message.rs

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

@@ -1,14 +1,38 @@
+//! # Signature-Based Messages Handling
+//!
+//! Defines the `SignatureNoiseMessage` struct, which represents a signed message used in the
+//! Noise protocol to authenticate and verify the identity of a party during the handshake. It
+//! includes functionality for signing and verifying messages using Schnorr signatures with the
+//! `secp256k1` elliptic curve.
+//!
+//! ## Usage
+//!
+//! The `SignatureNoiseMessage` is used in both the `Responder` and `Initiator` during the Noise
+//! handshake to ensure that messages are authentic and have not been tampered with.
+
 use secp256k1::{hashes::sha256, schnorr::Signature, Keypair, Message, Secp256k1, XOnlyPublicKey};
 use std::{convert::TryInto, time::SystemTime};
 
+/// `SignatureNoiseMessage` is a structure that encapsulates a cryptographic signature message
+/// used in the Noise NX protocol. This message includes versioning and timestamp information,
+/// ensuring that the signature is valid only within a specific time window.
 pub struct SignatureNoiseMessage {
+    /// Version of the protocol being used.
     pub version: u16,
+    /// Start of the validity period for the message, expressed as a Unix timestamp.
     pub valid_from: u32,
+    /// End of the validity period for the message, expressed as a Unix timestamp.
     pub not_valid_after: u32,
+    /// 64-byte Schnorr signature that authenticates the message.
     pub signature: [u8; 64],
 }
 
 impl From<[u8; 74]> for SignatureNoiseMessage {
+    /// Converts a 74-byte array into a `SignatureNoiseMessage`.
+    ///
+    /// Allows a raw 74-byte array to be converted into a `SignatureNoiseMessage`, extracting the
+    /// version, validity periods, and signature from the provided data. Panics if the byte array
+    /// cannot be correctly converted into the struct fields.
     fn from(value: [u8; 74]) -> Self {
         let version = u16::from_le_bytes(value[0..2].try_into().unwrap());
         let valid_from = u32::from_le_bytes(value[2..6].try_into().unwrap());
@@ -24,6 +48,13 @@ impl From<[u8; 74]> for SignatureNoiseMessage {
 }
 
 impl SignatureNoiseMessage {
+    /// Verifies the `SignatureNoiseMessage` against the provided public key and an optional
+    /// authority public key. The verification checks that the message is currently valid
+    /// (i.e., within the `valid_from` and `not_valid_after` time window) and that the signature
+    /// is correctly signed by the authority.
+    ///
+    /// If an authority public key is not provided, the function assumes that the signature
+    /// is already valid without further verification.
     pub fn verify(self, pk: &XOnlyPublicKey, authority_pk: &Option<XOnlyPublicKey>) -> bool {
         if let Some(authority_pk) = authority_pk {
             let now = SystemTime::now()
@@ -48,6 +79,12 @@ impl SignatureNoiseMessage {
             true
         }
     }
+
+    /// Signs a `SignatureNoiseMessage` using the provided keypair (`kp`).
+    ///
+    /// 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`).
     pub fn sign(msg: &mut [u8; 74], static_pk: &XOnlyPublicKey, kp: &Keypair) {
         let secp = Secp256k1::signing_only();
         let m = [&msg[0..10], &static_pk.serialize()].concat();
@@ -58,6 +95,12 @@ impl SignatureNoiseMessage {
         }
     }
 
+    /// Splits the `SignatureNoiseMessage` into its component parts: the message hash and the
+    /// signature.
+    ///
+    /// Separates the message into the first 10 bytes (containing the version and validity period)
+    /// and the 64-byte Schnorr signature, returning them in a tuple. Used internally during the
+    /// verification process.
     fn split(self) -> ([u8; 10], [u8; 64]) {
         let mut m = [0; 10];
         m[0] = self.version.to_le_bytes()[0];