Add ExportPubKey support for ML-KEM

Author: Frauschi

CLAUDE.md

@@ -0,0 +1,99 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+wolfHSM is a portable client-server framework for hardware cryptography, non-volatile memory (NVM), and isolated secure processing. The server runs in a trusted environment; clients communicate via a message-based protocol. wolfCrypt APIs are automatically offloaded to the server as remote procedure calls. Targeted at automotive HSM-enabled microcontrollers but runs on any platform with a secure execution environment.
+
+## Build Commands
+
+All builds use Make. wolfSSL must be available at `../../wolfssl` relative to this repo (override with `WOLFSSL_DIR=`).
+
+```bash
+# Build and run tests (from repo root or test/)
+cd test && make -j && make run
+
+# Common build flags (combine as needed)
+make DEBUG=1              # Basic debug output
+make DEBUG_VERBOSE=1      # Verbose debug (implies DEBUG)
+make ASAN=1               # Address Sanitizer
+make TSAN=1               # Thread Sanitizer (requires THREADSAFE=1)
+make THREADSAFE=1         # Thread-safe mode with locking
+make DMA=1                # DMA support
+make SHE=1                # AUTOSAR SHE extensions
+make TLS=1                # TLS transport
+make COVERAGE=1           # Code coverage instrumentation
+make TESTWOLFCRYPT=1      # Run wolfCrypt test suite as client
+make CLIENT_ONLY=1        # Client-only (connects to remote server)
+make STRESS=1             # Stress testing (requires THREADSAFE=1)
+
+# Coverage report
+cd test && make coverage  # Builds, runs, generates ../coverage/index.html
+
+# Static analysis
+make scan                 # scan-build (excludes wolfSSL/wolfCrypt)
+
+# Benchmarks
+cd benchmark && make -j && make run
+
+# Examples
+cd examples/posix/wh_posix_server && make
+cd examples/posix/wh_posix_client && make
+
+# NVM tool
+cd tools/whnvmtool && make && make test
+```
+
+## Code Formatting
+
+Uses clang-format-15 (CI enforced). 4-space indent, 80-column limit, braces on new line after functions only, `else` on new line. Pointer alignment left (`int* p`). Run: `clang-format-15 -i <file>`.
+
+## Architecture
+
+### Client-Server Model
+
+- **Client** (`src/wh_client*.c`, `wolfhsm/wh_client*.h`): Sends requests to the server. Registers wolfCrypt crypto callbacks so wolfCrypt calls are transparently offloaded. Device IDs: `WH_DEV_ID` (0x5748534D) for standard ops, `WH_DEV_ID_DMA` (0x57444D41) for DMA ops.
+- **Server** (`src/wh_server*.c`, `wolfhsm/wh_server*.h`): Dispatches incoming requests to handlers for crypto, NVM, keystore, SHE, certificates, image management, counters, and custom callbacks.
+- **Communication** (`src/wh_comm.c`, `wolfhsm/wh_comm.h`): 8-byte header + variable payload (default 1280 bytes, configurable via `WOLFHSM_CFG_COMM_DATA_LEN`). Message groups: COMM, NVM, KEY, CRYPTO, IMAGE, PKCS11, SHE, COUNTER, CUSTOM, CRYPTO_DMA, CERT.
+
+### Transport Layer
+
+Pluggable transport backends behind a common interface:
+- `wh_transport_mem` — shared memory buffer (used in tests)
+- POSIX port: shared memory (pthread), TCP sockets, TLS over TCP
+
+### Non-Volatile Memory (NVM)
+
+Log-based flash storage with crash recovery (`wh_nvm_flash_log.c`). Objects have metadata (ID, access, flags, label). RAM flash simulator (`wh_flash_ramsim.c`) used for testing.
+
+### Key Management
+
+RAM key cache + persistent NVM storage. Keys have access control (per-client), usage policies (encrypt/decrypt/sign/verify/wrap/derive), and flags (non-exportable, sensitive, non-modifiable, etc.).
+
+### Platform Ports
+
+`port/` contains platform-specific implementations. `port/posix/` is the reference port (flash sim, transport, locks, logging). `port/skeleton/` is a template for new ports.
+
+## Configuration
+
+Three-layer configuration (lowest to highest priority):
+
+1. **`wolfhsm/wh_settings.h`** — defaults for all `WOLFHSM_CFG_*` macros
+2. **`wolfhsm_cfg.h`** — per-project overrides (included when `WOLFHSM_CFG` is defined). Test version at `test/config/wolfhsm_cfg.h`
+3. **Compiler `-D` flags** — set via Makefile variables
+
+wolfCrypt is configured separately via `user_settings.h` (test version at `test/config/user_settings.h`).
+
+## Testing
+
+Tests are in `test/`. Each module has its own `wh_test_<module>.c` file with a corresponding header. The main driver is `wh_test.c`. Tests must be portable (no system dependencies) except POSIX-specific tests gated by `WOLFHSM_CFG_TEST_POSIX`.
+
+## Error Codes
+
+Defined in `wolfhsm/wh_error.h`:
+- General: -2000 to -2010 (BADARGS, NOTREADY, ABORTED, TIMEOUT, etc.)
+- NVM: -2100 to -2105 (LOCKED, ACCESS, NOTFOUND, NOSPACE, etc.)
+- SHE: -2200 to -2211
+
+All wolfHSM functions return `int` where 0 is success (`WH_ERROR_OK`) and negative values are errors.

