Add CB_ONLY mode for ML-KEM

.github/workflows/cryptocb-only.yml

@@ -1,3 +1,3 @@
 name: cryptocb-only Tests
 
 # START OF COMMON SECTION
@@ -117,9 +117,15 @@
           {"name": "curve25519",
            "comment": "WOLF_CRYPTO_CB_ONLY_CURVE25519: strips software X25519 (keygen/shared-secret); swdev provides the software path via cryptocb. Nonblock and async X25519 have no callback path and are left disabled.",
            "configure": ["CPPFLAGS=-DWOLF_CRYPTO_CB_ONLY_CURVE25519"]},
+          {"name": "mlkem",
+           "comment": "WOLF_CRYPTO_CB_ONLY_MLKEM: strips the ML-KEM lattice math (key generation, encapsulation, decapsulation, the NTT, matrix generation, noise sampling and compression, plus the x86 and ARM assembly). The encode/decode helpers and the hash/PRF object lifecycle stay, because a callback that returns key material needs them. Built with --enable-cryptonly: TLS 1.3 offers ML-KEM key shares by default, and with the software path gone every such handshake needs a registered device, which no test device provides yet.",
+           "configure": ["--enable-cryptonly", "CPPFLAGS=-DWOLF_CRYPTO_CB_ONLY_MLKEM"]},
           {"name": "all",
-           "comment": "All seven ONLY_* macros at once: every supported software primitive is stripped and dispatched through cryptocb. Catches any cross-algorithm call that a single-strip entry would still resolve via the remaining software paths.",
-           "configure": ["CPPFLAGS=-DWOLF_CRYPTO_CB_ONLY_ECC -DWOLF_CRYPTO_CB_ONLY_RSA -DWOLF_CRYPTO_CB_ONLY_SHA256 -DWOLF_CRYPTO_CB_ONLY_SHA512 -DWOLF_CRYPTO_CB_ONLY_AES -DWOLF_CRYPTO_CB_ONLY_ED25519 -DWOLF_CRYPTO_CB_ONLY_CURVE25519"]}
+           "comment": "All seven TLS-compatible ONLY_* macros at once: every supported software primitive is stripped and dispatched through cryptocb. Catches any cross-algorithm call that a single-strip entry would still resolve via the remaining software paths. MLKEM is not here because it needs --enable-cryptonly; the all-cryptonly entry below covers it alongside the rest.",
+           "configure": ["CPPFLAGS=-DWOLF_CRYPTO_CB_ONLY_ECC -DWOLF_CRYPTO_CB_ONLY_RSA -DWOLF_CRYPTO_CB_ONLY_SHA256 -DWOLF_CRYPTO_CB_ONLY_SHA512 -DWOLF_CRYPTO_CB_ONLY_AES -DWOLF_CRYPTO_CB_ONLY_ED25519 -DWOLF_CRYPTO_CB_ONLY_CURVE25519"]},
+          {"name": "all-cryptonly",
+           "comment": "The 'all' set plus MLKEM, built --enable-cryptonly so ML-KEM can join. This is the only entry where a stripped ML-KEM meets the other stripped primitives; TLS is off because TLS 1.3 offers ML-KEM key shares by default and no test device services them.",
+           "configure": ["--enable-cryptonly", "CPPFLAGS=-DWOLF_CRYPTO_CB_ONLY_ECC -DWOLF_CRYPTO_CB_ONLY_RSA -DWOLF_CRYPTO_CB_ONLY_SHA256 -DWOLF_CRYPTO_CB_ONLY_SHA512 -DWOLF_CRYPTO_CB_ONLY_AES -DWOLF_CRYPTO_CB_ONLY_ED25519 -DWOLF_CRYPTO_CB_ONLY_CURVE25519 -DWOLF_CRYPTO_CB_ONLY_MLKEM"]}
           ]}
           EOF
           .github/scripts/parallel-make-check.py \

tests/api/test_mlkem.c

