pq_crypto 0.6.4 → 0.6.6

data/ext/pqcrypto/vendor/mlkem-native/mlkem/mlkem_native.h

@@ -6,6 +6,12 @@
 /* References
  * ==========
  *
+ * - [FIPS140_3_IG]
+ *   Implementation Guidance for FIPS 140-3 and the Cryptographic Module
+ *   Validation Program
+ *   National Institute of Standards and Technology
+ *   https://csrc.nist.gov/projects/cryptographic-module-validation-program/fips-140-3-ig-announcements
+ *
  * - [FIPS203]
  *   FIPS 203 Module-Lattice-Based Key-Encapsulation Mechanism Standard
  *   National Institute of Standards and Technology
@@ -23,6 +29,11 @@
  * Make sure the configuration file is in the include path
  * (this is "mlkem_native_config.h" by default, or MLK_CONFIG_FILE if defined).
  *
+ * # API conventions
+ *
+ * Conventions shared by all functions below (return values, pointer validity,
+ * output buffers on error) are documented in API-CONVENTIONS.md.
+ *
  * # Multi-level builds
  *
  * This header specifies a build of mlkem-native for a fixed security level.
@@ -31,51 +42,15 @@
  * MLK_CONFIG_PARAMETER_SET accordingly for each, and #undef'ing the MLK_H
  * guard to allow multiple inclusions.
  *
- * # Legacy configuration (deprecated)
- *
- * Instead of providing the config file used for the build, you can
- * alternatively set the following configuration options prior to
- * including this header.
- *
- * This method of configuration is deprecated.
- * It will be removed in mlkem-native-v2.
- *
- * - MLK_CONFIG_API_PARAMETER_SET [required]
- *
- *   The parameter set used for the build; 512, 768, or 1024.
- *
- * - MLK_CONFIG_API_NAMESPACE_PREFIX [required]
- *
- *   The namespace prefix used for the build.
- *
- *   NOTE:
- *   For a multi-level build, you must include the 512/768/1024 suffixes
- *   in MLK_CONFIG_API_NAMESPACE_PREFIX.
- *
- * - MLK_CONFIG_API_NO_SUPERCOP [optional]
- *
- *   By default, this header will also expose the mlkem-native API in the
- *   SUPERCOP naming convention crypto_kem_xxx. If you don't want/need this,
- *   set MLK_CONFIG_API_NO_SUPERCOP. You must set this for a multi-level build.
- *
- * - MLK_CONFIG_API_CONSTANTS_ONLY [optional]
- *
- *   If you don't want this header to expose any function declarations,
- *   but only constants for the sizes of key material, set
- *   MLK_CONFIG_API_CONSTANTS_ONLY. In this case, you don't need to set
- *   MLK_CONFIG_API_PARAMETER_SET or MLK_CONFIG_API_NAMESPACE_PREFIX,
- *   nor include a configuration.
- *
- * - MLK_CONFIG_API_QUALIFIER [optional]
- *
- *   Qualifier to apply to external API.
- *
- ******************************************************************************/
+ * In this case, the configuration file must also set
+ * MLK_CONFIG_MULTILEVEL_BUILD. Without it, the parameter set is not appended
+ * to the namespace prefix and all inclusions declare the same symbol names.
+ */
 
 /******************************* Key sizes ************************************/
 
 /* Sizes of cryptographic material, per parameter set */
-/* See mlkem/common.h for the arithmetic expressions giving rise to these */
+/* See mlkem/src/params.h for the arithmetic expressions giving rise to these */
 /* check-magic: off */
 #define MLKEM512_SECRETKEYBYTES 1632
 #define MLKEM512_PUBLICKEYBYTES 800
@@ -111,28 +86,35 @@
 
 /****************************** Error codes ***********************************/
 
-/* Generic failure condition */
+/* Generic failure condition. Currently not returned by any function;
+ * reserved for failures that no more specific code covers. */
 #define MLK_ERR_FAIL (-1)
 /* An allocation failed. This can only happen if MLK_CONFIG_CUSTOM_ALLOC_FREE
  * is defined and the provided MLK_CUSTOM_ALLOC can fail. */
 #define MLK_ERR_OUT_OF_MEMORY (-2)
-/* An rng failure occured. Might be due to insufficient entropy or
+/* An RNG failure occurred. Might be due to insufficient entropy or
  * system misconfiguration. */
 #define MLK_ERR_RNG_FAIL (-3)
