Skip to content

Commit c196d23

Browse files
dgarskeGrom-
dgarske
authored and
Grom-
committed
[platform/wolfssl] add wolfCrypt crypto platform support
Add platform abstraction layer implementation using wolfSSL/wolfCrypt for cryptographic operations including: - AES-ECB, AES-CBC, AES-CMAC encryption/decryption - SHA-256/SHA-384 hash computation - ECC key generation, signing, verification (NIST P-256/P-384, Brainpool) - ECDH key exchange (including Curve25519) - HMAC-SHA256 HKDF extract/expand (RFC 5869) - NIST SP 800-38F AES Key Wrap This enables STSELib integration on platforms using wolfSSL as the cryptographic provider, providing an alternative to STM32 CMOX. New files: - examples/wolfssl/stse_platform_crypto_wolfssl.c: Complete implementation - examples/wolfssl/user_settings.h: Sample wolfSSL configuration - examples/wolfssl/README.md: Usage instructions - doc/.../stse_platform_wolfssl.c.md: Porting guide documentation Tested on STSAFE-A120 hardware with Raspberry Pi 5.
1 parent 3b8d263 commit c196d23

File tree

5 files changed

+1806
-0
lines changed

5 files changed

+1806
-0
lines changed

‎doc/resources/Markdown/04_PORTING_GUIDE/03_PORTINNG_GUIDE.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,19 @@ Following platform files architecture are recommended to simplify the porting of
4141
- @subpage stse_platform_power
4242
- @subpage stse_platform_i2c
4343
- @subpage stse_platform_st1wire
44+
45+
# Reference Implementations
46+
47+
The following reference implementations are available for common cryptographic libraries:
48+
49+
## STM32 CMOX Library
50+
51+
The examples above demonstrate implementation using the STM32 Cryptographic Library (CMOX), which is optimized for STM32 microcontrollers.
52+
53+
## wolfSSL/wolfCrypt Library
54+
55+
A complete reference implementation using wolfSSL/wolfCrypt is available for platforms where wolfSSL is the cryptographic provider. This implementation supports Linux, RTOS, and bare-metal environments.
56+
57+
- @subpage stse_platform_wolfssl
58+
59+
See also the `examples/wolfssl/` directory for ready-to-use implementation files.

