pq_crypto 0.6.5 → 0.6.7

data/ext/pqcrypto/vendor/mldsa-native/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
 
@@ -31,20 +41,22 @@ typedef struct
 /**
  * Sample vector of polynomials with uniformly random coefficients in
  * [-(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1] by unpacking output stream of
- * SHAKE256(seed|nonce).
+ * SHAKE256(seed|kappa+i) for component i.
+ *
+ * @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.
+ * @param      kappa Base counter; component i uses kappa + i.
  */
 MLD_INTERNAL_API
 void mld_polyvecl_uniform_gamma1(mld_polyvecl *v,
                                  const uint8_t seed[MLDSA_CRHBYTES],
-                                 uint16_t nonce)
+                                 uint16_t kappa)
 __contract__(
   requires(memory_no_alias(v, sizeof(mld_polyvecl)))
   requires(memory_no_alias(seed, MLDSA_CRHBYTES))
-  requires(nonce <= (UINT16_MAX - MLDSA_L) / MLDSA_L)
+  requires(kappa <= MLD_MAX_KAPPA)
   assigns(memory_slice(v, sizeof(mld_polyvecl)))
   ensures(forall(k0, 0, MLDSA_L,
     array_bound(v->vec[k0].coeffs, 0, MLDSA_N, -(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1 + 1)))
@@ -58,8 +70,8 @@ __contract__(
      (!defined(MLD_CONFIG_REDUCE_RAM) || defined(MLD_UNIT_TEST)))
 #define mld_polyvecl_ntt MLD_NAMESPACE_KL(polyvecl_ntt)
 /**
- * Forward NTT of all polynomials in vector of length MLDSA_L. Coefficients
- * can grow by 8*MLDSA_Q in absolute value.
+ * Forward NTT of all polynomials in vector of length MLDSA_L. Output
+ * coefficients are bounded by MLD_NTT_BOUND in absolute value.
  *
  * @param[in,out] v Pointer to input/output vector.
  */
@@ -87,7 +99,10 @@ __contract__(
  * have coefficients in [0, MLDSA_Q-1] inclusive.
  *
  * The second input "v" is assumed to be output of an NTT, and hence must have
- * coefficients bounded by [-(9*MLDSA_Q-1), 9*MLDSA_Q-1] inclusive.
+ * 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.
@@ -186,8 +201,8 @@ __contract__(
     (!defined(MLD_CONFIG_REDUCE_RAM) || defined(MLD_UNIT_TEST))
 #define mld_polyveck_ntt MLD_NAMESPACE_KL(polyveck_ntt)
 /**
- * Forward NTT of all polynomials in vector of length MLDSA_K. Coefficients
- * can grow by 8*MLDSA_Q in absolute value.
+ * Forward NTT of all polynomials in vector of length MLDSA_K. Output
+ * coefficients are bounded by MLD_NTT_BOUND in absolute value.
  *
  * @param[in,out] v Pointer to input/output 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.

data/ext/pqcrypto/vendor/mldsa-native/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

data/ext/pqcrypto/vendor/mldsa-native/mldsa/src/polyvec_lazy.h

@@ -127,11 +127,11 @@ typedef struct
   mld_polyvecl vec; /**< Masking vector y. */
 } mld_yvec_eager;
 
-/** Lazy yvec: store seed and nonce, regenerate y[i] on demand. */
+/** Lazy yvec: store seed and base counter kappa, regenerate y[i] on demand. */
 typedef struct
 {
   const uint8_t *rhoprime; /**< Pointer to seed used to derive y. */
-  uint16_t nonce; /**< Base nonce; component i uses MLDSA_L*nonce + i. */
+  uint16_t kappa;          /**< Base counter; component i uses kappa + i. */
 } mld_yvec_lazy;
 
 #if !defined(MLD_CONFIG_NO_KEYPAIR_API) || !defined(MLD_CONFIG_NO_SIGN_API)
@@ -341,17 +341,17 @@ __contract__(
 #if !defined(MLD_CONFIG_NO_SIGN_API) && \
     (!defined(MLD_CONFIG_REDUCE_RAM) || defined(MLD_UNIT_TEST))
 static MLD_INLINE void mld_yvec_init_eager(
-    mld_yvec_eager *y, const uint8_t rhoprime[MLDSA_CRHBYTES], uint16_t nonce)
+    mld_yvec_eager *y, const uint8_t rhoprime[MLDSA_CRHBYTES], uint16_t kappa)
 __contract__(
   requires(memory_no_alias(y, sizeof(mld_yvec_eager)))
   requires(memory_no_alias(rhoprime, MLDSA_CRHBYTES))
-  requires(nonce <= (UINT16_MAX - MLDSA_L) / MLDSA_L)
+  requires(kappa <= MLD_MAX_KAPPA)
   assigns(memory_slice(y, sizeof(mld_yvec_eager)))
   ensures(forall(k1, 0, MLDSA_L,
     array_bound(y->vec.vec[k1].coeffs, 0, MLDSA_N, -(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1 + 1)))
 )
 {
-  mld_polyvecl_uniform_gamma1(&y->vec, rhoprime, nonce);
+  mld_polyvecl_uniform_gamma1(&y->vec, rhoprime, kappa);
 }
 
 static MLD_INLINE void mld_yvec_get_poly_eager(mld_poly *buf,
@@ -370,16 +370,16 @@ __contract__(
 #if !defined(MLD_CONFIG_NO_SIGN_API) && \
     (defined(MLD_CONFIG_REDUCE_RAM) || defined(MLD_UNIT_TEST))
 static MLD_INLINE void mld_yvec_init_lazy(
-    mld_yvec_lazy *y, const uint8_t rhoprime[MLDSA_CRHBYTES], uint16_t nonce)
+    mld_yvec_lazy *y, const uint8_t rhoprime[MLDSA_CRHBYTES], uint16_t kappa)
 __contract__(
   requires(memory_no_alias(y, sizeof(mld_yvec_lazy)))
   assigns(memory_slice(y, sizeof(mld_yvec_lazy)))
   ensures(y->rhoprime == old(rhoprime))
-  ensures(y->nonce == old(nonce))
+  ensures(y->kappa == old(kappa))
 )
 {
   y->rhoprime = rhoprime;
-  y->nonce = nonce;
+  y->kappa = kappa;
 }
 
 static MLD_INLINE void mld_yvec_get_poly_lazy(mld_poly *buf,
@@ -390,16 +390,14 @@ __contract__(
   requires(memory_no_alias(y, sizeof(mld_yvec_lazy)))
   requires(i < MLDSA_L)
   requires(memory_no_alias(y->rhoprime, MLDSA_CRHBYTES))
-  requires(y->nonce <= ((UINT16_MAX - MLDSA_L) / MLDSA_L))
+  requires(y->kappa <= MLD_MAX_KAPPA)
   assigns(memory_slice(buf, sizeof(mld_poly)))
   ensures(array_bound(buf->coeffs, 0, MLDSA_N, -(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1 + 1))
 )
 {
-  /* Safety: y->nonce is at most ((UINT16_MAX - MLDSA_L) / MLDSA_L) and
-   * i < MLDSA_L, so MLDSA_L * y->nonce + i fits in uint16_t. See
-   * MLD_NONCE_UB comment in sign.c. */
-  mld_poly_uniform_gamma1(buf, y->rhoprime,
-                          (uint16_t)(MLDSA_L * y->nonce + (int)i));
+  /* Safety: y->kappa <= MLD_MAX_KAPPA and i < MLDSA_L, so y->kappa + i
+   * fits in uint16_t. See MLD_MAX_KAPPA comment in params.h. */
+  mld_poly_uniform_gamma1(buf, y->rhoprime, (uint16_t)(y->kappa + i));
 }
 #endif /* !MLD_CONFIG_NO_SIGN_API && (MLD_CONFIG_REDUCE_RAM || MLD_UNIT_TEST) \
         */
@@ -441,9 +439,10 @@ __contract__(
 
 #if !defined(MLD_CONFIG_REDUCE_RAM) || defined(MLD_UNIT_TEST)
 /**
- * Implementation of ExpandA. Generates matrix A with uniformly random
- * coefficients a_{i,j} by performing rejection sampling on the output stream
- * of SHAKE128(rho|j|i).
+ * Generates matrix A with uniformly random coefficients a_{i,j} by performing
+ * rejection sampling on the output stream of SHAKE128(rho|j|i).
+ *
+ * @spec{Implements @[FIPS204, Algorithm 32, ExpandA].}
  *
  * @param[out] mat Pointer to output matrix.
  * @param[in]  rho Byte array containing seed rho.
@@ -579,7 +578,7 @@ __contract__(
  *
  * @param[out]    w       Pointer to output vector.
  * @param[in,out] mat     Pointer to input matrix.
- * @param[in]     y       Pointer to y seed/nonce.
+ * @param[in]     y       Pointer to y seed/kappa.
  * @param[out]    scratch Scratch (only &scratch->vec[0] used).
  */
 MLD_INTERNAL_API
@@ -593,7 +592,7 @@ __contract__(
   requires(memory_no_alias(y, sizeof(mld_yvec_lazy)))
   requires(memory_no_alias(scratch, sizeof(mld_polyvecl)))
   requires(memory_no_alias(y->rhoprime, MLDSA_CRHBYTES))
-  requires(y->nonce <= ((UINT16_MAX - MLDSA_L) / MLDSA_L))
+  requires(y->kappa <= MLD_MAX_KAPPA)
   assigns(memory_slice(w, sizeof(mld_polyveck)))
   assigns(memory_slice(mat, sizeof(mld_polymat_lazy)))
   assigns(memory_slice(scratch, sizeof(mld_polyvecl)))

data/ext/pqcrypto/vendor/mldsa-native/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
 
@@ -11,10 +21,10 @@
 #include "debug.h"
 
 /* check-magic: -4186625 == pow(2,32,MLDSA_Q) */
-#define MLD_MONT -4186625
+#define MLD_MONT (-4186625)
 
 /* Upper bound for domain of mld_reduce32() */
-#define MLD_REDUCE32_DOMAIN_MAX (INT32_MAX - (1 << 22))
+#define MLD_REDUCE32_DOMAIN_MAX (INT32_MAX - ((int32_t)1 << 22))
 
 /* Absolute bound for range of mld_reduce32() */
 /* check-magic: 6283009 == (MLD_REDUCE32_DOMAIN_MAX - 255 * MLDSA_Q + 1) */
@@ -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.
  *
@@ -102,7 +114,7 @@ __contract__(
 {
   int32_t t;
 
-  t = (a + (1 << 22)) >> 23;
+  t = (a + ((int32_t)1 << 22)) >> 23;
   t = a - t * MLDSA_Q;
   mld_assert((t - a) % MLDSA_Q == 0);
   return t;

data/ext/pqcrypto/vendor/mldsa-native/mldsa/src/rounding.h

@@ -38,6 +38,8 @@
  * -2^{MLDSA_D-1} < a0 <= 2^{MLDSA_D-1}. Assumes a to be standard
  * representative.
  *
+ * @spec{Implements @[FIPS204, Algorithm 35, Power2Round].}
+ *
  * @reference{In the reference implementation, a1 is passed as a return value
  * instead.}
  *
@@ -69,6 +71,8 @@ __contract__(
  * -MLDSA_GAMMA2 <= a0 = a mod^+ MLDSA_Q - MLDSA_Q < 0. Assumes a to be
  * standard representative.
  *
+ * @spec{Implements @[FIPS204, Algorithm 36, Decompose].}
+ *
  * @reference{In the reference implementation, a1 is passed as a return value
  * instead.}
  *
@@ -83,8 +87,9 @@ __contract__(
   requires(a >= 0 && a < MLDSA_Q)
   assigns(memory_slice(a0, sizeof(int32_t)))
   assigns(memory_slice(a1, sizeof(int32_t)))
-  /* a0 = -MLDSA_GAMMA2 can only occur when (q-1) = a - (a mod MLDSA_GAMMA2),
-   * then a1=1; and a0 = a - (a mod MLDSA_GAMMA2) - 1 (@[FIPS204, Algorithm 36 (Decompose)]) */
+  /* a0 = -MLDSA_GAMMA2 occurs exactly when a = MLDSA_Q - MLDSA_GAMMA2: the
+   * border case of Decompose where a1 = (MLDSA_Q-1)/(2*MLDSA_GAMMA2) is
+   * wrapped to 0 and a0 = a - MLDSA_Q (@[FIPS204, Algorithm 36, Decompose]) */
   ensures(*a0 >= -MLDSA_GAMMA2  && *a0 <= MLDSA_GAMMA2)
   ensures(*a1 >= 0 && *a1 < (MLDSA_Q-1)/(2*MLDSA_GAMMA2))
   ensures((*a1 * 2 * MLDSA_GAMMA2 + *a0 - a) % MLDSA_Q == 0)
@@ -141,7 +146,7 @@ __contract__(
    *
    * See proofs/isabelle/compress for a formalization of the above argument.
    */
-  *a1 = (*a1 * 11275 + (1 << 23)) >> 24;
+  *a1 = (*a1 * 11275 + ((int32_t)1 << 23)) >> 24;
   mld_assert(*a1 >= 0 && *a1 <= 44);
 
   *a1 = mld_ct_sel_int32(0, *a1, mld_ct_cmask_neg_i32(43 - *a1));
@@ -157,7 +162,7 @@ __contract__(
    * eps = 1 / 4290772992 ≈ 2^(-31.99) < 2^(-31), therefore f1' * eps <
    * 2^16 * 2^(-31) = 1 / 2^15 < 1 / 2^12 < 1 / B.
    */
-  *a1 = (*a1 * 1025 + (1 << 21)) >> 22;
+  *a1 = (*a1 * 1025 + ((int32_t)1 << 21)) >> 22;
   mld_assert(*a1 >= 0 && *a1 <= 16);
 
   *a1 &= 15;
@@ -171,8 +176,21 @@ __contract__(
 }
 
 /**
- * Compute hint bit indicating whether the low bits of the input element
- * overflow into the high bits.
+ * Decide a single hint bit from the low part a0 and high part a1 of a
+ * coefficient: return 1 unless a0 lies in the range (-GAMMA2, GAMMA2] that
+ * LowBits would produce, with the boundary value -GAMMA2 also admitted when
+ * a1 == 0 (the Decompose border case).
+ *
+ * @note This is not a line-for-line implementation of FIPS 204's MakeHint(z, r)
+ * (@[FIPS204, Algorithm 39, MakeHint]), which takes two ring elements and
+ * returns [[HighBits(r) != HighBits(r + z)]]. Instead, it takes the already
+ * decomposed low/high parts (a0, a1) of a coefficient and decides the hint bit
+ * from them directly. As explained in the block comment of
+ * mld_attempt_signature_generation (sign.c), for the specific values that arise
+ * during signing -- a0 = w0 - cs2 + ct0 and a1 = w1 = HighBits(w) -- this is
+ * equivalent to the spec's MakeHint(-ct0, w - cs2 + ct0) coefficient-wise.
+ * Because it consumes (a0, a1) rather than (z, r), it relies on the caller
+ * having computed a compatible decomposition.
  *
  * @param a0 Low bits of input element.
  * @param a1 High bits of input element.
@@ -183,6 +201,8 @@ MLD_MUST_CHECK_RETURN_VALUE
 static MLD_INLINE unsigned int mld_make_hint(int32_t a0, int32_t a1)
 __contract__(
   ensures(return_value >= 0 && return_value <= 1)
+  ensures(return_value == (a0 > MLDSA_GAMMA2 || a0 < -MLDSA_GAMMA2 ||
+                           (a0 == -MLDSA_GAMMA2 && a1 != 0)))
 )
 {
   if (a0 > MLDSA_GAMMA2 || a0 < -MLDSA_GAMMA2 ||
@@ -197,6 +217,8 @@ __contract__(
 /**
  * Correct high bits according to hint.
  *
+ * @spec{Implements @[FIPS204, Algorithm 40, UseHint].}
+ *
  * @param a    Input element.
  * @param hint Hint bit.
  *