Global keystore

[bigbrett]

Adds support for global keys, enabling cryptographic keys to be shared across multiple wolfHSM clients. When a key is marked as global, it becomes accessible to all clients rather than being isolated to the client that cached it. The global keycache is currently located in the NVM context, as this is the only global state accessible from every server struct instance, and also serves to explicitly indicate the NVM (if there were to be multiple instances) that should be used as the backing store.

Also refactors wrapped keys to use a similar signaling mechanism to the server, such that they can be stored as a different keytype, enabling them to have the same client-facing IDs as regular keys, meaning the feature is able to coexist with dynamic ID generation for non-wrapped keys.

Feature Additions

• Refactors key cache into its own structure that can be instantiated either locally (in a server context) or globally (in the NVM context)
• Adds new global keycache to NVM struct and new keyId translation macros that handle managing client's global indicator flag
• Refactors crypto and keystore layers to properly handle global keys
• Refactors wrapped key support to use an indicator flag in the keyId, enabling separate keyId space
• Adds new multi-client test harness, currently supporting only sequential operations, and adds global key tests to it
• Adds default keyId for tests that don't care about it

Details

• Global keys stored in globalCache in NVM context (shared across all servers)
• Local keys remain in per-client localCache in server context
• Global keys are indicated to the server by the client setting the WH_KEYID_GLOBAL bit in the keyId (bit 8) when caching/using global keys (e.g. a client specifying keyId of 0x1005 indicates global key 5, whereas 0x0005 indicates client-local key 5)
• Server strips the flag and associates key with USER=WH_KEYUSER_GLOBAL==0 encoding via WH_TRANSLATE_CLIENT_KEYID macro
• Cache routing via _GetCacheContext() helper allows the server to automatically select the appropriate cache based on the updated user field
• Refactors wrapped keys to use the same scheme, but instead of storing the key to the global user, it stores it as different keytype.

  Client API:                                                                                                                                                                                                                                                                                                                 
  // Mark key as global                                                                                                                                                                                                                                                                                                       
  whKeyId globalKey = WH_MAKE_KEYID_GLOBAL(5);                                                                                                                                                                                                                                                                                
  wh_Client_KeyCache(client, globalKey, data, len, ...);                                                                                                                                                                                                                                                                      
                                                                                                                                                                                                                                                                                                                              
  // Regular local key (not shared)                                                                                                                                                                                                                                                                                           
  whKeyId localKey = 10;                                                                                                                                                                                                                                                                                                      
  wh_Client_KeyCache(client, localKey, data, len, ...);

[Copilot]

Pull Request Overview

This PR implements global keystore functionality, enabling cryptographic keys to be shared across multiple wolfHSM clients. The feature refactors the key cache architecture to support both client-local and globally accessible keys, with the global cache residing in the NVM context to ensure visibility across all server instances.

Key changes:

• Refactors cache structures into a unified whKeyCacheContext that can be instantiated globally or locally
• Adds client-facing macros (WH_MAKE_KEYID_GLOBAL) and server-side translation logic (WH_TRANSLATE_CLIENT_KEYID) to manage global key routing
• Implements comprehensive multi-client test suite validating global key operations, isolation, and persistence

Reviewed Changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
wolfhsm/wh_server_cache.h	New header defining unified cache structures to avoid circular dependencies
wolfhsm/wh_common.h	Adds global key flag definitions and client-to-server keyId translation macros
wolfhsm/wh_nvm.h	Adds global cache field to NVM context when feature enabled
wolfhsm/wh_server.h	Refactors server to use unified cache structure for local keys
wolfhsm/wh_client.h	Adds client-facing helper macro for marking keys as global
wolfhsm/wh_settings.h	Documents new configuration option
src/wh_server_keystore.c	Core refactor implementing cache routing and global key support
src/wh_server_crypto.c	Updates all crypto operations to use translation macro
src/wh_server_cert.c	Updates certificate operations for global key support
src/wh_server.c	Adds validation preventing client_id=0 (reserved for global keys)
src/wh_nvm.c	Initializes global cache during NVM setup
test/wh_test_multiclient.{h,c}	New multi-client test framework and comprehensive test suite
test/wh_test_*.c	Updates tests to use default client ID constant
test/config/wolfhsm_cfg.h	Enables global keys for testing

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[AlexLanzano]

Initial high level review. Just some minor questions and concerns. Great work otherwise

[Copilot]

Pull Request Overview

Copilot reviewed 36 out of 37 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[AlexLanzano]

Whoops meant to approve

[billphipps]

Excellent addition and awesome testing! I had a few questions and nits, but nothing that would stop this from being merged.