add missing documentation

src/blake2b.rs

@@ -35,6 +35,7 @@ use crate::mac::{Mac, MacResult};
 use alloc::vec::Vec;
 use core::iter::repeat;
 
+/// Blake2b Context (Dynamic output size)
 pub type Context = blake2b::ContextDyn;
 
 /// Blake2b Context
@@ -84,11 +85,13 @@ impl Blake2b {
         self.computed = false;
     }
 
+    /// Reset the blake2 context with a key
     pub fn reset_with_key(&mut self, key: &[u8]) {
         self.ctx.reset_with_key(key);
         self.computed = false;
     }
 
+    /// Compute the blake2 function as one call
     pub fn blake2b(out: &mut [u8], input: &[u8], key: &[u8]) {
         let mut hasher: Blake2b = if !key.is_empty() {
             Blake2b::new_keyed(out.len(), key)

src/blake2s.rs

@@ -35,6 +35,7 @@ use crate::mac::{Mac, MacResult};
 use alloc::vec::Vec;
 use core::iter::repeat;
 
+/// Blake2s Context (Dynamic output size)
 pub type Context = blake2s::ContextDyn;
 
 /// Blake2s Context
@@ -84,11 +85,13 @@ impl Blake2s {
         self.computed = false;
     }
 
+    /// Reset the blake2 context with a key
     pub fn reset_with_key(&mut self, key: &[u8]) {
         self.ctx.reset_with_key(key);
         self.computed = false;
     }
 
+    /// Compute the blake2 function as one call
     pub fn blake2s(out: &mut [u8], input: &[u8], key: &[u8]) {
         let mut hasher: Blake2s = if !key.is_empty() {
             Blake2s::new_keyed(out.len(), key)

src/chacha/mod.rs

@@ -1,3 +1,21 @@
+//! ChaCha Stream Cipher -- Engine implementation
+//!
+//! Implementation of [ChaCha spec](https://www.rfc-editor.org/info/rfc7539)
+//! which is a fast and lean stream cipher.
+//!
+//! The maximum amount of data to be processed by a single instance of a ChaCha
+//! Context, is 256Gb (due to the 32 bits counter). Note that this is not
+//! enforced by the context, and using a context to process more than 256Gb of
+//! data would be insecure.
+//!
+//! The Engine is parametrized with the number of rounds to execute, which is
+//! enforced by assertion to be either 8, 12 or 20.
+//!
+//! Note that with stream cipher, there's only one operation [`ChaChaEngine::<N>::process`]
+//! and its variant [`ChaChaEngine::<N>::process_mut`] instead of the typical
+//! cipher operation encrypt and decrypt.
+//!
+
 #[cfg(not(all(
     any(target_arch = "x86", target_arch = "x86_64"),
     any(target_feature = "sse2", target_feature = "avx2")

src/chacha20.rs

@@ -60,6 +60,7 @@ pub struct ChaCha<const ROUNDS: usize> {
     offset: usize,
 }
 
+/// Alias to usual ChaCha context with 20 rounds
 pub type ChaCha20 = ChaCha<20>;
 
 impl<const ROUNDS: usize> ChaCha<ROUNDS> {

src/chacha20poly1305.rs

@@ -232,7 +232,9 @@ impl<const ROUNDS: usize> ContextEncryption<ROUNDS> {
 /// Whether or not, the decryption was succesful related to the expected tag
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum DecryptionResult {
+    /// The tag matched, the data has been verified as not tempered
     Match,
+    /// The tag mismatched, which imply that some data is incorrect or has been tempered
     MisMatch,
 }
 
@@ -281,6 +283,7 @@ fn pad16(mac: &mut Poly1305, len: u64) {
     }
 }
 
+/// Type alias to the common ChaChaPoly1305 with 20 rounds ChaCha
 pub type ChaCha20Poly1305 = ChaChaPoly1305<20>;
 
 impl<const ROUNDS: usize> ChaChaPoly1305<ROUNDS> {

src/constant_time.rs

@@ -46,12 +46,17 @@ pub struct CtOption<T> {
 }
 
 impl Choice {
+    /// Return true if the Choice represent true
     pub fn is_true(self) -> bool {
         self.0 == 1
     }
+    /// return true if the Choice represent false
     pub fn is_false(self) -> bool {
         self.0 == 0
     }
+    /// Toggle the value represented by the Choice in constant time
+    ///
+    /// true become false, false become true
     pub fn negate(self) -> Self {
         Choice(1 ^ self.0)
     }
@@ -94,6 +99,7 @@ impl<T> From<(Choice, T)> for CtOption<T> {
 }
 
 impl<T> CtOption<T> {
+    /// Transform a `CtOption<T>` into a non constant `Option<T>`
     pub fn into_option(self) -> Option<T> {
         if self.present.is_true() {
             Some(self.t)
@@ -108,15 +114,27 @@ impl<T> CtOption<T> {
 /// Note that zero means 0 with integer primitive, or for array of integer
 /// it means all elements are 0
 pub trait CtZero {
+    /// Check that the element is 'zero' in constant time and return the associated `Choice`
     fn ct_zero(self) -> Choice;
+
+    /// Check that the element is 'non-zero' in constant time and return the associated `Choice`
+    ///
+    /// The following call `ct_nonzero(t)` is equivalent to `ct_zero(t).negate()`
     fn ct_nonzero(self) -> Choice;
 }
 
 /// Check in constant time if the left object is greater than right object
 ///
 /// This equivalent to the > operator found in the core library.
 pub trait CtGreater: Sized {
+    /// Check that the first element is greater to the second element in
+    /// constant time and return the associated `Choice`
     fn ct_gt(a: Self, b: Self) -> Choice;
+
+    /// Check that the first element is lesser or equal to the second element in
+    /// constant time and return the associated `Choice`
+    ///
+    /// This is equivalent to calling `ct_gt` with the argument swapped
     fn ct_le(a: Self, b: Self) -> Choice {
         Self::ct_gt(b, a)
     }
@@ -126,7 +144,14 @@ pub trait CtGreater: Sized {
 ///
 /// This equivalent to the < operator found in the core library.
 pub trait CtLesser: Sized {
+    /// Check that the first element is lesser to the second element in
+    /// constant time and return the associated `Choice`
     fn ct_lt(a: Self, b: Self) -> Choice;
+
+    /// Check that the first element is greater or equal to the second element in
+    /// constant time and return the associated `Choice`
+    ///
+    /// This is equivalent of calling `ct_lt` with the argument swapped
     fn ct_ge(a: Self, b: Self) -> Choice {
         Self::ct_lt(b, a)
     }
@@ -136,7 +161,12 @@ pub trait CtLesser: Sized {
 ///
 /// This equivalent to the == operator found in the core library.
 pub trait CtEqual<Rhs: ?Sized = Self> {
+    /// Check that the two element are equal in constant time and return the associated `Choice`
     fn ct_eq(self, b: Rhs) -> Choice;
+
+    /// Check that the two element are not equal in constant time and return the associated `Choice`
+    ///
+    /// this is equivalent to calling `lhs.ct_eq(rhs).negate()`
     fn ct_ne(self, b: Rhs) -> Choice;
 }
 

src/curve25519/fe/fe64/mod.rs

@@ -36,23 +36,31 @@ impl PartialEq for Fe {
 impl Eq for Fe {}
 
 impl Fe {
+    /// Field Element constant representing 0
     pub const ZERO: Fe = Fe([0, 0, 0, 0, 0]);
+
+    /// Field Element constant representing 1
     pub const ONE: Fe = Fe([1, 0, 0, 0, 0]);
 
+    /// Field Element constant for Sqrt(-1)
     pub const SQRTM1: Fe = Fe([
         0x61B274A0EA0B0,
         0xD5A5FC8F189D,
         0x7EF5E9CBD0C60,
         0x78595A6804C9E,
         0x2B8324804FC1D,
     ]);
+
+    /// Field element constant for D
     pub const D: Fe = Fe([
         0x34DCA135978A3,
         0x1A8283B156EBD,
         0x5E7A26001C029,
         0x739C663A03CBB,
         0x52036CEE2B6FF,
     ]);
+
+    /// Field element constant for D2
     pub const D2: Fe = Fe([
         0x69B9426B2F159,
         0x35050762ADD7A,
@@ -381,10 +389,12 @@ impl Fe {
         x
     }
 
+    /// Check that the field element is non zero
     pub fn is_nonzero(&self) -> bool {
         CtEqual::ct_ne(&self.to_bytes(), &[0; 32]).into()
     }
 
+    /// Check that the field element is 'negative'
     pub fn is_negative(&self) -> bool {
         (self.to_packed()[0] & 1) != 0
     }

src/curve25519/fe/mod.rs

@@ -25,6 +25,7 @@ pub use fe32::*;
 pub use fe64::*;
 
 impl Fe {
+    /// Raise a field element to 2^255-23
     pub fn pow25523(&self) -> Fe {
         let z2 = self.square();
         let z8 = z2.square_repeatdly(2);

src/curve25519/ge.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use core::cmp::Ordering;
 use core::ops::{Add, Neg, Sub};
 

src/curve25519/scalar/scalar64.rs

@@ -2,7 +2,7 @@
 //!
 //! port of <https://github.com/floodyberry/ed25519-donna/blob/master/modm-donna-64bit.h>
 //!
-//! scalar is back by 5 Limbs in 56 bits unsaturated (except last)
+//! scalar is backed by 5 Limbs in 56 bits unsaturated (except last)
 
 /// Scalar in the field ℤ/2^252 + 27742317777372353535851937790883648493)
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -80,9 +80,15 @@ const MASK40: u64 = 0x0000_00ff_ffff_ffff;
 const MASK56: u64 = 0x00ff_ffff_ffff_ffff;
 
 impl Scalar {
+    /// The 0 Scalar constant
     pub const ZERO: Self = Scalar([0, 0, 0, 0, 0]);
+
+    /// The 1 Scalar constant
     pub const ONE: Self = Scalar([1, 0, 0, 0, 0]);
 
+    /// Create a Scalar from bytes
+    ///
+    /// Unpack 32 bytes into the 5 64bits limbs unsaturated representation
     pub const fn from_bytes(bytes: &[u8; 32]) -> Self {
         // load 8 bytes from input[ofs..ofs+7] as little endian u64
         #[inline]
@@ -110,7 +116,7 @@ impl Scalar {
         Scalar([out0, out1, out2, out3, out4])
     }
 
-    // Same as from_bytes but check whether the value
+    /// Same as from_bytes but check whether the value is less than the order of the `Scalar` Field.
     pub fn from_bytes_canonical(bytes: &[u8; 32]) -> Option<Self> {
         let scalar = Self::from_bytes(bytes);
         if lt_order(&scalar.0) {
@@ -120,6 +126,10 @@ impl Scalar {
         }
     }
 
+    /// Convert the Scalar back into a raw array of 32 bytes
+    ///
+    /// The function expect the limbs to have been reduce
+    /// ahead of calling.
     pub const fn to_bytes(&self) -> [u8; 32] {
         // contract limbs into saturated limbs
         let c0 = self.0[1] << 56 | self.0[0];

src/ed25519.rs

@@ -27,11 +27,22 @@ use crate::hashing::sha2::Sha512;
 use core::convert::TryFrom;
 
 #[deprecated(since = "0.4.0", note = "use `PRIVATE_KEY_LENGTH`")]
+/// ED25519 Seed length
 pub const SEED_LENGTH: usize = 32;
+
+/// ED25519 Private key length (32 bytes)
 pub const PRIVATE_KEY_LENGTH: usize = 32;
+
+/// ED25519 Public key length (32 bytes)
 pub const PUBLIC_KEY_LENGTH: usize = 32;
+
+/// ED25519 Keypair length (64 bytes)
 pub const KEYPAIR_LENGTH: usize = PRIVATE_KEY_LENGTH + PUBLIC_KEY_LENGTH;
+
+/// ED25519 Extended key size (64 bytes)
 pub const EXTENDED_KEY_LENGTH: usize = 64;
+
+/// ED25519 Signature size (64 bytes)
 pub const SIGNATURE_LENGTH: usize = 64;
 
 // clamp the scalar by: