pq_crypto 0.6.1 → 0.6.3

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

@@ -55,26 +55,25 @@
 #define mlk_kem_check_pk MLK_NAMESPACE_K(check_pk) MLK_CONTEXT_PARAMETERS_1
 #define mlk_kem_check_sk MLK_NAMESPACE_K(check_sk) MLK_CONTEXT_PARAMETERS_1
 
-/*************************************************
- * Name:        mlk_kem_check_pk
+/**
+ * Implements modulus check mandated by FIPS 203, i.e., ensures that
+ * coefficients are in [0,q-1].
  *
- * Description: Implements modulus check mandated by FIPS 203,
- *              i.e., ensures that coefficients are in [0,q-1].
+ * @spec{Implements @[FIPS203, Section 7.2, 'modulus check'].}
  *
- * Arguments:   - const uint8_t *pk: pointer to input public key
- *                (an already allocated array of MLKEM_INDCCA_PUBLICKEYBYTES
- *                 bytes)
+ * @reference{Not implemented in the reference implementation @[REF].}
  *
- * Returns: - 0 on success
- *          - MLK_ERR_FAIL: If the modulus check failed.
- *          - MLK_ERR_OUT_OF_MEMORY: If MLK_CONFIG_CUSTOM_ALLOC_FREE is
- *              used and an allocation via MLK_CUSTOM_ALLOC returned NULL.
+ * @param[in] pk      Input public key (an already allocated array of
+ *                    MLKEM_INDCCA_PUBLICKEYBYTES bytes).
+ * @param     context Application context. Only present when
+ *                    MLK_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                    MLK_CONFIG_CONTEXT_PARAMETER_TYPE.
  *
- * Specification: Implements @[FIPS203, Section 7.2, 'modulus check']
- *
- **************************************************/
-
-/* Reference: Not implemented in the reference implementation @[REF]. */
+ * @retval 0                     Success.
+ * @retval MLK_ERR_FAIL          Modulus check failed.
+ * @retval MLK_ERR_OUT_OF_MEMORY MLK_CONFIG_CUSTOM_ALLOC_FREE was used and
+ *                               MLK_CUSTOM_ALLOC returned NULL.
+ */
 MLK_EXTERNAL_API
 MLK_MUST_CHECK_RETURN_VALUE
 int mlk_kem_check_pk(const uint8_t pk[MLKEM_INDCCA_PUBLICKEYBYTES],
@@ -86,27 +85,25 @@ __contract__(
 );
 
 
-/*************************************************
- * Name:        mlk_kem_check_sk
+/**
+ * Implements public key hash check mandated by FIPS 203, i.e., ensures that
+ * sk[768𝑘+32 ∶ 768𝑘+64] = H(pk) = H(sk[384𝑘 : 768𝑘+32]).
  *
- * Description: Implements public key hash check mandated by FIPS 203,
- *              i.e., ensures that
- *              sk[768𝑘+32 ∶ 768𝑘+64] = H(pk)= H(sk[384𝑘 : 768𝑘+32])
+ * @spec{Implements @[FIPS203, Section 7.3, 'hash check'].}
  *
- * Arguments:   - const uint8_t *sk: pointer to input private key
- *                (an already allocated array of MLKEM_INDCCA_SECRETKEYBYTES
- *                 bytes)
+ * @reference{Not implemented in the reference implementation @[REF].}
  *
- * Returns: - 0 on success
- *          - MLK_ERR_FAIL: If the public key hash check failed.
- *          - MLK_ERR_OUT_OF_MEMORY: If MLK_CONFIG_CUSTOM_ALLOC_FREE is
- *              used and an allocation via MLK_CUSTOM_ALLOC returned NULL.
+ * @param[in] sk      Input private key (an already allocated array of
+ *                    MLKEM_INDCCA_SECRETKEYBYTES bytes).
+ * @param     context Application context. Only present when
+ *                    MLK_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                    MLK_CONFIG_CONTEXT_PARAMETER_TYPE.
  *
- * Specification: Implements @[FIPS203, Section 7.3, 'hash check']
- *
- **************************************************/
-
-/* Reference: Not implemented in the reference implementation @[REF]. */
+ * @retval 0                     Success.
+ * @retval MLK_ERR_FAIL          Public key hash check failed.
+ * @retval MLK_ERR_OUT_OF_MEMORY MLK_CONFIG_CUSTOM_ALLOC_FREE was used and
+ *                               MLK_CUSTOM_ALLOC returned NULL.
+ */
 MLK_EXTERNAL_API
 MLK_MUST_CHECK_RETURN_VALUE
 int mlk_kem_check_sk(const uint8_t sk[MLKEM_INDCCA_SECRETKEYBYTES],
@@ -117,31 +114,26 @@ __contract__(
           return_value == MLK_ERR_OUT_OF_MEMORY)
 );
 
-/*************************************************
- * Name:        mlk_kem_keypair_derand
- *
- * Description: Generates public and private key
- *              for CCA-secure ML-KEM key encapsulation mechanism
- *
- * Arguments:   - uint8_t *pk: pointer to output public key
- *                (an already allocated array of MLKEM_INDCCA_PUBLICKEYBYTES
- *                 bytes)
- *              - uint8_t *sk: pointer to output private key
- *                (an already allocated array of MLKEM_INDCCA_SECRETKEYBYTES
- *                 bytes)
- *              - uint8_t *coins: pointer to input randomness
- *                (an already allocated array filled with 2*MLKEM_SYMBYTES
- *                 random bytes)
- *
- * Returns:     - 0: On success
- *              - MLK_ERR_FAIL: If MLK_CONFIG_KEYGEN_PCT is enabled and the
- *                  PCT failed.
- *              - MLK_ERR_OUT_OF_MEMORY: If MLK_CONFIG_CUSTOM_ALLOC_FREE is
- *                  used and an allocation via MLK_CUSTOM_ALLOC returned NULL.
- *
- * Specification: Implements @[FIPS203, Algorithm 16, ML-KEM.KeyGen_Internal]
- *
- **************************************************/
+/**
+ * Generate a public/private keypair for the ML-KEM key encapsulation mechanism.
+ *
+ * @spec{Implements @[FIPS203, Algorithm 16, ML-KEM.KeyGen_Internal].}
+ *
+ * @param[out] pk      Output public key (an already allocated array of
+ *                     MLKEM_INDCCA_PUBLICKEYBYTES bytes).
+ * @param[out] sk      Output private key (an already allocated array of
+ *                     MLKEM_INDCCA_SECRETKEYBYTES bytes).
+ * @param[in]  coins   Input randomness (an already allocated array filled
+ *                     with 2*MLKEM_SYMBYTES random bytes).
+ * @param      context Application context. Only present when
+ *                     MLK_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                     MLK_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                     Success.
+ * @retval MLK_ERR_FAIL          MLK_CONFIG_KEYGEN_PCT enabled and PCT failed.
+ * @retval MLK_ERR_OUT_OF_MEMORY MLK_CONFIG_CUSTOM_ALLOC_FREE was used and
+ *                               MLK_CUSTOM_ALLOC returned NULL.
+ */
 MLK_EXTERNAL_API
 MLK_MUST_CHECK_RETURN_VALUE
 int mlk_kem_keypair_derand(uint8_t pk[MLKEM_INDCCA_PUBLICKEYBYTES],
@@ -159,29 +151,25 @@ __contract__(
           return_value == MLK_ERR_RNG_FAIL)
 );
 
-/*************************************************
- * Name:        mlk_kem_keypair
- *
- * Description: Generates public and private key
- *              for CCA-secure ML-KEM key encapsulation mechanism
- *
- * Arguments:   - uint8_t *pk: pointer to output public key
- *                (an already allocated array of MLKEM_INDCCA_PUBLICKEYBYTES
- *                 bytes)
- *              - uint8_t *sk: pointer to output private key
- *                (an already allocated array of MLKEM_INDCCA_SECRETKEYBYTES
- *                 bytes)
- *
- * Returns:     - 0: On success
- *              - MLK_ERR_OUT_OF_MEMORY: If MLK_CONFIG_CUSTOM_ALLOC_FREE is
- *                  used and an allocation via MLK_CUSTOM_ALLOC returned NULL.
- *              - MLK_ERR_RNG_FAIL: Random number generation failed.
- *              - MLK_ERR_FAIL: If MLK_CONFIG_KEYGEN_PCT is enabled and the
- *                  PCT failed.
- *
- * Specification: Implements @[FIPS203, Algorithm 19, ML-KEM.KeyGen]
- *
- **************************************************/
+/**
+ * Generate a public/private keypair for the ML-KEM key encapsulation mechanism.
+ *
+ * @spec{Implements @[FIPS203, Algorithm 19, ML-KEM.KeyGen].}
+ *
+ * @param[out] pk      Output public key (an already allocated array of
+ *                     MLKEM_INDCCA_PUBLICKEYBYTES bytes).
+ * @param[out] sk      Output private key (an already allocated array of
+ *                     MLKEM_INDCCA_SECRETKEYBYTES bytes).
+ * @param      context Application context. Only present when
+ *                     MLK_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                     MLK_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                     Success.
+ * @retval MLK_ERR_OUT_OF_MEMORY MLK_CONFIG_CUSTOM_ALLOC_FREE was used and
+ *                               MLK_CUSTOM_ALLOC returned NULL.
+ * @retval MLK_ERR_RNG_FAIL      Random number generation failed.
+ * @retval MLK_ERR_FAIL          MLK_CONFIG_KEYGEN_PCT enabled and PCT failed.
+ */
 MLK_EXTERNAL_API
 MLK_MUST_CHECK_RETURN_VALUE
 int mlk_kem_keypair(uint8_t pk[MLKEM_INDCCA_PUBLICKEYBYTES],
@@ -197,33 +185,29 @@ __contract__(
           return_value == MLK_ERR_RNG_FAIL)
 );
 
-/*************************************************
- * Name:        mlk_kem_enc_derand
- *
- * Description: Generates cipher text and shared
- *              secret for given public key
- *
- * Arguments:   - uint8_t *ct: pointer to output cipher text
- *                (an already allocated array of MLKEM_INDCCA_CIPHERTEXTBYTES
- *                 bytes)
- *              - uint8_t *ss: pointer to output shared secret
- *                (an already allocated array of MLKEM_SSBYTES bytes)
- *              - const uint8_t *pk: pointer to input public key
- *                (an already allocated array of MLKEM_INDCCA_PUBLICKEYBYTES
- *                 bytes)
- *              - const uint8_t *coins: pointer to input randomness
- *                (an already allocated array filled with MLKEM_SYMBYTES random
- *                 bytes)
- *
- * Returns: - 0 on success
- *          - MLK_ERR_FAIL: If the 'modulus check' @[FIPS203, Section 7.2]
- *              for the public key fails.
- *          - MLK_ERR_OUT_OF_MEMORY: If MLK_CONFIG_CUSTOM_ALLOC_FREE is
- *              used and an allocation via MLK_CUSTOM_ALLOC returned NULL.
- *
- * Specification: Implements @[FIPS203, Algorithm 17, ML-KEM.Encaps_Internal]
- *
- **************************************************/
+/**
+ * Generate ciphertext and shared secret for a given public key.
+ *
+ * @spec{Implements @[FIPS203, Algorithm 17, ML-KEM.Encaps_Internal].}
+ *
+ * @param[out] ct      Output ciphertext (an already allocated array of
+ *                     MLKEM_INDCCA_CIPHERTEXTBYTES bytes).
+ * @param[out] ss      Output shared secret (an already allocated array of
+ *                     MLKEM_SSBYTES bytes).
+ * @param[in]  pk      Input public key (an already allocated array of
+ *                     MLKEM_INDCCA_PUBLICKEYBYTES bytes).
+ * @param[in]  coins   Input randomness (an already allocated array filled
+ *                     with MLKEM_SYMBYTES random bytes).
+ * @param      context Application context. Only present when
+ *                     MLK_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                     MLK_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                     Success.
+ * @retval MLK_ERR_FAIL          The 'modulus check' @[FIPS203, Section 7.2]
+ *                               for the public key failed.
+ * @retval MLK_ERR_OUT_OF_MEMORY MLK_CONFIG_CUSTOM_ALLOC_FREE was used and
+ *                               MLK_CUSTOM_ALLOC returned NULL.
+ */
 MLK_EXTERNAL_API
 MLK_MUST_CHECK_RETURN_VALUE
 int mlk_kem_enc_derand(uint8_t ct[MLKEM_INDCCA_CIPHERTEXTBYTES],
@@ -242,31 +226,28 @@ __contract__(
           return_value == MLK_ERR_OUT_OF_MEMORY)
 );
 
-/*************************************************
- * Name:        mlk_kem_enc
- *
- * Description: Generates cipher text and shared
- *              secret for given public key
- *
- * Arguments:   - uint8_t *ct: pointer to output cipher text
- *                (an already allocated array of MLKEM_INDCCA_CIPHERTEXTBYTES
- *                 bytes)
- *              - uint8_t *ss: pointer to output shared secret
- *                (an already allocated array of MLKEM_SSBYTES bytes)
- *              - const uint8_t *pk: pointer to input public key
- *                (an already allocated array of MLKEM_INDCCA_PUBLICKEYBYTES
- *                 bytes)
- *
- * Returns: - 0 on success
- *          - MLK_ERR_OUT_OF_MEMORY: If MLK_CONFIG_CUSTOM_ALLOC_FREE is
- *              used and an allocation via MLK_CUSTOM_ALLOC returned NULL.
- *          - MLK_ERR_RNG_FAIL: Random number generation failed.
- *          - MLK_ERR_FAIL: If the 'modulus check' @[FIPS203, Section 7.2]
- *              for the public key fails.
- *
- * Specification: Implements @[FIPS203, Algorithm 20, ML-KEM.Encaps]
- *
- **************************************************/
+/**
+ * Generate ciphertext and shared secret for a given public key.
+ *
+ * @spec{Implements @[FIPS203, Algorithm 20, ML-KEM.Encaps].}
+ *
+ * @param[out] ct      Output ciphertext (an already allocated array of
+ *                     MLKEM_INDCCA_CIPHERTEXTBYTES bytes).
+ * @param[out] ss      Output shared secret (an already allocated array of
+ *                     MLKEM_SSBYTES bytes).
+ * @param[in]  pk      Input public key (an already allocated array of
+ *                     MLKEM_INDCCA_PUBLICKEYBYTES bytes).
+ * @param      context Application context. Only present when
+ *                     MLK_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                     MLK_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                     Success.
+ * @retval MLK_ERR_OUT_OF_MEMORY MLK_CONFIG_CUSTOM_ALLOC_FREE was used and
+ *                               MLK_CUSTOM_ALLOC returned NULL.
+ * @retval MLK_ERR_RNG_FAIL      Random number generation failed.
+ * @retval MLK_ERR_FAIL          The 'modulus check' @[FIPS203, Section 7.2]
+ *                               for the public key failed.
+ */
 MLK_EXTERNAL_API
 MLK_MUST_CHECK_RETURN_VALUE
 int mlk_kem_enc(uint8_t ct[MLKEM_INDCCA_CIPHERTEXTBYTES],
@@ -284,30 +265,27 @@ __contract__(
           return_value == MLK_ERR_RNG_FAIL)
 );
 
-/*************************************************
- * Name:        mlk_kem_dec
- *
- * Description: Generates shared secret for given
- *              cipher text and private key
- *
- * Arguments:   - uint8_t *ss: pointer to output shared secret
- *                (an already allocated array of MLKEM_SSBYTES bytes)
- *              - const uint8_t *ct: pointer to input cipher text
- *                (an already allocated array of MLKEM_INDCCA_CIPHERTEXTBYTES
- *                 bytes)
- *              - const uint8_t *sk: pointer to input private key
- *                (an already allocated array of MLKEM_INDCCA_SECRETKEYBYTES
- *                 bytes)
- *
- * Returns: - 0 on success
- *          - MLK_ERR_FAIL: If the 'hash check' @[FIPS203, Section 7.3]
- *              for the secret key fails.
- *          - MLK_ERR_OUT_OF_MEMORY: If MLK_CONFIG_CUSTOM_ALLOC_FREE is
- *              used and an allocation via MLK_CUSTOM_ALLOC returned NULL.
- *
- * Specification: Implements @[FIPS203, Algorithm 21, ML-KEM.Decaps]
- *
- **************************************************/
+/**
+ * Generate shared secret for a given ciphertext and private key.
+ *
+ * @spec{Implements @[FIPS203, Algorithm 21, ML-KEM.Decaps].}
+ *
+ * @param[out] ss      Output shared secret (an already allocated array of
+ *                     MLKEM_SSBYTES bytes).
+ * @param[in]  ct      Input ciphertext (an already allocated array of
+ *                     MLKEM_INDCCA_CIPHERTEXTBYTES bytes).
+ * @param[in]  sk      Input private key (an already allocated array of
+ *                     MLKEM_INDCCA_SECRETKEYBYTES bytes).
+ * @param      context Application context. Only present when
+ *                     MLK_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                     MLK_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                     Success.
+ * @retval MLK_ERR_FAIL          The 'hash check' @[FIPS203, Section 7.3]
+ *                               for the secret key failed.
+ * @retval MLK_ERR_OUT_OF_MEMORY MLK_CONFIG_CUSTOM_ALLOC_FREE was used and
+ *                               MLK_CUSTOM_ALLOC returned NULL.
+ */
 MLK_EXTERNAL_API
 MLK_MUST_CHECK_RETURN_VALUE
 int mlk_kem_dec(uint8_t ss[MLKEM_SSBYTES],

data/ext/pqcrypto/vendor/mlkem-native/mlkem/src/native/aarch64/meta.h

@@ -28,30 +28,30 @@
 MLK_MUST_CHECK_RETURN_VALUE
 static MLK_INLINE int mlk_ntt_native(int16_t data[MLKEM_N])
 {
-  mlk_ntt_asm(data, mlk_aarch64_ntt_zetas_layer12345,
-              mlk_aarch64_ntt_zetas_layer67);
+  mlk_ntt_aarch64_asm(data, mlk_aarch64_ntt_zetas_layer12345,
+                      mlk_aarch64_ntt_zetas_layer67);
   return MLK_NATIVE_FUNC_SUCCESS;
 }
 
 MLK_MUST_CHECK_RETURN_VALUE
 static MLK_INLINE int mlk_intt_native(int16_t data[MLKEM_N])
 {
-  mlk_intt_asm(data, mlk_aarch64_invntt_zetas_layer12345,
-               mlk_aarch64_invntt_zetas_layer67);
+  mlk_intt_aarch64_asm(data, mlk_aarch64_invntt_zetas_layer12345,
+                       mlk_aarch64_invntt_zetas_layer67);
   return MLK_NATIVE_FUNC_SUCCESS;
 }
 
 MLK_MUST_CHECK_RETURN_VALUE
 static MLK_INLINE int mlk_poly_reduce_native(int16_t data[MLKEM_N])
 {
-  mlk_poly_reduce_asm(data);
+  mlk_poly_reduce_aarch64_asm(data);
   return MLK_NATIVE_FUNC_SUCCESS;
 }
 
 MLK_MUST_CHECK_RETURN_VALUE
 static MLK_INLINE int mlk_poly_tomont_native(int16_t data[MLKEM_N])
 {
-  mlk_poly_tomont_asm(data);
+  mlk_poly_tomont_aarch64_asm(data);
   return MLK_NATIVE_FUNC_SUCCESS;
 }
 
@@ -59,8 +59,9 @@ MLK_MUST_CHECK_RETURN_VALUE
 static MLK_INLINE int mlk_poly_mulcache_compute_native(int16_t x[MLKEM_N / 2],
                                                        const int16_t y[MLKEM_N])
 {
-  mlk_poly_mulcache_compute_asm(x, y, mlk_aarch64_zetas_mulcache_native,
-                                mlk_aarch64_zetas_mulcache_twisted_native);
+  mlk_poly_mulcache_compute_aarch64_asm(
+      x, y, mlk_aarch64_zetas_mulcache_native,
+      mlk_aarch64_zetas_mulcache_twisted_native);
   return MLK_NATIVE_FUNC_SUCCESS;
 }
 
@@ -70,7 +71,7 @@ static MLK_INLINE int mlk_polyvec_basemul_acc_montgomery_cached_k2_native(
     int16_t r[MLKEM_N], const int16_t a[2 * MLKEM_N],
     const int16_t b[2 * MLKEM_N], const int16_t b_cache[2 * (MLKEM_N / 2)])
 {
-  mlk_polyvec_basemul_acc_montgomery_cached_asm_k2(r, a, b, b_cache);
+  mlk_polyvec_basemul_acc_montgomery_cached_k2_aarch64_asm(r, a, b, b_cache);
   return MLK_NATIVE_FUNC_SUCCESS;
 }
 #endif /* MLK_CONFIG_MULTILEVEL_WITH_SHARED || MLKEM_K == 2 */
@@ -81,7 +82,7 @@ static MLK_INLINE int mlk_polyvec_basemul_acc_montgomery_cached_k3_native(
     int16_t r[MLKEM_N], const int16_t a[3 * MLKEM_N],
     const int16_t b[3 * MLKEM_N], const int16_t b_cache[3 * (MLKEM_N / 2)])
 {
-  mlk_polyvec_basemul_acc_montgomery_cached_asm_k3(r, a, b, b_cache);
+  mlk_polyvec_basemul_acc_montgomery_cached_k3_aarch64_asm(r, a, b, b_cache);
   return MLK_NATIVE_FUNC_SUCCESS;
 }
 #endif /* MLK_CONFIG_MULTILEVEL_WITH_SHARED || MLKEM_K == 3 */
@@ -92,7 +93,7 @@ static MLK_INLINE int mlk_polyvec_basemul_acc_montgomery_cached_k4_native(
     int16_t r[MLKEM_N], const int16_t a[4 * MLKEM_N],
     const int16_t b[4 * MLKEM_N], const int16_t b_cache[4 * (MLKEM_N / 2)])
 {
-  mlk_polyvec_basemul_acc_montgomery_cached_asm_k4(r, a, b, b_cache);
+  mlk_polyvec_basemul_acc_montgomery_cached_k4_aarch64_asm(r, a, b, b_cache);
   return MLK_NATIVE_FUNC_SUCCESS;
 }
 #endif /* MLK_CONFIG_MULTILEVEL_WITH_SHARED || MLKEM_K == 4 */
@@ -101,7 +102,7 @@ MLK_MUST_CHECK_RETURN_VALUE
 static MLK_INLINE int mlk_poly_tobytes_native(uint8_t r[MLKEM_POLYBYTES],
                                               const int16_t a[MLKEM_N])
 {
-  mlk_poly_tobytes_asm(r, a);
+  mlk_poly_tobytes_aarch64_asm(r, a);
   return MLK_NATIVE_FUNC_SUCCESS;
 }
 
@@ -115,7 +116,8 @@ static MLK_INLINE int mlk_rej_uniform_native(int16_t *r, unsigned len,
   {
     return MLK_NATIVE_FUNC_FALLBACK;
   }
-  return (int)mlk_rej_uniform_asm(r, buf, buflen, mlk_rej_uniform_table);
+  return (int)mlk_rej_uniform_aarch64_asm(r, buf, buflen,
+                                          mlk_rej_uniform_table);
 }
 #endif /* !__ASSEMBLER__ */