pq_crypto 0.6.2 → 0.6.3

data/ext/pqcrypto/vendor/mlkem-native/mlkem/src/randombytes.h

@@ -11,45 +11,37 @@
 
 #if !defined(MLK_CONFIG_NO_RANDOMIZED_API)
 #if !defined(MLK_CONFIG_CUSTOM_RANDOMBYTES)
-/*************************************************
- * Name:        randombytes
+/**
+ * Fill a buffer with cryptographically secure random bytes.
  *
- * Description: Fill a buffer with cryptographically secure random bytes.
+ * mlkem-native does not provide an implementation of this function.
+ * It must be provided by the consumer.
  *
- *              mlkem-native does not provide an implementation of this
- *              function. It must be provided by the consumer.
+ * To use a custom random byte source with a different name or signature,
+ * set MLK_CONFIG_CUSTOM_RANDOMBYTES and define mlk_randombytes directly.
  *
- *              To use a custom random byte source with a different name
- *              or signature, set MLK_CONFIG_CUSTOM_RANDOMBYTES and define
- *              mlk_randombytes directly.
+ * @param[out] out    Output buffer.
+ * @param      outlen Number of random bytes to write.
  *
- * Arguments:   - uint8_t *out: pointer to output buffer
- *              - size_t outlen: number of random bytes to write
- *
- * Returns:     0 on success, non-zero on failure.
- *              On failure, top-level APIs return MLK_ERR_RNG_FAIL.
- *
- **************************************************/
+ * @retval 0     Success.
+ * @retval other Failure; top-level APIs propagate this as MLK_ERR_RNG_FAIL.
+ */
 int randombytes(uint8_t *out, size_t outlen);
 
