Support raw sign callbacks without privateKey for HSM/secure element use case

jackctj117 · jackctj117 · commit 352c362494cd · 2026-01-26T10:15:02.000-07:00
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,155 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Development Commands
+
+### Primary Build System (Autotools)
+```bash
+# From git checkout
+./autogen.sh                    # Generate configure script (requires autoconf, automake, libtool)
+./configure                     # Configure build with default options
+make                           # Build the library
+make check                     # Run tests (highly recommended)
+sudo make install             # Install the library
+
+# Quick test configurations
+make test                      # Run unit tests
+make egs                       # Build client/server examples
+make wc_egs                    # Build wolfCrypt test/benchmark
+```
+
+### Alternative Build System (CMake)
+```bash
+# Basic CMake build
+mkdir build && cd build
+cmake ..
+cmake --build .
+
+# With options (example)
+cmake .. -DWOLFSSL_TLS13=no -DWOLFSSL_DSA=yes -DCMAKE_BUILD_TYPE=Debug
+cmake --build .
+```
+
+### Testing Commands
+```bash
+# Commit tests (must pass before commits)
+./commit-tests.sh              # Runs current, basic, and full config tests
+
+# Individual test suites
+./wolfcrypt/test/testwolfcrypt # wolfCrypt unit tests
+./wolfcrypt/benchmark/benchmark # Performance benchmarks  
+./testsuite/testsuite          # Main test suite
+./tests/unit.test              # Unit test runner
+```
+
+### Package Building
+```bash
+make deb                       # Generate Debian package
+make deb-docker               # Generate Debian package in Docker
+make rpm                      # Generate RPM package 
+make rpm-docker              # Generate RPM package in Docker
+```
+
+## Code Architecture
+
+### Core Directory Structure
+- **`src/`** - Main wolfSSL/TLS implementation
+  - `ssl.c` - Core SSL/TLS functionality
+  - `internal.c` - Internal helper functions
+  - `ssl_crypto.c` - Cryptographic operations for TLS
+  - `x509*.c` - X.509 certificate handling
+  - `ocsp.c`, `crl.c` - Certificate revocation
+  - `sniffer.c` - Packet capture/analysis
+  - `quic.c` - QUIC protocol support
+
+- **`wolfssl/`** - Public header files
+  - Main API headers and OpenSSL compatibility layer
+  - `wolfssl/options.h` - Build configuration (auto-generated)
+
+- **`wolfcrypt/`** - Cryptographic library (can be used standalone)
+  - `src/` - Implementation of crypto primitives
+  - `test/` - Crypto unit tests
+  - `benchmark/` - Performance testing
+
+- **`examples/`** - Sample applications
+  - `client/`, `server/` - Basic TLS client/server
+  - `echoclient/`, `echoserver/` - Echo examples
+  - `benchmark/` - TLS performance testing
+
+- **`tests/`** - Test configuration files and API tests
+- **`testsuite/`** - Main test orchestration
+- **`certs/`** - Test certificates and keys
+
+### Key Build Files
+- `configure.ac` - Autotools configuration
+- `Makefile.am` - Automake configuration  
+- `CMakeLists.txt` - CMake configuration
+- `wolfssl/options.h` - Generated build options (include first in applications)
+
+### Platform Support
+wolfSSL supports numerous platforms through `IDE/` directory:
+- Embedded: STM32, ESP32, Renesas, TI, NXP
+- Mobile: iOS, Android
+- RTOS: FreeRTOS, ThreadX, Zephyr
+- Kernel: Linux kernel module (`linuxkm/`), BSD kernel module (`bsdkm/`)
+
+## Development Workflows
+
+### Configuration Options
+wolfSSL uses extensive `./configure` options for feature selection:
+```bash
+# Common feature flags
+--enable-opensslextra          # OpenSSL API compatibility
+--enable-tls13                 # TLS 1.3 support  
+--enable-dtls                  # DTLS protocol
+--enable-psk                   # Pre-shared key support
+--enable-ecc                   # Elliptic curve cryptography
+--enable-fips                  # FIPS 140-2 mode
+--enable-kyber --enable-dilithium  # Post-quantum algorithms
+
+# Debug and testing
+--enable-debug                 # Debug symbols and logging
+--enable-debuglog             # Verbose debugging
+--enable-test                  # Include test features
+```
+
+### Code Style and Standards
+- **ANSI C** - Written in ANSI C for maximum portability
+- **Options Header** - Applications must include `wolfssl/options.h` first, or define `WOLFSSL_USE_OPTIONS_H`
+- **Security Focus** - Constant-time implementations, secure defaults
+- **FIPS Compliance** - FIPS 140-2 validated versions available
+
+### Git Workflow
+- Pre-commit hooks run `commit-tests.sh` automatically
+- Tests must pass on current config, basic config, and full-featured config
+- Use `--no-verify` to bypass commit tests during development
+
+### Testing Strategy
+- Unit tests for individual components
+- Integration tests via examples
+- Configuration matrix testing via CI
+- External library compatibility testing (OpenSSL apps, etc.)
+
+## Key Concepts
+
+### FIPS Mode
+- wolfCrypt has FIPS 140-2 validated versions
+- Use `fips-check.sh` and `fips-hash.sh` for FIPS builds
+- Special build requirements and restrictions apply
+
+### Certificate Management  
+- `gencertbuf.pl` generates C arrays from certificates for embedded use
+- Test certificates renewable via `certs/renewcerts.sh`
+- OCSP responder test scripts in `certs/ocsp/`
+
+### Compatibility Layers
+- OpenSSL compatibility API for porting existing applications
+- Extensive platform abstraction for embedded/RTOS use
+- Hardware acceleration support for various crypto engines
+
+### Security Notes
+- Perfect forward secrecy enabled by default (ephemeral key exchange)
+- Static key cipher suites disabled by default for security
+- Memory management designed for resource-constrained environments
+- Constant-time implementations to prevent timing attacks
diff --git a/tests/api/test_pkcs7.c b/tests/api/test_pkcs7.c
@@ -388,12 +388,15 @@ int test_wc_PKCS7_EncodeData(void)
 
 #if defined(HAVE_PKCS7) && defined(HAVE_PKCS7_RSA_RAW_SIGN_CALLBACK) && \
     !defined(NO_RSA) && !defined(NO_SHA256)
