pq_crypto 0.6.1 → 0.6.2

data/ext/pqcrypto/vendor/mldsa-native/mldsa/src/poly_kl.c

@@ -37,6 +37,7 @@
 /* End of parameter set namespacing */
 
 
+#if !defined(MLD_CONFIG_NO_SIGN_API)
 MLD_STATIC_TESTABLE
 void mld_poly_decompose_c(mld_poly *a1, mld_poly *a0)
 __contract__(
@@ -100,40 +101,17 @@ void mld_poly_decompose(mld_poly *a1, mld_poly *a0)
   mld_poly_decompose_c(a1, a0);
 }
 
-MLD_INTERNAL_API
-unsigned int mld_poly_make_hint(mld_poly *h, const mld_poly *a0,
-                                const mld_poly *a1)
-{
-  unsigned int i, s = 0;
-
-  for (i = 0; i < MLDSA_N; ++i)
-  __loop__(
-    invariant(i <= MLDSA_N)
-    invariant(s <= i)
-    invariant(array_bound(h->coeffs, 0, i, 0, 2))
-    decreases(MLDSA_N - i)
-  )
-  {
-    const unsigned int hint_bit = mld_make_hint(a0->coeffs[i], a1->coeffs[i]);
-    h->coeffs[i] = (int32_t)hint_bit;
-    s += hint_bit;
-  }
+#endif /* !MLD_CONFIG_NO_SIGN_API */
 
-  mld_assert(s <= MLDSA_N);
-  mld_assert_bound(h->coeffs, MLDSA_N, 0, 2);
-  return s;
-}
-
-MLD_STATIC_TESTABLE void mld_poly_use_hint_c(mld_poly *b, const mld_poly *a,
-                                             const mld_poly *h)
+#if !defined(MLD_CONFIG_NO_VERIFY_API)
+MLD_STATIC_TESTABLE void mld_poly_use_hint_c(mld_poly *a, const mld_poly *h)
 __contract__(
-  requires(memory_no_alias(a,  sizeof(mld_poly)))
-  requires(memory_no_alias(b, sizeof(mld_poly)))
+  requires(memory_no_alias(a, sizeof(mld_poly)))
   requires(memory_no_alias(h, sizeof(mld_poly)))
   requires(array_bound(a->coeffs, 0, MLDSA_N, 0, MLDSA_Q))
   requires(array_bound(h->coeffs, 0, MLDSA_N, 0, 2))
-  assigns(memory_slice(b, sizeof(mld_poly)))
-  ensures(array_bound(b->coeffs, 0, MLDSA_N, 0, (MLDSA_Q-1)/(2*MLDSA_GAMMA2)))
+  assigns(memory_slice(a, sizeof(mld_poly)))
+  ensures(array_bound(a->coeffs, 0, MLDSA_N, 0, (MLDSA_Q-1)/(2*MLDSA_GAMMA2)))
 )
 {
   unsigned int i;
@@ -143,26 +121,27 @@ __contract__(
   for (i = 0; i < MLDSA_N; ++i)
   __loop__(
     invariant(i <= MLDSA_N)
-    invariant(array_bound(b->coeffs, 0, i, 0, (MLDSA_Q-1)/(2*MLDSA_GAMMA2)))
+    invariant(array_bound(a->coeffs, 0, i, 0, (MLDSA_Q-1)/(2*MLDSA_GAMMA2)))
+    invariant(array_bound(a->coeffs, i, MLDSA_N, 0, MLDSA_Q))
     decreases(MLDSA_N - i)
   )
   {
-    b->coeffs[i] = mld_use_hint(a->coeffs[i], h->coeffs[i]);
+    a->coeffs[i] = mld_use_hint(a->coeffs[i], h->coeffs[i]);
   }
-  mld_assert_bound(b->coeffs, MLDSA_N, 0, (MLDSA_Q - 1) / (2 * MLDSA_GAMMA2));
+  mld_assert_bound(a->coeffs, MLDSA_N, 0, (MLDSA_Q - 1) / (2 * MLDSA_GAMMA2));
 }
 
 MLD_INTERNAL_API
-void mld_poly_use_hint(mld_poly *b, const mld_poly *a, const mld_poly *h)
+void mld_poly_use_hint(mld_poly *a, const mld_poly *h)
 {
 #if defined(MLD_USE_NATIVE_POLY_USE_HINT_88) && MLD_CONFIG_PARAMETER_SET == 44
   int ret;
   mld_assert_bound(a->coeffs, MLDSA_N, 0, MLDSA_Q);
   mld_assert_bound(h->coeffs, MLDSA_N, 0, 2);
-  ret = mld_poly_use_hint_88_native(b->coeffs, a->coeffs, h->coeffs);
+  ret = mld_poly_use_hint_88_native(a->coeffs, h->coeffs);
   if (ret == MLD_NATIVE_FUNC_SUCCESS)
   {
-    mld_assert_bound(b->coeffs, MLDSA_N, 0, (MLDSA_Q - 1) / (2 * MLDSA_GAMMA2));
+    mld_assert_bound(a->coeffs, MLDSA_N, 0, (MLDSA_Q - 1) / (2 * MLDSA_GAMMA2));
     return;
   }
 #elif defined(MLD_USE_NATIVE_POLY_USE_HINT_32) && \
@@ -170,34 +149,33 @@ void mld_poly_use_hint(mld_poly *b, const mld_poly *a, const mld_poly *h)
   int ret;
   mld_assert_bound(a->coeffs, MLDSA_N, 0, MLDSA_Q);
   mld_assert_bound(h->coeffs, MLDSA_N, 0, 2);
-  ret = mld_poly_use_hint_32_native(b->coeffs, a->coeffs, h->coeffs);
+  ret = mld_poly_use_hint_32_native(a->coeffs, h->coeffs);
   if (ret == MLD_NATIVE_FUNC_SUCCESS)
   {
-    mld_assert_bound(b->coeffs, MLDSA_N, 0, (MLDSA_Q - 1) / (2 * MLDSA_GAMMA2));
+    mld_assert_bound(a->coeffs, MLDSA_N, 0, (MLDSA_Q - 1) / (2 * MLDSA_GAMMA2));
     return;
   }
 #endif /* !(MLD_USE_NATIVE_POLY_USE_HINT_88 && MLD_CONFIG_PARAMETER_SET == 44) \
           && MLD_USE_NATIVE_POLY_USE_HINT_32 && (MLD_CONFIG_PARAMETER_SET ==   \
           65 || MLD_CONFIG_PARAMETER_SET == 87) */
-  mld_poly_use_hint_c(b, a, h);
+  mld_poly_use_hint_c(a, h);
 }
+#endif /* !MLD_CONFIG_NO_VERIFY_API */
 
-/*************************************************
- * Name:        mld_rej_eta
+#if !defined(MLD_CONFIG_NO_KEYPAIR_API)
+/**
+ * Sample uniformly random coefficients in [-MLDSA_ETA, MLDSA_ETA] by
+ * performing rejection sampling on an array of random bytes.
  *
- * Description: Sample uniformly random coefficients in [-MLDSA_ETA, MLDSA_ETA]
- *by performing rejection sampling on array of random bytes.
+ * @param[out] a      Pointer to output array (allocated).
+ * @param      target Requested number of coefficients to sample.
+ * @param      offset Number of coefficients already sampled.
+ * @param[in]  buf    Array of random bytes to sample from.
+ * @param      buflen Length of array of random bytes.
  *
- * Arguments:   - int32_t *a:          pointer to output array (allocated)
- *              - unsigned int target: requested number of coefficients to
- *sample
- *              - unsigned int offset: number of coefficients already sampled
- *              - const uint8_t *buf:  array of random bytes to sample from
- *              - unsigned int buflen: length of array of random bytes
- *
- * Returns number of sampled coefficients. Can be smaller than target if not
- *enough random bytes were given.
- **************************************************/
+ * @return Number of sampled coefficients. Can be smaller than target if not
+ *         enough random bytes were given.
+ */
 
 /* Reference: `mld_rej_eta()` in the reference implementation @[REF].
  *            - Our signature differs from the reference implementation
@@ -485,12 +463,16 @@ void mld_poly_uniform_eta(mld_poly *r, const uint8_t seed[MLDSA_CRHBYTES],
   mld_zeroize(extseed, sizeof(extseed));
 }
 #endif /* MLD_CONFIG_SERIAL_FIPS202_ONLY */
+#endif /* !MLD_CONFIG_NO_KEYPAIR_API */
 
+#if !defined(MLD_CONFIG_NO_SIGN_API)
 #define MLD_POLY_UNIFORM_GAMMA1_NBLOCKS                       \
   ((MLDSA_POLYZ_PACKEDBYTES + MLD_STREAM256_BLOCKBYTES - 1) / \
    MLD_STREAM256_BLOCKBYTES)
 
-#if MLD_CONFIG_PARAMETER_SET == 65 || defined(MLD_CONFIG_SERIAL_FIPS202_ONLY)
+#if MLD_CONFIG_PARAMETER_SET == 65 ||              \
+    defined(MLD_CONFIG_SERIAL_FIPS202_ONLY) ||     \
+    defined(MLD_CONFIG_REDUCE_RAM) || defined(MLD_UNIT_TEST)
 MLD_INTERNAL_API
 void mld_poly_uniform_gamma1(mld_poly *a, const uint8_t seed[MLDSA_CRHBYTES],
                              uint16_t nonce)
@@ -518,10 +500,12 @@ void mld_poly_uniform_gamma1(mld_poly *a, const uint8_t seed[MLDSA_CRHBYTES],
   mld_zeroize(buf, sizeof(buf));
   mld_zeroize(extseed, sizeof(extseed));
 }
-#endif /* MLD_CONFIG_PARAMETER_SET == 65 || MLD_CONFIG_SERIAL_FIPS202_ONLY */
+#endif /* MLD_CONFIG_PARAMETER_SET == 65 || MLD_CONFIG_SERIAL_FIPS202_ONLY || \
+          MLD_CONFIG_REDUCE_RAM || MLD_UNIT_TEST */
 
 
-#if !defined(MLD_CONFIG_SERIAL_FIPS202_ONLY)
+#if !defined(MLD_CONFIG_SERIAL_FIPS202_ONLY) && \
+    (!defined(MLD_CONFIG_REDUCE_RAM) || defined(MLD_UNIT_TEST))
 MLD_INTERNAL_API
 void mld_poly_uniform_gamma1_4x(mld_poly *r0, mld_poly *r1, mld_poly *r2,
                                 mld_poly *r3,
@@ -570,8 +554,11 @@ void mld_poly_uniform_gamma1_4x(mld_poly *r0, mld_poly *r1, mld_poly *r2,
   mld_zeroize(buf, sizeof(buf));
   mld_zeroize(extseed, sizeof(extseed));
 }
-#endif /* !MLD_CONFIG_SERIAL_FIPS202_ONLY */
+#endif /* !MLD_CONFIG_SERIAL_FIPS202_ONLY && (!MLD_CONFIG_REDUCE_RAM || \
+          MLD_UNIT_TEST) */
+#endif /* !MLD_CONFIG_NO_SIGN_API */
 
+#if !defined(MLD_CONFIG_NO_SIGN_API) || !defined(MLD_CONFIG_NO_VERIFY_API)
 MLD_INTERNAL_API
 void mld_poly_challenge(mld_poly *c, const uint8_t seed[MLDSA_CTILDEBYTES])
 {
@@ -654,7 +641,9 @@ void mld_poly_challenge(mld_poly *c, const uint8_t seed[MLDSA_CTILDEBYTES])
   mld_zeroize(buf, sizeof(buf));
   mld_zeroize(&signs, sizeof(signs));
 }
+#endif /* !MLD_CONFIG_NO_SIGN_API || !MLD_CONFIG_NO_VERIFY_API */
 
+#if !defined(MLD_CONFIG_NO_KEYPAIR_API)
 MLD_INTERNAL_API
 void mld_polyeta_pack(uint8_t r[MLDSA_POLYETA_PACKEDBYTES], const mld_poly *a)
 {
@@ -702,7 +691,9 @@ void mld_polyeta_pack(uint8_t r[MLDSA_POLYETA_PACKEDBYTES], const mld_poly *a)
 #error "Invalid value of MLDSA_ETA"
 #endif /* MLDSA_ETA != 2 && MLDSA_ETA != 4 */
 }
+#endif /* !MLD_CONFIG_NO_KEYPAIR_API */
 
+#if !defined(MLD_CONFIG_NO_KEYPAIR_API) || !defined(MLD_CONFIG_NO_SIGN_API)
 void mld_polyeta_unpack(mld_poly *r, const uint8_t a[MLDSA_POLYETA_PACKEDBYTES])
 {
   unsigned int i;
@@ -751,8 +742,9 @@ void mld_polyeta_unpack(mld_poly *r, const uint8_t a[MLDSA_POLYETA_PACKEDBYTES])
   mld_assert_bound(r->coeffs, MLDSA_N, MLD_POLYETA_UNPACK_LOWER_BOUND,
                    MLDSA_ETA + 1);
 }
+#endif /* !MLD_CONFIG_NO_KEYPAIR_API || !MLD_CONFIG_NO_SIGN_API */
 
-
+#if !defined(MLD_CONFIG_NO_SIGN_API)
 MLD_INTERNAL_API
 void mld_polyz_pack(uint8_t r[MLDSA_POLYZ_PACKEDBYTES], const mld_poly *a)
 {
@@ -805,7 +797,9 @@ void mld_polyz_pack(uint8_t r[MLDSA_POLYZ_PACKEDBYTES], const mld_poly *a)
   }
 #endif /* MLD_CONFIG_PARAMETER_SET != 44 */
 }