-/*************************************************
- * Name:        mlk_randombytes
+/**
+ * Internal wrapper around randombytes().
  *
- * Description: Internal wrapper around randombytes().
+ * Fills a buffer with cryptographically secure random bytes.
  *
- *              Fill a buffer with cryptographically secure random bytes.
+ * This function can be replaced by setting MLK_CONFIG_CUSTOM_RANDOMBYTES
+ * and defining mlk_randombytes directly.
  *
- *              This function can be replaced by setting
- *              MLK_CONFIG_CUSTOM_RANDOMBYTES and defining mlk_randombytes
- *              directly.
+ * @param[out] out    Output buffer.
+ * @param      outlen Number of random bytes to write.
  *
- * Arguments:   - uint8_t *out: pointer to output buffer
- *              - size_t outlen: number of random bytes to write
- *
- * Returns:     0 on success, non-zero on failure.
- *              On failure, top-level APIs return MLK_ERR_RNG_FAIL.
- *
- **************************************************/
+ * @retval 0     Success.
+ * @retval other Failure; top-level APIs propagate this as MLK_ERR_RNG_FAIL.
+ */
 MLK_MUST_CHECK_RETURN_VALUE
 static MLK_INLINE int mlk_randombytes(uint8_t *out, size_t outlen)
 __contract__(

data/ext/pqcrypto/vendor/mlkem-native/mlkem/src/sampling.c

@@ -23,6 +23,7 @@
 #include "debug.h"
 #include "sampling.h"
 #include "symmetric.h"
+#include "verify.h"
 
 /* Reference: `rej_uniform()` in the reference implementation @[REF].
  *            - Our signature differs from the reference implementation
@@ -53,10 +54,18 @@ __contract__(
   while (ctr < target && pos + 3 <= buflen)
   __loop__(
     invariant(offset <= ctr && ctr <= target && pos <= buflen)
-    invariant(array_bound(r, 0, ctr, 0, MLKEM_Q)))
+    invariant(array_bound(r, 0, ctr, 0, MLKEM_Q))
+    decreases(buflen - pos))
   {
-    val0 = ((buf[pos + 0] >> 0) | (buf[pos + 1] << 8)) & 0xFFF;
-    val1 = ((buf[pos + 1] >> 4) | (buf[pos + 2] << 4)) & 0xFFF;
+    /* Safety:
+     * - The explicit cast to uint16_t ensures that << 8 does
+     *   not signed-overflow even on a 16-bit system.
+     * - The conversion to int16_t is safe due to the explicit 0xFFF
+     *   truncation.
+     */
+    val0 = (int16_t)(((buf[pos + 0] >> 0) | ((uint16_t)buf[pos + 1] << 8)) &
+                     0xFFF);
+    val1 = (int16_t)(((buf[pos + 1] >> 4) | (buf[pos + 2] << 4)) & 0xFFF);
     pos += 3;
 
     if (val0 < MLKEM_Q)
@@ -73,42 +82,36 @@ __contract__(
   return ctr;
 }
 
-/*************************************************
- * Name:        mlk_rej_uniform
+/**
+ * Run rejection sampling on uniform random bytes to generate uniform random
+ * integers mod MLKEM_Q.
  *
- * Description: Run rejection sampling on uniform random bytes to generate
- *              uniform random integers mod q
+ * @reference{`rej_uniform()` in the reference implementation @[REF]. Our
+ * signature differs from the reference in that it adds the offset and always
+ * expects the base of the target buffer; this avoids shifting the buffer
+ * base in the caller, which is tricky to reason about. Has an optional
+ * fallback to a native implementation.}
  *
- * Arguments:   - int16_t *r:          pointer to output buffer
- *              - unsigned target:     requested number of 16-bit integers
- *                                     (uniform mod q).
- *                                     Must be <= 4096.
- *              - unsigned offset:     number of 16-bit integers that have
- *                                     already been sampled.
- *                                     Must be <= target.
- *              - const uint8_t *buf:  pointer to input buffer
- *                                     (assumed to be uniform random bytes)
- *              - unsigned buflen:     length of input buffer in bytes
- *                                     Must be <= 4096.
- *                                     Must be a multiple of 3.
+ * @param[out] r      Output buffer.
+ * @param      target Requested number of 16-bit integers (uniform mod MLKEM_Q).
+ *                    Must be <= 4096.
+ * @param      offset Number of 16-bit integers that have already been
+ *                    sampled. Must be <= @p target.
+ * @param[in]  buf    Input buffer (assumed to be uniform random bytes).
+ * @param      buflen Length of input buffer in bytes. Must be <= 4096 and a
+ *                    multiple of 3.
  *
- * Note: Strictly speaking, only a few values of buflen near UINT_MAX need
- * excluding. The limit of 4096 is somewhat arbitrary but sufficient for all
- * uses of this function. Similarly, the actual limit for target is UINT_MAX/2.
+ * @note Strictly speaking, only a few values of @p buflen near UINT_MAX need
+ *       excluding. The limit of 4096 is somewhat arbitrary but sufficient
+ *       for all uses of this function. Similarly, the actual limit for
+ *       @p target is UINT_MAX/2.
  *
- * Returns the new offset of sampled 16-bit integers, at most target,
- * and at least the initial offset.
- * If the new offset is strictly less than len, all of the input buffers
- * is guaranteed to have been consumed. If it is equal to len, no information
- * is provided on how many bytes of the input buffer have been consumed.
- **************************************************/
-
-/* Reference: `rej_uniform()` in the reference implementation @[REF].
- *            - Our signature differs from the reference implementation
- *              in that it adds the offset and always expects the base of the
- *              target buffer. This avoids shifting the buffer base in the
- *              caller, which appears tricky to reason about.
- *            - Optional fallback to native implementation. */
+ * @return New offset of sampled 16-bit integers, at most @p target and at
+ *         least the initial @p offset. If the new offset is strictly less
+ *         than @p target, the entire input buffer is guaranteed to have been
+ *         consumed; otherwise no information is provided on how many bytes
+ *         of the input buffer have been consumed.
+ */
 static unsigned mlk_rej_uniform(int16_t *r, unsigned target, unsigned offset,
                                 const uint8_t *buf, unsigned buflen)
 __contract__(
@@ -248,19 +251,15 @@ void mlk_poly_rej_uniform(mlk_poly *entry, uint8_t seed[MLKEM_SYMBYTES + 2])
   mlk_zeroize(buf, sizeof(buf));
 }
 
-/*************************************************
- * Name:        mlk_load32_littleendian
+/**
+ * Load 4 bytes into a 32-bit integer in little-endian order.
  *
- * Description: load 4 bytes into a 32-bit integer
- *              in little-endian order
+ * @reference{`load32_littleendian()` in the reference implementation @[REF].}
  *
- * Arguments:   - const uint8_t *x: pointer to input byte array
+ * @param[in] x Input byte array.
  *
- * Returns 32-bit unsigned integer loaded from x
- *
- **************************************************/
-
-/* Reference: `load32_littleendian()` in the reference implementation @[REF]. */
+ * @return 32-bit unsigned integer loaded from @p x.
+ */
 static uint32_t mlk_load32_littleendian(const uint8_t x[4])
 {
   uint32_t r;
@@ -279,7 +278,8 @@ void mlk_poly_cbd2(mlk_poly *r, const uint8_t buf[2 * MLKEM_N / 4])
   for (i = 0; i < MLKEM_N / 8; i++)
   __loop__(
     invariant(i <= MLKEM_N / 8)
-    invariant(array_abs_bound(r->coeffs, 0, 8 * i, 3)))
+    invariant(array_abs_bound(r->coeffs, 0, 8 * i, 3))
+    decreases(MLKEM_N / 8 - i))
   {
     unsigned j;
     uint32_t t = mlk_load32_littleendian(buf + 4 * i);
@@ -289,30 +289,31 @@ void mlk_poly_cbd2(mlk_poly *r, const uint8_t buf[2 * MLKEM_N / 4])
     for (j = 0; j < 8; j++)
     __loop__(
       invariant(i <= MLKEM_N / 8 && j <= 8)
-      invariant(array_abs_bound(r->coeffs, 0, 8 * i + j, 3)))
+      invariant(array_abs_bound(r->coeffs, 0, 8 * i + j, 3))
+      decreases(8 - j))
     {
-      const int16_t a = (d >> (4 * j + 0)) & 0x3;
-      const int16_t b = (d >> (4 * j + 2)) & 0x3;
+      /* Safety: The & 0x3 masks each value to 2 bits (range [0, 3]), so the
+       * truncation and subsequent subtraction in int16_t is lossless. */
+      const int16_t a = (int16_t)((d >> (4 * j + 0)) & 0x3);
+      const int16_t b = (int16_t)((d >> (4 * j + 2)) & 0x3);
       r->coeffs[8 * i + j] = (int16_t)(a - b);
     }
   }
 }
 
 #if defined(MLK_CONFIG_MULTILEVEL_WITH_SHARED) || MLKEM_ETA1 == 3
