Merge pull request #337 from bigbrett/async-crypto-v2

Async crypto v2

Author: AlexLanzano

.github/workflows/code-coverage.yml

@@ -45,7 +45,7 @@ jobs:
       run: |
         echo "=== Coverage Summary ==="
         cd test
-        gcovr --gcov-ignore-parse-errors="negative_hits.warn" Build --root .. --filter '\.\./src/.*' --filter '\.\./wolfhsm/.*' --print-summary
+        gcovr Build --root .. --gcov-ignore-parse-errors=negative_hits.warn_once_per_file --filter '\.\./src/.*' --filter '\.\./wolfhsm/.*' --print-summary
 
     # Upload coverage report as artifact
     - name: Upload coverage report

docs/draft/async-crypto.md

@@ -0,0 +1,67 @@
+# POSIX SHM DMA Transport
+
+## Overview
+
+There are two independent features at play in the POSIX SHM transport port. Understanding which is which is key.
+
+## 1. The Transport: POSIX Shared Memory (`posix_transport_shm`)
+
+This is purely a **transport layer** -- it moves request/response messages between client and server processes. It works like this:
+
+- **Server** creates a POSIX shared memory object (`shm_open`) with a layout of:
+  ```
+  [ 64-byte header | request buffer | response buffer | optional DMA section ]
+  ```
+- **Client** opens the same named object and `mmap`s it into its address space
+- Both sides then delegate to `wh_transport_mem` (the generic memory-based transport) for actual message passing via CSR registers in the request/response buffers
+- The header contains PIDs for RT-signal-based async notification
+
+The transport's job is **only** to shuttle serialized request/response packets. It knows nothing about crypto, keys, or DMA semantics.
+
+The optional **DMA section** at the end of the shared memory region is the transport providing a chunk of shared address space that *both* processes can access. This is just raw shared memory -- the transport allocates it but doesn't use it itself. It's plumbing for the DMA feature.
+
+## 2. The Feature: DMA (`WOLFHSM_CFG_DMA`)
+
+DMA is a **separate, transport-agnostic feature** in wolfHSM core (`wh_dma.h`, `wh_server_dma.c`, `wh_client_dma.c`). It allows crypto operations to reference client memory **by address** rather than copying data into the transport's request/response buffers. This matters because:
+
+- Standard messages are limited by `WOLFHSM_CFG_COMM_DATA_LEN` (typically ~4KB)
+- DMA messages send *addresses* in the request, and the server reads/writes client memory directly
+
+The DMA feature has a callback-based architecture:
+- `wh_Server_DmaProcessClientAddress()` -- server calls this with a client address, the registered callback transforms it to something the server can dereference
+- `wh_Client_DmaProcessClientAddress()` -- client calls this to transform its local address into whatever the server will receive in the message
+- PRE/POST operations handle setup and teardown (cache flush/invalidate, temporary buffer allocation, etc.)
+
+On real hardware (e.g. Infineon TC3xx), this is literal hardware DMA -- client and server are on different cores with different address maps, and the callbacks handle the MMU/bus address translation.
+
+## 3. The Glue: Static Memory Pool Allocator in the SHM DMA Callbacks
+
+The `posixTransportShm_ClientStaticMemDmaCallback` and `posixTransportShm_ServerStaticMemDmaCallback` in `posix_transport_shm.c` are the **port-specific DMA callbacks** that bridge the POSIX SHM transport with the DMA feature. Here's the clever part:
+
+**Problem:** On POSIX, client and server are separate processes with separate virtual address spaces. A raw client pointer like `0x7fff12345000` means nothing to the server. But the DMA section in shared memory is mapped into *both* processes (at potentially different virtual addresses).
+
+**Solution using the pool allocator:**
+
+1. wolfCrypt's `WOLFSSL_STATIC_MEMORY` pool allocator (`wc_LoadStaticMemory_ex`) is initialized with the DMA section as its backing memory pool
+2. When the client DMA callback gets a PRE operation with a client address that's **not** already in the DMA area, it:
+   - Allocates a temporary buffer from the pool (`XMALLOC` with the heap hint)
+   - Copies client data into it
+   - Returns an **offset** from the DMA base (not a pointer) -- this is what gets sent to the server
+3. The server DMA callback simply takes that offset, validates it's in bounds, and returns `dma_base + offset`
+4. On POST, the client callback copies results back (for writes) and frees the temporary buffer
+
+If the client address **is already** in the DMA section (the client allocated directly from the pool), it skips the copy and just computes the offset -- zero-copy.
+
+The pool allocator here is used as a **bump/slab allocator for the shared DMA region**. It has nothing to do with the transport itself -- it's the DMA callback's strategy for managing the shared buffer. wolfHSM could use a different allocator; the pool allocator was chosen because it's already available in wolfCrypt and works without `malloc`.
+
+## Summary Table
+
+| Aspect | Transport (SHM) | DMA Feature | Pool Allocator |
+|--------|-----------------|-------------|----------------|
+| **Layer** | Communication | Application/Crypto | Memory management |
+| **Scope** | Port-specific (POSIX) | Core wolfHSM | DMA callback impl detail |
+| **Purpose** | Move request/response packets | Let server access client memory by address | Manage temporary buffers in shared DMA area |
+| **Config** | `posixTransportShmConfig` | `WOLFHSM_CFG_DMA` | `WOLFSSL_STATIC_MEMORY` |
+| **Without it** | No communication | Data must fit in request/response buffers | Would need a different allocator for DMA region |
+
+The DMA section is **allocated by the transport** but **used by the DMA callbacks**. The pool allocator is **used by the DMA callbacks** to subdivide that DMA section. Three layers, three concerns.