-
-/****************************** Function API **********************************/
+/* Public key validation failed: the @[FIPS203, Section 7.2, 'modulus check']
+ * found a coefficient outside [0,q-1]. Returned by check_pk and by the
+ * encapsulation API. */
+#define MLK_ERR_INVALID_PK (-4)
+/* Secret key validation failed: the @[FIPS203, Section 7.3, 'hash check']
+ * found the embedded public key hash inconsistent. Returned by check_sk and
+ * by the decapsulation API. */
+#define MLK_ERR_INVALID_SK (-5)
+/* The 'Pairwise Consistency Test' @[FIPS140_3_IG, p.87] and
+ * @[FIPS203, Section 7.1, Pairwise Consistency] failed. Only possible when
+ * MLK_CONFIG_KEYGEN_PCT is enabled; signals that the freshly generated key
+ * pair failed its encaps/decaps self-test. */
+#define MLK_ERR_PCT_FAIL (-6)
+
+/********************* Namespacing and Qualifiers *****************************/
 
 #define MLK_API_CONCAT_(x, y) x##y
 #define MLK_API_CONCAT(x, y) MLK_API_CONCAT_(x, y)
 #define MLK_API_CONCAT_UNDERSCORE(x, y) MLK_API_CONCAT(MLK_API_CONCAT(x, _), y)
 
-#if !defined(MLK_CONFIG_API_PARAMETER_SET)
-/* Recommended configuration via same config file as used for the build. */
-
-/* For now, we derive the legacy API configuration MLK_CONFIG_API_XXX from
- * the config file. In mlkem-native-v2, this will be removed and we will
- * exclusively work with MLK_CONFIG_XXX. */
-
 /* You need to make sure the config file is in the include path. */
 #if defined(MLK_CONFIG_FILE)
 #include MLK_CONFIG_FILE
@@ -140,35 +122,17 @@
 #include "mlkem_native_config.h"
 #endif
 
-#define MLK_CONFIG_API_PARAMETER_SET MLK_CONFIG_PARAMETER_SET
-
+/* Namespace prefix for the public API symbols. For multi-level builds, the
+ * parameter set is appended to disambiguate the security levels. */
 #if defined(MLK_CONFIG_MULTILEVEL_BUILD)
-#define MLK_CONFIG_API_NAMESPACE_PREFIX \
+#define MLK_API_NAMESPACE_PREFIX \
   MLK_API_CONCAT(MLK_CONFIG_NAMESPACE_PREFIX, MLK_CONFIG_PARAMETER_SET)
 #else
-#define MLK_CONFIG_API_NAMESPACE_PREFIX MLK_CONFIG_NAMESPACE_PREFIX
-#endif
-
-#if defined(MLK_CONFIG_NO_SUPERCOP)
-#define MLK_CONFIG_API_NO_SUPERCOP
-#endif
-
-#if defined(MLK_CONFIG_CONSTANTS_ONLY)
-#define MLK_CONFIG_API_CONSTANTS_ONLY
+#define MLK_API_NAMESPACE_PREFIX MLK_CONFIG_NAMESPACE_PREFIX
 #endif
 
-#if defined(MLK_CONFIG_EXTERNAL_API_QUALIFIER)
-#define MLK_CONFIG_API_QUALIFIER MLK_CONFIG_EXTERNAL_API_QUALIFIER
-#endif
-
-#else /* !MLK_CONFIG_API_PARAMETER_SET */
-
-#define MLK_API_LEGACY_CONFIG
-
-#endif /* MLK_CONFIG_API_PARAMETER_SET */
-
 #define MLK_API_NAMESPACE(sym) \
-  MLK_API_CONCAT_UNDERSCORE(MLK_CONFIG_API_NAMESPACE_PREFIX, sym)
+  MLK_API_CONCAT_UNDERSCORE(MLK_API_NAMESPACE_PREFIX, sym)
 
 #if defined(__GNUC__) || defined(__clang__)
 #define MLK_API_MUST_CHECK_RETURN_VALUE __attribute__((warn_unused_result))
@@ -176,13 +140,15 @@
 #define MLK_API_MUST_CHECK_RETURN_VALUE
 #endif
 
-#if defined(MLK_CONFIG_API_QUALIFIER)
-#define MLK_API_QUALIFIER MLK_CONFIG_API_QUALIFIER
+#if defined(MLK_CONFIG_EXTERNAL_API_QUALIFIER)
+#define MLK_API_QUALIFIER MLK_CONFIG_EXTERNAL_API_QUALIFIER
 #else
 #define MLK_API_QUALIFIER
 #endif
 
-#if !defined(MLK_CONFIG_API_CONSTANTS_ONLY)
+/****************************** Function API **********************************/
+
+#if !defined(MLK_CONFIG_CONSTANTS_ONLY)
 
 #include <stdint.h>
 