-/* RSA sign raw digest callback */
+/* RSA sign raw digest callback
+ * This callback demonstrates HSM/secure element use case where the private
+ * key is not passed through PKCS7 structure but obtained independently.
+ */
 static int rsaSignRawDigestCb(PKCS7* pkcs7, byte* digest, word32 digestSz,
                               byte* out, word32 outSz, byte* privateKey,
                               word32 privateKeySz, int devid, int hashOID)
 {
-    /* specific DigestInfo ASN.1 encoding prefix for a SHA2565 digest */
+    /* specific DigestInfo ASN.1 encoding prefix for a SHA256 digest */
     byte digInfoEncoding[] = {
         0x30, 0x31, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86,
         0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01, 0x05,
@@ -407,6 +410,11 @@ static int rsaSignRawDigestCb(PKCS7* pkcs7, byte* digest, word32 digestSz,
     word32 idx = 0;
     RsaKey rsa;
 
+    /* privateKey may be NULL in HSM/secure element use case - we load it
+     * independently in this callback to simulate that scenario */
+    (void)privateKey;
+    (void)privateKeySz;
+
     /* SHA-256 required only for this example callback due to above
      * digInfoEncoding[] */
     if (pkcs7 == NULL || digest == NULL || out == NULL ||
@@ -427,7 +435,33 @@ static int rsaSignRawDigestCb(PKCS7* pkcs7, byte* digest, word32 digestSz,
         return ret;
     }
 
-    ret = wc_RsaPrivateKeyDecode(privateKey, &idx, &rsa, privateKeySz);
+    /* Load key from test buffer - simulates HSM/secure element access */
+#if defined(USE_CERT_BUFFERS_2048)
+    ret = wc_RsaPrivateKeyDecode(client_key_der_2048, &idx, &rsa,
+                                 sizeof_client_key_der_2048);
+#elif defined(USE_CERT_BUFFERS_1024)
+    ret = wc_RsaPrivateKeyDecode(client_key_der_1024, &idx, &rsa,
+                                 sizeof_client_key_der_1024);
+#else
+    {
+        XFILE fp;
+        byte keyBuf[ONEK_BUF];
+        int keySz;
+
+        fp = XFOPEN("./certs/client-key.der", "rb");
+        if (fp == XBADFILE) {
+            wc_FreeRsaKey(&rsa);
+            return -1;
+        }
+        keySz = (int)XFREAD(keyBuf, 1, sizeof(keyBuf), fp);
+        XFCLOSE(fp);
+        if (keySz <= 0) {
+            wc_FreeRsaKey(&rsa);
+            return -1;
+        }
+        ret = wc_RsaPrivateKeyDecode(keyBuf, &idx, &rsa, (word32)keySz);
+    }
+#endif
 
     /* sign DigestInfo */
     if (ret == 0) {
@@ -453,7 +487,10 @@ static int rsaSignRawDigestCb(PKCS7* pkcs7, byte* digest, word32 digestSz,
 
 #if defined(HAVE_PKCS7) && defined(HAVE_PKCS7_ECC_RAW_SIGN_CALLBACK) && \
     defined(HAVE_ECC) && !defined(NO_SHA256)
-/* ECC sign raw digest callback */
+/* ECC sign raw digest callback
+ * This callback demonstrates HSM/secure element use case where the private
+ * key is not passed through PKCS7 structure but obtained independently.
+ */
 static int eccSignRawDigestCb(PKCS7* pkcs7, byte* digest, word32 digestSz,
                               byte* out, word32 outSz, byte* privateKey,
                               word32 privateKeySz, int devid, int hashOID)
@@ -463,19 +500,46 @@ static int eccSignRawDigestCb(PKCS7* pkcs7, byte* digest, word32 digestSz,
     word32 sigSz = outSz;
     ecc_key ecc;
 
+    /* privateKey may be NULL in HSM/secure element use case - we load it
+     * independently in this callback to simulate that scenario */
+    (void)privateKey;
+    (void)privateKeySz;
+    (void)hashOID;
+
     if (pkcs7 == NULL || digest == NULL || out == NULL) {
         return -1;
     }
 
-    (void)hashOID;
-
     /* set up ECC key */
     ret = wc_ecc_init_ex(&ecc, pkcs7->heap, devid);
     if (ret != 0) {
         return ret;
     }
 
-    ret = wc_EccPrivateKeyDecode(privateKey, &idx, &ecc, privateKeySz);
+    /* Load key from test buffer - simulates HSM/secure element access */
+#if defined(USE_CERT_BUFFERS_256)
+    ret = wc_EccPrivateKeyDecode(ecc_clikey_der_256, &idx, &ecc,
+                                 sizeof_ecc_clikey_der_256);
+#else
+    {
+        XFILE fp;
+        byte keyBuf[ONEK_BUF];
+        int keySz;
+
+        fp = XFOPEN("./certs/client-ecc-key.der", "rb");
+        if (fp == XBADFILE) {
+            wc_ecc_free(&ecc);
+            return -1;
+        }
+        keySz = (int)XFREAD(keyBuf, 1, sizeof(keyBuf), fp);
+        XFCLOSE(fp);
+        if (keySz <= 0) {
+            wc_ecc_free(&ecc);
+            return -1;
+        }
+        ret = wc_EccPrivateKeyDecode(keyBuf, &idx, &ecc, (word32)keySz);
+    }
+#endif
 
     /* sign digest */
     if (ret == 0) {
@@ -797,8 +861,7 @@ int test_wc_PKCS7_EncodeSignedData(void)
     if (pkcs7 != NULL) {
         pkcs7->content = data;
         pkcs7->contentSz = (word32)sizeof(data);
-        pkcs7->privateKey = key;
-        pkcs7->privateKeySz = (word32)sizeof(key);
+        /* privateKey not set - callback simulates HSM/secure element access */
         pkcs7->encryptOID = RSAk;
         pkcs7->hashOID = SHA256h;
         pkcs7->rng = &rng;
@@ -813,24 +876,41 @@ int test_wc_PKCS7_EncodeSignedData(void)
     defined(HAVE_ECC) && !defined(NO_SHA256)
     /* test ECC sign raw digest callback, if using ECC and compiled in.
      * Example callback assumes SHA-256, so only run test if compiled in. */
-    wc_PKCS7_Free(pkcs7);
-    pkcs7 = NULL;
-    ExpectNotNull(pkcs7 = wc_PKCS7_New(HEAP_HINT, testDevId));
-    ExpectIntEQ(wc_PKCS7_InitWithCert(pkcs7, cert, certSz), 0);
+    {
+    #if defined(USE_CERT_BUFFERS_256)
+        byte        eccCert[sizeof(cliecc_cert_der_256)];
+        word32      eccCertSz = (word32)sizeof(eccCert);
+        XMEMCPY(eccCert, cliecc_cert_der_256, eccCertSz);
+    #else
+        byte        eccCert[ONEK_BUF];
+        int         eccCertSz;
+        XFILE       eccFp = XBADFILE;
 
-    if (pkcs7 != NULL) {
-        pkcs7->content = data;
-        pkcs7->contentSz = (word32)sizeof(data);
-        pkcs7->privateKey = key;
-        pkcs7->privateKeySz = (word32)keySz;
-        pkcs7->encryptOID = ECDSAk;
-        pkcs7->hashOID = SHA256h;
-        pkcs7->rng = &rng;
-    }
+        ExpectTrue((eccFp = XFOPEN("./certs/client-ecc-cert.der", "rb")) !=
+            XBADFILE);
+        ExpectIntGT(eccCertSz = (int)XFREAD(eccCert, 1, ONEK_BUF, eccFp), 0);
+        if (eccFp != XBADFILE)
+            XFCLOSE(eccFp);
+    #endif
+
+        wc_PKCS7_Free(pkcs7);
+        pkcs7 = NULL;
+        ExpectNotNull(pkcs7 = wc_PKCS7_New(HEAP_HINT, testDevId));
+        ExpectIntEQ(wc_PKCS7_InitWithCert(pkcs7, eccCert, (word32)eccCertSz), 0);
 
-    ExpectIntEQ(wc_PKCS7_SetEccSignRawDigestCb(pkcs7, eccSignRawDigestCb), 0);
+        if (pkcs7 != NULL) {
+            pkcs7->content = data;
+            pkcs7->contentSz = (word32)sizeof(data);
+            /* privateKey not set - callback simulates HSM/secure element access */
+            pkcs7->encryptOID = ECDSAk;
+            pkcs7->hashOID = SHA256h;
+            pkcs7->rng = &rng;
+        }
 
-    ExpectIntGT(wc_PKCS7_EncodeSignedData(pkcs7, output, outputSz), 0);
+        ExpectIntEQ(wc_PKCS7_SetEccSignRawDigestCb(pkcs7, eccSignRawDigestCb), 0);
+
+        ExpectIntGT(wc_PKCS7_EncodeSignedData(pkcs7, output, outputSz), 0);
+    }
 #endif
 
     wc_PKCS7_Free(pkcs7);
diff --git a/wolfcrypt/src/pkcs7.c b/wolfcrypt/src/pkcs7.c
@@ -1794,6 +1794,16 @@ static int wc_PKCS7_ImportRSA(wc_PKCS7* pkcs7, RsaKey* privKey)
             }
         #endif
         }
+    #ifdef HAVE_PKCS7_RSA_RAW_SIGN_CALLBACK
+        else if (pkcs7->rsaSignRawDigestCb != NULL && pkcs7->publicKeySz > 0) {
+            /* When using raw sign callback (e.g., HSM/secure element), private
+             * key may not be available. Use public key from signer certificate
+             * for signature size calculation. */
+            idx = 0;
+            ret = wc_RsaPublicKeyDecode(pkcs7->publicKey, &idx, privKey,
+                                        pkcs7->publicKeySz);
+        }
+    #endif
         else if (pkcs7->devId == INVALID_DEVID) {
             ret = BAD_FUNC_ARG;
         }
@@ -1874,6 +1884,16 @@ static int wc_PKCS7_ImportECC(wc_PKCS7* pkcs7, ecc_key* privKey)
             }
         #endif
         }
+    #ifdef HAVE_PKCS7_ECC_RAW_SIGN_CALLBACK
+        else if (pkcs7->eccSignRawDigestCb != NULL && pkcs7->publicKeySz > 0) {
+            /* When using raw sign callback (e.g., HSM/secure element), private
+             * key may not be available. Use public key from signer certificate
+             * for signature size calculation. */
+            idx = 0;
+            ret = wc_EccPublicKeyDecode(pkcs7->publicKey, &idx, privKey,
+                                        pkcs7->publicKeySz);
+        }
+    #endif
         else if (pkcs7->devId == INVALID_DEVID) {
             ret = BAD_FUNC_ARG;
         }

Original file line number	Diff line number	Diff line change
`@@ -1794,6 +1794,16 @@ static int wc_PKCS7_ImportRSA(wc_PKCS7* pkcs7, RsaKey* privKey)`
`1794`	`1794`	`}`
`1795`	`1795`	`#endif`
`1796`	`1796`	`}`
	`1797`	`+ #ifdef HAVE_PKCS7_RSA_RAW_SIGN_CALLBACK`
	`1798`	`+ else if (pkcs7->rsaSignRawDigestCb != NULL && pkcs7->publicKeySz > 0) {`
	`1799`	`+ /* When using raw sign callback (e.g., HSM/secure element), private`
	`1800`	`+ * key may not be available. Use public key from signer certificate`
	`1801`	`+ * for signature size calculation. */`
	`1802`	`+ idx = 0;`
	`1803`	`+ ret = wc_RsaPublicKeyDecode(pkcs7->publicKey, &idx, privKey,`
	`1804`	`+ pkcs7->publicKeySz);`
	`1805`	`+ }`
	`1806`	`+ #endif`
`1797`	`1807`	`else if (pkcs7->devId == INVALID_DEVID) {`
`1798`	`1808`	`ret = BAD_FUNC_ARG;`
`1799`	`1809`	`}`
`@@ -1874,6 +1884,16 @@ static int wc_PKCS7_ImportECC(wc_PKCS7* pkcs7, ecc_key* privKey)`
`1874`	`1884`	`}`
`1875`	`1885`	`#endif`
`1876`	`1886`	`}`
	`1887`	`+ #ifdef HAVE_PKCS7_ECC_RAW_SIGN_CALLBACK`
	`1888`	`+ else if (pkcs7->eccSignRawDigestCb != NULL && pkcs7->publicKeySz > 0) {`
	`1889`	`+ /* When using raw sign callback (e.g., HSM/secure element), private`
	`1890`	`+ * key may not be available. Use public key from signer certificate`
	`1891`	`+ * for signature size calculation. */`
	`1892`	`+ idx = 0;`
	`1893`	`+ ret = wc_EccPublicKeyDecode(pkcs7->publicKey, &idx, privKey,`
	`1894`	`+ pkcs7->publicKeySz);`
	`1895`	`+ }`
	`1896`	`+ #endif`
`1877`	`1897`	`else if (pkcs7->devId == INVALID_DEVID) {`
`1878`	`1898`	`ret = BAD_FUNC_ARG;`
`1879`	`1899`	`}`