+#endif /* !MLD_CONFIG_NO_SIGN_API */
 
+#if !defined(MLD_CONFIG_NO_SIGN_API) || !defined(MLD_CONFIG_NO_VERIFY_API)
 MLD_STATIC_TESTABLE void mld_polyz_unpack_c(
     mld_poly *r, const uint8_t a[MLDSA_POLYZ_PACKEDBYTES])
 __contract__(
@@ -931,6 +925,7 @@ void mld_polyw1_pack(uint8_t r[MLDSA_POLYW1_PACKEDBYTES], const mld_poly *a)
   }
 #endif /* MLD_CONFIG_PARAMETER_SET != 44 */
 }
+#endif /* !MLD_CONFIG_NO_SIGN_API || !MLD_CONFIG_NO_VERIFY_API */
 
 /* To facilitate single-compilation-unit (SCU) builds, undefine all macros. */
 

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

@@ -9,27 +9,23 @@
 #include "common.h"
 #include "poly.h"
 
+#if !defined(MLD_CONFIG_NO_SIGN_API)
 #define mld_poly_decompose MLD_NAMESPACE_KL(poly_decompose)
-/*************************************************
- * Name:        mld_poly_decompose
+/**
+ * For all coefficients c of the input polynomial, compute high and low bits
+ * c0, c1 such c mod MLDSA_Q = c1*ALPHA + c0 with -ALPHA/2 < c0 <= ALPHA/2
+ * except c1 = (MLDSA_Q-1)/ALPHA where we set c1 = 0 and
+ * -ALPHA/2 <= c0 = c mod MLDSA_Q - MLDSA_Q < 0. Assumes coefficients to be
+ * standard representatives.
  *
- * Description: For all coefficients c of the input polynomial,
- *              compute high and low bits c0, c1 such c mod MLDSA_Q = c1*ALPHA +
- *              c0 with -ALPHA/2 < c0 <= ALPHA/2 except
- *              c1 = (MLDSA_Q-1)/ALPHA where we set
- *              c1 = 0 and -ALPHA/2 <= c0 = c mod MLDSA_Q - MLDSA_Q < 0.
- *              Assumes coefficients to be standard representatives.
+ * @reference{The reference implementation has the input polynomial as a
+ * separate argument that may be aliased with either of the outputs. Removing
+ * the aliasing eases CBMC proofs.}
  *
- * Arguments:   - mld_poly *a1: pointer to output polynomial with coefficients
- *                              c1
- *              - mld_poly *a0: pointer to input/output polynomial. Output
- *                              polynomial has coefficients c0
- *
- * Reference: The reference implementation has the input polynomial as a
- *            separate argument that may be aliased with either of the outputs.
- *            Removing the aliasing eases CBMC proofs.
- *
- **************************************************/
+ * @param[out]    a1 Pointer to output polynomial with coefficients c1.
+ * @param[in,out] a0 Pointer to input/output polynomial. Output polynomial has
+ *                   coefficients c0.
+ */
 MLD_INTERNAL_API
 void mld_poly_decompose(mld_poly *a1, mld_poly *a0)
 __contract__(
@@ -42,77 +38,46 @@ __contract__(
   ensures(array_abs_bound(a0->coeffs, 0, MLDSA_N, MLDSA_GAMMA2+1))
 );
 
+#endif /* !MLD_CONFIG_NO_SIGN_API */
 
-#define mld_poly_make_hint MLD_NAMESPACE_KL(poly_make_hint)
-/*************************************************
- * Name:        mld_poly_make_hint
- *
- * Description: Compute hint polynomial. The coefficients of which indicate
- *              whether the low bits of the corresponding coefficient of
- *              the input polynomial overflow into the high bits.
- *
- * Arguments:   - mld_poly *h: pointer to output hint polynomial
- *              - const mld_poly *a0: pointer to low part of input polynomial
- *              - const mld_poly *a1: pointer to high part of input polynomial
- *
- * Returns number of 1 bits.
- **************************************************/
-MLD_INTERNAL_API
-MLD_MUST_CHECK_RETURN_VALUE
-unsigned int mld_poly_make_hint(mld_poly *h, const mld_poly *a0,
-                                const mld_poly *a1)
-__contract__(
-  requires(memory_no_alias(h,  sizeof(mld_poly)))
-  requires(memory_no_alias(a0, sizeof(mld_poly)))
-  requires(memory_no_alias(a1, sizeof(mld_poly)))
-  assigns(memory_slice(h, sizeof(mld_poly)))
-  ensures(return_value <= MLDSA_N)
-  ensures(array_bound(h->coeffs, 0, MLDSA_N, 0, 2))
-);
-
+#if !defined(MLD_CONFIG_NO_VERIFY_API)
 #define mld_poly_use_hint MLD_NAMESPACE_KL(poly_use_hint)
-/*************************************************
- * Name:        mld_poly_use_hint
- *
- * Description: Use hint polynomial to correct the high bits of a polynomial.
+/**
+ * Use hint polynomial h to correct the high bits of a in-place.
  *
- * Arguments:   - mld_poly *b: pointer to output polynomial with corrected high
- *bits
- *              - const mld_poly *a: pointer to input polynomial
- *              - const mld_poly *h: pointer to input hint polynomial
- **************************************************/
+ * @param[in,out] a Input/output polynomial.
+ * @param[in]     h Hint polynomial.
+ */
 MLD_INTERNAL_API
-void mld_poly_use_hint(mld_poly *b, const mld_poly *a, const mld_poly *h)
+void mld_poly_use_hint(mld_poly *a, const mld_poly *h)
 __contract__(
-  requires(memory_no_alias(a,  sizeof(mld_poly)))
-  requires(memory_no_alias(b, sizeof(mld_poly)))
+  requires(memory_no_alias(a, sizeof(mld_poly)))
   requires(memory_no_alias(h, sizeof(mld_poly)))
   requires(array_bound(a->coeffs, 0, MLDSA_N, 0, MLDSA_Q))
   requires(array_bound(h->coeffs, 0, MLDSA_N, 0, 2))
-  assigns(memory_slice(b, sizeof(mld_poly)))
-  ensures(array_bound(b->coeffs, 0, MLDSA_N, 0, (MLDSA_Q-1)/(2*MLDSA_GAMMA2)))
+  assigns(memory_slice(a, sizeof(mld_poly)))
+  ensures(array_bound(a->coeffs, 0, MLDSA_N, 0, (MLDSA_Q-1)/(2*MLDSA_GAMMA2)))
 );
+#endif /* !MLD_CONFIG_NO_VERIFY_API */
 
+#if !defined(MLD_CONFIG_NO_KEYPAIR_API)
 #if !defined(MLD_CONFIG_SERIAL_FIPS202_ONLY)
 #define mld_poly_uniform_eta_4x MLD_NAMESPACE_KL(poly_uniform_eta_4x)
-/*************************************************
- * Name:        mld_poly_uniform_eta
+/**
+ * Sample four polynomials with uniformly random coefficients in
+ * [-MLDSA_ETA, MLDSA_ETA] by performing rejection sampling on the output
+ * stream from SHAKE256(seed|nonce_i).
  *
- * Description: Sample four polynomials with uniformly random coefficients
- *              in [-MLDSA_ETA,MLDSA_ETA] by performing rejection sampling on
- *              the output stream from SHAKE256(seed|nonce_i)
- *
- * Arguments:   - mld_poly *r0: pointer to first output polynomial
- *              - mld_poly *r1: pointer to second output polynomial
- *              - mld_poly *r2: pointer to third output polynomial
- *              - mld_poly *r3: pointer to fourth output polynomial
- *              - const uint8_t seed[]: byte array with seed of length
- *                MLDSA_CRHBYTES
- *              - uint8_t nonce0: first nonce
- *              - uint8_t nonce1: second nonce
- *              - uint8_t nonce2: third nonce
- *              - uint8_t nonce3: fourth nonce
- **************************************************/
+ * @param[out] r0     Pointer to first output polynomial.
+ * @param[out] r1     Pointer to second output polynomial.
+ * @param[out] r2     Pointer to third output polynomial.
+ * @param[out] r3     Pointer to fourth output polynomial.
+ * @param[in]  seed   Byte array with seed of length MLDSA_CRHBYTES.
+ * @param      nonce0 First nonce.
+ * @param      nonce1 Second nonce.
+ * @param      nonce2 Third nonce.
+ * @param      nonce3 Fourth nonce.
+ */
 MLD_INTERNAL_API
 void mld_poly_uniform_eta_4x(mld_poly *r0, mld_poly *r1, mld_poly *r2,
                              mld_poly *r3, const uint8_t seed[MLDSA_CRHBYTES],
@@ -137,18 +102,15 @@ __contract__(
 
 #if defined(MLD_CONFIG_SERIAL_FIPS202_ONLY)
 #define mld_poly_uniform_eta MLD_NAMESPACE_KL(poly_uniform_eta)
-/*************************************************
- * Name:        mld_poly_uniform_eta
+/**
+ * Sample polynomial with uniformly random coefficients in
+ * [-MLDSA_ETA, MLDSA_ETA] by performing rejection sampling on the output
+ * stream from SHAKE256(seed|nonce).
  *
- * Description: Sample polynomial with uniformly random coefficients
- *              in [-MLDSA_ETA,MLDSA_ETA] by performing rejection sampling on
- *              the output stream from SHAKE256(seed|nonce)
- *
- * Arguments:   - mld_poly *r: pointer to output polynomial
- *              - const uint8_t seed[]: byte array with seed of length
- *                MLDSA_CRHBYTES
- *              - uint8_t nonce: nonce
- **************************************************/
+ * @param[out] r     Pointer to output polynomial.
+ * @param[in]  seed  Byte array with seed of length MLDSA_CRHBYTES.
+ * @param      nonce Nonce.
+ */
 MLD_INTERNAL_API
 void mld_poly_uniform_eta(mld_poly *r, const uint8_t seed[MLDSA_CRHBYTES],
                           uint8_t nonce)
@@ -159,21 +121,22 @@ __contract__(
   ensures(array_abs_bound(r->coeffs, 0, MLDSA_N, MLDSA_ETA + 1))
 );
 #endif /* MLD_CONFIG_SERIAL_FIPS202_ONLY */
+#endif /* !MLD_CONFIG_NO_KEYPAIR_API */
 
-#if MLD_CONFIG_PARAMETER_SET == 65 || defined(MLD_CONFIG_SERIAL_FIPS202_ONLY)
+#if !defined(MLD_CONFIG_NO_SIGN_API)
+#if MLD_CONFIG_PARAMETER_SET == 65 ||          \
+    defined(MLD_CONFIG_SERIAL_FIPS202_ONLY) || \
+    defined(MLD_CONFIG_REDUCE_RAM) || defined(MLD_UNIT_TEST)
 #define mld_poly_uniform_gamma1 MLD_NAMESPACE_KL(poly_uniform_gamma1)
-/*************************************************
- * Name:        mld_poly_uniform_gamma1
+/**
+ * Sample polynomial with uniformly random coefficients in
+ * [-(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1] by unpacking output stream of
+ * SHAKE256(seed|nonce).
  *
- * Description: Sample polynomial with uniformly random coefficients
- *              in [-(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1] by unpacking output
- *              stream of SHAKE256(seed|nonce)
- *
- * Arguments:   - mld_poly *a: pointer to output polynomial
- *              - const uint8_t seed[]: byte array with seed of length
- *                MLDSA_CRHBYTES
- *              - uint16_t nonce: 16-bit nonce
- **************************************************/
+ * @param[out] a     Pointer to output polynomial.
+ * @param[in]  seed  Byte array with seed of length MLDSA_CRHBYTES.
+ * @param      nonce 16-bit nonce.
+ */
 MLD_INTERNAL_API
 void mld_poly_uniform_gamma1(mld_poly *a, const uint8_t seed[MLDSA_CRHBYTES],
                              uint16_t nonce)
@@ -183,22 +146,27 @@ __contract__(
   assigns(memory_slice(a, sizeof(mld_poly)))
   ensures(array_bound(a->coeffs, 0, MLDSA_N, -(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1 + 1))
 );
-#endif /* MLD_CONFIG_PARAMETER_SET == 65 || MLD_CONFIG_SERIAL_FIPS202_ONLY */
+#endif /* MLD_CONFIG_PARAMETER_SET == 65 || MLD_CONFIG_SERIAL_FIPS202_ONLY || \
+          MLD_CONFIG_REDUCE_RAM || MLD_UNIT_TEST */
 
-#if !defined(MLD_CONFIG_SERIAL_FIPS202_ONLY)
+#if !defined(MLD_CONFIG_SERIAL_FIPS202_ONLY) && \
+    (!defined(MLD_CONFIG_REDUCE_RAM) || defined(MLD_UNIT_TEST))
 #define mld_poly_uniform_gamma1_4x MLD_NAMESPACE_KL(poly_uniform_gamma1_4x)
-/*************************************************
- * Name:        mld_poly_uniform_gamma1_4x
+/**
+ * Sample four polynomials with uniformly random coefficients in
+ * [-(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1] by unpacking output streams of
+ * SHAKE256(seed|nonce_i).
  *
- * Description: Sample polynomial with uniformly random coefficients
- *              in [-(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1] by unpacking output
- *              stream of SHAKE256(seed|nonce)
- *
- * Arguments:   - mld_poly *a: pointer to output polynomial
- *              - const uint8_t seed[]: byte array with seed of length
- *                MLDSA_CRHBYTES
- *              - uint16_t nonce: 16-bit nonce
- **************************************************/
+ * @param[out] r0     Pointer to first output polynomial.
+ * @param[out] r1     Pointer to second output polynomial.
+ * @param[out] r2     Pointer to third output polynomial.
+ * @param[out] r3     Pointer to fourth output polynomial.
+ * @param[in]  seed   Byte array with seed of length MLDSA_CRHBYTES.
+ * @param      nonce0 First 16-bit nonce.
+ * @param      nonce1 Second 16-bit nonce.
+ * @param      nonce2 Third 16-bit nonce.
+ * @param      nonce3 Fourth 16-bit nonce.
+ */
 MLD_INTERNAL_API
 void mld_poly_uniform_gamma1_4x(mld_poly *r0, mld_poly *r1, mld_poly *r2,
                                 mld_poly *r3,
@@ -220,20 +188,19 @@ __contract__(
   ensures(array_bound(r2->coeffs, 0, MLDSA_N, -(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1 + 1))
   ensures(array_bound(r3->coeffs, 0, MLDSA_N, -(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1 + 1))
 );
-#endif /* !MLD_CONFIG_SERIAL_FIPS202_ONLY */
+#endif /* !MLD_CONFIG_SERIAL_FIPS202_ONLY && (!MLD_CONFIG_REDUCE_RAM || \
+          MLD_UNIT_TEST) */
+#endif /* !MLD_CONFIG_NO_SIGN_API */
 
+#if !defined(MLD_CONFIG_NO_SIGN_API) || !defined(MLD_CONFIG_NO_VERIFY_API)
 #define mld_poly_challenge MLD_NAMESPACE_KL(poly_challenge)
-/*************************************************
- * Name:        mld_poly_challenge
- *
- * Description: Implementation of H. Samples polynomial with MLDSA_TAU nonzero
- *              coefficients in {-1,1} using the output stream of
- *              SHAKE256(seed).
+/**
+ * Implementation of H. Samples polynomial with MLDSA_TAU nonzero coefficients
+ * in {-1, 1} using the output stream of SHAKE256(seed).
  *
- * Arguments:   - mld_poly *c: pointer to output polynomial
- *              - const uint8_t mu[]: byte array containing seed of length
- *                MLDSA_CTILDEBYTES
- **************************************************/
+ * @param[out] c    Pointer to output polynomial.
+ * @param[in]  seed Byte array containing seed of length MLDSA_CTILDEBYTES.
+ */
 MLD_INTERNAL_API
 void mld_poly_challenge(mld_poly *c, const uint8_t seed[MLDSA_CTILDEBYTES])
 __contract__(
@@ -243,17 +210,17 @@ __contract__(
   /* All coefficients of c are -1, 0 or +1 */
   ensures(array_bound(c->coeffs, 0, MLDSA_N, -1, 2))
 );
+#endif /* !MLD_CONFIG_NO_SIGN_API || !MLD_CONFIG_NO_VERIFY_API */
 
+#if !defined(MLD_CONFIG_NO_KEYPAIR_API)
 #define mld_polyeta_pack MLD_NAMESPACE_KL(polyeta_pack)
-/*************************************************
- * Name:        mld_polyeta_pack
+/**
+ * Bit-pack polynomial with coefficients in [-MLDSA_ETA, MLDSA_ETA].
  *
- * Description: Bit-pack polynomial with coefficients in [-MLDSA_ETA,MLDSA_ETA].
- *
- * Arguments:   - uint8_t *r: pointer to output byte array with at least
- *                            MLDSA_POLYETA_PACKEDBYTES bytes
- *              - const mld_poly *a: pointer to input polynomial
- **************************************************/
+ * @param[out] r Pointer to output byte array with at least
+ *               MLDSA_POLYETA_PACKEDBYTES bytes.
+ * @param[in]  a Pointer to input polynomial.
+ */
 MLD_INTERNAL_API
 void mld_polyeta_pack(uint8_t r[MLDSA_POLYETA_PACKEDBYTES], const mld_poly *a)
 __contract__(
@@ -262,12 +229,14 @@ __contract__(
   requires(array_abs_bound(a->coeffs, 0, MLDSA_N, MLDSA_ETA + 1))
   assigns(memory_slice(r, MLDSA_POLYETA_PACKEDBYTES))
 );
+#endif /* !MLD_CONFIG_NO_KEYPAIR_API */
 
+#if !defined(MLD_CONFIG_NO_KEYPAIR_API) || !defined(MLD_CONFIG_NO_SIGN_API)
 /*
- * polyeta_unpack produces coefficients in [-MLDSA_ETA,MLDSA_ETA] for
+ * polyeta_unpack produces coefficients in [-MLDSA_ETA, MLDSA_ETA] for
  * well-formed inputs (i.e., those produced by polyeta_pack).
  * However, when passed an arbitrary byte array, it may produce smaller values,
- * i.e, values in [MLD_POLYETA_UNPACK_LOWER_BOUND,MLDSA_ETA]
+ * i.e., values in [MLD_POLYETA_UNPACK_LOWER_BOUND, MLDSA_ETA].
  * Even though this should never happen, we use use the bound for arbitrary
  * inputs in the CBMC proofs.
  */
@@ -280,14 +249,12 @@ __contract__(
 #endif
 
 #define mld_polyeta_unpack MLD_NAMESPACE_KL(polyeta_unpack)
-/*************************************************
- * Name:        mld_polyeta_unpack
+/**
+ * Unpack polynomial with coefficients in [-MLDSA_ETA, MLDSA_ETA].
  *
- * Description: Unpack polynomial with coefficients in [-MLDSA_ETA,MLDSA_ETA].
- *
- * Arguments:   - mld_poly *r: pointer to output polynomial
- *              - const uint8_t *a: byte array with bit-packed polynomial
- **************************************************/
+ * @param[out] r Pointer to output polynomial.
+ * @param[in]  a Byte array with bit-packed polynomial.
+ */
 MLD_INTERNAL_API
 void mld_polyeta_unpack(mld_poly *r, const uint8_t a[MLDSA_POLYETA_PACKEDBYTES])
 __contract__(
@@ -296,18 +263,18 @@ __contract__(
   assigns(memory_slice(r, sizeof(mld_poly)))
   ensures(array_bound(r->coeffs, 0, MLDSA_N, MLD_POLYETA_UNPACK_LOWER_BOUND, MLDSA_ETA + 1))
 );
+#endif /* !MLD_CONFIG_NO_KEYPAIR_API || !MLD_CONFIG_NO_SIGN_API */
 
+#if !defined(MLD_CONFIG_NO_SIGN_API)
 #define mld_polyz_pack MLD_NAMESPACE_KL(polyz_pack)
-/*************************************************
- * Name:        mld_polyz_pack
- *
- * Description: Bit-pack polynomial with coefficients
- *              in [-(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1].
+/**
+ * Bit-pack polynomial with coefficients in
+ * [-(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1].
  *
- * Arguments:   - uint8_t *r: pointer to output byte array with at least
- *                            MLDSA_POLYZ_PACKEDBYTES bytes
- *              - const mld_poly *a: pointer to input polynomial
- **************************************************/
+ * @param[out] r Pointer to output byte array with at least
+ *               MLDSA_POLYZ_PACKEDBYTES bytes.
+ * @param[in]  a Pointer to input polynomial.
+ */
 MLD_INTERNAL_API
 void mld_polyz_pack(uint8_t r[MLDSA_POLYZ_PACKEDBYTES], const mld_poly *a)
 __contract__(
@@ -316,18 +283,17 @@ __contract__(
   requires(array_bound(a->coeffs, 0, MLDSA_N, -(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1 + 1))
   assigns(memory_slice(r, MLDSA_POLYZ_PACKEDBYTES))
 );
+#endif /* !MLD_CONFIG_NO_SIGN_API */
 
-
+#if !defined(MLD_CONFIG_NO_SIGN_API) || !defined(MLD_CONFIG_NO_VERIFY_API)
 #define mld_polyz_unpack MLD_NAMESPACE_KL(polyz_unpack)
-/*************************************************
- * Name:        mld_polyz_unpack
+/**
+ * Unpack polynomial z with coefficients in
+ * [-(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1].
  *
- * Description: Unpack polynomial z with coefficients
- *              in [-(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1].
- *
- * Arguments:   - mld_poly *r: pointer to output polynomial
- *              - const uint8_t *a: byte array with bit-packed polynomial
- **************************************************/
+ * @param[out] r Pointer to output polynomial.
+ * @param[in]  a Byte array with bit-packed polynomial.
+ */
 MLD_INTERNAL_API
 void mld_polyz_unpack(mld_poly *r, const uint8_t a[MLDSA_POLYZ_PACKEDBYTES])
 __contract__(
@@ -338,16 +304,14 @@ __contract__(
 );
 
 #define mld_polyw1_pack MLD_NAMESPACE_KL(polyw1_pack)
-/*************************************************
- * Name:        mld_polyw1_pack
+/**
+ * Bit-pack polynomial w1 with coefficients in [0, 15] or [0, 43]. Input
+ * coefficients are assumed to be standard representatives.
  *
- * Description: Bit-pack polynomial w1 with coefficients in [0,15] or [0,43].
- *              Input coefficients are assumed to be standard representatives.
- *
- * Arguments:   - uint8_t *r: pointer to output byte array with at least
- *                            MLDSA_POLYW1_PACKEDBYTES bytes
- *              - const mld_poly *a: pointer to input polynomial
- **************************************************/
+ * @param[out] r Pointer to output byte array with at least
+ *               MLDSA_POLYW1_PACKEDBYTES bytes.
+ * @param[in]  a Pointer to input polynomial.
+ */
 MLD_INTERNAL_API
 void mld_polyw1_pack(uint8_t r[MLDSA_POLYW1_PACKEDBYTES], const mld_poly *a)
 __contract__(
@@ -356,5 +320,6 @@ __contract__(
   requires(array_bound(a->coeffs, 0, MLDSA_N, 0, (MLDSA_Q-1)/(2*MLDSA_GAMMA2)))
   assigns(memory_slice(r, MLDSA_POLYW1_PACKEDBYTES))
 );
+#endif /* !MLD_CONFIG_NO_SIGN_API || !MLD_CONFIG_NO_VERIFY_API */
 
 #endif /* !MLD_POLY_KL_H */