Implement HW/SW crypto affinity #281

AlexLanzano · 2026-02-04T21:22:32Z

Add SetCryptoAffinity API for runtime HW/SW crypto selection

Summary

This PR adds a new client API to dynamically switch between hardware and software cryptographic implementations at runtime. This allows clients to control whether the server uses crypto callbacks (hardware acceleration) or pure software wolfCrypt implementations.

Changes

New Client API (wh_client.c, wh_client.h)
- wh_Client_SetCryptoAffinity() - blocking call
- wh_Client_SetCryptoAffinityRequest() / wh_Client_SetCryptoAffinityResponse() - async API
New Message Types (wh_message_comm.c, wh_message_comm.h)
- WH_MESSAGE_COMM_ACTION_SET_CRYPTO_AFFINITY action
- WH_CRYPTO_AFFINITY_SW / WH_CRYPTO_AFFINITY_HW enum values
- Request/response structures with translation functions
Server Handler (wh_server.c, wh_server.h)
- Added configDevId field to preserve the original configured device ID
- Handler switches devId between INVALID_DEVID (SW) and configDevId (HW)
Tests (wh_test_clientserver.c)
- Added _testCryptoAffinity() to verify SW/HW switching behavior
Documentation (docs/draft/crypto_affinity.md)
- API usage guide with examples

Usage

int32_t server_rc;
uint32_t affinity;

// Switch to software crypto
wh_Client_SetCryptoAffinity(client, WH_CRYPTO_AFFINITY_SW, &server_rc, &affinity);

// Switch to hardware crypto (if configured)
wh_Client_SetCryptoAffinity(client, WH_CRYPTO_AFFINITY_HW, &server_rc, &affinity);

Copilot

Pull request overview

This PR implements a new client API to dynamically switch between hardware and software cryptographic implementations at runtime. The feature allows clients to control whether the server uses hardware acceleration (via crypto callbacks) or pure software wolfCrypt implementations by modifying the server's devId field.

Changes:

New client API with both blocking and async variants for setting crypto affinity
Server handler to process affinity change requests with proper validation and error handling
New message types and translation functions for client-server communication
Comprehensive test coverage including edge cases and error conditions

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
wolfhsm/wh_server.h	Added `configDevId` field to preserve original device ID configuration
wolfhsm/wh_message_comm.h	Defined message action, enum values, and request/response structures
wolfhsm/wh_error.h	Added `WH_ERROR_BADCONFIG` error code for configuration failures
wolfhsm/wh_client.h	Declared new client API functions with comprehensive documentation
src/wh_server.c	Implemented initialization of `configDevId` and request handler with validation
src/wh_message_comm.c	Implemented message translation functions following existing patterns
src/wh_client.c	Implemented client APIs with proper error handling and retry logic
test/wh_test_clientserver.c	Added comprehensive test coverage for various scenarios
docs/draft/crypto_affinity.md	Created API documentation with usage examples and return code reference

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

test/wh_test_clientserver.c

docs/draft/crypto_affinity.md

Copilot

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 2 comments.

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

test/wh_test_crypto_affinity.c

Copilot

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 3 comments.

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

test/wh_test_crypto_affinity.c

wolfhsm/wh_message_comm.h

test/wh_test_crypto_affinity.h

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

bigbrett

Nice work. Some tweaks required and some deeper architectural questions.

bigbrett · 2026-02-06T19:08:36Z

docs/draft/crypto_affinity.md

