HW-only keys#409
Draft
bigbrett wants to merge 2 commits into
Draft
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds an optional “hardware keystore” front-end (WOLFHSM_CFG_HWKEYSTORE) and introduces a new hardware-only keyId signaling flag, allowing clients to reference hardware-resident KEKs for keywrap operations while ensuring the key material is never cached, persisted, or exported.
Changes:
- Adds the
wh_HwKeystore_*module (callback + optional lock) and wires it intowhServerContext/whServerConfigwhen enabled. - Extends keyId encoding/translation to support hardware-only keys (
WH_KEYID_CLIENT_HW_FLAG↔WH_KEYTYPE_HW) and updates server keystore policy to reject HW-only ids for all non-keywrap keystore operations. - Updates keywrap KEK resolution to fetch HW-only KEKs from the hardware keystore into a local buffer (with zeroization), and adds/refactors tests + documentation for the feature.
Reviewed changes
Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
wolfhsm/wh_settings.h |
Adds HW keystore config macros and default max HW key size. |
wolfhsm/wh_server.h |
Adds optional hwKeystore pointer in server config/context behind WOLFHSM_CFG_HWKEYSTORE. |
wolfhsm/wh_keyid.h |
Introduces HW-only client flag, WH_KEYTYPE_HW, and related helpers/docs. |
wolfhsm/wh_hwkeystore.h |
New public header defining the HW keystore front-end API and types. |
wolfhsm/wh_client.h |
Documents async DataWrap/DataUnwrap request/response APIs and adds WH_CLIENT_KEYID_MAKE_HW(). |
src/wh_server.c |
Plumbs hwKeystore from whServerConfig into whServerContext. |
src/wh_server_keystore.c |
Enforces HW-only keystore rejections and adds keywrap KEK resolution that can fetch HW KEKs. |
src/wh_keyid.c |
Implements HW-only flag ↔ type translation in keyId conversion helpers. |
src/wh_hwkeystore.c |
New implementation of the HW keystore front-end (validation + optional locking). |
test/config/wolfhsm_cfg.h |
Enables WOLFHSM_CFG_HWKEYSTORE in the legacy test configuration. |
test/wh_test_keywrap.h |
Adds declarations for HW keystore test callback/test case. |
test/wh_test_keywrap.c |
Adds legacy keywrap-focused HW-only KEK tests and a test backend callback. |
test/wh_test_crypto.c |
Binds the HW keystore into the in-process server config for relevant test paths. |
test-refactor/config/wolfhsm_cfg.h |
Enables WOLFHSM_CFG_HWKEYSTORE in refactor test configuration. |
test-refactor/wh_test_list.c |
Registers new HW keystore tests in misc/server groups. |
test-refactor/server/wh_test_hwkeystore_server.c |
New server-side unit tests for HW keystore module + keystore rejection behavior. |
test-refactor/misc/wh_test_hwkeystore.c |
New end-to-end HW-only KEK keywrap/datawrap tests using a private mem-transport client/server pair. |
docs/src/9-Configuration.md |
Documents new HW keystore configuration macros. |
docs/src/5-Features.md |
Adds a “Hardware-Only Keys” feature section describing behavior and constraints. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+95
to
+101
| rc = context->getKey(context->context, keyId, out, inout_len); | ||
|
|
||
| #ifdef WOLFHSM_CFG_THREADSAFE | ||
| (void)wh_Lock_Release(&context->lock); | ||
| #endif /* WOLFHSM_CFG_THREADSAFE */ | ||
|
|
||
| return rc; |
| int whTest_Client_HwKeystore(whClientContext* ctx); | ||
| #endif /* WOLFHSM_CFG_HWKEYSTORE && WOLFHSM_CFG_KEYWRAP */ | ||
|
|
||
| #endif /* WH_TEST_COMM_H_ */ |
Comment on lines
63
to
+67
| const whTestCase whTestsMisc[] = { | ||
| { "whTest_Comm", whTest_Comm }, | ||
| { "whTest_Dma", whTest_Dma }, | ||
| { "whTest_KeystoreReqSize", whTest_KeystoreReqSize }, | ||
| {"whTest_Comm", whTest_Comm}, | ||
| {"whTest_Dma", whTest_Dma}, | ||
| {"whTest_HwKeystore", whTest_HwKeystore}, | ||
| {"whTest_KeystoreReqSize", whTest_KeystoreReqSize}, |
Comment on lines
71
to
75
| const whTestCase whTestsServer[] = { | ||
| {"whTest_CertVerify", whTest_CertVerify}, | ||
| {"whTest_HwKeystoreServer", whTest_HwKeystoreServer}, | ||
| {"whTest_NvmOptional", whTest_NvmOptional}, | ||
| }; |
wolfSSL-Fenrir-bot
left a comment
wolfSSL-Fenrir-bot
left a comment
There was a problem hiding this comment.
Fenrir Automated Review — PR #409
Scan targets checked: wolfhsm-core-bugs, wolfhsm-crypto-bugs, wolfhsm-src
No new issues found in the changed files. ✅
Comment on lines
+116
to
+119
| #define WH_KEYTYPE_HW \ | ||
| 0x5 /* Hardware-only key. Material is served by a \ | ||
| * hardware keystore backend and never enters \ | ||
| * the key cache or NVM */ |
Comment on lines
+3589
to
+3593
| * Sets the hardware-only flag in a client keyId to indicate to the server | ||
| * that this key's material lives exclusively in a hardware keystore. The | ||
| * server will translate this to KEYTYPE=WH_KEYTYPE_HW and fetch the | ||
| * material from its hardware keystore backend on demand. | ||
| * |
| int whTest_Client_HwKeystore(whClientContext* ctx); | ||
| #endif /* WOLFHSM_CFG_HWKEYSTORE && WOLFHSM_CFG_KEYWRAP */ | ||
|
|
||
| #endif /* WH_TEST_COMM_H_ */ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds extremely basic support for hardware-only keys. Keys are tagged as hardware-only by the client through the upper keyId flag bits, just like global or wrapped keys. On the server-side the abstraction is a thin wrapper around a user-specified callback to retrieve the key.
The only server component that currently can use hardware-only keys is the keywrap module. Others could be brought online in the future.
Notably, this PR deliberately does NOT integrate caching hardware keys into the keycache, and therefore does not require adding a new keytype (yet). This means HW keys only exist transiently and there does not yet need to be any management/lifecycle/eviction.
Support for HW crypto with HW keys is therefore delegated to the platform-specific server-side crypto callbacks, since there is no "generic" way to handle this. The port's cryptoCb has direct access to the keyId and so can determine if it is a HW only keyId and can act appropriately.