mldsa: annotate functions with FIPS 204 algorithm references

BIBLIOGRAPHY.md

@@ -108,9 +108,14 @@ source code and documentation.
   - [mldsa/src/ct.h](mldsa/src/ct.h)
   - [mldsa/src/fips202/fips202.c](mldsa/src/fips202/fips202.c)
   - [mldsa/src/fips202/fips202x4.c](mldsa/src/fips202/fips202x4.c)
+  - [mldsa/src/packing.h](mldsa/src/packing.h)
   - [mldsa/src/poly.c](mldsa/src/poly.c)
+  - [mldsa/src/poly.h](mldsa/src/poly.h)
   - [mldsa/src/poly_kl.c](mldsa/src/poly_kl.c)
+  - [mldsa/src/poly_kl.h](mldsa/src/poly_kl.h)
+  - [mldsa/src/polyvec.h](mldsa/src/polyvec.h)
   - [mldsa/src/polyvec_lazy.c](mldsa/src/polyvec_lazy.c)
+  - [mldsa/src/reduce.h](mldsa/src/reduce.h)
   - [mldsa/src/rounding.h](mldsa/src/rounding.h)
   - [mldsa/src/sign.c](mldsa/src/sign.c)
   - [mldsa/src/sign.h](mldsa/src/sign.h)

mldsa/src/packing.h

@@ -2,6 +2,16 @@
  * Copyright (c) The mldsa-native project authors
  * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
  */
+
+/* References
+ * ==========
+ *
+ * - [FIPS204]
+ *   FIPS 204 Module-Lattice-Based Digital Signature Standard
+ *   National Institute of Standards and Technology
+ *   https://csrc.nist.gov/pubs/fips/204/final
+ */
+
 #ifndef MLD_PACKING_H
 #define MLD_PACKING_H
 
@@ -13,6 +23,9 @@
 /**
  * Bit-pack the s1 component into the secret key.
  *
+ * @spec{Partially implements @[FIPS204, Algorithm 24, skEncode] (s1
+ * component).}
+ *
  * @param[out] sk Output byte array.
  * @param[in]  s1 Pointer to vector s1.
  */