@@ -191,6 +157,7 @@ extern "C"
 {
 #endif
 
+#if !defined(MLK_CONFIG_NO_KEYPAIR_API)
 /**
  * Generate a public/private keypair for the ML-KEM key encapsulation mechanism.
  *
@@ -207,15 +174,17 @@ extern "C"
  *                     MLK_CONFIG_CONTEXT_PARAMETER_TYPE.
  *
  * @retval 0                     Success.
- * @retval MLK_ERR_FAIL          MLK_CONFIG_KEYGEN_PCT enabled and PCT failed.
+ * @retval MLK_ERR_PCT_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.
+ * @retval MLK_ERR_RNG_FAIL      MLK_CONFIG_KEYGEN_PCT enabled and random
+ *                               number generation failed within the PCT.
  */
 MLK_API_QUALIFIER
 MLK_API_MUST_CHECK_RETURN_VALUE
 int MLK_API_NAMESPACE(keypair_derand)(
-    uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)],
-    uint8_t sk[MLKEM_SECRETKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)],
+    uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_PARAMETER_SET)],
+    uint8_t sk[MLKEM_SECRETKEYBYTES(MLK_CONFIG_PARAMETER_SET)],
     const uint8_t coins[2 * MLKEM_SYMBYTES]
 #ifdef MLK_CONFIG_CONTEXT_PARAMETER
     ,
@@ -239,7 +208,7 @@ int MLK_API_NAMESPACE(keypair_derand)(
  *                     MLK_CONFIG_CONTEXT_PARAMETER_TYPE.
  *
  * @retval 0                     Success.
- * @retval MLK_ERR_FAIL          MLK_CONFIG_KEYGEN_PCT enabled and PCT failed.
+ * @retval MLK_ERR_PCT_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.
  * @retval MLK_ERR_RNG_FAIL      Random number generation failed.
@@ -247,15 +216,17 @@ int MLK_API_NAMESPACE(keypair_derand)(
 MLK_API_QUALIFIER
 MLK_API_MUST_CHECK_RETURN_VALUE
 int MLK_API_NAMESPACE(keypair)(
-    uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)],
-    uint8_t sk[MLKEM_SECRETKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)]
+    uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_PARAMETER_SET)],
+    uint8_t sk[MLKEM_SECRETKEYBYTES(MLK_CONFIG_PARAMETER_SET)]
 #ifdef MLK_CONFIG_CONTEXT_PARAMETER
     ,
     MLK_CONFIG_CONTEXT_PARAMETER_TYPE context
 #endif
 );
 #endif /* !MLK_CONFIG_NO_RANDOMIZED_API */
+#endif /* !MLK_CONFIG_NO_KEYPAIR_API */
 
+#if !defined(MLK_CONFIG_NO_ENCAPS_API)
 /**
  * Generate ciphertext and shared secret for a given public key.
  *
@@ -272,7 +243,7 @@ int MLK_API_NAMESPACE(keypair)(
  *                     MLK_CONFIG_CONTEXT_PARAMETER_TYPE.
  *
  * @retval 0                     Success.
- * @retval MLK_ERR_FAIL          The 'modulus check' @[FIPS203, Section 7.2]
+ * @retval MLK_ERR_INVALID_PK    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.
@@ -280,9 +251,9 @@ int MLK_API_NAMESPACE(keypair)(
 MLK_API_QUALIFIER
 MLK_API_MUST_CHECK_RETURN_VALUE
 int MLK_API_NAMESPACE(enc_derand)(
-    uint8_t ct[MLKEM_CIPHERTEXTBYTES(MLK_CONFIG_API_PARAMETER_SET)],
+    uint8_t ct[MLKEM_CIPHERTEXTBYTES(MLK_CONFIG_PARAMETER_SET)],
     uint8_t ss[MLKEM_BYTES],
-    const uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)],
+    const uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_PARAMETER_SET)],
     const uint8_t coins[MLKEM_SYMBYTES]
 #ifdef MLK_CONFIG_CONTEXT_PARAMETER
     ,
@@ -306,7 +277,7 @@ int MLK_API_NAMESPACE(enc_derand)(
  *                     MLK_CONFIG_CONTEXT_PARAMETER_TYPE.
  *
  * @retval 0                     Success.
- * @retval MLK_ERR_FAIL          The 'modulus check' @[FIPS203, Section 7.2]
+ * @retval MLK_ERR_INVALID_PK    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.
@@ -315,16 +286,18 @@ int MLK_API_NAMESPACE(enc_derand)(
 MLK_API_QUALIFIER
 MLK_API_MUST_CHECK_RETURN_VALUE
 int MLK_API_NAMESPACE(enc)(
-    uint8_t ct[MLKEM_CIPHERTEXTBYTES(MLK_CONFIG_API_PARAMETER_SET)],
+    uint8_t ct[MLKEM_CIPHERTEXTBYTES(MLK_CONFIG_PARAMETER_SET)],
     uint8_t ss[MLKEM_BYTES],
-    const uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)]
+    const uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_PARAMETER_SET)]
 #ifdef MLK_CONFIG_CONTEXT_PARAMETER
     ,
     MLK_CONFIG_CONTEXT_PARAMETER_TYPE context
 #endif
 );
 #endif /* !MLK_CONFIG_NO_RANDOMIZED_API */
