PKCS#11: add ML-KEM support

Add PKCS#11 integration for ML-KEM with key generation,
encapsulation and decapsulation support through the crypto
callback path.

Includes ML-KEM PKCS#11 constants/types, key store handling,
token object lifecycle management, and ML-KEM key init helpers
for private-key ID/label workflows.

Align implementation details with current upstream conventions
and review feedback:
- internal wolfCrypt ML-KEM path only for PKCS#11
- inline ML-KEM key-type/flag checks in PKCS#11 code
- proper key template formatting and enum placement
- ensure TLS ML-KEM object storage behavior is compatible with
  PKCS#11 ephemeral-key decapsulation flow

Author: Frauschi

.wolfssl_known_macro_extras

@@ -421,6 +421,7 @@ NO_PKCS11_ECDH
 NO_PKCS11_EC_KEYGEN
 NO_PKCS11_HMAC
 NO_PKCS11_MLDSA
+NO_PKCS11_MLKEM
 NO_PKCS11_RNG
 NO_PKCS11_RSA
 NO_PKCS11_RSA_PKCS

src/tls.c

@@ -8596,7 +8596,9 @@ static int TLSX_KeyShare_GenEccKey(WOLFSSL *ssl, KeyShareEntry* kse)
 }
 
 #ifdef WOLFSSL_HAVE_MLKEM
-#if defined(WOLFSSL_MLKEM_CACHE_A) && \
+#if (defined(WOLFSSL_MLKEM_CACHE_A) || \
+    (defined(HAVE_PKCS11) && defined(WOLFSSL_WC_MLKEM) && \
+     !defined(NO_PKCS11_MLKEM))) && \
     !defined(WOLFSSL_TLSX_PQC_MLKEM_STORE_PRIV_KEY)
     /* Store KyberKey object rather than private key bytes in key share entry.
      * Improves performance at cost of more dynamic memory being used. */
@@ -9957,6 +9959,11 @@ static int TLSX_KeyShare_ProcessPqcClient_ex(WOLFSSL* ssl,
     XFREE(keyShareEntry->ke, ssl->heap, DYNAMIC_TYPE_PUBLIC_KEY);
     keyShareEntry->ke = NULL;
 
+#ifndef WOLFSSL_TLSX_PQC_MLKEM_STORE_OBJ
+    ForceZero(keyShareEntry->privKey, keyShareEntry->privKeyLen);
+    XFREE(keyShareEntry->privKey, ssl->heap, DYNAMIC_TYPE_PRIVATE_KEY);
+    keyShareEntry->privKey = NULL;
+#endif
     return ret;
 }
 
