Add support for HKDF

Author: bigbrett

benchmark/bench_modules/wh_bench_mod_all.h

@@ -143,6 +143,12 @@ int wh_Bench_Mod_HmacSha3256(whClientContext* client, whBenchOpContext* ctx,
 int wh_Bench_Mod_HmacSha3256Dma(whClientContext* client, whBenchOpContext* ctx,
                                 int id, void* params);
 
+/* HKDF benchmark module prototypes (wh_bench_mod_hkdf.c) */
+#if defined(HAVE_HKDF)
+int wh_Bench_Mod_HkdfSha256(whClientContext* client, whBenchOpContext* ctx,
+                            int id, void* params);
+#endif /* HAVE_HKDF */
+
 /*
  * ECC benchmark module prototypes (wh_bench_mod_ecc.c)
  */

benchmark/bench_modules/wh_bench_mod_hkdf.c

@@ -0,0 +1,96 @@
+/*
+ * Copyright (C) 2025 wolfSSL Inc.
+ *
+ * This file is part of wolfHSM.
+ *
+ * wolfHSM is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * wolfHSM is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with wolfHSM.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "wh_bench_mod.h"
+#include "wolfhsm/wh_error.h"
+
+#include "wolfssl/wolfcrypt/hmac.h"
+#include "wolfssl/wolfcrypt/kdf.h"
+#include "wolfssl/wolfcrypt/sha256.h"
+
+#if defined(WOLFHSM_CFG_BENCH_ENABLE)
+
+#if defined(HAVE_HKDF)
+
+
+/* Output keying material size */
+#define WH_BENCH_HKDF_OKM_SIZE 42
+
+static int _benchHkdf(whClientContext* client, whBenchOpContext* ctx, int id,
+                      int devId)
+{
+    /* Simple fixed inputs for HKDF to measure performance. The data mirrors
+     * sizes from RFC 5869 test case 1 but we only care about timing here. */
+    static const uint8_t hkdf_ikm[] = {
+        0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b,
+        0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b};
+    static const uint8_t hkdf_salt[] = {0x00, 0x01, 0x02, 0x03, 0x04,
+                                        0x05, 0x06, 0x07, 0x08, 0x09,
+                                        0x0a, 0x0b, 0x0c};
+    static const uint8_t hkdf_info[] = {0xf0, 0xf1, 0xf2, 0xf3, 0xf4,
+                                        0xf5, 0xf6, 0xf7, 0xf8, 0xf9};
+
+
+    int     ret = 0;
+    uint8_t okm[WH_BENCH_HKDF_OKM_SIZE];
+    int     i;
+
+    (void)client;
+
+    for (i = 0; i < WOLFHSM_CFG_BENCH_KG_ITERS && ret == 0; i++) {
+        int benchStartRet;
+        int benchStopRet;
+
+        benchStartRet = wh_Bench_StartOp(ctx, id);
+        ret          = wc_HKDF_ex(WC_SHA256, hkdf_ikm, (word32)sizeof(hkdf_ikm),
+                                  hkdf_salt, (word32)sizeof(hkdf_salt), hkdf_info,
+                                  (word32)sizeof(hkdf_info), okm, (word32)sizeof(okm),
+                                  NULL, /* heap */
+                                  devId);
+        benchStopRet = wh_Bench_StopOp(ctx, id);
+
+        if (benchStartRet != 0) {
+            WH_BENCH_PRINTF("Failed to wh_Bench_StartOp %d\n", benchStartRet);
+            ret = benchStartRet;
+            break;
+        }
+        if (ret != 0) {
+            WH_BENCH_PRINTF("Failed to wc_HKDF_ex %d\n", ret);
+            break;
+        }
+        if (benchStopRet != 0) {
+            WH_BENCH_PRINTF("Failed to wh_Bench_StopOp %d\n", benchStopRet);
+            ret = benchStopRet;
+            break;
+        }
+    }
+
+    return ret;
+}
+
+int wh_Bench_Mod_HkdfSha256(whClientContext* client, whBenchOpContext* ctx,
+                            int id, void* params)
+{
+    (void)params;
+    return _benchHkdf(client, ctx, id, WH_DEV_ID);
+}
+
+#endif /* defined(HAVE_HKDF) */
+
+#endif /* WOLFHSM_CFG_BENCH_ENABLE */

benchmark/wh_bench.c

@@ -155,6 +155,11 @@ typedef enum BenchModuleIdx {
 #endif /* WOLFSSL_SHA3 */
 #endif /* !(NO_HMAC) */
 
+/* HKDF */
+#if defined(HAVE_HKDF)
+    BENCH_MODULE_IDX_HKDF_SHA2_256,
+#endif /* HAVE_HKDF */
+
 /* ECC */
 #if defined(HAVE_ECC)
     BENCH_MODULE_IDX_ECC_P256_SIGN,
@@ -314,6 +319,11 @@ static BenchModule g_benchModules[] = {
 #endif /* WOLFSSL_SHA3 */
 #endif /* !(NO_HMAC) */
 
+    /* HKDF */
+#if defined(HAVE_HKDF)
+    [BENCH_MODULE_IDX_HKDF_SHA2_256]           = {"HKDF-SHA2-256",               wh_Bench_Mod_HkdfSha256,            BENCH_THROUGHPUT_OPS, 0, NULL},
+#endif /* HAVE_HKDF */
+
     /* ECC */
 #if defined(HAVE_ECC)
     [BENCH_MODULE_IDX_ECC_P256_SIGN]           = {"ECC-P256-SIGN",                wh_Bench_Mod_EccP256Sign,            BENCH_THROUGHPUT_OPS, 0, NULL},

benchmark/wh_bench_ops.h

@@ -26,7 +26,7 @@
 #include <stdint.h>
 
 /* Maximum number of operations that can be registered */
-#define MAX_BENCH_OPS 83
+#define MAX_BENCH_OPS 84
 /* Maximum length of operation name */
 #define MAX_OP_NAME 64
 

examples/demo/client/wh_demo_client_all.c

@@ -114,6 +114,18 @@ int wh_DemoClient_All(whClientContext* clientContext)
     }
 #endif /* !NO_AES && HAVE_AESGCM */
 
+#ifdef HAVE_HKDF
+    rc = wh_DemoClient_CryptoHkdfExport(clientContext);
+    if (rc != 0) {
+        return rc;
+    }
+
+    rc = wh_DemoClient_CryptoHkdfCache(clientContext);
+    if (rc != 0) {
+        return rc;
+    }
+#endif /* HAVE_HKDF */
+
 #if defined(WOLFSSL_CMAC)
     rc = wh_DemoClient_CryptoCmac(clientContext);
     if (rc != 0) {

examples/demo/client/wh_demo_client_crypto.c

@@ -1357,3 +1357,96 @@ int wh_DemoClient_CryptoCmacOneshotImport(whClientContext* clientContext)
     return ret;
 }
 #endif /* WOLFSSL_CMAC && !NO_AES */
+
+#if defined(HAVE_HKDF)
+/*
+ * Demonstrates deriving key material using HKDF and exporting it directly to
+ * the client with the wolfCrypt API. This example provides the HKDF operation
+ * with input keying material (IKM), optional salt, and info. The derived output
+ * key material (OKM) is produced on the HSM and returned to the client buffer.
+ *
+ * After deriving the OKM, you can use it as a symmetric key (for example as an
+ * AES key) or application-specific secret.
+ */
+int wh_DemoClient_CryptoHkdfExport(whClientContext* clientContext)
+{
+    int ret   = 0;
+    int devId = WH_DEV_ID;
+    /* Example inputs for HKDF. The data mirrors sizes from RFC 5869 test case 1
+     */
+    const byte ikm[]  = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
+                         0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F};
+    const byte salt[] = {0xA0, 0xA1, 0xA2, 0xA3};
+    const byte info[] = {0xB0, 0xB1, 0xB2, 0xB3, 0xB4};
+    byte       okm[32]; /* 32 bytes for WC_SHA256-based HKDF */
+
+    (void)clientContext; /* Unused in the export form */
+
+    /* Derive 32 bytes using HKDF with SHA-256. The OKM is exported directly
+     * back to the client buffer 'okm'. */
+    ret = wc_HKDF_ex(WC_SHA256, ikm, sizeof(ikm), salt, sizeof(salt), info,
+                     sizeof(info), okm, (word32)sizeof(okm), NULL, devId);
+    if (ret != 0) {
+        printf("Failed to wc_HKDF_ex %d\n", ret);
+    }
+
+    /* At this point 'okm' holds the derived key material.
+     * Now you can use the key for your application. */
+
+    return ret;
+}
+
+/*
+ * Demonstrates deriving key material using HKDF and storing it in the HSM
+ * key cache. The client does not receive the key material; instead, it gets a
+ * keyId that can be used with compatible operations (for example, attaching
+ * the keyId to an AES context).
+ *
+ * After the key is cached, you can reference it by keyId for relevant
+ * operations. This example optionally evicts the cached key at the end.
+ */
+int wh_DemoClient_CryptoHkdfCache(whClientContext* clientContext)
+{
+    int     ret       = 0;
+    int     needEvict = 0;
+    whKeyId keyId     = WH_KEYID_ERASED;
+    /* Example inputs for HKDF. */
+    const byte     ikm[]  = {0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
+                             0x18, 0x19, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E, 0x1F};
+    const byte     salt[] = {0xC0, 0xC1, 0xC2, 0xC3};
+    const byte     info[] = {0xD0, 0xD1, 0xD2};
+    const uint32_t outSz  = 32; /* arbitrary output size */
+    /* Metadata flags/label for the cached key. Adjust to your requirements. */
+    whNvmFlags flags   = WH_NVM_FLAGS_NONE;
+    char       label[] = "hkdf-derived key";
+
+    /* Request the HSM to derive HKDF output and store it in the key cache.
+     * On success, 'keyId' is assigned by the HSM (unless pre-set) and can be
+     * used to reference the cached key material. */
+    ret = wh_Client_HkdfMakeCacheKey(
+        clientContext, WC_SHA256, ikm, (uint32_t)sizeof(ikm), salt,
+        (uint32_t)sizeof(salt), info, (uint32_t)sizeof(info), &keyId, flags,
+        (const uint8_t*)label, (uint32_t)strlen(label), outSz);
+    if (ret != WH_ERROR_OK) {
+        printf("Failed to wh_Client_HkdfMakeCacheKey %d\n", ret);
+        goto exit;
+    }
+
+    needEvict = 1;
+
+    /* Now you can use the cached key, referring to it by ID for relevant
+     * operations. */
+
+exit:
+    if (needEvict) {
+        int evictRet = wh_Client_KeyEvict(clientContext, keyId);
+        if (evictRet != 0) {
+            printf("Failed to wh_Client_KeyEvict %d\n", evictRet);
+            if (ret == 0) {
+                ret = evictRet;
+            }
+        }
+    }
+    return ret;
+}
+#endif /* HAVE_HKDF */

examples/demo/client/wh_demo_client_crypto.h

@@ -22,4 +22,9 @@ int wh_DemoClient_CryptoCmac(whClientContext* clientContext);
 int wh_DemoClient_CryptoCmacImport(whClientContext* clientContext);
 int wh_DemoClient_CryptoCmacOneshotImport(whClientContext* clientContext);
 
+#ifdef HAVE_HKDF
+int wh_DemoClient_CryptoHkdfExport(whClientContext* clientContext);
+int wh_DemoClient_CryptoHkdfCache(whClientContext* clientContext);
+#endif /* HAVE_HKDF */
+
 #endif /* !DEMO_CLIENT_CRYPTO_H_ */