Refactor to move crypto affinity state to client and add affinity field to generic crypto header

Author: bigbrett

docs/draft/crypto_affinity.md

@@ -1,130 +1,94 @@
 # Crypto Affinity Client API
 
-The crypto affinity feature allows a client to control and query whether the server uses **software** or **hardware** cryptographic implementations.
+The crypto affinity feature allows a client to control whether the server uses **software** or **hardware** cryptographic implementations on a per-request basis.
+
+Affinity is stored as **client-local state** and is transmitted to the server in every crypto request message header. There is no dedicated round-trip required to change affinity -- setting it is instantaneous and takes effect on the next crypto operation. Affinity persists for all subsequent requests once changed.
 
 ## Affinity Values
 
 ```c
 enum WH_CRYPTO_AFFINITY_ENUM {
-    WH_CRYPTO_AFFINITY_SW = 0,  // Use software crypto (devId = INVALID_DEVID)
-    WH_CRYPTO_AFFINITY_HW = 1,  // Attempt to use hardware crypto (devId = configured value)
+    WH_CRYPTO_AFFINITY_HW = 0,  // Attempt to use hardware crypto (devId = configured value)
+    WH_CRYPTO_AFFINITY_SW = 1,  // Use software crypto (devId = INVALID_DEVID)
 };
 ```
 
-## SetCryptoAffinity
+The default affinity after client initialization is `WH_CRYPTO_AFFINITY_HW`.
+
+## API
 
-### Blocking API (simplest)
+### SetCryptoAffinity
 
 ```c
-int wh_Client_SetCryptoAffinity(whClientContext* c, uint32_t affinity,
-        int32_t* out_rc, uint32_t* out_affinity);
+int wh_Client_SetCryptoAffinity(whClientContext* c, uint32_t affinity);
 ```
 
-### Non-blocking (async) API
+Sets the client's crypto affinity. This is a **local operation** that does not communicate with the server. The new affinity value will be included in all subsequent crypto request messages.
 
-```c
-// Send request
-int wh_Client_SetCryptoAffinityRequest(whClientContext* c, uint32_t affinity);
-
-// Receive response
-int wh_Client_SetCryptoAffinityResponse(whClientContext* c, int32_t* out_rc,
-        uint32_t* out_affinity);
-```
+**Parameters:**
+- `c` -- Client context
+- `affinity` -- `WH_CRYPTO_AFFINITY_SW` or `WH_CRYPTO_AFFINITY_HW`
 
-## GetCryptoAffinity
+**Returns:**
+- `WH_ERROR_OK` -- Affinity set successfully
+- `WH_ERROR_BADARGS` -- NULL context or invalid affinity value
 
-### Blocking API (simplest)
+### GetCryptoAffinity
 
 ```c
-int wh_Client_GetCryptoAffinity(whClientContext* c,
-        int32_t* out_rc, uint32_t* out_affinity);
+int wh_Client_GetCryptoAffinity(whClientContext* c, uint32_t* out_affinity);
 ```
 
-### Non-blocking (async) API
+Retrieves the client's current crypto affinity. This is a **local operation** that does not communicate with the server.
 
-```c
-// Send request
-int wh_Client_GetCryptoAffinityRequest(whClientContext* c);
+**Parameters:**
+- `c` -- Client context
+- `out_affinity` -- Pointer to receive the current affinity value
 
-// Receive response
-int wh_Client_GetCryptoAffinityResponse(whClientContext* c, int32_t* out_rc,
-        uint32_t* out_affinity);
-```
+**Returns:**
+- `WH_ERROR_OK` -- Affinity retrieved successfully
+- `WH_ERROR_BADARGS` -- NULL context or NULL output pointer
 
 ## Usage Example
 
 ```c
-int32_t  server_rc;
-uint32_t current_affinity;
-
-// Query current crypto affinity
-int rc = wh_Client_GetCryptoAffinity(client,
-        &server_rc,
-        &current_affinity);
-
-if (rc == WH_ERROR_OK && server_rc == WH_ERROR_OK) {
-    // current_affinity contains the active affinity
-}
+uint32_t affinity;
 
-// Switch to software crypto
-rc = wh_Client_SetCryptoAffinity(client,
-        WH_CRYPTO_AFFINITY_SW,
-        &server_rc,
-        &current_affinity);
-
-if (rc == WH_ERROR_OK && server_rc == WH_ERROR_OK) {
-    // Server is now using software crypto
-    // current_affinity == WH_CRYPTO_AFFINITY_SW
-}
-
-// Switch to hardware crypto
-rc = wh_Client_SetCryptoAffinity(client,
-        WH_CRYPTO_AFFINITY_HW,
-        &server_rc,
-        &current_affinity);
+/* Default affinity is WH_CRYPTO_AFFINITY_SW after wh_Client_Init() */
+wh_Client_GetCryptoAffinity(client, &affinity);
+/* affinity == WH_CRYPTO_AFFINITY_SW */
 
+/* Switch to hardware crypto -- takes effect immediately, no round-trip */
+int rc = wh_Client_SetCryptoAffinity(client, WH_CRYPTO_AFFINITY_HW);
 if (rc == WH_ERROR_OK) {
-    if (server_rc == WH_ERROR_OK) {
-        // Server is now using hardware crypto
-    } else if (server_rc == WH_ERROR_NOTIMPL) {
-        // HW crypto not available (server wasn't configured with a valid devId)
-    }
+    /* All subsequent crypto operations will request HW acceleration */
 }
-```
-
-## Return Values
 