docs/draft/posix-shm.md

@@ -23,9 +23,11 @@
  * DMA AND BUFFER SIZES
  * =========================================== */
 
-/* Request and Response Buffer Sizes */
-#define WH_POSIX_REQ_SIZE 2048
-#define WH_POSIX_RESP_SIZE 2048
+/* Request and Response Buffer Sizes. Must be at least
+ * sizeof(whTransportMemCsr) + sizeof(whCommHeader) + WOLFHSM_CFG_COMM_DATA_LEN
+ * to carry a full comm packet through the SHM transport. */
+#define WH_POSIX_REQ_SIZE (16 + (1024 * 8))
+#define WH_POSIX_RESP_SIZE (16 + (1024 * 8))
 #define WH_POSIX_DMA_SIZE 8000
 
 /* Data Buffer Sizes */

examples/posix/wh_posix_cfg.h

@@ -32,7 +32,7 @@
 /** wolfHSM settings */
 #define WOLFHSM_CFG_ENABLE_CLIENT
 #define WOLFHSM_CFG_HEXDUMP
-#define WOLFHSM_CFG_COMM_DATA_LEN 5000
+#define WOLFHSM_CFG_COMM_DATA_LEN (1024 * 8)
 #ifndef WOLFHSM_CFG_NO_CRYPTO
 #define WOLFHSM_CFG_KEYWRAP
 #define WOLFHSM_CFG_GLOBAL_KEYS

examples/posix/wh_posix_client/wolfhsm_cfg.h

@@ -34,8 +34,8 @@
 
 #define WOLFHSM_CFG_HEXDUMP
 
-/* Large enough for ML-DSA level 5 key */
-#define WOLFHSM_CFG_COMM_DATA_LEN 5000
+/* Must match client WOLFHSM_CFG_COMM_DATA_LEN */
+#define WOLFHSM_CFG_COMM_DATA_LEN (1024 * 8)
 
 #define WOLFHSM_CFG_NVM_OBJECT_COUNT 30
 #define WOLFHSM_CFG_SERVER_KEYCACHE_COUNT 9

examples/posix/wh_posix_server/wolfhsm_cfg.h

@@ -139,18 +139,18 @@ int wh_Client_SendRequest(whClientContext* c,
         uint16_t group, uint16_t action,
         uint16_t data_size, const void* data)
 {
-    int rc = 0;
+    int      rc     = 0;
     uint16_t req_id = 0;
-    uint16_t kind = WH_MESSAGE_KIND(group, action);
+    uint16_t kind   = WH_MESSAGE_KIND(group, action);
 
     if (c == NULL) {
         return WH_ERROR_BADARGS;
     }
     rc = wh_CommClient_SendRequest(c->comm, WH_COMM_MAGIC_NATIVE, kind, &req_id,
-        data_size, data);
+                                   data_size, data);
     if (rc == 0) {
         c->last_req_kind = kind;
-        c->last_req_id = req_id;
+        c->last_req_id   = req_id;
     }
     return rc;
 }
@@ -159,28 +159,24 @@ int wh_Client_RecvResponse(whClientContext *c,
         uint16_t *out_group, uint16_t *out_action,
         uint16_t *out_size, void* data)
 {
-    int rc = 0;
-    uint16_t resp_magic = 0;
+    int      rc        = 0;
     uint16_t resp_kind = 0;
-    uint16_t resp_id = 0;
+    uint16_t resp_id   = 0;
     uint16_t resp_size = 0;
 
     if (c == NULL) {
         return WH_ERROR_BADARGS;
     }
 
-    rc = wh_CommClient_RecvResponse(c->comm,
-                &resp_magic, &resp_kind, &resp_id,
-                &resp_size, data);
+    /* Comm layer performs magic and sequence validation */
+    rc = wh_CommClient_RecvResponse(c->comm, NULL, &resp_kind, &resp_id,
+                                    &resp_size, data);
     if (rc == 0) {
-        /* Validate response */
-        if (    (resp_magic != WH_COMM_MAGIC_NATIVE) ||
-                (resp_kind != c->last_req_kind) ||
-                (resp_id != c->last_req_id) ){
-            /* Invalid or unexpected message */
+        if ((resp_kind != c->last_req_kind) || (resp_id != c->last_req_id)) {
+            /* Response kind/id doesn't match outstanding request. */
             rc = WH_ERROR_ABORTED;
-        } else {
-            /* Valid and expected message. Set outputs */
+        }
+        else {
             if (out_group != NULL) {
                 *out_group = WH_MESSAGE_GROUP(resp_kind);
             }
@@ -195,6 +191,14 @@ int wh_Client_RecvResponse(whClientContext *c,
     return rc;
 }
 
+int wh_Client_IsRequestPending(const whClientContext* c)
+{
+    if (c == NULL) {
+        return WH_ERROR_BADARGS;
+    }
+    return wh_CommClient_IsRequestPending(c->comm);
+}
+
 int wh_Client_CommInitRequest(whClientContext* c)
 {
     whMessageCommInitRequest msg = {0};