+```c
+enum WH_CRYPTO_AFFINITY_ENUM {
+    WH_CRYPTO_AFFINITY_SW = 0,  // Use software crypto (devId = INVALID_DEVID)
+    WH_CRYPTO_AFFINITY_HW = 1,  // Use hardware crypto (devId = configured value)


Suggested change

WH_CRYPTO_AFFINITY_HW = 1, // Use hardware crypto (devId = configured value)

WH_CRYPTO_AFFINITY_HW = 1, // Attempt hardware crypto (devId = configured value)

bigbrett · 2026-02-06T19:09:51Z

docs/draft/crypto_affinity.md

@@ -0,0 +1,92 @@
+# SetCryptoAffinity Client API
+
+The SetCryptoAffinity feature allows a client to control whether the server uses **software** or **hardware** cryptographic implementations.


Suggested change

The SetCryptoAffinity feature allows a client to control whether the server uses **software** or **hardware** cryptographic implementations.

The SetCryptoAffinity feature allows a client to control whether the server should use **software** or attempt to use a **hardware** cryptographic implementation when processing crypto requests.

Also add a blurb describing how it applies to future requests, vs just one. Also mention default values.

bigbrett · 2026-02-06T19:13:14Z

wolfhsm/wh_client.h

Just for flexibility, should we add a GetCryptoAffinity too?

bigbrett · 2026-02-06T19:24:55Z

src/wh_server.c

+                    resp.rc               = WH_ERROR_OK;
+                    break;
+                case WH_CRYPTO_AFFINITY_HW:
+#ifdef WOLF_CRYPTO_CB


we don't need to check against WOLF_CRYPTO_CB, we error out in wh_settings.h if this isn't defined. All crypto depends on it.

bigbrett · 2026-02-06T19:32:46Z

src/wh_server.c

+                    if (server->crypto->configDevId != INVALID_DEVID) {
+                        server->crypto->devId = server->crypto->configDevId;
+                        resp.rc               = WH_ERROR_OK;
+                    }


This is a bit confusing to reason about, not because of anything you are doing, but because we really aren't saying "prefer HW" here, but rather "prefer the devId you were initialized with, vs overriding it to software". I think from the clients perspective this is fine, but could you add a comment here explaining what is going on?

I appreciate the thoughtful handling of if the server's configDevId is INVALID_DEVID though. This will help provide feedback to the client for annoying dumb scenarios like if you have native HW support in wolfCrypt for a platform (e.g. part of the underlying algo implementation, not supplied via cryptoCb) where toggling this doesn't do anything.

I think adding a comment to briefly summarize this and why we are checking would be helpful.

bigbrett · 2026-02-06T20:02:17Z

test/wh_test_crypto_affinity.c

Instead of setting up YANTH (yet another test harness) do you think we could integrate this into wh_test_clientserver.c:whTest_ClientServerSequential()`? Fine to just register the test crypto callback as part of that function as long as it isn't destructive or interferes with other stuff? I don't believe that test runs crypto tests anyway. Could always register it on the fly too if needed.

Ideally we have as few harnesses as possible, and a bunch of generic test drivers that can be run within any harness

For readability and organization sake I believe it's best to keep this separate from wh_test_clientserver.c. From a user perspective it's immediately apparent where how this specific affinity feature is tested instead of having to reason about a generic test function.

bigbrett · 2026-02-06T20:07:09Z

src/wh_server.c