@@ -34,6 +47,9 @@ __contract__(
  * s1 must already be packed via mld_pack_sk_s1, and t0 via
  * mld_compute_pack_t0_t1.
  *
+ * @spec{Partially implements @[FIPS204, Algorithm 24, skEncode] (rho, key, tr,
+ * s2 components).}
+ *
  * @param[out] sk  Output byte array.
  * @param[in]  rho Byte array containing rho.
  * @param[in]  tr  Byte array containing tr.
@@ -64,6 +80,9 @@ __contract__(
 /**
  * Bit-pack challenge c into sig = (c, z, h).
  *
+ * @spec{Partially implements @[FIPS204, Algorithm 26, sigEncode] (c
+ * component).}
+ *
  * @param[out] sig Output byte array.
  * @param[in]  c   Pointer to challenge hash.
  */
@@ -80,6 +99,10 @@ __contract__(
 /**
  * Compute hints from (w0, w1) and pack them into the hint section of sig.
  *
+ * @spec{Implements @[FIPS204, Algorithm 20, HintBitPack], computing the hints
+ * via @[FIPS204, Algorithm 39, MakeHint] (h component of @[FIPS204,
+ * Algorithm 26, sigEncode]).}
+ *
  * @param[in,out] sig Byte array containing signature.
  * @param[in]     w0  Pointer to low part of input vector.
  * @param[in]     w1  Pointer to high part of input vector.
@@ -109,6 +132,9 @@ __contract__(
  * The c and h components are packed separately using mld_pack_sig_c and
  * mld_pack_sig_h.
  *
+ * @spec{Partially implements @[FIPS204, Algorithm 26, sigEncode] (one
+ * polynomial of the z component).}
+ *
  * @param[in,out] sig Output byte array.
  * @param[in]     zi  Pointer to a single polynomial in z.
  * @param         i   Index of zi in vector z.
@@ -131,6 +157,9 @@ __contract__(
  * Unpack a single polynomial of the t1 component of a public key
  * pk = (rho, t1).
  *
+ * @spec{Partially implements @[FIPS204, Algorithm 23, pkDecode] (one polynomial
+ * of t1).}
+ *
  * @param[out] t1 Pointer to output polynomial t1[i].
  * @param[in]  pk Byte array containing bit-packed pk.
  * @param      i  Row index, must be < MLDSA_K.
@@ -155,6 +184,8 @@ __contract__(
  *
  * NOTE: In REDUCE_RAM mode, s1/s2/t0 borrow from sk rather than copying.
  *
+ * @spec{Implements @[FIPS204, Algorithm 25, skDecode].}
+ *
  * @param[out] rho Output byte array for rho.
  * @param[out] tr  Output byte array for tr.
  * @param[out] key Output byte array for key.
@@ -215,6 +246,9 @@ __contract__(
  * call returns MLD_ERR_FAIL the encoding is malformed and the signature must
  * be rejected.
  *
+ * @spec{Implements @[FIPS204, Algorithm 21, HintBitUnpack] (one row; part of
+ * @[FIPS204, Algorithm 27, sigDecode]).}
+ *
  * @param[out] h   Pointer to output polynomial h[i].
  * @param[in]  sig Signature buffer.
  * @param      i   Row index, must be < MLDSA_K.

mldsa/src/poly.h

@@ -2,6 +2,16 @@
  * Copyright (c) The mldsa-native project authors
  * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
  */
+
+/* References
+ * ==========
+ *
+ * - [FIPS204]
+ *   FIPS 204 Module-Lattice-Based Digital Signature Standard
+ *   National Institute of Standards and Technology
+ *   https://csrc.nist.gov/pubs/fips/204/final
+ */
+
 #ifndef MLD_POLY_H
 #define MLD_POLY_H
 
@@ -64,6 +74,8 @@ __contract__(
 /**
  * Add polynomials. No modular reduction is performed.
  *
+ * @spec{Implements @[FIPS204, Algorithm 44, AddNTT].}
+ *
  * @param[in,out] r Pointer to input-output polynomial to be added to.
  * @param[in]     b Pointer to input polynomial that should be added to r.
  *                  Must be disjoint from r.
@@ -136,6 +148,8 @@ __contract__(
  * In-place forward NTT. Output coefficients are bounded by MLD_NTT_BOUND in
  * absolute value.
  *
+ * @spec{Implements @[FIPS204, Algorithm 41, NTT].}
+ *
  * @param[in,out] a Pointer to input/output polynomial.
  */
 MLD_INTERNAL_API
@@ -155,6 +169,8 @@ __contract__(
  * Input coefficients need to be less than MLDSA_Q in absolute value and
  * output coefficients are bounded by MLD_INTT_BOUND.
  *
+ * @spec{Implements @[FIPS204, Algorithm 42, NTT^{-1}].}
+ *
  * @param[in,out] a Pointer to input/output polynomial.
  */
 MLD_INTERNAL_API
@@ -174,6 +190,8 @@ __contract__(
  * multiplication of resulting polynomial by 2^{-32}. Destructive in the first
  * argument.
  *
+ * @spec{Implements @[FIPS204, Algorithm 45, MultiplyNTT].}
+ *
  * @param[in,out] a Pointer to first input/output polynomial. On entry, holds
  *                  the first multiplicand; on exit, holds the product
  *                  a * b * 2^{-32}.
@@ -225,6 +243,8 @@ __contract__(
  * Sample polynomial with uniformly random coefficients in [0, MLDSA_Q-1] by
  * performing rejection sampling on the output stream of SHAKE128(seed|nonce).
  *
+ * @spec{Implements @[FIPS204, Algorithm 30, RejNTTPoly].}
+ *
  * @param[out] a    Pointer to output polynomial.
  * @param[in]  seed Byte array with seed of length MLDSA_SEEDBYTES and the
  *                  packed 2-byte nonce.
@@ -245,6 +265,8 @@ __contract__(
  * Generate four polynomials using rejection sampling on (pseudo-)uniformly
  * random bytes sampled from a seed.
  *
+ * @spec{Implements @[FIPS204, Algorithm 30, RejNTTPoly] (four-way batched).}
+ *
  * @param[out] vec0 Pointer to first polynomial to be sampled.
  * @param[out] vec1 Pointer to second polynomial to be sampled.
  * @param[out] vec2 Pointer to third polynomial to be sampled.
@@ -280,6 +302,8 @@ __contract__(
  * Bit-pack polynomial t1 with coefficients fitting in 10 bits. Input
  * coefficients are assumed to be standard representatives.
  *
+ * @spec{Implements @[FIPS204, Algorithm 16, SimpleBitPack].}
+ *
  * @param[out] r Pointer to output byte array with at least
  *               MLDSA_POLYT1_PACKEDBYTES bytes.
  * @param[in]  a Pointer to input polynomial.
@@ -300,6 +324,8 @@ __contract__(
  * Unpack polynomial t1 with 10-bit coefficients. Output coefficients are
  * standard representatives.
  *
+ * @spec{Implements @[FIPS204, Algorithm 18, SimpleBitUnpack].}
+ *
  * @param[out] r Pointer to output polynomial.
  * @param[in]  a Byte array with bit-packed polynomial.
  */
@@ -318,6 +344,8 @@ __contract__(
 /**
  * Bit-pack polynomial t0 with coefficients in ]-2^{MLDSA_D-1}, 2^{MLDSA_D-1}].
  *
+ * @spec{Implements @[FIPS204, Algorithm 17, BitPack].}
+ *
  * @param[out] r Pointer to output byte array with at least
  *               MLDSA_POLYT0_PACKEDBYTES bytes.
  * @param[in]  a Pointer to input polynomial.
@@ -337,6 +365,8 @@ __contract__(
 /**
  * Unpack polynomial t0 with coefficients in ]-2^{MLDSA_D-1}, 2^{MLDSA_D-1}].
  *
+ * @spec{Implements @[FIPS204, Algorithm 19, BitUnpack].}
+ *
  * @param[out] r Pointer to output polynomial.
  * @param[in]  a Byte array with bit-packed polynomial.
  */

mldsa/src/poly_kl.h

@@ -2,6 +2,16 @@
  * Copyright (c) The mldsa-native project authors
  * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
  */
+
+/* References
+ * ==========
+ *
+ * - [FIPS204]
+ *   FIPS 204 Module-Lattice-Based Digital Signature Standard
+ *   National Institute of Standards and Technology
+ *   https://csrc.nist.gov/pubs/fips/204/final
+ */
+
 #ifndef MLD_POLY_KL_H
 #define MLD_POLY_KL_H
 
@@ -68,6 +78,9 @@ __contract__(
  * [-MLDSA_ETA, MLDSA_ETA] by performing rejection sampling on the output
  * stream from SHAKE256(seed|nonce_i).
  *
+ * @spec{Implements @[FIPS204, Algorithm 31, RejBoundedPoly] (four-way
+ * batched).}
+ *
  * @param[out] r0     Pointer to first output polynomial.
  * @param[out] r1     Pointer to second output polynomial.
  * @param[out] r2     Pointer to third output polynomial.
@@ -107,6 +120,8 @@ __contract__(
  * [-MLDSA_ETA, MLDSA_ETA] by performing rejection sampling on the output
  * stream from SHAKE256(seed|nonce).
  *
+ * @spec{Implements @[FIPS204, Algorithm 31, RejBoundedPoly].}
+ *
  * @param[out] r     Pointer to output polynomial.
  * @param[in]  seed  Byte array with seed of length MLDSA_CRHBYTES.
  * @param      nonce Nonce.
@@ -198,6 +213,8 @@ __contract__(
  * Implementation of H. Samples polynomial with MLDSA_TAU nonzero coefficients
  * in {-1, 1} using the output stream of SHAKE256(seed).
  *
+ * @spec{Implements @[FIPS204, Algorithm 29, SampleInBall].}
+ *
  * @param[out] c    Pointer to output polynomial.
  * @param[in]  seed Byte array containing seed of length MLDSA_CTILDEBYTES.
  */
@@ -217,6 +234,8 @@ __contract__(
 /**
  * Bit-pack polynomial with coefficients in [-MLDSA_ETA, MLDSA_ETA].
  *
+ * @spec{Implements @[FIPS204, Algorithm 17, BitPack].}
+ *
  * @param[out] r Pointer to output byte array with at least
  *               MLDSA_POLYETA_PACKEDBYTES bytes.
  * @param[in]  a Pointer to input polynomial.
@@ -252,6 +271,8 @@ __contract__(
 /**
  * Unpack polynomial with coefficients in [-MLDSA_ETA, MLDSA_ETA].
  *
+ * @spec{Implements @[FIPS204, Algorithm 19, BitUnpack].}
+ *
  * @param[out] r Pointer to output polynomial.
  * @param[in]  a Byte array with bit-packed polynomial.
  */
@@ -271,6 +292,8 @@ __contract__(
  * Bit-pack polynomial with coefficients in
  * [-(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1].
  *
+ * @spec{Implements @[FIPS204, Algorithm 17, BitPack].}
+ *
  * @param[out] r Pointer to output byte array with at least
  *               MLDSA_POLYZ_PACKEDBYTES bytes.
  * @param[in]  a Pointer to input polynomial.
@@ -291,6 +314,8 @@ __contract__(
  * Unpack polynomial z with coefficients in
  * [-(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1].
  *
+ * @spec{Implements @[FIPS204, Algorithm 19, BitUnpack].}
+ *
  * @param[out] r Pointer to output polynomial.
  * @param[in]  a Byte array with bit-packed polynomial.
  */
@@ -308,6 +333,8 @@ __contract__(
  * Bit-pack polynomial w1 with coefficients in [0, 15] or [0, 43]. Input
  * coefficients are assumed to be standard representatives.
  *
+ * @spec{Implements @[FIPS204, Algorithm 16, SimpleBitPack].}
+ *
  * @param[out] r Pointer to output byte array with at least
  *               MLDSA_POLYW1_PACKEDBYTES bytes.
  * @param[in]  a Pointer to input polynomial.

mldsa/src/polyvec.h

@@ -2,6 +2,16 @@
  * Copyright (c) The mldsa-native project authors
  * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
  */
+
+/* References
+ * ==========
+ *
+ * - [FIPS204]
+ *   FIPS 204 Module-Lattice-Based Digital Signature Standard
+ *   National Institute of Standards and Technology
+ *   https://csrc.nist.gov/pubs/fips/204/final
+ */
+
 #ifndef MLD_POLYVEC_H
 #define MLD_POLYVEC_H
 
@@ -33,6 +43,8 @@ typedef struct
  * [-(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1] by unpacking output stream of
  * SHAKE256(seed|nonce).
  *
+ * @spec{Implements @[FIPS204, Algorithm 34, ExpandMask].}
+ *
  * @param[out] v     Pointer to output vector.
  * @param[in]  seed  Byte array with seed of length MLDSA_CRHBYTES.
  * @param      nonce 16-bit nonce.
@@ -89,6 +101,9 @@ __contract__(
  * The second input "v" is assumed to be output of an NTT, and hence must have
  * coefficients bounded by [-(MLD_NTT_BOUND-1), MLD_NTT_BOUND-1] inclusive.
  *
+ * @spec{Partially implements @[FIPS204, Algorithm 48, MatrixVectorNTT]
+ * (one output polynomial; multiply-accumulate of two NTT-domain vectors).}
+ *
  * @param[out] w Output polynomial.
  * @param[in]  u Pointer to first input vector.
  * @param[in]  v Pointer to second input vector.
@@ -290,6 +305,8 @@ __contract__(
  * Bit-pack polynomial vector w1 with coefficients in [0, 15] or [0, 43]. Input
  * coefficients are assumed to be standard representatives.
  *
+ * @spec{Implements @[FIPS204, Algorithm 28, w1Encode].}
+ *
  * @param[out] r  Pointer to output byte array with at least
  *                MLDSA_K * MLDSA_POLYW1_PACKEDBYTES bytes.
  * @param[in]  w1 Pointer to input polynomial vector.

mldsa/src/polyvec_lazy.c

@@ -29,6 +29,9 @@
  * of seed_ext. This function writes the domain-separation bytes
  * seed_ext[SEEDBYTES..+2] = {l, k} before sampling.
  *
+ * @spec{Partially implements @[FIPS204, Algorithm 32, ExpandA] (samples one
+ * matrix entry via @[FIPS204, Algorithm 30, RejNTTPoly]).}
+ *
  * @param[out]    p        Pointer to output polynomial.
  * @param[in,out] seed_ext Seed buffer pre-filled with rho in the first
  *                         MLDSA_SEEDBYTES; the final two bytes are

mldsa/src/reduce.h

@@ -2,6 +2,16 @@
  * Copyright (c) The mldsa-native project authors
  * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
  */
+
+/* References
+ * ==========
+ *
+ * - [FIPS204]
+ *   FIPS 204 Module-Lattice-Based Digital Signature Standard
+ *   National Institute of Standards and Technology
+ *   https://csrc.nist.gov/pubs/fips/204/final
+ */
+
 #ifndef MLD_REDUCE_H
 #define MLD_REDUCE_H
 
@@ -24,6 +34,8 @@
  * Generic Montgomery reduction; given a 64-bit integer a, computes a 32-bit
  * integer congruent to a * R^-1 mod MLDSA_Q, where R=2^32.
  *
+ * @spec{Implements @[FIPS204, Algorithm 49, MontgomeryReduce].}
+ *
  * @param a Input integer to be reduced, of absolute value smaller or equal
  *          to INT64_MAX - 2^31 * MLDSA_Q.
  *