Merge pull request #10077 from Frauschi/pkcs11-mlkem

Add ML-KEM support for PKCS#11

Author: dgarske

.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

@@ -8603,7 +8603,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. */

wolfcrypt/src/dilithium.c

@@ -10963,22 +10963,15 @@ int wc_dilithium_get_level(dilithium_key* key, byte* level)
  */
 void wc_dilithium_free(dilithium_key* 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,
+            (void)wc_CryptoCb_Free(key->devId, WC_ALGO_TYPE_PK,
                              WC_PK_TYPE_PQC_SIG_KEYGEN,
                              WC_PQC_SIG_TYPE_DILITHIUM,
                              (void*)key);
-            if (ret != WC_NO_ERR_TRACE(CRYPTOCB_UNAVAILABLE))
-                return;
-            /* fall-through to software cleanup */
+            /* always continue to software cleanup */
         }
-        (void)ret;
 #endif
 #ifdef WOLFSSL_WC_DILITHIUM
 #ifndef WC_DILITHIUM_FIXED_ARRAY

wolfcrypt/src/ecc.c

@@ -7930,23 +7930,19 @@ void wc_ecc_free_curve(ecc_set_type* curve, void* heap)
 WOLFSSL_ABI
 int wc_ecc_free(ecc_key* key)
 {
-#if defined(WOLF_CRYPTO_CB) && defined(WOLF_CRYPTO_CB_FREE)
-    int ret = 0;
-#endif
-
     if (key == NULL) {
         return 0;
     }
 
 #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,
+        /* Best-effort HSM resource release; errors are intentionally discarded
+         * so that software cleanup always runs and wc_ecc_free() retains its
+         * ABI guarantee of returning 0 on success. */
+        (void)wc_CryptoCb_Free(key->devId, WC_ALGO_TYPE_PK,
                          WC_PK_TYPE_EC_KEYGEN, 0, key);
-        if (ret != WC_NO_ERR_TRACE(CRYPTOCB_UNAVAILABLE))
-            return ret;
-        /* fall-through to software cleanup */
+        /* always continue to software cleanup */
     }
-    (void)ret;
 #endif
 
 #if defined(WOLFSSL_ECDSA_SET_K) || defined(WOLFSSL_ECDSA_SET_K_ONE_LOOP) || \
@@ -7960,6 +7956,7 @@ int wc_ecc_free(ecc_key* key)
         mp_free(key->sign_k);
 #ifndef WOLFSSL_NO_MALLOC
         XFREE(key->sign_k, key->heap, DYNAMIC_TYPE_ECC);
+        key->sign_k = NULL;
 #endif
     }
 #endif
@@ -8025,8 +8022,10 @@ int wc_ecc_free(ecc_key* key)
 #endif
 
 #ifdef WOLFSSL_CUSTOM_CURVES
-    if (key->deallocSet && key->dp != NULL)
+    if (key->deallocSet && key->dp != NULL) {
         wc_ecc_free_curve((ecc_set_type *)(wc_ptr_t)key->dp, key->heap);
+        key->dp = NULL;
+    }
 #endif
 
 #ifdef WOLFSSL_CHECK_MEM_ZERO

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,60 @@ 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) {
+        /* The string in key->label is not necessarily null-terminated.
+         * Use key->labelLen to get the length if required. */
+        XMEMCPY(key->label, label, (size_t)labelLen);
+        key->labelLen = labelLen;
+    }
+
+    return ret;
+}
+#endif
+
 /**
  * Free the Kyber key object.
  *
@@ -331,6 +392,15 @@ int wc_MlKemKey_Init(MlKemKey* key, int type, void* heap, int devId)
 int wc_MlKemKey_Free(MlKemKey* key)
 {
     if (key != NULL) {
+#if defined(WOLF_CRYPTO_CB) && defined(WOLF_CRYPTO_CB_FREE)
+        if (key->devId != INVALID_DEVID) {
+            (void)wc_CryptoCb_Free(key->devId, WC_ALGO_TYPE_PK,
+                                   WC_PK_TYPE_PQC_KEM_KEYGEN,
+                                   WC_PQC_KEM_TYPE_KYBER,
+                                   (void*)key);
+            /* always continue to software cleanup */
+        }
+#endif
         /* Dispose of PRF object. */
         mlkem_prf_free(&key->prf);
         /* Dispose of hash object. */
@@ -382,6 +452,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 +1148,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
@@ -1534,6 +1640,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. */