pq_crypto 0.6.1 → 0.6.3

data/ext/pqcrypto/vendor/mlkem-native/README.md

@@ -20,7 +20,7 @@ All C code in [mlkem/src/*](mlkem) and [mlkem/src/fips202/*](mlkem/src/fips202)
 using CBMC[^CBMC]. All AArch64 and x86_64 assembly is proved to be functionally correct,
 memory-safe, and of secret-independent timing (constant-time), using HOL-Light[^HOL-Light].
 
-mlkem-native includes native backends for Arm (64-bit, Neon), Intel/AMD (64-bit, AVX2), and RISC-V (64-bit, RVV). See [benchmarks](https://pq-code-package.github.io/mlkem-native/dev/bench/) for performance data.
+mlkem-native includes native backends for Arm (64-bit, Neon), Intel/AMD (64-bit, AVX2), RISC-V (64-bit, RVV), and POWER (ppc64le, VSX). See [benchmarks](https://pq-code-package.github.io/mlkem-native/dev/bench/) for performance data.
 
 mlkem-native is supported by the [Post-Quantum Cryptography Alliance](https://pqca.org/) as part of the [Linux Foundation](https://linuxfoundation.org/).
 
@@ -53,7 +53,7 @@ mlkem-native is used in
  - [libOQS](https://github.com/open-quantum-safe/liboqs/) of the Open Quantum Safe project since [0.13.0](https://github.com/open-quantum-safe/liboqs/releases/tag/0.13.0) (as the default ML-KEM implementation)
  - AWS' Cryptography library [AWS-LC](https://github.com/aws/aws-lc/) since [v1.50.0](https://github.com/aws/aws-lc/releases/tag/v1.50.0)
  - The [rustls](https://github.com/rustls/rustls) TLS library written in Rust since [0.23.28](https://github.com/rustls/rustls/releases/tag/v%2F0.23.28) (through AWS-LC as the default cryptography provider)
- - The [zeroRISC's fork of OpenTitan](https://github.com/zerorisc/expo) - an open source silicon Root of Trust (RoT)
+ - [Pavona](https://github.com/pavona/pavona) - a library of modular, tapeout-proven, and secure-by-default open silicon blocks
 
 ## Formal Verification
 
@@ -80,6 +80,8 @@ through suitable barriers and constant-time patterns.
 Absence of secret-dependent branches, memory-access patterns and variable-latency instructions is also tested using `valgrind`
 with various combinations of compilers and compilation options.
 
+**Other attacks.** mlkem-native targets resistance against timing side-channels only. Other attack classes, such as power and electromagnetic side-channels, microarchitectural side-channels (e.g. speculative execution), or fault-injection attacks, are currently out of scope.
+
 ## Design
 
 mlkem-native is split into a _frontend_ and two _backends_ for arithmetic and FIPS202 / SHA3. The frontend is
@@ -94,12 +96,13 @@ mlkem-native currently offers the following backends:
 * 64-bit Arm backend (using Neon)
 * 64-bit Intel/AMD backend (using AVX2)
 * 64-bit RISC-V backend (using RVV)
+* 64-bit POWER backend (ppc64le, using VSX; supports POWER8 and above)
 * 32-bit Armv8.1-M backend (using Helium/MVE) -- see [#1501](https://github.com/pq-code-package/mlkem-native/issues/1501). This is still experimental and disabled by default.
 
 If you'd like contribute new backends, please reach out or just open a PR.
 
 Our AArch64 assembly is developed using the [SLOTHY](https://github.com/slothy-optimizer/slothy) superoptimizer, following the approach described in the SLOTHY paper[^SLOTHY_Paper]:
-We write 'clean' assembly by hand and automate micro-optimizations (e.g. see the [clean](dev/aarch64_clean/src/ntt.S) vs [optimized](dev/aarch64_opt/src/ntt.S) AArch64 NTT).
+We write 'clean' assembly by hand and automate micro-optimizations (e.g. see the [clean](dev/aarch64_clean/src/ntt_aarch64_asm.S) vs [optimized](dev/aarch64_opt/src/ntt_aarch64_asm.S) AArch64 NTT).
 See [dev/README.md](dev/README.md) for more details.
 
 ## Test Vectors

data/ext/pqcrypto/vendor/mlkem-native/RELEASE.md

@@ -1,4 +1,26 @@
 [//]: # (SPDX-License-Identifier: CC-BY-4.0)
+
+mlkem-native v1.2.0
+===================
+
+Release notes
+-------------
+
+mlkem-native v1.2.0 adds a new **PowerPC (ppc64le)** assembly backend and broadens portability of the existing
+backends: the x86_64 backend can now be used on Windows, the RISC-V backend compiles under C90, and a new
+Cortex-M33 baremetal target is tested. It also fixes a signed-shift undefined behavior on 16-bit-`int` targets
+and hardens the RISC-V backend against secret-dependent timing. Finally, the CBMC proofs are extended to
+establish loop termination for all functions except rejection sampling.
+
+What's New
+----------
+
+- **PowerPC (ppc64le) backend**: New VSX arithmetic backend (NTT, inverse NTT, `poly_reduce`, `poly_tomont`) for POWER8 and above, with automatic fallback to C on older targets. Thanks to IBM, and in particular Danny Tsen (@dannytsen) and Basil Hess (@bhess), for this contribution! ([#1677](https://github.com/pq-code-package/mlkem-native/pull/1677))
+- **Assurance**: CBMC now proves loop termination for all functions except rejection sampling. Thanks to Nicky Mouha (@nmouha) for making us aware of the absence of termination proofs. ([#1625](https://github.com/pq-code-package/mlkem-native/pull/1625))
+- **Verification tooling**: Bump CBMC to a development build that works around a Z3 soundness issue ([Z3#9550](https://github.com/Z3Prover/z3/issues/9550)) affecting the SMT solver used by the CBMC proofs. ([#1745](https://github.com/pq-code-package/mlkem-native/pull/1745))
+- **Portability**: the x86_64 assembly backend can now be used on Windows with compilers that support the SysV calling convention per function (GCC and Clang, via `__attribute__((sysv_abi))`) ([#1730](https://github.com/pq-code-package/mlkem-native/pull/1730)), the RISC-V backend compiles under C90 ([#1732](https://github.com/pq-code-package/mlkem-native/pull/1732)), and a new Cortex-M33 baremetal target is tested ([#1579](https://github.com/pq-code-package/mlkem-native/pull/1579)).
+- **Correctness / CT**: Fix signed-shift undefined behavior on 16-bit-`int` targets ([#1727](https://github.com/pq-code-package/mlkem-native/pull/1727)) and harden the RISC-V backend against secret-dependent timing ([#1732](https://github.com/pq-code-package/mlkem-native/pull/1732)).
+
 mlkem-native v1.1.0
 ====================
 

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

@@ -88,6 +88,9 @@
 #include "src/native/riscv64/src/rv64v_debug.c"
 #include "src/native/riscv64/src/rv64v_poly.c"
 #endif
+#if defined(MLK_SYS_PPC64LE)
+#include "src/native/ppc64le/src/consts.c"
+#endif
 #endif /* MLK_CONFIG_USE_NATIVE_BACKEND_ARITH */
 
 #if defined(MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202)
@@ -213,6 +216,8 @@
 #undef MLK_FIPS202_HEADER_FILE
 #undef MLK_FREE
 #undef MLK_INTERNAL_API
+#undef MLK_INTERNAL_DATA_DECLARATION
+#undef MLK_INTERNAL_DATA_DEFINITION
 #undef MLK_NAMESPACE
 #undef MLK_NAMESPACE_K
 #undef MLK_NAMESPACE_PREFIX
@@ -365,8 +370,11 @@
 #undef MLK_HAVE_INLINE_ASM
 #undef MLK_INLINE
 #undef MLK_MUST_CHECK_RETURN_VALUE
+#undef MLK_NOINLINE
 #undef MLK_RESTRICT
 #undef MLK_STATIC_TESTABLE
+#undef MLK_SYSV_ABI
+#undef MLK_SYSV_ABI_SUPPORTED
 #undef MLK_SYS_AARCH64
 #undef MLK_SYS_AARCH64_EB
 #undef MLK_SYS_APPLE
@@ -446,11 +454,11 @@
 #undef MLK_FIPS202_NATIVE_AARCH64_AUTO_H
 /* mlkem/src/fips202/native/aarch64/src/fips202_native_aarch64.h */
 #undef MLK_FIPS202_NATIVE_AARCH64_SRC_FIPS202_NATIVE_AARCH64_H
-#undef mlk_keccak_f1600_x1_scalar_asm
-#undef mlk_keccak_f1600_x1_v84a_asm
-#undef mlk_keccak_f1600_x2_v84a_asm
-#undef mlk_keccak_f1600_x4_v8a_scalar_hybrid_asm
-#undef mlk_keccak_f1600_x4_v8a_v84a_scalar_hybrid_asm
+#undef mlk_keccak_f1600_x1_scalar_aarch64_asm
+#undef mlk_keccak_f1600_x1_v84a_aarch64_asm
+#undef mlk_keccak_f1600_x2_v84a_aarch64_asm
+#undef mlk_keccak_f1600_x4_v8a_scalar_hybrid_aarch64_asm
+#undef mlk_keccak_f1600_x4_v8a_v84a_scalar_hybrid_aarch64_asm
 #undef mlk_keccakf1600_round_constants
 /* mlkem/src/fips202/native/aarch64/x1_scalar.h */
 #undef MLK_FIPS202_AARCH64_NEED_X1_SCALAR
@@ -483,7 +491,7 @@
 #undef MLK_USE_FIPS202_X4_NATIVE
 /* 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
+#undef mlk_keccak_f1600_x4_avx2_asm
 #undef mlk_keccak_rho56
 #undef mlk_keccak_rho8
 #undef mlk_keccakf1600_round_constants
@@ -542,16 +550,16 @@
 #undef mlk_aarch64_ntt_zetas_layer67
 #undef mlk_aarch64_zetas_mulcache_native
 #undef mlk_aarch64_zetas_mulcache_twisted_native
-#undef mlk_intt_asm
-#undef mlk_ntt_asm
-#undef mlk_poly_mulcache_compute_asm
-#undef mlk_poly_reduce_asm
-#undef mlk_poly_tobytes_asm
-#undef mlk_poly_tomont_asm
-#undef mlk_polyvec_basemul_acc_montgomery_cached_asm_k2
-#undef mlk_polyvec_basemul_acc_montgomery_cached_asm_k3
-#undef mlk_polyvec_basemul_acc_montgomery_cached_asm_k4
-#undef mlk_rej_uniform_asm
+#undef mlk_intt_aarch64_asm
+#undef mlk_ntt_aarch64_asm
+#undef mlk_poly_mulcache_compute_aarch64_asm
+#undef mlk_poly_reduce_aarch64_asm
+#undef mlk_poly_tobytes_aarch64_asm
+#undef mlk_poly_tomont_aarch64_asm
+#undef mlk_polyvec_basemul_acc_montgomery_cached_k2_aarch64_asm
+#undef mlk_polyvec_basemul_acc_montgomery_cached_k3_aarch64_asm
+#undef mlk_polyvec_basemul_acc_montgomery_cached_k4_aarch64_asm
+#undef mlk_rej_uniform_aarch64_asm
 #undef mlk_rej_uniform_table
 #endif /* MLK_SYS_AARCH64 */
 #if defined(MLK_SYS_X86_64)
@@ -582,27 +590,27 @@
 /* mlkem/src/native/x86_64/src/arith_native_x86_64.h */
 #undef MLK_AVX2_REJ_UNIFORM_BUFLEN
 #undef MLK_NATIVE_X86_64_SRC_ARITH_NATIVE_X86_64_H
-#undef mlk_invntt_avx2
-#undef mlk_ntt_avx2
-#undef mlk_nttfrombytes_avx2
-#undef mlk_ntttobytes_avx2
-#undef mlk_nttunpack_avx2
-#undef mlk_poly_compress_d10_avx2
-#undef mlk_poly_compress_d11_avx2
-#undef mlk_poly_compress_d4_avx2
-#undef mlk_poly_compress_d5_avx2
-#undef mlk_poly_decompress_d10_avx2
-#undef mlk_poly_decompress_d11_avx2
-#undef mlk_poly_decompress_d4_avx2
-#undef mlk_poly_decompress_d5_avx2
-#undef mlk_poly_mulcache_compute_avx2
-#undef mlk_polyvec_basemul_acc_montgomery_cached_asm_k2
-#undef mlk_polyvec_basemul_acc_montgomery_cached_asm_k3
-#undef mlk_polyvec_basemul_acc_montgomery_cached_asm_k4
-#undef mlk_reduce_avx2
-#undef mlk_rej_uniform_asm
+#undef mlk_invntt_avx2_asm
+#undef mlk_ntt_avx2_asm
+#undef mlk_nttfrombytes_avx2_asm
+#undef mlk_ntttobytes_avx2_asm
+#undef mlk_nttunpack_avx2_asm
+#undef mlk_poly_compress_d10_avx2_asm
+#undef mlk_poly_compress_d11_avx2_asm
+#undef mlk_poly_compress_d4_avx2_asm
+#undef mlk_poly_compress_d5_avx2_asm
+#undef mlk_poly_decompress_d10_avx2_asm
+#undef mlk_poly_decompress_d11_avx2_asm
+#undef mlk_poly_decompress_d4_avx2_asm
+#undef mlk_poly_decompress_d5_avx2_asm
+#undef mlk_poly_mulcache_compute_avx2_asm
+#undef mlk_polyvec_basemul_acc_montgomery_cached_k2_avx2_asm
+#undef mlk_polyvec_basemul_acc_montgomery_cached_k3_avx2_asm
+#undef mlk_polyvec_basemul_acc_montgomery_cached_k4_avx2_asm
+#undef mlk_reduce_avx2_asm
+#undef mlk_rej_uniform_avx2_asm
 #undef mlk_rej_uniform_table
-#undef mlk_tomont_avx2
+#undef mlk_tomont_avx2_asm
 /* mlkem/src/native/x86_64/src/compress_consts.h */
 #undef MLK_NATIVE_X86_64_SRC_COMPRESS_CONSTS_H
 #undef mlk_compress_d10_data
@@ -656,5 +664,38 @@
 #undef mlk_debug_check_bounds_int16m1
 #undef mlk_debug_check_bounds_int16m2
 #endif /* MLK_SYS_RISCV64 */
+#if defined(MLK_SYS_PPC64LE)
+/*
+ * Undefine macros from native code (Arith, PPC64LE)
+ */
+/* mlkem/src/native/ppc64le/meta.h */
+#undef MLK_ARITH_BACKEND_NAME
+#undef MLK_ARITH_BACKEND_PPC64LE_DEFAULT
+#undef MLK_NATIVE_PPC64LE_META_H
+#undef MLK_USE_NATIVE_INTT
+#undef MLK_USE_NATIVE_NTT
+#undef MLK_USE_NATIVE_POLY_REDUCE
+#undef MLK_USE_NATIVE_POLY_TOMONT
+/* mlkem/src/native/ppc64le/src/arith_native_ppc64le.h */
+#undef MLK_NATIVE_PPC64LE_SRC_ARITH_NATIVE_PPC64LE_H
+#undef mlk_intt_ppc_asm
+#undef mlk_ntt_ppc_asm
+#undef mlk_poly_tomont_ppc_asm
+#undef mlk_reduce_ppc_asm
+/* mlkem/src/native/ppc64le/src/consts.h */
+#undef MLK_NATIVE_PPC64LE_SRC_CONSTS_H
+#undef MLK_PPC_C20159_OFFSET
+#undef MLK_PPC_NQ_OFFSET
+#undef MLK_PPC_N_INV_OFFSET
+#undef MLK_PPC_N_INV_TW_OFFSET
+#undef MLK_PPC_Q_OFFSET
+#undef MLK_PPC_TOMONT_OFFSET
+#undef MLK_PPC_TOMONT_TW_OFFSET
+#undef MLK_PPC_ZETA_INTT_OFFSET
+#undef MLK_PPC_ZETA_INTT_TW_OFFSET
+#undef MLK_PPC_ZETA_NTT_OFFSET
+#undef MLK_PPC_ZETA_NTT_TW_OFFSET
+#undef mlk_ppc_qdata
+#endif /* MLK_SYS_PPC64LE */
 #endif /* MLK_CONFIG_USE_NATIVE_BACKEND_ARITH */
 #endif /* !MLK_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS */

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

@@ -112,13 +112,13 @@
 /****************************** Error codes ***********************************/
 
 /* Generic failure condition */
-#define MLK_ERR_FAIL -1
+#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
+#define MLK_ERR_OUT_OF_MEMORY (-2)
 /* An rng failure occured. Might be due to insufficient entropy or
  * system misconfiguration. */
-#define MLK_ERR_RNG_FAIL -3
+#define MLK_ERR_RNG_FAIL (-3)
 
 /****************************** Function API **********************************/
 
@@ -170,7 +170,7 @@
 #define MLK_API_NAMESPACE(sym) \
   MLK_API_CONCAT_UNDERSCORE(MLK_CONFIG_API_NAMESPACE_PREFIX, sym)
 
-#if defined(__GNUC__) || defined(clang)
+#if defined(__GNUC__) || defined(__clang__)
 #define MLK_API_MUST_CHECK_RETURN_VALUE __attribute__((warn_unused_result))
 #else
 #define MLK_API_MUST_CHECK_RETURN_VALUE
@@ -191,28 +191,26 @@ extern "C"
 {
 #endif
 
-/*************************************************
- * Name:        crypto_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 array of
- *                 length MLKEM{512,768,1024}_PUBLICKEYBYTES bytes.
- *              - uint8_t sk[]: pointer to output private key, an array of
- *                  of MLKEM{512,768,1024}_SECRETKEYBYTES bytes.
- *              - uint8_t *coins: pointer to input randomness, an array of
- *                  2*MLKEM_SYMBYTES uniformly 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 array of
+ *                     MLKEM{512,768,1024}_PUBLICKEYBYTES bytes.
+ * @param[out] sk      Output private key, an array of
+ *                     MLKEM{512,768,1024}_SECRETKEYBYTES bytes.
+ * @param[in]  coins   Input randomness, an array of 2*MLKEM_SYMBYTES uniformly
+ *                     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_API_QUALIFIER
 MLK_API_MUST_CHECK_RETURN_VALUE
 int MLK_API_NAMESPACE(keypair_derand)(
@@ -227,27 +225,25 @@ int MLK_API_NAMESPACE(keypair_derand)(
 
 
 #if !defined(MLK_CONFIG_NO_RANDOMIZED_API)
-/*************************************************
- * Name:        crypto_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 array of
- *                 MLKEM{512,768,1024}_PUBLICKEYBYTES bytes.
- *              - uint8_t *sk: pointer to output private key, an array of
- *                 MLKEM{512,768,1024}_SECRETKEYBYTES 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.
- *              - MLK_ERR_RNG_FAIL: Random number generation 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 array of
+ *                     MLKEM{512,768,1024}_PUBLICKEYBYTES bytes.
+ * @param[out] sk      Output private key, an array of
+ *                     MLKEM{512,768,1024}_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          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.
+ */
 MLK_API_QUALIFIER
 MLK_API_MUST_CHECK_RETURN_VALUE
 int MLK_API_NAMESPACE(keypair)(
@@ -260,30 +256,27 @@ int MLK_API_NAMESPACE(keypair)(
 );
 #endif /* !MLK_CONFIG_NO_RANDOMIZED_API */
 
-/*************************************************
- * Name:        crypto_kem_enc_derand
- *
- * Description: Generates cipher text and shared
- *              secret for given public key
- *
- * Arguments:   - uint8_t *ct: pointer to output cipher text, an array of
- *                 MLKEM{512,768,1024}_CIPHERTEXTBYTES bytes.
- *              - uint8_t *ss: pointer to output shared secret, an array of
- *                 MLKEM_BYTES bytes.
- *              - const uint8_t *pk: pointer to input public key, an array of
- *                 MLKEM{512,768,1024}_PUBLICKEYBYTES bytes.
- *              - const uint8_t *coins: pointer to input randomness, an array of
- *                 MLKEM_SYMBYTES 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 array of
+ *                     MLKEM{512,768,1024}_CIPHERTEXTBYTES bytes.
+ * @param[out] ss      Output shared secret, an array of MLKEM_BYTES bytes.
+ * @param[in]  pk      Input public key, an array of
+ *                     MLKEM{512,768,1024}_PUBLICKEYBYTES bytes.
+ * @param[in]  coins   Input randomness, an array of MLKEM_SYMBYTES 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_API_QUALIFIER
 MLK_API_MUST_CHECK_RETURN_VALUE
 int MLK_API_NAMESPACE(enc_derand)(
@@ -298,29 +291,27 @@ int MLK_API_NAMESPACE(enc_derand)(
 );
 
 #if !defined(MLK_CONFIG_NO_RANDOMIZED_API)
-/*************************************************
- * Name:        crypto_kem_enc
- *
- * Description: Generates cipher text and shared
- *              secret for given public key
- *
- * Arguments:   - uint8_t *ct: pointer to output cipher text, an array of
- *                 MLKEM{512,768,1024}_CIPHERTEXTBYTES bytes.
- *              - uint8_t *ss: pointer to output shared secret, an array of
- *                 MLKEM_BYTES bytes.
- *              - const uint8_t *pk: pointer to input public key, an array of
- *                 MLKEM{512,768,1024}_PUBLICKEYBYTES 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.
- *          - MLK_ERR_RNG_FAIL: Random number generation failed.
- *
- * 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 array of
+ *                     MLKEM{512,768,1024}_CIPHERTEXTBYTES bytes.
+ * @param[out] ss      Output shared secret, an array of MLKEM_BYTES bytes.
+ * @param[in]  pk      Input public key, an array of
+ *                     MLKEM{512,768,1024}_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_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.
+ * @retval MLK_ERR_RNG_FAIL      Random number generation failed.
+ */
 MLK_API_QUALIFIER
 MLK_API_MUST_CHECK_RETURN_VALUE
 int MLK_API_NAMESPACE(enc)(
@@ -334,28 +325,26 @@ int MLK_API_NAMESPACE(enc)(
 );
 #endif /* !MLK_CONFIG_NO_RANDOMIZED_API */
 
-/*************************************************
- * Name:        crypto_kem_dec
- *
- * Description: Generates shared secret for given
- *              cipher text and private key
- *
- * Arguments:   - uint8_t *ss: pointer to output shared secret, an array of
- *                 MLKEM_BYTES bytes.
- *              - const uint8_t *ct: pointer to input cipher text, an array of
- *                 MLKEM{512,768,1024}_CIPHERTEXTBYTES bytes.
- *              - const uint8_t *sk: pointer to input private key, an array of
- *                 MLKEM{512,768,1024}_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 array of MLKEM_BYTES bytes.
+ * @param[in]  ct      Input ciphertext, an array of
+ *                     MLKEM{512,768,1024}_CIPHERTEXTBYTES bytes.
+ * @param[in]  sk      Input private key, an array of
+ *                     MLKEM{512,768,1024}_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_API_QUALIFIER
 MLK_API_MUST_CHECK_RETURN_VALUE
 int MLK_API_NAMESPACE(dec)(
@@ -369,23 +358,23 @@ int MLK_API_NAMESPACE(dec)(
 );
 
 
-/*************************************************
- * Name:        crypto_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 array of
- *                 MLKEM{512,768,1024}_PUBLICKEYBYTES bytes.
+ * @param[in] pk      Input public key, an array of
+ *                    MLKEM{512,768,1024}_PUBLICKEYBYTES bytes.
+ * @param     context Application context. Only present when
+ *                    MLK_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                    MLK_CONFIG_CONTEXT_PARAMETER_TYPE.
  *
- * 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.
- *
- * Specification: Implements @[FIPS203, Section 7.2, 'modulus check']
- *
- **************************************************/
+ * @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_API_QUALIFIER
 MLK_API_MUST_CHECK_RETURN_VALUE
 int MLK_API_NAMESPACE(check_pk)(
@@ -396,24 +385,23 @@ int MLK_API_NAMESPACE(check_pk)(
 #endif
 );
 
-/*************************************************
- * Name:        crypto_kem_check_sk
- *
- * 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])
- *
- * Arguments:   - const uint8_t *sk: pointer to input private key, an array of
- *                 MLKEM{512,768,1024}_SECRETKEYBYTES bytes.
+/**
+ * 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]).
  *
- * 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.
+ * @spec{Implements @[FIPS203, Section 7.3, 'hash check'].}
  *
- * Specification: Implements @[FIPS203, Section 7.3, 'hash check']
+ * @param[in] sk      Input private key, an array of
+ *                    MLKEM{512,768,1024}_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          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_API_QUALIFIER
 MLK_API_MUST_CHECK_RETURN_VALUE
 int MLK_API_NAMESPACE(check_sk)(
@@ -465,7 +453,6 @@ int MLK_API_NAMESPACE(check_sk)(
 #undef MLK_API_NAMESPACE
 #undef MLK_API_MUST_CHECK_RETURN_VALUE
 #undef MLK_API_QUALIFIER
-#undef MLK_API_LEGACY_CONFIG
 
 #endif /* MLK_CONFIG_API_NO_SUPERCOP */
 #endif /* !MLK_CONFIG_API_CONSTANTS_ONLY */
@@ -535,4 +522,6 @@ 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 */