address review feedback

chacha20poly1305/src/impl_hacl.rs

@@ -19,6 +19,7 @@ pub fn encrypt<'a>(
 
     let aad_len: u32 = aad.len().try_into().map_err(|_| AeadError::AadTooLarge)?;
 
+    // we already knwo that ptxt.len() < u32::MAX, so we can safely add here.
     if ctxt.len() < ptxt.len() + TAG_LEN {
         return Err(AeadError::CiphertextTooShort);
     }
@@ -50,6 +51,7 @@ pub fn decrypt<'a>(
         return Err(AeadError::InvalidCiphertext);
     }
 
+    // we know that ctxt.len() >= TAG_LEN, so we can subtract
     if ptxt.len() < ctxt.len() - TAG_LEN {
         return Err(AeadError::PlaintextTooShort);
     }

rsa/src/impl_hacl.rs

@@ -1,8 +1,10 @@
 use crate::Error;
 
+/// An RSA Signature that is `LEN` bytes long.
 #[derive(Debug)]
 pub struct Signature<const LEN: usize>([u8; LEN]);
 
+/// An RSA Public Key that is `LEN` bytes long.
 #[derive(Debug, Clone)]
 pub struct PublicKey<const LEN: usize> {
     n: [u8; LEN],
@@ -14,16 +16,19 @@ impl<const LEN: usize> From<[u8; LEN]> for PublicKey<LEN> {
     }
 }
 
+/// An RSA Private Key that is `LEN` bytes long.
 pub struct PrivateKey<const LEN: usize> {
     pk: PublicKey<LEN>,
     d: [u8; LEN],
 }
 
 impl<const LEN: usize> PrivateKey<LEN> {
+    /// Constructor for the private key based on `n` and `d`.
     pub fn from_components(n: [u8; LEN], d: [u8; LEN]) -> Self {
         Self { pk: n.into(), d }
     }
 
+    /// Returns the public key of the private key.
     pub fn pk(&self) -> &PublicKey<LEN> {
         &self.pk
     }
@@ -76,6 +81,7 @@ macro_rules! impl_rsapss {
 
             // required by precondition to verify, see
             // https://github.com/hacl-star/hacl-star/blob/efbf82f29190e2aecdac8899e4f42c8cb9defc98/code/rsapss/Hacl.Spec.RSAPSS.fst#L162
+            // all operands are at most u32, so coercing to u64 and then adding is safe.
             if (salt_len as u64) + alg.hash_len() as u64 + 8 > u32::MAX as u64 {
                 return Err(Error::SaltTooLarge);
             }
@@ -87,7 +93,8 @@ macro_rules! impl_rsapss {
             let sgnt = &mut sig.0;
 
             // required by precondition to verify, see
-            // https://github.com/hacl-star/hacl-star/blob/main/code/rsapss/Hacl.Spec.RSAPSS.fst#L164
+            // https://github.com/hacl-star/hacl-star/blob/efbf82f29190e2aecdac8899e4f42c8cb9defc98/code/rsapss/Hacl.Spec.RSAPSS.fst#L164
+            // all operands are at most u32, so coercing to u64 and then adding is safe.
             if salt_len as u64 + alg.hash_len() as u64 + 2 > (mod_bits as u64 - 1) / 8 + 1 {
                 return Err(Error::SaltTooLarge);
             }
@@ -127,6 +134,7 @@ macro_rules! impl_rsapss {
         ) -> Result<(), Error> {
             // required by precondition to verify, see
             // https://github.com/hacl-star/hacl-star/blob/efbf82f29190e2aecdac8899e4f42c8cb9defc98/code/rsapss/Hacl.Spec.RSAPSS.fst#L236
+            // all operands are at most u32, so coercing to u64 and then adding is safe.
             if (salt_len as u64) + alg.hash_len() as u64 + 8 > u32::MAX as u64 {
                 return Err(Error::SaltTooLarge);
             }

rsa/src/lib.rs

@@ -8,14 +8,17 @@ mod hacl {
     use libcrux_sha2::hacl as hash_sha2;
 }
 
+/// The hacl-rs code for RSA signatures
 #[cfg(feature = "expose-hacl")]
 pub mod hacl {
+    /// The RSA-PSS signature code.
     pub mod rsapss;
 
     use libcrux_hacl_rs::streaming_types;
     use libcrux_sha2::hacl as hash_sha2;
 }
 
+/// The hash algorithm used for signing or verifying.
 #[derive(Clone, Copy, Debug)]
 pub enum DigestAlgorithm {
     Sha2_256,
@@ -34,11 +37,19 @@ impl DigestAlgorithm {
     }
 }
 
+/// Represents errors that occurred during signing or verifying.
 #[derive(Debug)]
 pub enum Error {
+    /// Indicates that the salt is too large.
     SaltTooLarge,
+
+    /// Indicates that the message is too large.
     MessageTooLarge,
+
+    /// Indicates that the verification of a signature failed.
     VerificationFailed,
+
+    /// Indicates that signing a message failed.
     SigningFailed,
 }