@@ -39,6 +39,7 @@ int test_wc_mlkem_make_key_kats(void)
 {
     EXPECT_DECLS;
 #if defined(WOLFSSL_HAVE_MLKEM) && \
+    defined(WC_MLKEM_HAVE_NATIVE) && \
     !defined(WOLFSSL_NO_ML_KEM) && !defined(WOLFSSL_MLKEM_NO_MAKE_KEY)
     MlKemKey* key;
 #ifndef WOLFSSL_NO_ML_KEM_512
@@ -1498,6 +1499,7 @@ int test_wc_mlkem_encapsulate_kats(void)
 {
     EXPECT_DECLS;
 #if defined(WOLFSSL_HAVE_MLKEM) && \
+    defined(WC_MLKEM_HAVE_NATIVE) && \
     !defined(WOLFSSL_NO_ML_KEM) && !defined(WOLFSSL_MLKEM_NO_ENCAPSULATE)
     MlKemKey* key;
 #ifndef WOLFSSL_NO_ML_KEM_512
@@ -2472,6 +2474,7 @@ int test_wc_mlkem_decapsulate_kats(void)
 {
     EXPECT_DECLS;
 #if defined(WOLFSSL_HAVE_MLKEM) && \
+    defined(WC_MLKEM_HAVE_NATIVE) && \
     !defined(WOLFSSL_NO_ML_KEM) && !defined(WOLFSSL_MLKEM_NO_DECAPSULATE)
     MlKemKey* key;
 #ifndef WOLFSSL_NO_ML_KEM_512
@@ -3885,7 +3888,8 @@ int test_wc_mlkem_decapsulate_kats(void)
 int test_wc_mlkem_decapsulate_pubonly_fails(void)
 {
     EXPECT_DECLS;
-#if !defined(HAVE_FIPS) || FIPS_VERSION3_GE(7,0,0)
+#if (!defined(HAVE_FIPS) || FIPS_VERSION3_GE(7,0,0)) && \
+    defined(WC_MLKEM_HAVE_NATIVE)
 #if defined(WOLFSSL_HAVE_MLKEM) && \
     !defined(WOLFSSL_NO_ML_KEM) && !defined(WOLFSSL_MLKEM_NO_DECAPSULATE) && \
     !defined(WOLFSSL_MLKEM_NO_ENCAPSULATE) && \
@@ -3962,7 +3966,8 @@ int test_wc_mlkem_decapsulate_pubonly_fails(void)
 int test_wc_mlkem_decap_fo_reject(void)
 {
     EXPECT_DECLS;
-#if !defined(HAVE_FIPS) || FIPS_VERSION3_GE(7,0,0)
+#if (!defined(HAVE_FIPS) || FIPS_VERSION3_GE(7,0,0)) && \
+    defined(WC_MLKEM_HAVE_NATIVE)
 #if defined(WOLFSSL_HAVE_MLKEM) && \
     !defined(WOLFSSL_NO_ML_KEM) && !defined(WOLFSSL_MLKEM_NO_DECAPSULATE) && \
     !defined(WOLFSSL_MLKEM_NO_ENCAPSULATE) && \
@@ -4037,7 +4042,8 @@ int test_wc_mlkem_decap_fo_reject(void)
 int test_wc_mlkem_decode_privkey_bad_pubhash(void)
 {
     EXPECT_DECLS;
-#if !defined(HAVE_FIPS) && !defined(HAVE_SELFTEST)
+#if !defined(HAVE_FIPS) && !defined(HAVE_SELFTEST) && \
+    defined(WC_MLKEM_HAVE_NATIVE)
 #if defined(WOLFSSL_HAVE_MLKEM) && \
     !defined(WOLFSSL_NO_ML_KEM) && !defined(WOLFSSL_MLKEM_NO_MAKE_KEY)
     MlKemKey* key = NULL;
@@ -4227,7 +4233,8 @@ int test_wc_MlkemFeatureCoverage(void)
 int test_wc_MlkemDecisionCoverage(void)
 {
     EXPECT_DECLS;
-#if defined(WOLFSSL_HAVE_MLKEM) && !defined(WOLFSSL_NO_ML_KEM)
+#if defined(WOLFSSL_HAVE_MLKEM) && !defined(WOLFSSL_NO_ML_KEM) && \
+    defined(WC_MLKEM_HAVE_NATIVE)
     MlKemKey* key = NULL;
 #ifndef WC_NO_CONSTRUCTORS
     MlKemKey* newKey = NULL;
@@ -4603,6 +4610,7 @@ int test_wc_mlkem_encode_key_len_decision(void)
 {
     EXPECT_DECLS;
 #if defined(WOLFSSL_HAVE_MLKEM) && !defined(WOLFSSL_NO_ML_KEM) && \
+    defined(WC_MLKEM_HAVE_NATIVE) && \
     !defined(WOLFSSL_MLKEM_NO_MAKE_KEY)
     MlKemKey* key;
     WC_RNG rng;

wolfcrypt/src/cryptocb.c

@@ -66,6 +66,7 @@ Crypto Callback Build Options:
  * WOLF_CRYPTO_CB_ONLY_AES: Use only callbacks for AES          default: off
  * WOLF_CRYPTO_CB_ONLY_ED25519: Use only callbacks for Ed25519  default: off
  * WOLF_CRYPTO_CB_ONLY_CURVE25519: Use only callbacks for X25519 default: off
+ * WOLF_CRYPTO_CB_ONLY_MLKEM: Use only callbacks for ML-KEM    default: off
  */
 
 #include <wolfssl/wolfcrypt/libwolfssl_sources.h>

wolfcrypt/src/port/arm/armv8-32-mlkem-asm.S

@@ -33,7 +33,7 @@
 #ifdef WOLFSSL_ARMASM
 #if !defined(__aarch64__) && !defined(WOLFSSL_ARMASM_THUMB2)
 #ifndef WOLFSSL_ARMASM_INLINE
-#ifdef WOLFSSL_HAVE_MLKEM
+#if defined(WOLFSSL_HAVE_MLKEM) && !defined(WOLF_CRYPTO_CB_ONLY_MLKEM)
 #ifndef __APPLE__
 	.text
 	.type	L_mlkem_arm32_ntt_zetas, %object
@@ -8516,7 +8516,7 @@ L_mlkem_arm32_rej_uniform_done:
 	lsr	r0, r12, #1
 	pop	{r4, r5, r6, r7, r8, pc}
 	.size	mlkem_arm32_rej_uniform,.-mlkem_arm32_rej_uniform
-#endif /* WOLFSSL_HAVE_MLKEM */
+#endif /* WOLFSSL_HAVE_MLKEM && !WOLF_CRYPTO_CB_ONLY_MLKEM */
 
 #if defined(__linux__) && defined(__ELF__)
 .section	.note.GNU-stack,"",%progbits

wolfcrypt/src/port/arm/armv8-32-mlkem-asm_c.c

@@ -52,7 +52,7 @@
 
 #include <wolfssl/wolfcrypt/wc_mlkem.h>
 
-#ifdef WOLFSSL_HAVE_MLKEM
+#if defined(WOLFSSL_HAVE_MLKEM) && !defined(WOLF_CRYPTO_CB_ONLY_MLKEM)
 XALIGNED(4) static const word16 L_mlkem_arm32_ntt_zetas[] = {
     0x08ed, 0x0a0b, 0x0b9a, 0x0714, 0x05d5, 0x058e, 0x011f, 0x00ca,
     0x0c56, 0x026e, 0x0629, 0x00b6, 0x03c2, 0x084f, 0x073f, 0x05bc,
@@ -8666,7 +8666,7 @@ WC_OMIT_FRAME_POINTER unsigned int mlkem_arm32_rej_uniform(sword16* p,
     return (word32)(size_t)p;
 }
 
-#endif /* WOLFSSL_HAVE_MLKEM */
+#endif /* WOLFSSL_HAVE_MLKEM && !WOLF_CRYPTO_CB_ONLY_MLKEM */
 
 #endif /* WOLFSSL_ARMASM_INLINE */
 #endif /* !__aarch64__ && !WOLFSSL_ARMASM_THUMB2 */

wolfcrypt/src/port/arm/armv8-mlkem-asm.S

@@ -49,7 +49,7 @@
 #endif /* __APPLE__ */
 L_mlkem_aarch64_consts:
 	.short	0x0d01,0xf301,0x4ebf,0x0549,0x5049,0x0000,0x0000,0x0000
-#ifdef WOLFSSL_HAVE_MLKEM
+#if defined(WOLFSSL_HAVE_MLKEM) && !defined(WOLF_CRYPTO_CB_ONLY_MLKEM)
 #ifndef __APPLE__
 	.text
 	.section	.rodata
@@ -12071,7 +12071,7 @@ L_SHA3_shake256_blocksx3_seed_neon_begin:
 #ifndef __APPLE__
 	.size	mlkem_shake256_blocksx3_seed_neon,.-mlkem_shake256_blocksx3_seed_neon
 #endif /* __APPLE__ */
-#endif /* WOLFSSL_HAVE_MLKEM */
+#endif /* WOLFSSL_HAVE_MLKEM && !WOLF_CRYPTO_CB_ONLY_MLKEM */
 #endif /* __aarch64__ */
 #endif /* WOLFSSL_ARMASM */
 

wolfcrypt/src/port/arm/armv8-mlkem-asm_c.c

@@ -40,7 +40,7 @@ XALIGNED(4) static const word16 L_mlkem_aarch64_consts[] = {
 
 #include <wolfssl/wolfcrypt/wc_mlkem.h>
 
-#ifdef WOLFSSL_HAVE_MLKEM
+#if defined(WOLFSSL_HAVE_MLKEM) && !defined(WOLF_CRYPTO_CB_ONLY_MLKEM)
 XALIGNED(4) static const word16 L_mlkem_aarch64_zetas[] = {
     0x08ed, 0x0a0b, 0x0b9a, 0x0714, 0x05d5, 0x058e, 0x011f, 0x00ca,
     0x0c56, 0x026e, 0x0629, 0x00b6, 0x03c2, 0x084f, 0x073f, 0x05bc,
@@ -11258,7 +11258,7 @@ void mlkem_shake256_blocksx3_seed_neon(word64* state, byte* seed)
     );
 }
 
-#endif /* WOLFSSL_HAVE_MLKEM */
+#endif /* WOLFSSL_HAVE_MLKEM && !WOLF_CRYPTO_CB_ONLY_MLKEM */
 #endif /* __aarch64__ */
 #endif /* WOLFSSL_ARMASM */
 #endif /* WOLFSSL_ARMASM_INLINE */

wolfcrypt/src/port/arm/thumb2-mlkem-asm.S

@@ -35,7 +35,7 @@
 #ifndef WOLFSSL_ARMASM_INLINE
 	.thumb
 	.syntax unified
-#ifdef WOLFSSL_HAVE_MLKEM
+#if defined(WOLFSSL_HAVE_MLKEM) && !defined(WOLF_CRYPTO_CB_ONLY_MLKEM)
 #ifndef __APPLE__
 	.text
 	.type	L_mlkem_thumb2_ntt_zetas, %object
@@ -3591,7 +3591,7 @@ L_mlkem_thumb2_rej_uniform_done:
 	POP	{r4, r5, r6, r7, r8, r9, r10, pc}
 	/* Cycle Count = 225 */
 	.size	mlkem_thumb2_rej_uniform,.-mlkem_thumb2_rej_uniform
-#endif /* WOLFSSL_HAVE_MLKEM */
+#endif /* WOLFSSL_HAVE_MLKEM && !WOLF_CRYPTO_CB_ONLY_MLKEM */
 
 #if defined(__linux__) && defined(__ELF__)
 .section	.note.GNU-stack,"",%progbits

wolfcrypt/src/port/arm/thumb2-mlkem-asm_c.c

@@ -52,7 +52,7 @@
 
 #include <wolfssl/wolfcrypt/wc_mlkem.h>
 
-#ifdef WOLFSSL_HAVE_MLKEM
+#if defined(WOLFSSL_HAVE_MLKEM) && !defined(WOLF_CRYPTO_CB_ONLY_MLKEM)
 XALIGNED(4) static const word16 L_mlkem_thumb2_ntt_zetas[] = {
     0x08ed, 0x0a0b, 0x0b9a, 0x0714, 0x05d5, 0x058e, 0x011f, 0x00ca,
     0x0c56, 0x026e, 0x0629, 0x00b6, 0x03c2, 0x084f, 0x073f, 0x05bc,
@@ -3889,7 +3889,7 @@ WC_OMIT_FRAME_POINTER unsigned int mlkem_thumb2_rej_uniform(sword16* p,
     return (word32)(size_t)p;
 }
 
-#endif /* WOLFSSL_HAVE_MLKEM */
+#endif /* WOLFSSL_HAVE_MLKEM && !WOLF_CRYPTO_CB_ONLY_MLKEM */
 
 #endif /* WOLFSSL_ARMASM_INLINE */
 #endif /* WOLFSSL_ARMASM_THUMB2 */

wolfcrypt/src/wc_mlkem.c

@@ -189,6 +189,7 @@ sword16 wc_mlkem_opt_blocker(void) {
  * @param  [in]  key  ML-KEM key object.
  * @return  k value for the key type, or 0 if not recognized.
  */
+#ifndef WOLF_CRYPTO_CB_ONLY_MLKEM
 static int mlkemkey_get_k(const MlKemKey* key)
 {
     switch (key->type) {
@@ -224,6 +225,7 @@ static int mlkemkey_get_k(const MlKemKey* key)
             return 0;
     }
 }
+#endif /* !WOLF_CRYPTO_CB_ONLY_MLKEM */
 #endif
 
 #ifdef WOLFSSL_MLKEM_DYNAMIC_KEYS
@@ -802,6 +804,19 @@ int wc_MlKemKey_MakeKey(MlKemKey* key, WC_RNG* rng)
 int wc_MlKemKey_MakeKeyWithRandom(MlKemKey* key, const unsigned char* rand,
     int len)
 {
+#ifdef WOLF_CRYPTO_CB_ONLY_MLKEM
+    /* Validate as the software path does, so the reported error stays the
+     * same for a bad call. */
+    if ((key == NULL) || (rand == NULL)) {
+        return BAD_FUNC_ARG;
+    }
+    if (len != WC_ML_KEM_MAKEKEY_RAND_SZ) {
+        return BUFFER_E;
+    }
+    /* No software fallback: only a crypto callback can service the request,
+     * and no callback takes caller-chosen key generation randomness. */
+    return NO_VALID_DEVID;
+#else
     byte buf[2 * WC_ML_KEM_SYM_SZ + 1];
     byte* rho = buf;
 #ifndef WC_MLKEM_FAULT_HARDEN
@@ -1036,6 +1051,7 @@ int wc_MlKemKey_MakeKeyWithRandom(MlKemKey* key, const unsigned char* rand,
      * function and has the RNG parameter needed for encapsulation. */
 
     return ret;
+#endif /* WOLF_CRYPTO_CB_ONLY_MLKEM */
 }
 #endif /* !WOLFSSL_MLKEM_NO_MAKE_KEY */
 
@@ -1131,6 +1147,7 @@ int wc_MlKemKey_SharedSecretSize(MlKemKey* key, word32* len)
 
 #if !defined(WOLFSSL_MLKEM_NO_ENCAPSULATE) || \
     !defined(WOLFSSL_MLKEM_NO_DECAPSULATE)
+#ifndef WOLF_CRYPTO_CB_ONLY_MLKEM
 /* Encrypt a message to cipher text with the encryption key.
  *
  * FIPS 203, Algorithm 14: K-PKE.Encrypt(ek_PKE, m, r)
@@ -1379,10 +1396,12 @@ static int mlkemkey_encapsulate(MlKemKey* key, const byte* m, byte* r, byte* c)
 
     return ret;
 }
+#endif /* !WOLF_CRYPTO_CB_ONLY_MLKEM */
 #endif
 
 #if !defined(WOLFSSL_MLKEM_NO_ENCAPSULATE) || \
     !defined(WOLFSSL_MLKEM_NO_DECAPSULATE)
+#ifndef WOLF_CRYPTO_CB_ONLY_MLKEM
 static int wc_mlkemkey_check_h(MlKemKey* key)
 {
     int ret = 0;
@@ -1424,6 +1443,7 @@ static int wc_mlkemkey_check_h(MlKemKey* key)
 
     return ret;
 }
+#endif /* !WOLF_CRYPTO_CB_ONLY_MLKEM */
 #endif
 
 #ifndef WOLFSSL_MLKEM_NO_ENCAPSULATE
@@ -1552,6 +1572,22 @@ int wc_MlKemKey_Encapsulate(MlKemKey* key, unsigned char* ct, unsigned char* ss,
 int wc_MlKemKey_EncapsulateWithRandom(MlKemKey* key, unsigned char* ct,
     unsigned char* ss, const unsigned char* rand, int len)
 {
+#ifdef WOLF_CRYPTO_CB_ONLY_MLKEM
+    /* Validate as the software path does, so the reported error stays the
+     * same for a bad call. */
+    if ((key == NULL) || (ct == NULL) || (ss == NULL) || (rand == NULL)) {
+        return BAD_FUNC_ARG;
+    }
+    if (len != WC_ML_KEM_ENC_RAND_SZ) {
+        return BUFFER_E;
+    }
+    if ((key->flags & MLKEM_FLAG_PUB_SET) == 0) {
+        return BAD_STATE_E;
+    }
+    /* No software fallback: only a crypto callback can service the request,
+     * and no callback takes caller-chosen encapsulation randomness. */
+    return NO_VALID_DEVID;
+#else
 #ifdef WOLFSSL_MLKEM_KYBER
     byte msg[WC_ML_KEM_SYM_SZ];
 #endif
@@ -1723,12 +1759,14 @@ int wc_MlKemKey_EncapsulateWithRandom(MlKemKey* key, unsigned char* ct,
 #endif
 
     return ret;
+#endif /* WOLF_CRYPTO_CB_ONLY_MLKEM */
 }
 #endif /* !WOLFSSL_MLKEM_NO_ENCAPSULATE */
 
 /******************************************************************************/
 
 #ifndef WOLFSSL_MLKEM_NO_DECAPSULATE
+#ifndef WOLF_CRYPTO_CB_ONLY_MLKEM
 /* Decapsulate cipher text to the message using key.
  *
  * FIPS 203, Algorithm 15: K-PKE.Decrypt(dk_PKE,c)
@@ -1893,6 +1931,7 @@ static MLKEM_NOINLINE int mlkemkey_decapsulate(MlKemKey* key, byte* m,
 
     return ret;
 }
+#endif /* !WOLF_CRYPTO_CB_ONLY_MLKEM */
 
 /**
  * Decapsulate the cipher text to calculate the shared secret.
@@ -1941,16 +1980,18 @@ static MLKEM_NOINLINE int mlkemkey_decapsulate(MlKemKey* key, byte* m,
 int wc_MlKemKey_Decapsulate(MlKemKey* key, unsigned char* ss,
     const unsigned char* ct, word32 len)
 {
-    byte msg[WC_ML_KEM_SYM_SZ];
-    byte kr[2 * WC_ML_KEM_SYM_SZ + 1];
     int ret = 0;
     unsigned int ctSz = 0;
+#ifndef WOLF_CRYPTO_CB_ONLY_MLKEM
+    byte msg[WC_ML_KEM_SYM_SZ];
+    byte kr[2 * WC_ML_KEM_SYM_SZ + 1];
     unsigned int i = 0;
     int fail = 0;
 #if !defined(USE_INTEL_SPEEDUP) && !defined(WOLFSSL_NO_MALLOC)
     byte* cmp = NULL;
 #else
     byte cmp[WC_ML_KEM_MAX_CIPHER_TEXT_SIZE];
+#endif
 #endif
 
     /* Validate parameters. */
@@ -2025,6 +2066,14 @@ int wc_MlKemKey_Decapsulate(MlKemKey* key, unsigned char* ss,
     }
 #endif
 
+#ifdef WOLF_CRYPTO_CB_ONLY_MLKEM
+    if (ret == 0) {
+        /* No software fallback: only a crypto callback can service
+         * the request. */
+        ret = NO_VALID_DEVID;
+    }
+#else
+
 #if !defined(USE_INTEL_SPEEDUP) && !defined(WOLFSSL_NO_MALLOC)
     if (ret == 0) {
         /* Allocate memory for cipher text that is generated. */
@@ -2119,6 +2168,7 @@ int wc_MlKemKey_Decapsulate(MlKemKey* key, unsigned char* ss,
     wc_MemZero_Check(msg, sizeof(msg));
     wc_MemZero_Check(kr, sizeof(kr));
 #endif
+#endif /* WOLF_CRYPTO_CB_ONLY_MLKEM */
 
     return ret;
 }