-/*************************************************
- * Name:        mlk_load24_littleendian
+/**
+ * Load 3 bytes into a 32-bit integer in little-endian order.
  *
- * Description: load 3 bytes into a 32-bit integer
- *              in little-endian order.
- *              This function is only needed for ML-KEM-512
+ * This function is only needed for ML-KEM-512.
  *
- * Arguments:   - const uint8_t *x: pointer to input byte array
+ * @reference{`load24_littleendian()` in the reference implementation @[REF].}
  *
- * Returns 32-bit unsigned integer loaded from x (most significant byte is zero)
+ * @param[in] x Input byte array.
  *
- **************************************************/
-
-/* Reference: `load24_littleendian()` in the reference implementation @[REF]. */
+ * @return 32-bit unsigned integer loaded from @p x (most significant byte
+ *         is zero).
+ */
 static uint32_t mlk_load24_littleendian(const uint8_t x[3])
 {
   uint32_t r;
@@ -330,7 +331,8 @@ void mlk_poly_cbd3(mlk_poly *r, const uint8_t buf[3 * MLKEM_N / 4])
   for (i = 0; i < MLKEM_N / 4; i++)
   __loop__(
     invariant(i <= MLKEM_N / 4)
-    invariant(array_abs_bound(r->coeffs, 0, 4 * i, 4)))
+    invariant(array_abs_bound(r->coeffs, 0, 4 * i, 4))
+    decreases(MLKEM_N / 4 - i))
   {
     unsigned j;
     const uint32_t t = mlk_load24_littleendian(buf + 3 * i);
@@ -341,10 +343,13 @@ void mlk_poly_cbd3(mlk_poly *r, const uint8_t buf[3 * MLKEM_N / 4])
     for (j = 0; j < 4; j++)
     __loop__(
       invariant(i <= MLKEM_N / 4 && j <= 4)
-      invariant(array_abs_bound(r->coeffs, 0, 4 * i + j, 4)))
+      invariant(array_abs_bound(r->coeffs, 0, 4 * i + j, 4))
+      decreases(4 - j))
     {
-      const int16_t a = (d >> (6 * j + 0)) & 0x7;
-      const int16_t b = (d >> (6 * j + 3)) & 0x7;
+      /* Safety: The & 0x7 masks each value to 3 bits (range [0, 7]), so the
+       * truncation and subsequent subtraction in int16_t is lossless. */
+      const int16_t a = (int16_t)((d >> (6 * j + 0)) & 0x7);
+      const int16_t b = (int16_t)((d >> (6 * j + 3)) & 0x7);
       r->coeffs[4 * i + j] = (int16_t)(a - b);
     }
   }

data/ext/pqcrypto/vendor/mlkem-native/mlkem/src/sampling.h