benchmark/config/user_settings.h

@@ -135,7 +135,6 @@ extern "C" {
 
 /* Dilithium Options */
 #define HAVE_DILITHIUM
-#define WOLFSSL_WC_DILITHIUM /* use wolfCrypt implementation, not libOQS */
 #define WOLFSSL_SHA3
 #define WOLFSSL_SHAKE128
 #define WOLFSSL_SHAKE256
@@ -157,7 +156,6 @@ extern "C" {
 
 /* ML-KEM Options */
 #define WOLFSSL_HAVE_MLKEM
-#define WOLFSSL_WC_MLKEM
 
 /** Composite features */
 #define HAVE_HKDF

docs/src-ja/chapter05.md

@@ -320,8 +320,12 @@ int wh_Client_Curve25519ExportPublicKey(whClientContext* ctx, whKeyId keyId,
         curve25519_key* key, uint16_t label_len, uint8_t* label);
 int wh_Client_MlDsaExportPublicKey(whClientContext* ctx, whKeyId keyId,
         MlDsaKey* key, uint16_t label_len, uint8_t* label);
+int wh_Client_MlKemExportPublicKey(whClientContext* ctx, whKeyId keyId,
+        MlKemKey* key, uint16_t label_len, uint8_t* label);
 ```
 
+DERベースのヘルパーとは異なり、ML-KEMは公開鍵を生のワイヤフォーマットバイト列として送信します（サイズは`WC_ML_KEM_MAX_PUBLIC_KEY_SIZE`）。クライアント側のデシリアライザはサポートされているレベルを順に試行します。汎用APIである`wh_Client_KeyExportPublic[Dma]`を直接呼び出す場合は、対応するアルゴリズムセレクタ`WH_KEY_ALGO_MLKEM`を使用します。
+
 例: HSM上でRSAの鍵ペアを生成し秘密鍵を`NONEXPORTABLE`でマークしたうえで、クライアント側で公開鍵を取得し、HSMがキャッシュされた秘密鍵で生成した署名を検証する。
 
 ```c
@@ -354,6 +358,8 @@ int wh_Client_KeyExportPublicDma(whClientContext* c, whKeyId keyId,
 
 int wh_Client_MlDsaExportPublicKeyDma(whClientContext* ctx, whKeyId keyId,
         MlDsaKey* key, uint16_t label_len, uint8_t* label);
+int wh_Client_MlKemExportPublicKeyDma(whClientContext* ctx, whKeyId keyId,
+        MlKemKey* key, uint16_t label_len, uint8_t* label);
 ```
 
 `wh_Client_KeyExportPublicDma`は汎用トランスポートで、呼び出し側は生の公開鍵DERを受け取って自身でデシリアライズします。`wh_Client_MlDsaExportPublicKeyDma`は既存の`wh_Client_MlDsaExportKeyDma`に対応するML-DSA専用ヘルパーで、ML-DSAの大きな公開鍵DERを通信バッファにコピーせずに済ませたい場合に使用できます。

docs/src/chapter05.md

@@ -313,8 +313,16 @@ int wh_Client_Curve25519ExportPublicKey(whClientContext* ctx, whKeyId keyId,
         curve25519_key* key, uint16_t label_len, uint8_t* label);
 int wh_Client_MlDsaExportPublicKey(whClientContext* ctx, whKeyId keyId,
         MlDsaKey* key, uint16_t label_len, uint8_t* label);
+int wh_Client_MlKemExportPublicKey(whClientContext* ctx, whKeyId keyId,
+        MlKemKey* key, uint16_t label_len, uint8_t* label);
 ```
 
+Unlike the DER-based helpers, ML-KEM emits the raw wire-format public key
+bytes (sized by `WC_ML_KEM_MAX_PUBLIC_KEY_SIZE`); the client deserializer
+probes the supported levels. `WH_KEY_ALGO_MLKEM` is the matching algo
+selector when calling the generic `wh_Client_KeyExportPublic[Dma]` API
+directly.
+
 Example: generate an RSA keypair on the HSM with the private key marked
 `NONEXPORTABLE`, obtain the public key on the client, and verify a signature
 the HSM produced using the cached private key.
@@ -359,6 +367,8 @@ int wh_Client_KeyExportPublicDma(whClientContext* c, whKeyId keyId,
 
 int wh_Client_MlDsaExportPublicKeyDma(whClientContext* ctx, whKeyId keyId,
         MlDsaKey* key, uint16_t label_len, uint8_t* label);
+int wh_Client_MlKemExportPublicKeyDma(whClientContext* ctx, whKeyId keyId,
+        MlKemKey* key, uint16_t label_len, uint8_t* label);
 ```
 
 `wh_Client_KeyExportPublicDma` is the generic transport — callers receive

examples/posix/wh_posix_server/user_settings.h

@@ -131,7 +131,6 @@ extern "C" {
 
 /* Dilithium Options */
 #define HAVE_DILITHIUM
-#define WOLFSSL_WC_DILITHIUM /* use wolfCrypt implementation, not libOQS */
 #define WOLFSSL_SHA3
 #define WOLFSSL_SHAKE128
 #define WOLFSSL_SHAKE256
@@ -153,7 +152,6 @@ extern "C" {
 
 /* ML-KEM Options */
 #define WOLFSSL_HAVE_MLKEM
-#define WOLFSSL_WC_MLKEM
 
 /** Composite features */
 #define HAVE_HKDF

src/wh_client_crypto.c

@@ -8196,6 +8196,26 @@ int wh_Client_MlKemExportKey(whClientContext* ctx, whKeyId keyId, MlKemKey* key,
     return ret;
 }
 
+int wh_Client_MlKemExportPublicKey(whClientContext* ctx, whKeyId keyId,
+                                   MlKemKey* key, uint16_t label_len,
+                                   uint8_t* label)
+{
+    int      ret;
+    byte     buffer[WC_ML_KEM_MAX_PUBLIC_KEY_SIZE] = {0};
+    uint16_t buffer_len = sizeof(buffer);
+
+    if ((ctx == NULL) || WH_KEYID_ISERASED(keyId) || (key == NULL)) {
+        return WH_ERROR_BADARGS;
+    }
+
+    ret = wh_Client_KeyExportPublic(ctx, keyId, WH_KEY_ALGO_MLKEM, label,
+                                    label_len, buffer, &buffer_len);
+    if (ret == WH_ERROR_OK) {
+        ret = wh_Crypto_MlKemDeserializeKey(buffer, buffer_len, key);
+    }
+    return ret;
+}
+
 static int _MlKemMakeKey(whClientContext* ctx, int level,
                          whKeyId* inout_key_id, whNvmFlags flags,
                          uint16_t label_len, uint8_t* label, MlKemKey* key)
@@ -8614,6 +8634,27 @@ int wh_Client_MlKemExportKeyDma(whClientContext* ctx, whKeyId keyId,
     return ret;
 }
 
+int wh_Client_MlKemExportPublicKeyDma(whClientContext* ctx, whKeyId keyId,
+                                      MlKemKey* key, uint16_t label_len,
+                                      uint8_t* label)
+{
+    int      ret;
+    byte     buffer[WC_ML_KEM_MAX_PUBLIC_KEY_SIZE] = {0};
+    uint16_t buffer_len = sizeof(buffer);
+
+    if ((ctx == NULL) || WH_KEYID_ISERASED(keyId) || (key == NULL)) {
+        return WH_ERROR_BADARGS;
+    }
+
+    ret = wh_Client_KeyExportPublicDma(ctx, keyId, WH_KEY_ALGO_MLKEM, buffer,
+                                       buffer_len, label, label_len,
+                                       &buffer_len);
+    if (ret == WH_ERROR_OK) {
+        ret = wh_Crypto_MlKemDeserializeKey(buffer, buffer_len, key);
+    }
+    return ret;
+}
+
 static int _MlKemMakeKeyDma(whClientContext* ctx, int level,
                             whKeyId* inout_key_id, whNvmFlags flags,
                             uint16_t label_len, uint8_t* label, MlKemKey* key)

src/wh_server_keystore.c

@@ -67,6 +67,9 @@
 #ifdef HAVE_DILITHIUM
 #include "wolfssl/wolfcrypt/dilithium.h"
 #endif
+#ifdef WOLFSSL_HAVE_MLKEM
+#include "wolfssl/wolfcrypt/wc_mlkem.h"
+#endif
 
 static int _FindInCache(whServerContext* server, whKeyId keyId, int* out_index,
                         int* out_big, uint8_t** out_buffer,
@@ -541,6 +544,47 @@ static int _ExportCurve25519PublicKey(whServerContext* server, whKeyId keyId,
 }
 #endif
 
+#ifdef WOLFSSL_HAVE_MLKEM
+static int _ExportMlkemPublicKey(whServerContext* server, whKeyId keyId,
+    uint8_t* out, uint16_t* outSz)
+{
+    int      ret = WH_ERROR_OK;
+    MlKemKey key[1];
+    word32   pubSize;
+    /* Pick the lowest compiled-in level as the initial hint;
+     * wh_Crypto_MlKemDeserializeKey (called via
+     * wh_Server_MlKemKeyCacheExport) probes the remaining enabled levels. */
+#ifndef WOLFSSL_NO_ML_KEM_512
+    const int initLevel = WC_ML_KEM_512;
+#elif !defined(WOLFSSL_NO_ML_KEM_768)
+    const int initLevel = WC_ML_KEM_768;
+#else
+    const int initLevel = WC_ML_KEM_1024;
+#endif
+
+    ret = wc_MlKemKey_Init(key, initLevel, NULL, INVALID_DEVID);
+    if (ret == 0) {
+        ret = wh_Server_MlKemKeyCacheExport(server, keyId, key);
+        if (ret == 0) {
+            ret = wc_MlKemKey_PublicKeySize(key, &pubSize);
+            if (ret == 0) {
+                if ((uint32_t)pubSize > (uint32_t)*outSz) {
+                    ret = WH_ERROR_NOSPACE;
+                }
+                else {
+                    ret = wc_MlKemKey_EncodePublicKey(key, out, pubSize);
+                    if (ret == 0) {
+                        *outSz = (uint16_t)pubSize;
+                    }
+                }
+            }
+        }
+        wc_MlKemKey_Free(key);
+    }
+    return ret;
+}
+#endif /* WOLFSSL_HAVE_MLKEM */
+
 int wh_Server_KeystoreGetUniqueId(whServerContext* server, whNvmId* inout_id)
 {
     int     ret   = WH_ERROR_OK;
@@ -2088,6 +2132,12 @@ int wh_Server_HandleKeyRequest(whServerContext* server, uint16_t magic,
                                                       stage, &stageMax);
                             break;
                     #endif /* HAVE_CURVE25519 */
+                    #ifdef WOLFSSL_HAVE_MLKEM
+                        case WH_KEY_ALGO_MLKEM:
+                            ret = _ExportMlkemPublicKey(server, serverKeyId,
+                                                        stage, &stageMax);
+                            break;
+                    #endif /* WOLFSSL_HAVE_MLKEM */
                         default:
                             ret = WH_ERROR_BADARGS;
                             break;
@@ -2285,6 +2335,12 @@ int wh_Server_HandleKeyRequest(whServerContext* server, uint16_t magic,
                                     serverKeyId, out, &max_der);
                             break;
                     #endif /* HAVE_CURVE25519 */
+                    #ifdef WOLFSSL_HAVE_MLKEM
+                        case WH_KEY_ALGO_MLKEM:
+                            ret = _ExportMlkemPublicKey(server, serverKeyId,
+                                                        out, &max_der);
+                            break;
+                    #endif /* WOLFSSL_HAVE_MLKEM */
                         default:
                             ret = WH_ERROR_BADARGS;
                             break;

test/config/user_settings.h

@@ -134,14 +134,12 @@
 
 /* Dilithium Options */
 #define HAVE_DILITHIUM
-#define WOLFSSL_WC_DILITHIUM /* use wolfCrypt implementation, not libOQS */
 #define WOLFSSL_SHA3
 #define WOLFSSL_SHAKE128
 #define WOLFSSL_SHAKE256
 
 /* ML-KEM Options */
 #define WOLFSSL_HAVE_MLKEM
-#define WOLFSSL_WC_MLKEM
 
 /* Ed25519 Options */
 #define HAVE_ED25519