-| Value | Description |
-|-------|-------------|
-| `rc` (function return) | Transport/communication errors |
-| `server_rc` (output parameter) | Server-side result |
+/* Perform a crypto operation -- affinity is sent in the request header */
+wc_AesCbcEncrypt(&aes, out, in, len);
+/* If server has a valid devId, hardware crypto callback is used */
 
-### Server Return Codes (SetCryptoAffinity)
-
-| Code | Description |
-|------|-------------|
-| `WH_ERROR_OK` | Affinity changed successfully |
-| `WH_ERROR_NOTIMPL` | HW requested but no HW crypto configured, `WOLF_CRYPTO_CB` is not defined, or `WOLFHSM_CFG_NO_CRYPTO` is defined |
-| `WH_ERROR_BADARGS` | Invalid affinity value |
-| `WH_ERROR_ABORTED` | Server crypto context is NULL |
+/* Switch back to software crypto */
+wh_Client_SetCryptoAffinity(client, WH_CRYPTO_AFFINITY_SW);
+/* Subsequent crypto operations use software implementation */
+```
 
-### Server Return Codes (GetCryptoAffinity)
+## Server Behavior
 
-| Code | Description |
-|------|-------------|
-| `WH_ERROR_OK` | Affinity queried successfully |
-| `WH_ERROR_ABORTED` | Server crypto context is NULL |
-| `WH_ERROR_NOTIMPL` | Not implemented (returned when `WOLFHSM_CFG_NO_CRYPTO` is defined) |
+When the server receives a crypto request, it reads the affinity field from the generic crypto request header and selects the appropriate `devId`:
 
-## Server Behavior
+| Affinity in Request | Server Action |
+|---------------------|---------------|
+| `WH_CRYPTO_AFFINITY_SW` | Uses `INVALID_DEVID` (wolfCrypt software implementation) |
+| `WH_CRYPTO_AFFINITY_HW` | Uses `server->defaultDevId` if valid, otherwise falls back to `INVALID_DEVID` |
 
-When affinity is set:
+The `defaultDevId` is configured at server initialization from `config->devId`. If the server was not configured with a valid hardware `devId`, hardware affinity requests will silently fall back to software crypto.
 
-| Affinity | Server Action |
-|----------|---------------|
-| `WH_CRYPTO_AFFINITY_SW` | `server->devId = INVALID_DEVID` (wolfCrypt uses software) |
-| `WH_CRYPTO_AFFINITY_HW` | `server->devId = server->defaultDevId` (wolfCrypt uses registered crypto callback) |
+## Protocol Details
 
-When affinity is queried (Get), the server reads the current `devId` and returns the corresponding affinity value without modifying any state.
+Affinity is transmitted in the `affinity` field of `whMessageCrypto_GenericRequestHeader`, which is included at the start of every crypto request message. This means:
 
-The `defaultDevId` is stored at server init from `config->devId`.
+- Each crypto operation independently specifies its desired affinity
+- Multiple clients can use different affinities concurrently without interference
+- No server-side affinity state is maintained per-client
+- Changing affinity has zero latency (no communication overhead)

src/wh_client.c

@@ -410,138 +410,26 @@ int wh_Client_CommInfo(whClientContext* c,
     return rc;
 }
 
-int wh_Client_SetCryptoAffinityRequest(whClientContext* c, uint32_t affinity)
+int wh_Client_SetCryptoAffinity(whClientContext* c, uint32_t affinity)
 {
-    whMessageCommSetCryptoAffinityRequest msg = {0};
-
-    if (c == NULL) {
-        return WH_ERROR_BADARGS;
-    }
-
-    msg.affinity = affinity;
-
-    return wh_Client_SendRequest(c, WH_MESSAGE_GROUP_COMM,
-                                 WH_MESSAGE_COMM_ACTION_SET_CRYPTO_AFFINITY,
-                                 sizeof(msg), &msg);
-}
-
-int wh_Client_SetCryptoAffinityResponse(whClientContext* c, int32_t* out_rc,
-                                        uint32_t* out_affinity)
-{
-    int                                    rc          = 0;
-    whMessageCommSetCryptoAffinityResponse msg         = {0};
-    uint16_t                               resp_group  = 0;
-    uint16_t                               resp_action = 0;
-    uint16_t                               resp_size   = 0;
-
     if (c == NULL) {
         return WH_ERROR_BADARGS;
     }
-
-    rc = wh_Client_RecvResponse(c, &resp_group, &resp_action, &resp_size, &msg);
-    if (rc == WH_ERROR_OK) {
-        /* Validate response */
-        if ((resp_group != WH_MESSAGE_GROUP_COMM) ||
-            (resp_action != WH_MESSAGE_COMM_ACTION_SET_CRYPTO_AFFINITY) ||
-            (resp_size != sizeof(msg))) {
-            /* Invalid message */
-            rc = WH_ERROR_ABORTED;
-        }
-        else {
-            /* Valid message */
-            if (out_rc != NULL) {
-                *out_rc = msg.rc;
-            }
-            if (out_affinity != NULL) {
-                *out_affinity = msg.affinity;
-            }
-        }
-    }
-    return rc;
-}
-
-int wh_Client_SetCryptoAffinity(whClientContext* c, uint32_t affinity,
-                                int32_t* out_rc, uint32_t* out_affinity)
-{
-    int rc = 0;
-    if (c == NULL) {
+    if (affinity != WH_CRYPTO_AFFINITY_SW &&
+        affinity != WH_CRYPTO_AFFINITY_HW) {
         return WH_ERROR_BADARGS;
     }
-    do {
-        rc = wh_Client_SetCryptoAffinityRequest(c, affinity);
-    } while (rc == WH_ERROR_NOTREADY);
-
-    if (rc == WH_ERROR_OK) {
-        do {
-            rc = wh_Client_SetCryptoAffinityResponse(c, out_rc, out_affinity);
-        } while (rc == WH_ERROR_NOTREADY);
-    }
-    return rc;
-}
-
-int wh_Client_GetCryptoAffinityRequest(whClientContext* c)
-{
-    if (c == NULL) {
-        return WH_ERROR_BADARGS;
-    }
-
-    return wh_Client_SendRequest(c, WH_MESSAGE_GROUP_COMM,
-                                 WH_MESSAGE_COMM_ACTION_GET_CRYPTO_AFFINITY,
-                                 0, NULL);
-}
-
-int wh_Client_GetCryptoAffinityResponse(whClientContext* c, int32_t* out_rc,
-                                        uint32_t* out_affinity)
-{
-    int                                    rc          = 0;
-    whMessageCommGetCryptoAffinityResponse msg         = {0};
-    uint16_t                               resp_group  = 0;
-    uint16_t                               resp_action = 0;
-    uint16_t                               resp_size   = 0;
-
-    if (c == NULL) {
-        return WH_ERROR_BADARGS;
-    }
-
-    rc = wh_Client_RecvResponse(c, &resp_group, &resp_action, &resp_size, &msg);
-    if (rc == 0) {
-        /* Validate response */
-        if ((resp_group != WH_MESSAGE_GROUP_COMM) ||
-            (resp_action != WH_MESSAGE_COMM_ACTION_GET_CRYPTO_AFFINITY) ||
-            (resp_size != sizeof(msg))) {
-            /* Invalid message */
-            rc = WH_ERROR_ABORTED;
-        }
-        else {
-            /* Valid message */
-            if (out_rc != NULL) {
-                *out_rc = msg.rc;
-            }
-            if (out_affinity != NULL) {
-                *out_affinity = msg.affinity;
-            }
-        }
-    }
-    return rc;
+    c->cryptoAffinity = affinity;
+    return WH_ERROR_OK;
 }
 
-int wh_Client_GetCryptoAffinity(whClientContext* c, int32_t* out_rc,
-                                uint32_t* out_affinity)
+int wh_Client_GetCryptoAffinity(whClientContext* c, uint32_t* out_affinity)
 {
-    int rc = 0;
-    if (c == NULL) {
+    if (c == NULL || out_affinity == NULL) {
         return WH_ERROR_BADARGS;
     }
-    do {
-        rc = wh_Client_GetCryptoAffinityRequest(c);
-    } while (rc == WH_ERROR_NOTREADY);
-
-    if (rc == 0) {
-        do {
-            rc = wh_Client_GetCryptoAffinityResponse(c, out_rc, out_affinity);
-        } while (rc == WH_ERROR_NOTREADY);
-    }
-    return rc;
+    *out_affinity = c->cryptoAffinity;
+    return WH_ERROR_OK;
 }