+#endif /* !MLK_CONFIG_NO_ENCAPS_API */
 
+#if !defined(MLK_CONFIG_NO_DECAPS_API)
 /**
  * Generate shared secret for a given ciphertext and private key.
  *
@@ -340,7 +313,7 @@ int MLK_API_NAMESPACE(enc)(
  *                     MLK_CONFIG_CONTEXT_PARAMETER_TYPE.
  *
  * @retval 0                     Success.
- * @retval MLK_ERR_FAIL          The 'hash check' @[FIPS203, Section 7.3]
+ * @retval MLK_ERR_INVALID_SK    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.
@@ -349,13 +322,14 @@ MLK_API_QUALIFIER
 MLK_API_MUST_CHECK_RETURN_VALUE
 int MLK_API_NAMESPACE(dec)(
     uint8_t ss[MLKEM_BYTES],
-    const uint8_t ct[MLKEM_CIPHERTEXTBYTES(MLK_CONFIG_API_PARAMETER_SET)],
-    const uint8_t sk[MLKEM_SECRETKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)]
+    const uint8_t ct[MLKEM_CIPHERTEXTBYTES(MLK_CONFIG_PARAMETER_SET)],
+    const uint8_t sk[MLKEM_SECRETKEYBYTES(MLK_CONFIG_PARAMETER_SET)]
 #ifdef MLK_CONFIG_CONTEXT_PARAMETER
     ,
     MLK_CONFIG_CONTEXT_PARAMETER_TYPE context
 #endif
 );
+#endif /* !MLK_CONFIG_NO_DECAPS_API */
 
 
 /**
@@ -371,19 +345,21 @@ int MLK_API_NAMESPACE(dec)(
  *                    MLK_CONFIG_CONTEXT_PARAMETER_TYPE.
  *
  * @retval 0                     Success.
- * @retval MLK_ERR_FAIL          Modulus check failed.
+ * @retval MLK_ERR_INVALID_PK    Modulus check failed.
  * @retval MLK_ERR_OUT_OF_MEMORY MLK_CONFIG_CUSTOM_ALLOC_FREE was used and
  *                               MLK_CUSTOM_ALLOC returned NULL.
  */
+#if !defined(MLK_CONFIG_NO_ENCAPS_API)
 MLK_API_QUALIFIER
 MLK_API_MUST_CHECK_RETURN_VALUE
 int MLK_API_NAMESPACE(check_pk)(
-    const uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)]
+    const uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_PARAMETER_SET)]
 #ifdef MLK_CONFIG_CONTEXT_PARAMETER
     ,
     MLK_CONFIG_CONTEXT_PARAMETER_TYPE context
 #endif
 );
+#endif /* !MLK_CONFIG_NO_ENCAPS_API */
 
 /**
  * Implements public key hash check mandated by FIPS 203, i.e., ensures that
@@ -398,64 +374,29 @@ int MLK_API_NAMESPACE(check_pk)(
  *                    MLK_CONFIG_CONTEXT_PARAMETER_TYPE.
  *
  * @retval 0                     Success.
- * @retval MLK_ERR_FAIL          Public key hash check failed.
+ * @retval MLK_ERR_INVALID_SK    Public key hash check failed.
  * @retval MLK_ERR_OUT_OF_MEMORY MLK_CONFIG_CUSTOM_ALLOC_FREE was used and
  *                               MLK_CUSTOM_ALLOC returned NULL.
  */
+#if !defined(MLK_CONFIG_NO_DECAPS_API)
 MLK_API_QUALIFIER
 MLK_API_MUST_CHECK_RETURN_VALUE
 int MLK_API_NAMESPACE(check_sk)(
-    const uint8_t sk[MLKEM_SECRETKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)]
+    const uint8_t sk[MLKEM_SECRETKEYBYTES(MLK_CONFIG_PARAMETER_SET)]
 #ifdef MLK_CONFIG_CONTEXT_PARAMETER
     ,
     MLK_CONFIG_CONTEXT_PARAMETER_TYPE context
 #endif
 );
+#endif /* !MLK_CONFIG_NO_DECAPS_API */
 
 #ifdef __cplusplus
 }
 #endif
 
