docs: improve documentation

src/dsa/rpo_falcon512/keys.rs

@@ -49,7 +49,28 @@ impl From<PublicKey> for Word {
 // SECRET KEY
 // ================================================================================================
 
-/// TODO: ADD DOCS
+/// The secret key is a quadruple [[g, -f], [G, -F]] of polynomials with integer coefficients. Each
+/// polynomial is of degree at most N = 512 and computations with these polynomials is done modulo
+/// the monic irreducible polynomial ϕ = x^N + 1. The secret key is a basis for a lattice and has
+/// the property of being short with respect to a certain norm and an upper bound appropriate for
+/// a given security parameter. The public key on the other hand is another basis for the same
+/// lattice and can be described by a single polynomial h with integer coefficients modulo ϕ.
+/// The two keys are related by the following relation:
+/// 
+/// 1. h = g /f [mod ϕ][mod M]
+/// 2. f.G - g.F = M [mod ϕ]
+/// 
+/// where M = 12289 is the Falcon prime. Equation 2 is called the NTRU equation.
+/// The secret key is generated by first sampling a random pair (f, g) of polynomials using
+/// an appropriate distribution that yields short but not too short polynomials with integer 
+/// coefficients modulo ϕ. The NTRU equation is then used to find a matching pair (F, G).
+/// The public key is then derived from the secret key using equation 2.
+/// 
+/// To allow for fast signature generation, the secret key is pre-processed into a more suitable
+/// form, called the LDL tree, and this allows for fast sampling of short vectors in the lattice
+/// using Fast Fourier sampling during signature generation (ffSampling algorithm 11 in [1]).
+/// 
+/// [1]: https://falcon-sign.info/falcon.pdf
 #[derive(Debug, Clone)]
 pub struct SecretKey {
     secret_key: ShortLatticeBasis,
@@ -73,17 +94,22 @@ impl SecretKey {
         Self::from_short_lattice_basis(basis)
     }
 
-    /// TODO: add docs
+    /// Given a short basis [[g, -f], [G, -F]], computes the normalized LDL tree i.e., Falcon tree.
     fn from_short_lattice_basis(basis: ShortLatticeBasis) -> SecretKey {
+        // FFT each polynomial of the short basis.
         let basis_fft = basis.clone().map(|c| c.map(|cc| Complex64::new(*cc as f64, 0.0)).fft());
 
-        let g0_fft = gram(basis_fft);
-        let mut tree = ffldl(g0_fft);
+        // compute the Gram matrix.
+        let g_fft = gram(basis_fft);
+        // construct the LDL tree of the Gram matrix.
+        let mut tree = ffldl(g_fft);
+        // normalize the leaves of the LDL tree.
         normalize_tree(&mut tree, SIGMA);
         Self { secret_key: basis, tree }
     }
 
-    /// Derives the public key corresponding to this secret key.
+    /// Derives the public key corresponding to this secret key using h = g /f [mod ϕ][mod M]. Uses
+    /// FFT for fast polynomial arithmetic.
     pub fn pub_key(&self) -> Polynomial<FalconFelt> {
         let f = self.secret_key[1].map(|&c| -FalconFelt::new(c));
         let f_ntt = f.fft();