pq_crypto 0.6.1 → 0.6.3

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

@@ -137,19 +137,16 @@ __contract__(ensures(return_value == b))
 #pragma CPROVER check push
 #pragma CPROVER check disable "conversion"
 #endif
-/*************************************************
- * Name:        mlk_cast_uint16_to_int16
+/**
+ * Cast uint16 value to int16.
  *
- * Description: Cast uint16 value to int16
+ * @param x Input value.
  *
- * Returns:     For uint16_t x, the unique y in int16_t
- *              so that x == y mod 2^16.
- *
- *              Concretely:
- *              - x <  32768: returns x
- *              - x >= 32768: returns x - 65536
- *
- **************************************************/
+ * @return For uint16_t x, the unique y in int16_t so that x == y mod 2^16.
+ *         Concretely:
+ *         - x <  32768: returns x
+ *         - x >= 32768: returns x - 65536
+ */
 static MLK_ALWAYS_INLINE int16_t mlk_cast_uint16_to_int16(uint16_t x)
 {
   /*
@@ -165,92 +162,96 @@ static MLK_ALWAYS_INLINE int16_t mlk_cast_uint16_to_int16(uint16_t x)
 #pragma CPROVER check pop
 #endif
 
-/*************************************************
- * Name:        mlk_cast_int32_to_uint16
+/**
+ * Cast int32 value to uint16 as per C standard.
  *
- * Description: Cast int32 value to uint16 as per C standard.
+ * @param x Input value.
  *
- * Returns:     For int32_t x, the unique y in uint16_t
- *              so that x == y mod 2^16.
- **************************************************/
+ * @return For int32_t x, the unique y in uint16_t so that x == y mod 2^16.
+ */
 static MLK_ALWAYS_INLINE uint16_t mlk_cast_int32_to_uint16(int32_t x)
 {
   return (uint16_t)(x & (int32_t)UINT16_MAX);
 }
 
-/*************************************************
- * Name:        mlk_cast_int16_to_uint16
+/**
+ * Cast int16 value to uint16 as per C standard.
  *
- * Description: Cast int16 value to uint16 as per C standard.
+ * @param x Input value.
  *
- * Returns:     For int16_t x, the unique y in uint16_t
- *              so that x == y mod 2^16.
- **************************************************/
+ * @return For int16_t x, the unique y in uint16_t so that x == y mod 2^16.
+ */
 static MLK_ALWAYS_INLINE uint16_t mlk_cast_int16_to_uint16(int32_t x)
 {
-  return mlk_cast_int32_to_uint16((int32_t)x);
+  return mlk_cast_int32_to_uint16(x);
 }
 
-/*************************************************
- * Name:        mlk_ct_cmask_neg_i16
+/**
+ * Return 0 if input is non-negative, and -1 otherwise.
  *
- * Description: Return 0 if input is non-negative, and -1 otherwise.
+ * @reference{Embedded in the polynomial compression function in the
+ * reference implementation @[REF]. Used as part of signed->unsigned
+ * conversion for modular representatives to detect whether the input is
+ * negative. This happens in `mlk_poly_reduce()` here, and as part of
+ * polynomial compression functions in the reference implementation. See
+ * `mlk_poly_reduce()`. We use value barriers to reduce the risk of
+ * compiler-introduced branches.}
  *
- * Arguments:   uint16_t x: Value to be converted into a mask
+ * @param x Value to be converted into a mask.
  *
- **************************************************/
-
-/* Reference: Embedded in polynomial compression function in the
- *            reference implementation @[REF].
- *            - Used as part of signed->unsigned conversion for modular
- *              representatives to detect whether the input is negative.
- *              This happen in `mlk_poly_reduce()` here, and as part of
- *              polynomial compression functions in the reference
- *              implementation. See `mlk_poly_reduce()`.
- *            - We use value barriers to reduce the risk of
- *              compiler-introduced branches. */
+ * @return Mask value (0 or 0xFFFF).
+ */
 static MLK_INLINE uint16_t mlk_ct_cmask_neg_i16(int16_t x)
 __contract__(ensures(return_value == ((x < 0) ? 0xFFFF : 0)))
 {
   int32_t tmp = mlk_value_barrier_i32((int32_t)x);
+  /*
+   * PORTABILITY: Right-shift on a signed integer is
+   * implementation-defined for negative left argument.
+   * Here, we assume it's sign-preserving "arithmetic" shift right.
+   * See (C99 6.5.7 (5))
+   */
   tmp >>= 16;
   return mlk_cast_int32_to_uint16(tmp);
 }
 
-/*************************************************
- * Name:        mlk_ct_cmask_nonzero_u16
+/**
+ * Return 0 if input is zero, and -1 otherwise.
  *
- * Description: Return 0 if input is zero, and -1 otherwise.
+ * @reference{Embedded in `cmov_int16()` in the reference implementation
+ * @[REF]. Uses a value barrier and shift instead of `b = -b` to convert
+ * condition into mask.}
  *
- * Arguments:   uint16_t x: Value to be converted into a mask
+ * @param x Value to be converted into a mask.
  *
- **************************************************/
-
-/* Reference: Embedded in `cmov_int16()` in the reference implementation @[REF].
- *            - Use value barrier and shift instead of `b = -b` to
- *              convert condition into mask. */
+ * @return Mask value (0 or 0xFFFF).
+ */
 static MLK_INLINE uint16_t mlk_ct_cmask_nonzero_u16(uint16_t x)
 __contract__(ensures(return_value == ((x == 0) ? 0 : 0xFFFF)))
 {
   int32_t tmp = mlk_value_barrier_i32(-((int32_t)x));
+  /*
+   * PORTABILITY: Right-shift on a signed integer is
+   * implementation-defined for negative left argument.
+   * Here, we assume it's sign-preserving "arithmetic" shift right.
+   * See (C99 6.5.7 (5))
+   */
   tmp >>= 16;
   return mlk_cast_int32_to_uint16(tmp);
 }
 
-/*************************************************
- * Name:        mlk_ct_cmask_nonzero_u8
+/**
+ * Return 0 if input is zero, and -1 otherwise.
  *
- * Description: Return 0 if input is zero, and -1 otherwise.
+ * @reference{Embedded in `verify()` and `cmov()` in the reference
+ * implementation @[REF]. We include a value barrier not present in the
+ * reference implementation, to prevent the compiler from realizing that
+ * this function returns a mask.}
  *
- * Arguments:   uint8_t x: Value to be converted into a mask
+ * @param x Value to be converted into a mask.
  *
- **************************************************/
-
-/* Reference: Embedded in `verify()` and `cmov()` in the
- *            reference implementation @[REF].
- *            - We include a value barrier not present in the
- *              reference implementation, to prevent the compiler
- *              from realizing that this function returns a mask. */
+ * @return Mask value (0 or 0xFF).
+ */
 static MLK_INLINE uint8_t mlk_ct_cmask_nonzero_u8(uint8_t x)
 __contract__(ensures(return_value == ((x == 0) ? 0 : 0xFF)))
 {
@@ -258,39 +259,33 @@ __contract__(ensures(return_value == ((x == 0) ? 0 : 0xFF)))
   return (uint8_t)(mask & 0xFF);
 }
 
-/*************************************************
- * Name:        mlk_ct_sel_int16
- *
- * Description: Functionally equivalent to cond ? a : b,
- *              but implemented with guards against
- *              compiler-introduced branches.
- *
- * Arguments:   int16_t a:       First alternative
- *              int16_t b:       Second alternative
- *              uint16_t cond:   Condition variable.
- *
- * Specification:
- * - With `a = MLKEM_Q_HALF` and `b=0`, this essentially
- *   implements `Decompress_1` @[FIPS203, Eq (4.8)] in `mlk_poly_frommsg()`.
- * - With `a = x + MLKEM_Q`, `b = x`, and `cond` indicating whether `x`
- *   is negative, implements signed->unsigned conversion of modular
- *   representatives. Questions of representation are not considered
- *   in the specification @[FIPS203, Section 2.4.1, "The pseudocode is
- *   agnostic regarding how an integer modulo 𝑚 is represented in
- *   actual implementations"].
- *
- **************************************************/
-
-/* Reference: Embedded in polynomial compression function in the
- *            reference implementation @[REF].
- *            - Used as part of signed->unsigned conversion for modular
- *              representatives. This happen in `mlk_poly_reduce()` here,
- *              and as part of polynomial compression functions in @[REF].
- *              See `mlk_poly_reduce()`.
- *            - Barrier to reduce the risk of compiler-introduced branches.
- *            For `a = MLKEM_Q_HALF` and `b=0`, also embedded in
- *            `poly_frommsg()` from the reference implementation, which uses
- *            `cmov_int16()` instead. */
+/**
+ * Functionally equivalent to cond ? a : b, but implemented with guards
+ * against compiler-introduced branches.
+ *
+ * @spec{With `a = MLKEM_Q_HALF` and `b=0`, this essentially implements
+ * `Decompress_1` @[FIPS203, Eq (4.8)] in `mlk_poly_frommsg()`. With
+ * `a = x + MLKEM_Q`, `b = x`, and `cond` indicating whether `x` is negative,
+ * implements signed->unsigned conversion of modular representatives.
+ * Questions of representation are not considered in the specification
+ * @[FIPS203, Section 2.4.1, "The pseudocode is agnostic regarding how an
+ * integer modulo 𝑚 is represented in actual implementations"].}
+ *
+ * @reference{Embedded in the polynomial compression function in the
+ * reference implementation @[REF]. Used as part of signed->unsigned
+ * conversion for modular representatives. This happens in `mlk_poly_reduce()`
+ * here, and as part of polynomial compression functions in @[REF]. See
+ * `mlk_poly_reduce()`. Barrier to reduce the risk of compiler-introduced
+ * branches. For `a = MLKEM_Q_HALF` and `b=0`, also embedded in
+ * `poly_frommsg()` from the reference implementation, which uses
+ * `cmov_int16()` instead.}
+ *
+ * @param a    First alternative.
+ * @param b    Second alternative.
+ * @param cond Condition variable.
+ *
+ * @return @p a if @p cond != 0, else @p b.
+ */
 static MLK_INLINE int16_t mlk_ct_sel_int16(int16_t a, int16_t b, uint16_t cond)
 __contract__(ensures(return_value == (cond ? a : b)))
 {
@@ -300,53 +295,46 @@ __contract__(ensures(return_value == (cond ? a : b)))
   return mlk_cast_uint16_to_int16(res);
 }
 
-/*************************************************
- * Name:        mlk_ct_sel_uint8
+/**
+ * Functionally equivalent to cond ? a : b, but implemented with guards
+ * against compiler-introduced branches.
  *
- * Description: Functionally equivalent to cond ? a : b,
- *              but implemented with guards against
- *              compiler-introduced branches.
+ * @reference{Embedded into `cmov()` in the reference implementation @[REF].
+ * Uses a value barrier to get mask from condition value.}
  *
- * Arguments:   uint8_t a:       First alternative
- *              uint8_t b:       Second alternative
- *              uuint8_t cond:   Condition variable.
+ * @param a    First alternative.
+ * @param b    Second alternative.
+ * @param cond Condition variable.
  *
- **************************************************/
-
-/* Reference: Embedded into `cmov()` in the reference implementation @[REF].
- *            - Use value barrier to get mask from condition value. */
+ * @return @p a if @p cond != 0, else @p b.
+ */
 static MLK_INLINE uint8_t mlk_ct_sel_uint8(uint8_t a, uint8_t b, uint8_t cond)
 __contract__(ensures(return_value == (cond ? a : b)))
 {
   return b ^ (mlk_ct_cmask_nonzero_u8(cond) & (a ^ b));
 }
 
-/*************************************************
- * Name:        mlk_ct_memcmp
+/**
+ * Compare two arrays for equality in constant time.
  *
- * Description: Compare two arrays for equality in constant time.
+ * @spec{Used to securely compute conditional move in @[FIPS203, Algorithm
+ * 18 (ML-KEM.Decaps_Internal, L9-11].}
  *
- * Arguments:   const uint8_t *a: pointer to first byte array
- *              const uint8_t *b: pointer to second byte array
- *              size_t len:       length of the byte arrays, upper-bounded
- *                                to UINT16_MAX to control proof complexity
- *                                only.
+ * @reference{`cmov()` in the reference implementation @[REF]. We return
+ * `uint8_t`, not `int`. We use an additional XOR-accumulator in the
+ * comparison loop which prevents early abort if the OR-accumulator is 0xFF.
+ * We use a value barrier to convert the OR-accumulator into a mask; the
+ * reference implementation uses a shift which the compiler can argue to
+ * result in either 0 or 0xFF..FF.}
  *
- * Returns 0 if the byte arrays are equal, 0xFF otherwise.
+ * @param[in] a   First byte array.
+ * @param[in] b   Second byte array.
+ * @param     len Length of the byte arrays, upper-bounded to UINT16_MAX to
+ *                control proof complexity only.
  *
- * Specification:
- * - Used to securely compute conditional move in
- *   @[FIPS203, Algorithm 18 (ML-KEM.Decaps_Internal, L9-11]
- *
- **************************************************/
-
-/* Reference: `cmov()` in the reference implementation @[REF]
- *            - We return `uint8_t`, not `int`.
- *            - We use an additional XOR-accumulator in the comparison loop
- *              which prevents early abort if the OR-accumulator is 0xFF.
- *            - We use a value barrier to convert the OR-accumulator into
- *              a mask. The reference implementation uses a shift which the
- *              compiler can argue to result in either 0 of 0xFF..FF. */
+ * @retval 0    The byte arrays are equal.
+ * @retval 0xFF The byte arrays are not equal.
+ */
 static MLK_INLINE uint8_t mlk_ct_memcmp(const uint8_t *a, const uint8_t *b,
                                         const size_t len)
 __contract__(
@@ -362,7 +350,8 @@ __contract__(
   for (i = 0; i < len; i++)
   __loop__(
     invariant(i <= len)
-    invariant((r == 0) == (forall(k, 0, i, (a[k] == b[k])))))
+    invariant((r == 0) == (forall(k, 0, i, (a[k] == b[k]))))
+    decreases(len - i))
   {
     r |= a[i] ^ b[i];
     /* s is useless, but prevents the loop from being aborted once r=0xff. */
@@ -379,32 +368,27 @@ __contract__(
   return (mlk_value_barrier_u8(mlk_ct_cmask_nonzero_u8(r) ^ s) ^ s);
 }
 
-/*************************************************
- * Name:        mlk_ct_cmov_zero
+/**
+ * Copy len bytes from x to r if b is zero; don't modify x if b is non-zero.
+ * Assumes two's complement representation of negative integers. Runs in
+ * constant time.
  *
- * Description: Copy len bytes from x to r if b is zero;
- *              don't modify x if b is non-zero.
- *              assumes two's complement representation of negative integers.
- *              Runs in constant time.
+ * @spec{Used to securely compute conditional move in @[FIPS203, Algorithm
+ * 18 (ML-KEM.Decaps_Internal, L9-11].}
  *
- * Arguments:   uint8_t *r:       pointer to output byte array
- *              const uint8_t *x: pointer to input byte array
- *              size_t len:       Amount of bytes to be copied
- *              uint8_t b:        Condition value.
+ * @reference{`cmov()` in the reference implementation @[REF]. We move if
+ * condition value is `0`, not `1`. We use `mlk_ct_sel_uint8` for
+ * constant-time selection.}
  *
- * Specification:
- * - Used to securely compute conditional move in
- *   @[FIPS203, Algorithm 18 (ML-KEM.Decaps_Internal, L9-11]
- *
- **************************************************/
-
-/* Reference: `cmov()` in the reference implementation @[REF].
- *            - We move if condition value is `0`, not `1`.
- *            - We use `mlk_ct_sel_uint8` for constant-time selection. */
+ * @param[out] r   Output byte array.
+ * @param[in]  x   Input byte array.
+ * @param      len Number of bytes to be copied.
+ * @param      b   Condition value.
+ */
 static MLK_INLINE void mlk_ct_cmov_zero(uint8_t *r, const uint8_t *x,
                                         size_t len, uint8_t b)
 __contract__(
-  requires(len <= MLK_MAX_BUFFER_SIZE)
+  requires(len <= UINT32_MAX)
   requires(memory_no_alias(r, len))
   requires(memory_no_alias(x, len))
   assigns(memory_slice(r, len))
@@ -414,26 +398,24 @@ __contract__(
   for (i = 0; i < len; i++)
   __loop__(
     invariant(i <= len)
-    invariant(forall(k, 0, i, r[k] == (b == 0 ? x[k] : loop_entry(r)[k]))))
+    invariant(forall(k, 0, i, r[k] == (b == 0 ? x[k] : loop_entry(r)[k])))
+    decreases(len - i))
   {
     r[i] = mlk_ct_sel_uint8(r[i], x[i], b);
   }
 }
 
-/*************************************************
- * Name:        mlk_zeroize
+/**
+ * Force-zeroize a buffer.
  *
- * Description: Force-zeroize a buffer.
+ * @spec{Used to implement @[FIPS203, Section 3.3, Destruction of
+ * intermediate values].}
  *
- * Arguments:   uint8_t *r:       pointer to byte array to be zeroed
- *              size_t len:       Amount of bytes to be zeroed
+ * @reference{Not present in the reference implementation @[REF].}
  *
- * Specification: Used to implement
- * @[FIPS203, Section 3.3, Destruction of intermediate values]
- *
- **************************************************/
-
-/* Reference: Not present in the reference implementation @[REF]. */
+ * @param[out] ptr Buffer to be zeroed.
+ * @param      len Number of bytes to be zeroed.
+ */
 #if !defined(MLK_CONFIG_CUSTOM_ZEROIZE)
 #if defined(MLK_SYS_WINDOWS)
 #include <windows.h>

data/lib/pq_crypto/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PQCrypto
-  VERSION = "0.6.1"
+  VERSION = "0.6.3"
 end

data/script/vendor_libs.rb

@@ -13,17 +13,17 @@ MANIFEST_PATH = File.join(VENDOR_DIR, ".vendored")
 PINS = {
   mlkem: {
     repo: "https://github.com/pq-code-package/mlkem-native.git",
-    ref: "v1.1.0",
-    commit: "d2cae2be522a67bfae26100fdb520576f1b2ef90",
-    tree_sha256: "c225de87a69e6d6360cddc4b5839b03e65fa9d5a1112a5f19700c905b7e74512",
+    ref: "v1.2.0",
+    commit: "0ba906cb14b1c241476134d7403a811b382ca498",
+    tree_sha256: "cc78ed199b8c65abe68635b23a13b294d5a8deb20c8bc7b4d76590c00976bb2d",
     target: "mlkem-native",
     source_dir: "mlkem"
   },
   mldsa: {
     repo: "https://github.com/pq-code-package/mldsa-native.git",
-    ref: "v1.0.0-beta",
-    commit: "db65535319d9750d75d34c6d170677415f9d2c46",
-    tree_sha256: "3b2cb648dade4540191f08d606b422042bf781fb37b434934ab02b58a0121f5c",
+    ref: "v1.0.0-beta2",
+    commit: "9b0ee84f4cf399043eca59eca4e5f8531ca1d61b",
+    tree_sha256: "2887f59926c18a877e8c5a5e30727e84497c357032093d00d7135aedf53f011e",
     target: "mldsa-native",
     source_dir: "mldsa"
   }