‎doc/resources/Markdown/04_PORTING_GUIDE/PAL_files/stse_platform_wolfssl.c.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# wolfSSL/wolfCrypt Platform Implementation {#stse_platform_wolfssl}
2+
3+
The `stse_platform_crypto_wolfssl.c` file provides a complete cryptographic platform implementation for the STSecureElement library using wolfSSL/wolfCrypt as the cryptographic provider. This implementation serves as an alternative to the STM32 CMOX library for platforms using wolfSSL.
4+
5+
## Overview
6+
7+
[wolfSSL](https://www.wolfssl.com/) is a lightweight, portable, C-language-based SSL/TLS library with an embedded cryptographic library (wolfCrypt). This platform implementation enables STSELib integration on any system where wolfSSL is available, including:
8+
9+
- Linux/POSIX systems
10+
- Embedded systems (ARM Cortex-M, RISC-V, etc.)
11+
- RTOS environments (FreeRTOS, Zephyr, etc.)
12+
- Custom microcontroller platforms
13+
14+
## Features Supported
15+
16+
| Category | Functions | wolfSSL API Used |
17+
|----------|-----------|------------------|
18+
| **Hash** | `stse_platform_hash_compute` | `wc_Sha256Hash`, `wc_Sha384Hash` |
19+
| **AES-ECB** | `stse_platform_aes_ecb_enc` | `wc_AesEncryptDirect` |
20+
| **AES-CBC** | `stse_platform_aes_cbc_enc`, `stse_platform_aes_cbc_dec` | `wc_AesCbcEncrypt`, `wc_AesCbcDecrypt` |
21+
| **AES-CMAC** | `stse_platform_aes_cmac_*` | Manual RFC 4493 implementation using `wc_AesCbcEncrypt` |
22+
| **HMAC/HKDF** | `stse_platform_hmac_sha256_*` | `wc_HmacSetKey`, `wc_HmacUpdate`, `wc_HmacFinal` |
23+
| **ECC Verify** | `stse_platform_ecc_verify` | `wc_ecc_verify_hash` |
24+
| **ECC KeyGen** | `stse_platform_ecc_generate_key_pair` | `wc_ecc_make_key_ex`, `wc_curve25519_make_key`, `wc_ed25519_make_key` |
25+
| **ECC Sign** | `stse_platform_ecc_sign` | `wc_ecc_sign_hash`, `wc_ed25519_sign_msg` |
26+
| **ECDH** | `stse_platform_ecc_ecdh` | `wc_ecc_shared_secret`, `wc_curve25519_shared_secret` |
27+
| **Key Wrap** | `stse_platform_nist_kw_encrypt` | `wc_AesKeyWrap` |
28+
29+
## ECC Curve Support
30+
31+
| STSE Key Type | wolfSSL Curve ID | Notes |
32+
|---------------|------------------|-------|
33+
| `STSE_ECC_KT_NIST_P_256` | `ECC_SECP256R1` | Default curve |
34+
| `STSE_ECC_KT_NIST_P_384` | `ECC_SECP384R1` | |
35+
| `STSE_ECC_KT_NIST_P_521` | `ECC_SECP521R1` | Requires `HAVE_ECC521` |
36+
| `STSE_ECC_KT_BP_P_256` | `ECC_BRAINPOOLP256R1` | Requires `HAVE_ECC_BRAINPOOL` |
37+
| `STSE_ECC_KT_BP_P_384` | `ECC_BRAINPOOLP384R1` | Requires `HAVE_ECC_BRAINPOOL` |
38+
| `STSE_ECC_KT_BP_P_512` | `ECC_BRAINPOOLP512R1` | Requires `HAVE_ECC_BRAINPOOL` |
39+
| `STSE_ECC_KT_CURVE25519` | `ECC_X25519` | Requires `HAVE_CURVE25519` |
40+
| `STSE_ECC_KT_ED25519` | `ECC_ED25519` | Requires `HAVE_ED25519` |
41+
42+
## Configuration
43+
44+
### wolfSSL Build Requirements
45+
46+
The wolfSSL library must be built with the following features enabled:
47+
48+
```bash
49+
./configure --enable-ecc --enable-sha384 --enable-sha512 \
50+
--enable-aescbc --enable-cmac --enable-keywrap \
51+
--enable-curve25519 --enable-ed25519 \
52+
--enable-brainpool
53+
```
54+
55+
Or define in `user_settings.h`:
56+
57+
```c
58+
#define WOLFSSL_USER_SETTINGS
59+
60+
/* ECC Support */
61+
#define HAVE_ECC
62+
#define TFM_ECC256
63+
#define ECC_TIMING_RESISTANT
64+
65+
/* Hash Support */
66+
#define WOLFSSL_SHA384
67+
#define WOLFSSL_SHA512
68+
69+
/* AES Support */
70+
#define HAVE_AES_CBC
71+
#define WOLFSSL_AES_DIRECT
72+
#define HAVE_AES_KEYWRAP
73+
74+
/* HMAC/HKDF Support */
75+
#define HAVE_HKDF
76+
77+
/* Optional: Additional curves */
78+
#define HAVE_ECC_BRAINPOOL
79+
#define HAVE_CURVE25519
80+
#define HAVE_ED25519
81+
```
82+
83+
### STSE Configuration
84+
85+
In your `stse_conf.h`, enable the required features:
86+
87+
```c
88+
/* Hash algorithms */
89+
#define STSE_CONF_HASH_SHA_256
90+
#define STSE_CONF_HASH_SHA_384
91+
92+
/* ECC curves */
93+
#define STSE_CONF_ECC_NIST_P_256
94+
#define STSE_CONF_ECC_NIST_P_384
95+
96+
/* Session/Key establishment features */
97+
#define STSE_CONF_USE_HOST_KEY_ESTABLISHMENT
98+
#define STSE_CONF_USE_HOST_SESSION
99+
```
100+
101+
## Implementation Details
102+
103+
### AES-CMAC Implementation
104+
105+
The AES-CMAC implementation follows RFC 4493 using wolfSSL's AES-CBC primitive. Subkeys K1 and K2 are generated according to the specification, and the streaming init/append/finish API is supported for processing data in chunks.
106+
107+
### Signature Format Conversion
108+
109+
STSE uses raw R||S signature format, while wolfSSL uses DER encoding. The implementation handles conversion using:
110+
- `wc_ecc_rs_raw_to_sig()` - Convert R||S to DER for verification
111+
- `wc_ecc_sig_to_rs()` - Convert DER to R||S after signing
112+
113+
### Public Key Format
114+
115+
Public keys are expected in raw X||Y coordinate format (uncompressed, without the 0x04 prefix). The implementation uses `wc_ecc_import_unsigned()` and `wc_ecc_export_public_raw()` for conversion.
116+
117+
## Usage Example
118+
119+
```c
120+
#include "stselib.h"
121+
#include "stse_conf.h"
122+
123+
/* Include wolfSSL with user settings */
124+
#define WOLFSSL_USER_SETTINGS
125+
#include "user_settings.h"
126+
#include <wolfssl/wolfcrypt/settings.h>
127+
128+
int main(void)
129+
{
130+
stse_Handler_t stse_handler;
131+
stse_ReturnCode_t ret;
132+
133+
/* Initialize STSE (calls stse_platform_crypto_init internally) */
134+
ret = stse_init(&stse_handler, STSAFE_A120, 1, 0x20);
135+
if (ret != STSE_OK) {
136+
return -1;
137+
}
138+
139+
/* Now use STSE APIs - platform crypto is ready */
140+
/* ... */
141+
142+
return 0;
143+
}
144+
```
145+
146+
## File Location
147+
148+
The reference implementation is located at:
149+
- `examples/wolfssl/stse_platform_crypto_wolfssl.c`
150+
151+
Copy this file to your platform directory and include it in your build.
152+
153+
## License
154+
155+
The wolfSSL platform implementation is provided under the wolfSSL license. wolfSSL is dual-licensed under GPLv2 and a commercial license. For commercial use, please contact wolfSSL Inc.
156+
157+
## References
158+
159+
- [wolfSSL Documentation](https://www.wolfssl.com/documentation/)
160+
- [wolfSSL GitHub](https://github.com/wolfSSL/wolfssl)
161+
- [RFC 4493 - AES-CMAC](https://tools.ietf.org/html/rfc4493)
162+
- [RFC 5869 - HKDF](https://tools.ietf.org/html/rfc5869)
163+
- [NIST SP 800-38F - Key Wrap](https://csrc.nist.gov/publications/detail/sp/800-38f/final)
164+

‎examples/wolfssl/README.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# wolfSSL Platform Implementation for STSELib
2+
3+
This directory contains a reference implementation of the STSELib Platform Abstraction Layer (PAL) using wolfSSL/wolfCrypt as the cryptographic provider.
4+
5+
## Files
6+
7+
| File | Description |
8+
|------|-------------|
9+
| `stse_platform_crypto_wolfssl.c` | Complete crypto PAL implementation |
10+
| `user_settings.h` | Sample wolfSSL configuration |
11+
12+
## Quick Start
13+
14+
1. **Copy files to your project:**
15+
```bash
16+
cp stse_platform_crypto_wolfssl.c /your/project/platform/
17+
cp user_settings.h /your/project/
18+
```
19+
20+
2. **Configure your build to include:**
21+
- wolfSSL library (with `WOLFSSL_USER_SETTINGS` defined)
22+
- STSELib headers
23+
- Your platform-specific I2C/delay implementations
24+
25+
3. **Build and link with wolfSSL:**
26+
```bash
27+
gcc -DWOLFSSL_USER_SETTINGS -I. -I/path/to/wolfssl -I/path/to/STSELib \
28+
your_app.c stse_platform_crypto_wolfssl.c \
29+
-lwolfssl -o your_app
30+
```
31+
32+
## Features Implemented
33+
34+
- ✅ SHA-256/SHA-384 hashing
35+
- ✅ AES-ECB/CBC encryption/decryption
36+
- ✅ AES-CMAC (streaming and one-shot)
37+
- ✅ HMAC-SHA256 HKDF (extract/expand)
38+
- ✅ ECC signature verification (NIST P-256/P-384, Brainpool, Ed25519)
39+
- ✅ ECC key pair generation
40+
- ✅ ECDSA/EdDSA signing
41+
- ✅ ECDH key exchange (including Curve25519)
42+
- ✅ NIST AES Key Wrap
43+
44+
## Requirements
45+
46+
### wolfSSL Configuration
47+
48+
Minimum required features in `user_settings.h` or configure:
49+
50+
```c
51+
#define HAVE_ECC
52+
#define HAVE_AES_CBC
53+
#define WOLFSSL_AES_DIRECT
54+
#define WOLFSSL_SHA384
55+
#define WOLFSSL_SHA512
56+
```
57+
58+
### Optional Features
59+
60+
For full curve support:
61+
```c
62+
#define HAVE_ECC_BRAINPOOL
63+
#define HAVE_CURVE25519
64+
#define HAVE_ED25519
65+
#define HAVE_AES_KEYWRAP
66+
```
67+
68+
## Testing
69+
70+
This implementation has been tested with:
71+
- STSAFE-A120 on Raspberry Pi 5
72+
- wolfSSL 5.x
73+
- Linux I2C driver
74+
75+
## License
76+
77+
Copyright 2025 wolfSSL Inc. Licensed under GPLv2 or commercial license.
78+
See https://www.wolfssl.com/license/ for details.
79+

0 commit comments

Comments
 (0)