-/****************************** SUPERCOP API *********************************/
-
-#if !defined(MLK_CONFIG_API_NO_SUPERCOP)
-/* Export API in SUPERCOP naming scheme CRYPTO_xxx / crypto_kem_xxx */
-#define CRYPTO_SECRETKEYBYTES MLKEM_SECRETKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)
-#define CRYPTO_PUBLICKEYBYTES MLKEM_PUBLICKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)
-#define CRYPTO_CIPHERTEXTBYTES \
-  MLKEM_CIPHERTEXTBYTES(MLK_CONFIG_API_PARAMETER_SET)
-#define CRYPTO_SYMBYTES MLKEM_SYMBYTES
-#define CRYPTO_BYTES MLKEM_BYTES
-
-#define crypto_kem_keypair_derand MLK_API_NAMESPACE(keypair_derand)
-#define crypto_kem_keypair MLK_API_NAMESPACE(keypair)
-#define crypto_kem_enc_derand MLK_API_NAMESPACE(enc_derand)
-#define crypto_kem_enc MLK_API_NAMESPACE(enc)
-#define crypto_kem_dec MLK_API_NAMESPACE(dec)
-#define crypto_kem_check_pk MLK_API_NAMESPACE(check_pk)
-#define crypto_kem_check_sk MLK_API_NAMESPACE(check_sk)
-
-#else /* !MLK_CONFIG_API_NO_SUPERCOP */
-
-/* If the SUPERCOP API is not needed, we can undefine the various helper macros
- * above. Otherwise, they are needed for lazy evaluation of crypto_kem_xxx. */
-#if !defined(MLK_API_LEGACY_CONFIG)
-#undef MLK_CONFIG_API_PARAMETER_SET
-#undef MLK_CONFIG_API_NAMESPACE_PREFIX
-#undef MLK_CONFIG_API_NO_SUPERCOP
-#undef MLK_CONFIG_API_CONSTANTS_ONLY
-#undef MLK_CONFIG_API_QUALIFIER
-#endif /* !MLK_API_LEGACY_CONFIG */
-
-#undef MLK_API_CONCAT
-#undef MLK_API_CONCAT_
-#undef MLK_API_CONCAT_UNDERSCORE
-#undef MLK_API_NAMESPACE
-#undef MLK_API_MUST_CHECK_RETURN_VALUE
-#undef MLK_API_QUALIFIER
-
-#endif /* MLK_CONFIG_API_NO_SUPERCOP */
-#endif /* !MLK_CONFIG_API_CONSTANTS_ONLY */
+#undef MLK_API_NAMESPACE_PREFIX
+
+#endif /* !MLK_CONFIG_CONSTANTS_ONLY */
 
 
 /***************************** Memory Usage **********************************/