@@ -20,59 +20,52 @@
 #include "poly.h"
 
 #define mlk_poly_cbd2 MLK_NAMESPACE(poly_cbd2)
-/*************************************************
- * Name:        mlk_poly_cbd2
+/**
+ * Given an array of uniformly random bytes, compute a polynomial with
+ * coefficients distributed according to a centered binomial distribution
+ * with parameter eta=2.
  *
- * Description: Given an array of uniformly random bytes, compute
- *              polynomial with coefficients distributed according to
- *              a centered binomial distribution with parameter eta=2
+ * @spec{Implements @[FIPS203, Algorithm 8, SamplePolyCBD_2].}
  *
- * Arguments:   - mlk_poly *r: pointer to output polynomial
- *              - const uint8_t *buf: pointer to input byte array
- *
- * Specification: Implements @[FIPS203, Algorithm 8, SamplePolyCBD_2]
- *
- **************************************************/
+ * @param[out] r   Output polynomial.
+ * @param[in]  buf Input byte array.
+ */
 MLK_INTERNAL_API
 void mlk_poly_cbd2(mlk_poly *r, const uint8_t buf[2 * MLKEM_N / 4]);
 
 #if defined(MLK_CONFIG_MULTILEVEL_WITH_SHARED) || MLKEM_ETA1 == 3
 #define mlk_poly_cbd3 MLK_NAMESPACE(poly_cbd3)
-/*************************************************
- * Name:        mlk_poly_cbd3
- *
- * Description: Given an array of uniformly random bytes, compute
- *              polynomial with coefficients distributed according to
- *              a centered binomial distribution with parameter eta=3.
- *              This function is only needed for ML-KEM-512
+/**
+ * Given an array of uniformly random bytes, compute a polynomial with
+ * coefficients distributed according to a centered binomial distribution
+ * with parameter eta=3.
  *
- * Arguments:   - mlk_poly *r: pointer to output polynomial
- *              - const uint8_t *buf: pointer to input byte array
+ * This function is only needed for ML-KEM-512.
  *
- * Specification: Implements @[FIPS203, Algorithm 8, SamplePolyCBD_3]
+ * @spec{Implements @[FIPS203, Algorithm 8, SamplePolyCBD_3].}
  *
- **************************************************/
+ * @param[out] r   Output polynomial.
+ * @param[in]  buf Input byte array.
+ */
 MLK_INTERNAL_API
 void mlk_poly_cbd3(mlk_poly *r, const uint8_t buf[3 * MLKEM_N / 4]);
 #endif /* MLK_CONFIG_MULTILEVEL_WITH_SHARED || MLKEM_ETA1 == 3 */
 
 #if !defined(MLK_CONFIG_SERIAL_FIPS202_ONLY)
 #define mlk_poly_rej_uniform_x4 MLK_NAMESPACE(poly_rej_uniform_x4)