@@ -10045,6 +10052,7 @@ static int TLSX_KeyShare_ProcessPqcHybridClient(WOLFSSL* ssl,
         int type;
 
         pqc_kse->privKey = keyShareEntry->privKey;
+        keyShareEntry->privKey = NULL;
 
         ret = mlkem_id2type(pqc_group, &type);
         if (ret != 0) {
@@ -10068,6 +10076,7 @@ static int TLSX_KeyShare_ProcessPqcHybridClient(WOLFSSL* ssl,
         }
     #else
         pqc_kse->key = keyShareEntry->privKey;
+        keyShareEntry->privKey = NULL;
     #endif
 
         pqc_kse->group = pqc_group;

wolfcrypt/src/wc_mlkem.c

@@ -75,6 +75,9 @@
 #include <wolfssl/wolfcrypt/wc_mlkem.h>
 #include <wolfssl/wolfcrypt/hash.h>
 #include <wolfssl/wolfcrypt/memory.h>
+#ifdef WOLF_CRYPTO_CB
+    #include <wolfssl/wolfcrypt/cryptocb.h>
+#endif
 
 #ifdef NO_INLINE
     #include <wolfssl/wolfcrypt/misc.h>
@@ -298,9 +301,13 @@ int wc_MlKemKey_Init(MlKemKey* key, int type, void* heap, int devId)
         /* Cache heap pointer. */
         key->heap = heap;
     #ifdef WOLF_CRYPTO_CB
-        /* Cache device id - not used in this algorithm yet. */
+        key->devCtx = NULL;
         key->devId = devId;
     #endif
+#ifdef WOLF_PRIVATE_KEY_ID
+        key->idLen = 0;
+        key->labelLen = 0;
+#endif
         key->flags = 0;
 
         /* Zero out all data. */
@@ -322,6 +329,58 @@ int wc_MlKemKey_Init(MlKemKey* key, int type, void* heap, int devId)
     return ret;
 }
 
+#ifdef WOLF_PRIVATE_KEY_ID
+int wc_MlKemKey_Init_Id(MlKemKey* key, int type, const unsigned char* id,
+    int len, void* heap, int devId)
+{
+    int ret = 0;
+
+    if (key == NULL || (id == NULL && len != 0)) {
+        ret = BAD_FUNC_ARG;
+    }
+    if (ret == 0 && (len < 0 || len > MLKEM_MAX_ID_LEN)) {
+        ret = BUFFER_E;
+    }
+
+    if (ret == 0) {
+        ret = wc_MlKemKey_Init(key, type, heap, devId);
+    }
+    if (ret == 0 && id != NULL && len != 0) {
+        XMEMCPY(key->id, id, (size_t)len);
+        key->idLen = len;
+    }
+
+    return ret;
+}
+
+int wc_MlKemKey_Init_Label(MlKemKey* key, int type, const char* label,
+    void* heap, int devId)
+{
+    int ret = 0;
+    int labelLen = 0;
+
+    if (key == NULL || label == NULL) {
+        ret = BAD_FUNC_ARG;
+    }
+    if (ret == 0) {
+        labelLen = (int)XSTRLEN(label);
+        if ((labelLen == 0) || (labelLen > MLKEM_MAX_LABEL_LEN)) {
+            ret = BUFFER_E;
+        }
+    }
+
+    if (ret == 0) {
+        ret = wc_MlKemKey_Init(key, type, heap, devId);
+    }
+    if (ret == 0) {
+        XMEMCPY(key->label, label, (size_t)labelLen);
+        key->labelLen = labelLen;
+    }
+
+    return ret;
+}
+#endif
+
 /**
  * Free the Kyber key object.
  *
@@ -330,7 +389,22 @@ int wc_MlKemKey_Init(MlKemKey* key, int type, void* heap, int devId)
  */
 int wc_MlKemKey_Free(MlKemKey* key)
 {
+#if defined(WOLF_CRYPTO_CB) && defined(WOLF_CRYPTO_CB_FREE)
+    int ret = 0;
+#endif
+
     if (key != NULL) {
+#if defined(WOLF_CRYPTO_CB) && defined(WOLF_CRYPTO_CB_FREE)
+        if (key->devId != INVALID_DEVID) {
+            ret = wc_CryptoCb_Free(key->devId, WC_ALGO_TYPE_PK,
+                WC_PK_TYPE_PQC_KEM_KEYGEN, WC_PQC_KEM_TYPE_KYBER, (void*)key);
+            if (ret != WC_NO_ERR_TRACE(CRYPTOCB_UNAVAILABLE)) {
+                return ret;
+            }
+            /* fall-through to software cleanup */
+        }
+        (void)ret;
+#endif
         /* Dispose of PRF object. */
         mlkem_prf_free(&key->prf);
         /* Dispose of hash object. */
@@ -382,6 +456,21 @@ int wc_MlKemKey_MakeKey(MlKemKey* key, WC_RNG* rng)
         ret = BAD_FUNC_ARG;
     }
 
+#ifdef WOLF_CRYPTO_CB
+    if ((ret == 0)
+    #ifndef WOLF_CRYPTO_CB_FIND
+        && (key->devId != INVALID_DEVID)
+    #endif
+    ) {
+        ret = wc_CryptoCb_MakePqcKemKey(rng, WC_PQC_KEM_TYPE_KYBER,
+                                        key->type, key);
+        if (ret != WC_NO_ERR_TRACE(CRYPTOCB_UNAVAILABLE))
+            return ret;
+        /* fall-through when unavailable */
+        ret = 0;
+    }
+#endif
+
     if (ret == 0) {
         /* Generate random to use with PRFs.
          * Step 1: d is 32 random bytes
@@ -1063,12 +1152,33 @@ int wc_MlKemKey_Encapsulate(MlKemKey* key, unsigned char* c, unsigned char* k,
 #ifndef WC_NO_RNG
     int ret = 0;
     unsigned char m[WC_ML_KEM_ENC_RAND_SZ];
+#ifdef WOLF_CRYPTO_CB
+    word32 ctlen = 0;
+#endif
 
     /* Validate parameters. */
     if ((key == NULL) || (c == NULL) || (k == NULL) || (rng == NULL)) {
         ret = BAD_FUNC_ARG;
     }
 
+#ifdef WOLF_CRYPTO_CB
+    if (ret == 0) {
+        ret = wc_MlKemKey_CipherTextSize(key, &ctlen);
+    }
+    if ((ret == 0)
+    #ifndef WOLF_CRYPTO_CB_FIND
+        && (key->devId != INVALID_DEVID)
+    #endif
+    ) {
+        ret = wc_CryptoCb_PqcEncapsulate(c, ctlen, k, KYBER_SS_SZ, rng,
+                                         WC_PQC_KEM_TYPE_KYBER, key);
+        if (ret != WC_NO_ERR_TRACE(CRYPTOCB_UNAVAILABLE))
+            return ret;
+        /* fall-through when unavailable */
+        ret = 0;
+    }
+#endif
+
     if (ret == 0) {
         /* Generate seed for use with PRFs.
          * Step 1: m is 32 random bytes
@@ -1531,6 +1641,21 @@ int wc_MlKemKey_Decapsulate(MlKemKey* key, unsigned char* ss,
         ret = BUFFER_E;
     }
 
+#ifdef WOLF_CRYPTO_CB
+    if ((ret == 0)
+    #ifndef WOLF_CRYPTO_CB_FIND
+        && (key->devId != INVALID_DEVID)
+    #endif
+    ) {
+        ret = wc_CryptoCb_PqcDecapsulate(ct, ctSz, ss, KYBER_SS_SZ,
+                                         WC_PQC_KEM_TYPE_KYBER, key);
+        if (ret != WC_NO_ERR_TRACE(CRYPTOCB_UNAVAILABLE))
+            return ret;
+        /* fall-through when unavailable */
+        ret = 0;
+    }
+#endif
+
 #if !defined(USE_INTEL_SPEEDUP) && !defined(WOLFSSL_NO_MALLOC)
     if (ret == 0) {
         /* Allocate memory for cipher text that is generated. */