Add global keys feature with comprehensive multi-client testing and keywrap

compatibility.

Key changes:
- Add WOLFHSM_CFG_GLOBAL_KEYS feature flag and configuration
- Implement global key cache in NVM context separate from local caches
- Add keyId translation layer between client flags and server encoding
- Create unified cache routing infrastructure for local/global keys
- Add comprehensive multi-client test suite with 15+ test cases
- Update all crypto/keystore operations to support global keys
- Major refactor to keywrap feature to add clientId-based access control and
  addiional test coverage for wrap/unwrap scenarios with global and local keys
- Standardize client_id usage across benchmarks and tests
- Add new wh_keyid module for keyId manipulation helpers

Author: bigbrett

benchmark/wh_bench.c

@@ -52,6 +52,9 @@
 
 #if defined(WOLFHSM_CFG_BENCH_ENABLE)
 
+/* Default client ID for benchmarks */
+#define WH_BENCH_CLIENT_ID (1)
+
 /* Buffer sizes for transport */
 /* Large enough to handle an RSA 4096 key */
 #define BUFFER_SIZE \
@@ -815,7 +818,7 @@ static whCommClientConfig          g_mem_cc_conf = {
              .transport_cb      = &g_mem_tccb,
              .transport_context = (void*)&g_mem_tmcc,
              .transport_config  = (void*)&g_mem_tmcf,
-             .client_id         = 123,
+             .client_id         = WH_BENCH_CLIENT_ID,
 };
 
 static whTransportServerCb         g_mem_tscb    = WH_TRANSPORT_MEM_SERVER_CB;
@@ -867,7 +870,7 @@ static int _configureClientTransport(whBenchTransportType transport,
                 .transport_cb      = pttcClientShmCb,
                 .transport_context = (void*)&tccShm,
                 .transport_config  = (void*)&myshmconfig,
-                .client_id         = 12,
+                .client_id         = WH_BENCH_CLIENT_ID,
             };
 
             memset(&tccShm, 0, sizeof(posixTransportShmClientContext));
@@ -887,7 +890,7 @@ static int _configureClientTransport(whBenchTransportType transport,
                 .transport_cb      = &pttcClientTcpCb,
                 .transport_context = (void*)&tccTcp,
                 .transport_config  = (void*)&mytcpconfig,
-                .client_id         = 12,
+                .client_id         = WH_BENCH_CLIENT_ID,
             };
 
             memset(&tccTcp, 0, sizeof(posixTransportTcpClientContext));

examples/demo/client/wh_demo_client_keywrap.c

@@ -35,13 +35,13 @@
 
 #ifdef WOLFHSM_CFG_KEYWRAP
 