-/*************************************************
- * Name:        mlk_poly_rej_uniform_x4
- *
- * Description: Generate four polynomials using rejection sampling
- *              on (pseudo-)uniformly random bytes sampled from a seed.
- *
- * Arguments:   - mlk_poly *vec0, *vec1, *vec2, *vec3:
- *                Pointers to 4 polynomials to be sampled.
- *              - uint8_t seed[4][MLK_ALIGN_UP(MLKEM_SYMBYTES + 2)]:
- *                Pointer consecutive array of seed buffers of size
- *                MLKEM_SYMBYTES + 2 each, plus padding for alignment.
- *
- * Specification: Implements @[FIPS203, Algorithm 7, SampleNTT]
- *
- **************************************************/
+/**
+ * Generate four polynomials using rejection sampling on (pseudo-)uniformly
+ * random bytes sampled from a seed.
+ *
+ * @spec{Implements @[FIPS203, Algorithm 7, SampleNTT].}
+ *
+ * @param[out] vec0 Polynomial to be sampled.
+ * @param[out] vec1 Polynomial to be sampled.
+ * @param[out] vec2 Polynomial to be sampled.
+ * @param[out] vec3 Polynomial to be sampled.
+ * @param[in]  seed Consecutive array of 4 seed buffers of size
+ *                  MLKEM_SYMBYTES + 2 each, plus padding for alignment.
+ */
 MLK_INTERNAL_API
 void mlk_poly_rej_uniform_x4(mlk_poly *vec0, mlk_poly *vec1, mlk_poly *vec2,
                              mlk_poly *vec3,
@@ -94,19 +87,15 @@ __contract__(
 #endif /* !MLK_CONFIG_SERIAL_FIPS202_ONLY */
 
 #define mlk_poly_rej_uniform MLK_NAMESPACE(poly_rej_uniform)
-/*************************************************
- * Name:        mlk_poly_rej_uniform
+/**
+ * Generate a polynomial using rejection sampling on (pseudo-)uniformly
+ * random bytes sampled from a seed.
  *
- * Description: Generate polynomial using rejection sampling
- *              on (pseudo-)uniformly random bytes sampled from a seed.
+ * @spec{Implements @[FIPS203, Algorithm 7, SampleNTT].}
  *
- * Arguments:   - mlk_poly *vec:           Pointer to polynomial to be sampled.
- *              - uint8_t *seed:       Pointer to seed buffer of size
- *                                     MLKEM_SYMBYTES + 2 each.
- *
- * Specification: Implements @[FIPS203, Algorithm 7, SampleNTT]
- *
- **************************************************/
+ * @param[out] entry Polynomial to be sampled.
+ * @param[in]  seed  Seed buffer of size MLKEM_SYMBYTES + 2.
+ */
 MLK_INTERNAL_API
 void mlk_poly_rej_uniform(mlk_poly *entry, uint8_t seed[MLKEM_SYMBYTES + 2])
 __contract__(

data/ext/pqcrypto/vendor/mlkem-native/mlkem/src/sys.h

@@ -47,12 +47,13 @@
 #define MLK_SYS_ARMV81M_MVE
 #endif
 
-#if defined(__x86_64__)
+/* Check if we're running on an x86_64 system. */
+#if defined(__x86_64__) || defined(_M_X64) || defined(_M_AMD64)
 #define MLK_SYS_X86_64
 #if defined(__AVX2__)
 #define MLK_SYS_X86_64_AVX2
 #endif
-#endif /* __x86_64__ */
+#endif /* __x86_64__ || _M_X64 || _M_AMD64 */
 
 #if defined(MLK_SYS_LITTLE_ENDIAN) && defined(__powerpc64__)
 #define MLK_SYS_PPC64LE
@@ -146,6 +147,22 @@
 #endif
 #endif /* !MLK_ALWAYS_INLINE */
 
+/*
+ * MLK_NOINLINE: Prevent inlining.
+ * - MSVC: __declspec(noinline)
+ * - GCC/Clang: __attribute__((noinline))
+ * - Other: empty
+ */
+#if !defined(MLK_NOINLINE)
+#if defined(_MSC_VER)
+#define MLK_NOINLINE __declspec(noinline)
+#elif defined(__GNUC__) || defined(__clang__)
+#define MLK_NOINLINE __attribute__((noinline))
+#else
+#define MLK_NOINLINE
+#endif
+#endif /* !MLK_NOINLINE */
+
 #ifndef MLK_STATIC_TESTABLE
 #define MLK_STATIC_TESTABLE static
 #endif
@@ -226,6 +243,31 @@
 #define MLK_MUST_CHECK_RETURN_VALUE
 #endif
 
+/* The x86_64 assembly backend uses the SysV calling convention. On Windows,
+ * where the Microsoft x64 calling convention is the default, it can still be
+ * used with compilers that allow choosing the calling convention per
+ * function: GCC and Clang support __attribute__((sysv_abi)), which makes
+ * calls to the annotated function follow the SysV calling convention.
+ *
+ * MLK_SYSV_ABI_SUPPORTED signals that the toolchain can call SysV assembly
+ * routines; the x86_64 assembly backend is only enabled if it is defined.
+ * MLK_SYSV_ABI is the attribute carried by declarations of x86_64 assembly
+ * routines. Both macros can be set externally for toolchains offering an
+ * equivalent mechanism that is not recognized here. */
+#if defined(MLK_SYS_X86_64) && !defined(MLK_SYSV_ABI_SUPPORTED)
+#if !defined(MLK_SYS_WINDOWS) || defined(__GNUC__) || defined(__clang__)
+#define MLK_SYSV_ABI_SUPPORTED
+#endif
+#endif
+
+#if !defined(MLK_SYSV_ABI)
+#if defined(MLK_SYS_WINDOWS) && defined(MLK_SYSV_ABI_SUPPORTED)
+#define MLK_SYSV_ABI __attribute__((sysv_abi))
+#else
+#define MLK_SYSV_ABI
+#endif
+#endif /* !MLK_SYSV_ABI */
+
 #if !defined(__ASSEMBLER__)
 /* System capability enumeration */
 typedef enum