+    case WH_MESSAGE_COMM_ACTION_SET_CRYPTO_AFFINITY: {
+        whMessageCommSetCryptoAffinityRequest  req  = {0};
+        whMessageCommSetCryptoAffinityResponse resp = {0};
+


need to check req_size == sizeof(req) to guard against underflow. If a short packet arrives, the translate function reads past the buffer

bigbrett · 2026-02-06T20:08:22Z

test/wh_test_crypto_affinity.c

+
+static int whTest_CryptoAffinityNoCb(void)
+{
+    int      rc        = 0;


bigbrett · 2026-02-06T20:10:24Z

src/wh_server.c

+            resp.affinity = WH_CRYPTO_AFFINITY_SW;
+        }
+        else {
+            switch (req.affinity) {


currently only have 2 cases so perhaps just if() else {}? Otherwise logic on 308 is broken now too.

bigbrett · 2026-02-06T20:20:05Z

src/wh_server.c

+    case WH_MESSAGE_COMM_ACTION_SET_CRYPTO_AFFINITY: {
+        whMessageCommSetCryptoAffinityRequest  req  = {0};
+        whMessageCommSetCryptoAffinityResponse resp = {0};
+
+        wh_MessageComm_TranslateSetCryptoAffinityRequest(
+            magic, (const whMessageCommSetCryptoAffinityRequest*)req_packet,
+            &req);
+
+#ifndef WOLFHSM_CFG_NO_CRYPTO
+        if (server->crypto == NULL) {
+            resp.rc       = WH_ERROR_ABORTED;
+            resp.affinity = WH_CRYPTO_AFFINITY_SW;
+        }
+        else {
+            switch (req.affinity) {
+                case WH_CRYPTO_AFFINITY_SW:
+                    server->crypto->devId = INVALID_DEVID;
+                    resp.rc               = WH_ERROR_OK;
+                    break;
+                case WH_CRYPTO_AFFINITY_HW:
+#ifdef WOLF_CRYPTO_CB
+                    if (server->crypto->configDevId != INVALID_DEVID) {
+                        server->crypto->devId = server->crypto->configDevId;
+                        resp.rc               = WH_ERROR_OK;
+                    }
+                    else {
+                        resp.rc = WH_ERROR_BADCONFIG;
+                    }
+                    break;
+#else
+                    resp.rc = WH_ERROR_NOTIMPL;
+                    break;
+#endif
+                default:
+                    resp.rc = WH_ERROR_BADARGS;
+                    break;
+            }
+            resp.affinity = (server->crypto->devId == INVALID_DEVID)
+                                ? WH_CRYPTO_AFFINITY_SW
+                                : WH_CRYPTO_AFFINITY_HW;
+        }
+#else
+        resp.rc       = WH_ERROR_NOTIMPL;
+        resp.affinity = WH_CRYPTO_AFFINITY_SW;
+#endif
+
+        wh_MessageComm_TranslateSetCryptoAffinityResponse(
+            magic, &resp, (whMessageCommSetCryptoAffinityResponse*)resp_packet);
+        *out_resp_size = sizeof(resp);
+    }; break;


in light of my other comment on this being part of the comm group, all of this begs the question: should the affinity persist across client comm connect/disconnects? Or should a disconnect trigger a restoration of the affinity to the default config value? I'm leaning towards the latter.

This would need to be handled in the user's server app, no?

Copilot

Pull request overview

Copilot reviewed 29 out of 30 changed files in this pull request and generated 7 comments.

Comments suppressed due to low confidence (1)

wolfhsm/wh_server.h:72

Removing devId from whServerCryptoContext is an API/ABI breaking change for downstream users that initialize this public struct (previously .devId = INVALID_DEVID). If this is intentional, it should be called out in release notes/migration docs; otherwise consider providing a compatibility shim (e.g., keep the field behind a deprecated macro) to avoid breaking existing integrations.

#ifndef WOLFHSM_CFG_NO_CRYPTO

typedef struct whServerCryptoContext {
#ifndef WC_NO_RNG
    WC_RNG rng[1];
#endif
} whServerCryptoContext;

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

src/wh_server.c

examples/posix/wh_posix_server/wh_posix_server.c

docs/draft/crypto_affinity.md

docs/src/chapter03.md

docs/src-ja/chapter03.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

bigbrett · 2026-02-10T22:22:06Z

benchmark/wh_bench.c


    /* Initialize RNG */
-    ret = wc_InitRng_ex(crypto->rng, NULL, crypto->devId);
+    ret = wc_InitRng_ex(crypto->rng, NULL, INVALID_DEVID);


per our discussion we talked about removing the global devId, but I'm now realizing that we do still need it to exist for this use case. RNG is the one thing that does make sense to keep global, since initialization is expensive. I think we need to keep the global crypto->devId so the RNG can be initialized with it, but the server stack allocated crypto can instead hold its own "active" devId that is either INVALID_DEVID for SW affinity or use crypto->devId for HW affinity. Key point being, the devId is still globally held, used for RNG, but not otherwise able to have cross-client effects for crypto requested by a client

AlexLanzano requested a review from Copilot February 4, 2026 21:22

Copilot started reviewing on behalf of AlexLanzano February 4, 2026 21:23 View session

Copilot AI reviewed Feb 4, 2026

View reviewed changes

test/wh_test_clientserver.c Outdated Show resolved Hide resolved

test/wh_test_clientserver.c Outdated Show resolved Hide resolved

docs/draft/crypto_affinity.md Show resolved Hide resolved

AlexLanzano requested a review from Copilot February 4, 2026 22:11

AlexLanzano force-pushed the crypto-hw-sw-affinity branch from e3fe789 to 571a0c7 Compare February 4, 2026 22:15

Copilot started reviewing on behalf of AlexLanzano February 4, 2026 22:20 View session

Copilot AI reviewed Feb 4, 2026

View reviewed changes

test/wh_test_crypto_affinity.c Outdated Show resolved Hide resolved

test/wh_test_crypto_affinity.c Outdated Show resolved Hide resolved

AlexLanzano force-pushed the crypto-hw-sw-affinity branch from 571a0c7 to 3655e5c Compare February 4, 2026 22:39

AlexLanzano requested a review from Copilot February 5, 2026 15:15

Copilot started reviewing on behalf of AlexLanzano February 5, 2026 15:27 View session

Copilot AI reviewed Feb 5, 2026

View reviewed changes

test/wh_test_crypto_affinity.c Outdated Show resolved Hide resolved

wolfhsm/wh_message_comm.h Show resolved Hide resolved

test/wh_test_crypto_affinity.h Outdated Show resolved Hide resolved

AlexLanzano force-pushed the crypto-hw-sw-affinity branch from 9949065 to 506f420 Compare February 5, 2026 19:08

AlexLanzano requested a review from Copilot February 5, 2026 19:18

Copilot AI reviewed Feb 5, 2026

View reviewed changes

Copilot started reviewing on behalf of AlexLanzano February 5, 2026 19:59 View session

AlexLanzano marked this pull request as ready for review February 5, 2026 20:53

AlexLanzano assigned bigbrett Feb 5, 2026

AlexLanzano requested review from bigbrett and billphipps February 5, 2026 20:53

AlexLanzano assigned billphipps Feb 5, 2026

AlexLanzano force-pushed the crypto-hw-sw-affinity branch from f1de629 to 55fe3ab Compare February 5, 2026 21:04

bigbrett requested changes Feb 6, 2026

View reviewed changes

bigbrett marked this pull request as draft February 10, 2026 15:49

AlexLanzano added 2 commits February 10, 2026 13:57

Implement HW/SW crypto affinity

153ba3a

Address comments

c1e2cbd

AlexLanzano force-pushed the crypto-hw-sw-affinity branch 3 times, most recently from d426556 to b109054 Compare February 10, 2026 19:31

Move devId from crypto context into server context

b109054

AlexLanzano requested a review from Copilot February 10, 2026 19:39

Copilot started reviewing on behalf of AlexLanzano February 10, 2026 19:40 View session

Copilot AI reviewed Feb 10, 2026

View reviewed changes

Update docs/draft/crypto_affinity.md

c72c40c

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

AlexLanzano marked this pull request as ready for review February 10, 2026 19:53

AlexLanzano requested a review from bigbrett February 10, 2026 19:53

bigbrett requested changes Feb 10, 2026

View reviewed changes

	WH_CRYPTO_AFFINITY_HW = 1, // Use hardware crypto (devId = configured value)
	WH_CRYPTO_AFFINITY_HW = 1, // Attempt hardware crypto (devId = configured value)

		@@ -0,0 +1,92 @@
		# SetCryptoAffinity Client API

		The SetCryptoAffinity feature allows a client to control whether the server uses software or hardware cryptographic implementations.

Implement HW/SW crypto affinity #281

Are you sure you want to change the base?

Implement HW/SW crypto affinity #281

Conversation

AlexLanzano commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add SetCryptoAffinity API for runtime HW/SW crypto selection

Summary

Changes

Usage

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

bigbrett left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

AlexLanzano commented Feb 4, 2026 •

edited

Loading