@@ -492,10 +433,8 @@ int MLK_API_NAMESPACE(check_sk)(
 
 /*
  * MLK_TOTAL_ALLOC_*_KEYPAIR adapts based on MLK_CONFIG_KEYGEN_PCT.
- * For legacy config, we don't know which options are used, so assume
- * the worst case (PCT enabled).
  */
-#if defined(MLK_API_LEGACY_CONFIG) || defined(MLK_CONFIG_KEYGEN_PCT)
+#if defined(MLK_CONFIG_KEYGEN_PCT)
 #define MLK_TOTAL_ALLOC_512_KEYPAIR MLK_TOTAL_ALLOC_512_KEYPAIR_PCT
 #define MLK_TOTAL_ALLOC_768_KEYPAIR MLK_TOTAL_ALLOC_768_KEYPAIR_PCT
 #define MLK_TOTAL_ALLOC_1024_KEYPAIR MLK_TOTAL_ALLOC_1024_KEYPAIR_PCT
@@ -522,6 +461,4 @@ int MLK_API_NAMESPACE(check_sk)(
   MLK_MAX3_(MLK_TOTAL_ALLOC_1024_KEYPAIR, MLK_TOTAL_ALLOC_1024_ENCAPS, \
             MLK_TOTAL_ALLOC_1024_DECAPS)
 
-#undef MLK_API_LEGACY_CONFIG
-
 #endif /* !MLK_H */

data/ext/pqcrypto/vendor/mlkem-native/mlkem/mlkem_native_asm.S

@@ -22,7 +22,7 @@
  * levels, you should include this file once with
  * MLK_CONFIG_MULTILEVEL_WITH_SHARED set.
  *
- * (You could also follow the same pattern as for mlkem_native_monobuild.c
+ * (You could also follow the same pattern as for mlkem_native.c
  *  and include it for every level, setting MLK_CONFIG_MULTILEVEL_NO_SHARED
  *  for all but one. For builds with MLK_CONFIG_MULTILEVEL_NO_SHARED, this
  *  file will then be ignored.)
@@ -60,46 +60,46 @@
 
 #if defined(MLK_CONFIG_USE_NATIVE_BACKEND_ARITH)
 #if defined(MLK_SYS_AARCH64)
-#include "src/native/aarch64/src/intt_aarch64_asm.S"
-#include "src/native/aarch64/src/ntt_aarch64_asm.S"
-#include "src/native/aarch64/src/poly_mulcache_compute_aarch64_asm.S"
-#include "src/native/aarch64/src/poly_reduce_aarch64_asm.S"
-#include "src/native/aarch64/src/poly_tobytes_aarch64_asm.S"
-#include "src/native/aarch64/src/poly_tomont_aarch64_asm.S"
-#include "src/native/aarch64/src/polyvec_basemul_acc_montgomery_cached_k2_aarch64_asm.S"
-#include "src/native/aarch64/src/polyvec_basemul_acc_montgomery_cached_k3_aarch64_asm.S"
-#include "src/native/aarch64/src/polyvec_basemul_acc_montgomery_cached_k4_aarch64_asm.S"
-#include "src/native/aarch64/src/rej_uniform_aarch64_asm.S"
+#include "src/native/aarch64/src/mlkem_intt_aarch64_asm.S"
+#include "src/native/aarch64/src/mlkem_ntt_aarch64_asm.S"
+#include "src/native/aarch64/src/mlkem_poly_mulcache_compute_aarch64_asm.S"
+#include "src/native/aarch64/src/mlkem_poly_reduce_aarch64_asm.S"
+#include "src/native/aarch64/src/mlkem_poly_tobytes_aarch64_asm.S"
+#include "src/native/aarch64/src/mlkem_poly_tomont_aarch64_asm.S"
+#include "src/native/aarch64/src/mlkem_polyvec_basemul_acc_montgomery_cached_k2_aarch64_asm.S"
+#include "src/native/aarch64/src/mlkem_polyvec_basemul_acc_montgomery_cached_k3_aarch64_asm.S"
+#include "src/native/aarch64/src/mlkem_polyvec_basemul_acc_montgomery_cached_k4_aarch64_asm.S"
+#include "src/native/aarch64/src/mlkem_rej_uniform_aarch64_asm.S"
 #endif /* MLK_SYS_AARCH64 */
 #if defined(MLK_SYS_X86_64)
-#include "src/native/x86_64/src/intt_avx2_asm.S"
-#include "src/native/x86_64/src/ntt_avx2_asm.S"
-#include "src/native/x86_64/src/nttfrombytes_avx2_asm.S"
-#include "src/native/x86_64/src/ntttobytes_avx2_asm.S"
-#include "src/native/x86_64/src/nttunpack_avx2_asm.S"
-#include "src/native/x86_64/src/poly_compress_d10_avx2_asm.S"
-#include "src/native/x86_64/src/poly_compress_d11_avx2_asm.S"
-#include "src/native/x86_64/src/poly_compress_d4_avx2_asm.S"
-#include "src/native/x86_64/src/poly_compress_d5_avx2_asm.S"
-#include "src/native/x86_64/src/poly_decompress_d10_avx2_asm.S"
-#include "src/native/x86_64/src/poly_decompress_d11_avx2_asm.S"
-#include "src/native/x86_64/src/poly_decompress_d4_avx2_asm.S"
-#include "src/native/x86_64/src/poly_decompress_d5_avx2_asm.S"
-#include "src/native/x86_64/src/poly_mulcache_compute_avx2_asm.S"
-#include "src/native/x86_64/src/polyvec_basemul_acc_montgomery_cached_k2_avx2_asm.S"
-#include "src/native/x86_64/src/polyvec_basemul_acc_montgomery_cached_k3_avx2_asm.S"
-#include "src/native/x86_64/src/polyvec_basemul_acc_montgomery_cached_k4_avx2_asm.S"
-#include "src/native/x86_64/src/reduce_avx2_asm.S"
-#include "src/native/x86_64/src/rej_uniform_avx2_asm.S"
-#include "src/native/x86_64/src/tomont_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_intt_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_ntt_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_nttfrombytes_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_ntttobytes_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_nttunpack_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_poly_compress_d10_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_poly_compress_d11_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_poly_compress_d4_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_poly_compress_d5_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_poly_decompress_d10_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_poly_decompress_d11_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_poly_decompress_d4_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_poly_decompress_d5_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_poly_mulcache_compute_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_polyvec_basemul_acc_montgomery_cached_k2_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_polyvec_basemul_acc_montgomery_cached_k3_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_polyvec_basemul_acc_montgomery_cached_k4_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_reduce_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_rej_uniform_avx2_asm.S"
+#include "src/native/x86_64/src/mlkem_tomont_avx2_asm.S"
 #endif /* MLK_SYS_X86_64 */
 #if defined(MLK_SYS_RISCV64)
 #endif
 #if defined(MLK_SYS_PPC64LE)
-#include "src/native/ppc64le/src/intt_ppc_asm.S"
-#include "src/native/ppc64le/src/ntt_ppc_asm.S"
-#include "src/native/ppc64le/src/poly_tomont_ppc_asm.S"
-#include "src/native/ppc64le/src/reduce_ppc_asm.S"
+#include "src/native/ppc64le/src/mlkem_intt_ppc_asm.S"
+#include "src/native/ppc64le/src/mlkem_ntt_ppc_asm.S"
+#include "src/native/ppc64le/src/mlkem_poly_tomont_ppc_asm.S"
+#include "src/native/ppc64le/src/mlkem_reduce_ppc_asm.S"
 #endif /* MLK_SYS_PPC64LE */
 #endif /* MLK_CONFIG_USE_NATIVE_BACKEND_ARITH */
 
@@ -116,8 +116,8 @@
 #endif
 #if defined(MLK_SYS_ARMV81M_MVE)
 #include "src/fips202/native/armv81m/src/keccak_f1600_x4_mve.S"
-#include "src/fips202/native/armv81m/src/state_extract_bytes_x4_mve.S"
-#include "src/fips202/native/armv81m/src/state_xor_bytes_x4_mve.S"
+#include "src/fips202/native/armv81m/src/keccak_f1600_x4_state_extract_bytes_mve.S"
+#include "src/fips202/native/armv81m/src/keccak_f1600_x4_state_xor_bytes_mve.S"
 #endif
 #endif /* MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202 */
 
@@ -145,11 +145,6 @@
  * Undefine macros from MLK_CONFIG_PARAMETER_SET-specific files
  */
 /* mlkem/mlkem_native.h */
-#undef CRYPTO_BYTES
-#undef CRYPTO_CIPHERTEXTBYTES
-#undef CRYPTO_PUBLICKEYBYTES
-#undef CRYPTO_SECRETKEYBYTES
-#undef CRYPTO_SYMBYTES
 #undef MLKEM1024_BYTES
 #undef MLKEM1024_CIPHERTEXTBYTES
 #undef MLKEM1024_PUBLICKEYBYTES
@@ -176,17 +171,15 @@
 #undef MLK_API_CONCAT
 #undef MLK_API_CONCAT_
 #undef MLK_API_CONCAT_UNDERSCORE
-#undef MLK_API_LEGACY_CONFIG
 #undef MLK_API_MUST_CHECK_RETURN_VALUE
 #undef MLK_API_NAMESPACE
+#undef MLK_API_NAMESPACE_PREFIX
 #undef MLK_API_QUALIFIER
-#undef MLK_CONFIG_API_CONSTANTS_ONLY
-#undef MLK_CONFIG_API_NAMESPACE_PREFIX
-#undef MLK_CONFIG_API_NO_SUPERCOP
-#undef MLK_CONFIG_API_PARAMETER_SET
-#undef MLK_CONFIG_API_QUALIFIER
 #undef MLK_ERR_FAIL
+#undef MLK_ERR_INVALID_PK
+#undef MLK_ERR_INVALID_SK
 #undef MLK_ERR_OUT_OF_MEMORY
+#undef MLK_ERR_PCT_FAIL
 #undef MLK_ERR_RNG_FAIL
 #undef MLK_H
 #undef MLK_MAX3_
@@ -208,13 +201,6 @@
 #undef MLK_TOTAL_ALLOC_768_KEYPAIR
 #undef MLK_TOTAL_ALLOC_768_KEYPAIR_NO_PCT
 #undef MLK_TOTAL_ALLOC_768_KEYPAIR_PCT
-#undef crypto_kem_check_pk
-#undef crypto_kem_check_sk
-#undef crypto_kem_dec
-#undef crypto_kem_enc
-#undef crypto_kem_enc_derand
-#undef crypto_kem_keypair
-#undef crypto_kem_keypair_derand
 /* mlkem/src/common.h */
 #undef MLK_ADD_PARAM_SET
 #undef MLK_ALLOC
@@ -226,14 +212,12 @@
 #undef MLK_COMMON_H
 #undef MLK_CONCAT
 #undef MLK_CONCAT_
-#undef MLK_CONTEXT_PARAMETERS_0
-#undef MLK_CONTEXT_PARAMETERS_1
-#undef MLK_CONTEXT_PARAMETERS_2
-#undef MLK_CONTEXT_PARAMETERS_3
-#undef MLK_CONTEXT_PARAMETERS_4
 #undef MLK_EMPTY_CU
 #undef MLK_ERR_FAIL
+#undef MLK_ERR_INVALID_PK
+#undef MLK_ERR_INVALID_SK
 #undef MLK_ERR_OUT_OF_MEMORY
+#undef MLK_ERR_PCT_FAIL
 #undef MLK_ERR_RNG_FAIL
 #undef MLK_EXTERNAL_API
 #undef MLK_FIPS202X4_HEADER_FILE
@@ -335,6 +319,14 @@
 #undef mlk_poly_frommsg
 #undef mlk_poly_tobytes
 #undef mlk_poly_tomsg
+/* mlkem/src/context.h */
+#undef MLK_CONTEXT_H
+#undef MLK_CONTEXT_PARAMETERS_0
+#undef MLK_CONTEXT_PARAMETERS_1
+#undef MLK_CONTEXT_PARAMETERS_2
+#undef MLK_CONTEXT_PARAMETERS_3
+#undef MLK_CONTEXT_PARAMETERS_4
+#undef MLK_CONTEXT_UNUSED
 /* mlkem/src/debug.h */
 #undef MLK_DEBUG_H
 #undef mlk_assert
@@ -401,6 +393,7 @@
 #undef MLK_SYSV_ABI_SUPPORTED
 #undef MLK_SYS_AARCH64
 #undef MLK_SYS_AARCH64_EB
+#undef MLK_SYS_AARCH64_NEON
 #undef MLK_SYS_APPLE
 #undef MLK_SYS_ARMV81M_MVE
 #undef MLK_SYS_BIG_ENDIAN
@@ -487,23 +480,23 @@
 /* mlkem/src/fips202/native/aarch64/x1_scalar.h */
 #undef MLK_FIPS202_AARCH64_NEED_X1_SCALAR
 #undef MLK_FIPS202_NATIVE_AARCH64_X1_SCALAR_H
-#undef MLK_USE_FIPS202_X1_NATIVE
+#undef MLK_USE_NATIVE_FIPS202_X1
 /* mlkem/src/fips202/native/aarch64/x1_v84a.h */
 #undef MLK_FIPS202_AARCH64_NEED_X1_V84A
 #undef MLK_FIPS202_NATIVE_AARCH64_X1_V84A_H
-#undef MLK_USE_FIPS202_X1_NATIVE
+#undef MLK_USE_NATIVE_FIPS202_X1
 /* mlkem/src/fips202/native/aarch64/x2_v84a.h */
 #undef MLK_FIPS202_AARCH64_NEED_X2_V84A
 #undef MLK_FIPS202_NATIVE_AARCH64_X2_V84A_H
-#undef MLK_USE_FIPS202_X4_NATIVE
+#undef MLK_USE_NATIVE_FIPS202_X4
 /* mlkem/src/fips202/native/aarch64/x4_v8a_scalar.h */
 #undef MLK_FIPS202_AARCH64_NEED_X4_V8A_SCALAR_HYBRID
 #undef MLK_FIPS202_NATIVE_AARCH64_X4_V8A_SCALAR_H
-#undef MLK_USE_FIPS202_X4_NATIVE
+#undef MLK_USE_NATIVE_FIPS202_X4
 /* mlkem/src/fips202/native/aarch64/x4_v8a_v84a_scalar.h */
 #undef MLK_FIPS202_AARCH64_NEED_X4_V8A_V84A_SCALAR_HYBRID
 #undef MLK_FIPS202_NATIVE_AARCH64_X4_V8A_V84A_SCALAR_H
-#undef MLK_USE_FIPS202_X4_NATIVE
+#undef MLK_USE_NATIVE_FIPS202_X4
 #endif /* MLK_SYS_AARCH64 */
 #if defined(MLK_SYS_X86_64)
 /*
@@ -512,7 +505,7 @@
 /* mlkem/src/fips202/native/x86_64/keccak_f1600_x4_avx2.h */
 #undef MLK_FIPS202_NATIVE_X86_64_KECCAK_F1600_X4_AVX2_H
 #undef MLK_FIPS202_X86_64_NEED_X4_AVX2
-#undef MLK_USE_FIPS202_X4_NATIVE
+#undef MLK_USE_NATIVE_FIPS202_X4
 /* mlkem/src/fips202/native/x86_64/src/fips202_native_x86_64.h */
 #undef MLK_FIPS202_NATIVE_X86_64_SRC_FIPS202_NATIVE_X86_64_H
 #undef mlk_keccak_f1600_x4_avx2_asm
@@ -528,12 +521,10 @@
 #undef MLK_FIPS202_ARMV81M_NEED_X4
 #undef MLK_FIPS202_NATIVE_ARMV81M
 #undef MLK_FIPS202_NATIVE_ARMV81M_MVE_H
-#undef MLK_USE_FIPS202_X4_EXTRACT_BYTES_NATIVE
-#undef MLK_USE_FIPS202_X4_NATIVE
-#undef MLK_USE_FIPS202_X4_XOR_BYTES_NATIVE
+#undef MLK_USE_NATIVE_FIPS202_X4
+#undef MLK_USE_NATIVE_FIPS202_X4_EXTRACT_BYTES
+#undef MLK_USE_NATIVE_FIPS202_X4_XOR_BYTES
 #undef mlk_keccak_f1600_x4_native_impl
-#undef mlk_keccak_f1600_x4_state_extract_bytes
-#undef mlk_keccak_f1600_x4_state_xor_bytes
 /* mlkem/src/fips202/native/armv81m/src/fips202_native_armv81m.h */
 #undef MLK_FIPS202_NATIVE_ARMV81M_SRC_FIPS202_NATIVE_ARMV81M_H
 #undef mlk_keccak_f1600_x4_mve_asm