-#define WH_TEST_KEKID 1
+#define WH_DEMO_KEYWRAP_KEKID 1
 static int _InitServerKek(whClientContext* ctx)
 {
     /* IMPORTANT NOTE: Server KEK is typically intrinsic or set during
      * provisioning. Uploading the KEK via the client is for testing purposes
      * only and not intended as a recommendation */
-    whKeyId    serverKeyId             = WH_TEST_KEKID;
+    whKeyId    serverKeyId             = WH_DEMO_KEYWRAP_KEKID;
     whNvmFlags flags                   = WH_NVM_FLAGS_NONEXPORTABLE;
     uint8_t    label[WH_NVM_LABEL_LEN] = "Server KEK key";
     uint8_t    kek[] = {0x03, 0x03, 0x0d, 0xd9, 0xeb, 0x18, 0x17, 0x2e,
@@ -55,43 +55,44 @@ static int _InitServerKek(whClientContext* ctx)
 
 static int _CleanupServerKek(whClientContext* ctx)
 {
-    return wh_Client_KeyErase(ctx, WH_TEST_KEKID);
+    return wh_Client_KeyErase(ctx, WH_DEMO_KEYWRAP_KEKID);
 }
 
 #ifndef NO_AES
 #ifdef HAVE_AESGCM
 
-#define WH_TEST_AES_KEYSIZE 16
-#define WH_TEST_AES_TEXTSIZE 16
-#define WH_TEST_AES_IVSIZE 12
-#define WH_TEST_AES_TAGSIZE 16
-#define WH_TEST_AES_WRAPPED_KEYSIZE                                   \
-    (WH_TEST_AES_IVSIZE + WH_TEST_AES_TAGSIZE + WH_TEST_AES_KEYSIZE + \
-     sizeof(whNvmMetadata))
-#define WH_TEST_AESGCM_WRAPKEY_ID 8
+#define WH_DEMO_KEYWRAP_AES_KEYSIZE 16
+#define WH_DEMO_KEYWRAP_AES_TEXTSIZE 16
+#define WH_DEMO_KEYWRAP_AES_IVSIZE 12
+#define WH_DEMO_KEYWRAP_AES_TAGSIZE 16
+#define WH_DEMO_KEYWRAP_AES_WRAPPED_KEYSIZE                     \
+    (WH_DEMO_KEYWRAP_AES_IVSIZE + WH_DEMO_KEYWRAP_AES_TAGSIZE + \
+     WH_DEMO_KEYWRAP_AES_KEYSIZE + sizeof(whNvmMetadata))
+#define WH_DEMO_KEYWRAP_AESGCM_WRAPKEY_ID 8
 
 int wh_DemoClient_AesGcmKeyWrap(whClientContext* client)
 {
     int           ret = 0;
     Aes           aes[1];
     WC_RNG        rng[1];
-    uint8_t       key[WH_TEST_AES_KEYSIZE];
-    uint8_t       exportedKey[WH_TEST_AES_KEYSIZE];
+    uint8_t       key[WH_DEMO_KEYWRAP_AES_KEYSIZE];
+    uint8_t       exportedKey[WH_DEMO_KEYWRAP_AES_KEYSIZE];
     whNvmMetadata metadata = {
-        .id    = WH_MAKE_KEYID(WH_KEYTYPE_CRYPTO, 0, WH_TEST_AESGCM_WRAPKEY_ID),
-        .label = "AES Key Label",
+        .id = WH_CLIENT_KEYID_MAKE_WRAPPED_META(
+            client->comm->client_id, WH_DEMO_KEYWRAP_AESGCM_WRAPKEY_ID),
+        .label  = "AES Key Label",
         .access = WH_NVM_ACCESS_ANY,
-        .len    = WH_TEST_AES_KEYSIZE};
+        .len    = WH_DEMO_KEYWRAP_AES_KEYSIZE};
     whNvmMetadata exportedMetadata;
-    uint8_t       wrappedKey[WH_TEST_AES_WRAPPED_KEYSIZE];
+    uint8_t       wrappedKey[WH_DEMO_KEYWRAP_AES_WRAPPED_KEYSIZE];
     whKeyId       wrappedKeyId;
 
     const uint8_t plaintext[] = "hello, wolfSSL AES-GCM!";
     uint8_t       ciphertext[sizeof(plaintext)];
     uint8_t       decrypted[sizeof(plaintext)];
 
-    uint8_t       tag[WH_TEST_AES_TAGSIZE];
-    uint8_t       iv[WH_TEST_AES_IVSIZE];
+    uint8_t       tag[WH_DEMO_KEYWRAP_AES_TAGSIZE];
+    uint8_t       iv[WH_DEMO_KEYWRAP_AES_IVSIZE];
     const uint8_t aad[] = {0xfe, 0xed, 0xfa, 0xce, 0xde, 0xad, 0xbe,
                            0xef, 0xfe, 0xed, 0xfa, 0xce, 0xde, 0xad,
                            0xbe, 0xef, 0xab, 0xad, 0xda, 0xd2};
@@ -127,8 +128,8 @@ int wh_DemoClient_AesGcmKeyWrap(whClientContext* client)
 
     /* Now we request the server to wrap the key using the KEK we
      * establish above in the first step. */
-    ret = wh_Client_KeyWrap(client, WC_CIPHER_AES_GCM, WH_TEST_KEKID, key,
-                            sizeof(key), &metadata, wrappedKey,
+    ret = wh_Client_KeyWrap(client, WC_CIPHER_AES_GCM, WH_DEMO_KEYWRAP_KEKID,
+                            key, sizeof(key), &metadata, wrappedKey,
                             sizeof(wrappedKey));
     if (ret != 0) {
         printf("Failed to wh_Client_KeyWrap %d\n", ret);
@@ -144,9 +145,9 @@ int wh_DemoClient_AesGcmKeyWrap(whClientContext* client)
     /* Request the server to unwrap and cache the wrapped key we just created.
      * This will provide us back a key ID that the client can use to do crypto
      * operations */
-    ret = wh_Client_KeyUnwrapAndCache(client, WC_CIPHER_AES_GCM, WH_TEST_KEKID,
-                                      wrappedKey, sizeof(wrappedKey),
-                                      &wrappedKeyId);
+    ret = wh_Client_KeyUnwrapAndCache(client, WC_CIPHER_AES_GCM,
+                                      WH_DEMO_KEYWRAP_KEKID, wrappedKey,
+                                      sizeof(wrappedKey), &wrappedKeyId);
     if (ret != 0) {
         printf("Failed to wh_Client_KeyUnwrapAndCache %d\n", ret);
         goto cleanup_rng;
@@ -161,7 +162,8 @@ int wh_DemoClient_AesGcmKeyWrap(whClientContext* client)
 
     /* Set the key id for this AES context to the wrapped key ID that the server
      * provided us */
-    ret = wh_Client_AesSetKeyId(aes, wrappedKeyId);
+    ret =
+        wh_Client_AesSetKeyId(aes, WH_CLIENT_KEYID_MAKE_WRAPPED(wrappedKeyId));
     if (ret != 0) {
         printf("Failed to wh_Client_AesSetKeyId %d\n", ret);
         goto cleanup_aes;
@@ -207,12 +209,12 @@ int wh_DemoClient_AesGcmKeyWrap(whClientContext* client)
     /* Exporting a wrapped key */
 
     /* Request the server to unwrap and export the wrapped key we created */
-    ret = wh_Client_KeyUnwrapAndExport(client, WC_CIPHER_AES_GCM, WH_TEST_KEKID,
-                                       wrappedKey, sizeof(wrappedKey),
-                                       &exportedMetadata, exportedKey,
-                                       sizeof(exportedKey));
+    ret = wh_Client_KeyUnwrapAndExport(client, WC_CIPHER_AES_GCM,
+                                       WH_DEMO_KEYWRAP_KEKID, wrappedKey,
+                                       sizeof(wrappedKey), &exportedMetadata,
+                                       exportedKey, sizeof(exportedKey));
     if (ret != 0) {
-        printf("Failed to wh_Client_KeyUnwrapAndCache %d\n", ret);
+        printf("Failed to wh_Client_KeyUnwrapAndExport%d\n", ret);
         goto cleanup_aes;
     }
 

examples/demo/client/wh_demo_client_keywrap.h

@@ -3,6 +3,9 @@
 
 #include "wolfhsm/wh_client.h"
 
+/* Exposed in header so the demo server can obtain the ID for registration */
+#define WH_DEMO_KEYWRAP_AESGCM_WRAPKEY_ID 8
+
 int wh_DemoClient_KeyWrap(whClientContext* clientContext);
 
 #endif /* !DEMO_CLIENT_KEYWRAP_H_ */

examples/posix/wh_posix_client/wh_posix_client.c

@@ -69,6 +69,14 @@ static int wh_ClientTask(void* cf, const char* type, int test)
 
     ret = wh_Client_Init(client, config);
 
+    if (ret == 0) {
+        ret = wh_Client_CommInit(client, NULL, NULL);
+        if (ret != 0) {
+            printf("Failed to initialize client communication\n");
+            return -1;
+        }
+    }
+
     if (strcmp(type, "dma") == 0) {
 #ifdef WOLFSSL_STATIC_MEMORY
         printf("Setting up DMA heap with static memory buckets\n");
@@ -85,6 +93,7 @@ static int wh_ClientTask(void* cf, const char* type, int test)
 
     printf("Client connecting to server...\n");
     if (ret == 0 && test) {
+        printf("Running client demos...\n");
         return wh_DemoClient_All(client);
     }
 

examples/posix/wh_posix_client/wolfhsm_cfg.h

@@ -30,5 +30,6 @@
 #define WOLFHSM_CFG_HEXDUMP
 #define WOLFHSM_CFG_COMM_DATA_LEN 5000
 #define WOLFHSM_CFG_KEYWRAP
+#define WOLFHSM_CFG_GLOBAL_KEYS
 
 #endif /* WOLFHSM_CFG_H_ */

examples/posix/wh_posix_server/wh_posix_server.c

@@ -118,7 +118,6 @@ static int loadAndStoreKeys(whServerContext* server, whKeyId* outKeyId,
     return ret;
 }
 
-
 static int wh_ServerTask(void* cf, const char* keyFilePath, int keyId,
                          int clientId)
 {

examples/posix/wh_posix_server/wolfhsm_cfg.h

@@ -44,9 +44,11 @@
 #define WOLFHSM_CFG_CERTIFICATE_MANAGER
 #define WOLFHSM_CFG_CERTIFICATE_MANAGER_ACERT
 
+#define WOLFHSM_CFG_KEYWRAP
 #define WOLFHSM_CFG_KEYWRAP_MAX_KEY_SIZE 5000
 
+#define WOLFHSM_CFG_GLOBAL_KEYS
+
 #define XMEMFENCE() __atomic_thread_fence(__ATOMIC_SEQ_CST)
-#define WOLFHSM_CFG_KEYWRAP
 
 #endif /* WOLFHSM_CFG_H_ */

src/wh_client_keywrap.c

@@ -185,13 +185,16 @@ int wh_Client_KeyUnwrapAndExportResponse(whClientContext*   ctx,
     if (group != WH_MESSAGE_GROUP_KEY || action != WH_KEY_UNWRAPEXPORT ||
         size < sizeof(*resp) ||
         size > sizeof(*resp) + sizeof(*metadataOut) + keySz ||
-        resp->keySz != keySz || resp->cipherType != cipherType) {
+        resp->cipherType != cipherType) {
         return WH_ERROR_ABORTED;
     }
 
-    if (resp->rc != 0) {
+    if (resp->rc != WH_ERROR_OK) {
         return resp->rc;
     }
+    else if (resp->keySz != keySz) {
+        return WH_ERROR_BUFFER_SIZE;
+    }
 
     /* Copy the metadata and key from the response data into metadataOut and
      * keyOut */
@@ -298,6 +301,8 @@ int wh_Client_KeyUnwrapAndCacheResponse(whClientContext*   ctx,
         return resp->rc;
     }
 
+    /* Server returns ID portion only. Client must track ownership
+     * and specify appropriate flags when later using the key. */
     *keyIdOut = resp->keyId;
 
     return WH_ERROR_OK;

src/wh_keyid.c

@@ -0,0 +1,48 @@
+/*
+ * 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/>.
+ */
+/*
+ * src/wh_keyid.c
+ *
+ * KeyId helper function implementations for wolfHSM
+ */
+
+#include "wolfhsm/wh_keyid.h"
+
+whKeyId wh_KeyId_TranslateClient(uint16_t type, uint16_t clientId,
+                                 whKeyId reqId)
+{
+    uint16_t user = clientId;
+    whKeyId  id   = reqId & WH_KEYID_MASK;
+
+#ifdef WOLFHSM_CFG_GLOBAL_KEYS
+    /* Check for global flag (bit 8: 0x0100) */
+    if ((reqId & 0x0100) != 0) {
+        user = WH_KEYUSER_GLOBAL;
+    }
+#endif
+
+#ifdef WOLFHSM_CFG_KEYWRAP
+    /* Check for wrapped flag (bit 9: 0x0200) */
+    if ((reqId & 0x0200) != 0) {
+        type = WH_KEYTYPE_WRAPPED;
+    }
+#endif
+
+    return WH_MAKE_KEYID(type, user, id);
+}

src/wh_nvm.c

@@ -46,6 +46,11 @@ int wh_Nvm_Init(whNvmContext* context, const whNvmConfig *config)
     context->cb = config->cb;
     context->context = config->context;
 
+#if !defined(WOLFHSM_CFG_NO_CRYPTO) && defined(WOLFHSM_CFG_GLOBAL_KEYS)
+    /* Initialize the global key cache */
+    memset(&context->globalCache, 0, sizeof(context->globalCache));
+#endif
+
     if (context->cb->Init != NULL) {
         rc = context->cb->Init(context->context, config->config);
         if (rc != 0) {
@@ -64,6 +69,11 @@ int wh_Nvm_Cleanup(whNvmContext* context)
         return WH_ERROR_BADARGS;
     }
 
+#if !defined(WOLFHSM_CFG_NO_CRYPTO) && defined(WOLFHSM_CFG_GLOBAL_KEYS)
+    /* Initialize the global key cache */
+    memset(&context->globalCache, 0, sizeof(context->globalCache));
+#endif
+
     /* No callback? Return ABORTED */
     if (context->cb->Cleanup == NULL) {
         return WH_ERROR_ABORTED;