wolfSSL/wolfssl
1
0
Fork 1
mirror of https://github.com/wolfSSL/wolfssl.git synced 2026-01-26 21:42:21 +01:00
Code Issues Packages Projects Releases Wiki Activity

Add STSAFE-A120 Support

Browse Source
This commit is contained in:
David Garske
2026-01-06 14:41:36 -08:00
parent c8867d8c52
commit a4c2398265
5 changed files with 1642 additions and 333 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.wolfssl_known_macro_extras
View File

@@ -513,6 +513,9 @@ SQRTMOD_USE_MOD_EXP
SSL_SNIFFER_EXPORTS
SSN_BUILDING_LIBYASSL
STATIC_CHUNKS_ONLY
STSAFE_HOST_KEY_CIPHER
STSAFE_HOST_KEY_MAC
STSAFE_I2C_BUS
STM32F107xC
STM32F207xx
STM32F217xx

185
wolfcrypt/src/port/st/README.md
View File

@@ -9,7 +9,9 @@ Support for the STM32 PKA on WB55, H7, MP13 and other devices with on-board
public-key acceleration:
- ECC192/ECC224/ECC256/ECC384
Support for the STSAFE-A100 crypto hardware accelerator co-processor via I2C for ECC supporting NIST or Brainpool 256-bit and 384-bit curves. It requires the ST-Safe SDK including wolfSSL's `stsafe_interface.c/.h` files. Please contact us at support@wolfssl.com to get this code.
Support for the STSAFE-A secure element family via I2C for ECC supporting NIST P-256/P-384 and Brainpool 256/384-bit curves:
- **STSAFE-A100/A110**: Uses ST's proprietary STSAFE-A1xx middleware. Contact us at support@wolfssl.com for integration assistance.
- **STSAFE-A120**: Uses ST's open-source [STSELib](https://github.com/STMicroelectronics/STSELib) (BSD-3 license).
For details see our [wolfSSL ST](https://www.wolfssl.com/docs/stm32/) page.
@@ -65,29 +67,69 @@ To enable support define the following
When the support is enabled, the ECC operations will be accelerated using the PKA crypto co-processor.
## STSAFE-A100 ECC Acceleration
## STSAFE-A ECC Acceleration
Using the wolfSSL PK callbacks and the reference ST Safe reference API's we support an ECC only cipher suite such as ECDHE-ECDSA-AES128-SHA256 for TLS client or server.
Using the wolfSSL PK callbacks or Crypto callbacks with the ST-Safe reference API's we support ECC operations for TLS client/server:
- **ECDSA Sign/Verify**: P-256 and P-384 (NIST and Brainpool curves)
- **ECDH Key Agreement**: For TLS key exchange
- **ECC Key Generation**: Ephemeral keys for TLS
At the wolfCrypt level we also support ECC native API's for `wc_ecc_*` using the ST-Safe.
At the wolfCrypt level we also support ECC native API's for `wc_ecc_*` using the ST-Safe via Crypto Callbacks.
### Supported Hardware
| Model | Macro | SDK |
|-------|-------|-----|
| STSAFE-A100/A110 | `WOLFSSL_STSAFEA100` | ST STSAFE-A1xx Middleware (proprietary) |
| STSAFE-A120 | `WOLFSSL_STSAFEA120` | [STSELib](https://github.com/STMicroelectronics/STSELib) (BSD-3, open source) |
### Building
`./configure --enable-pkcallbacks CFLAGS="-DWOLFSSL_STSAFEA100"`
For STSAFE-A100/A110 (legacy):
or
```
./configure --enable-pkcallbacks CFLAGS="-DWOLFSSL_STSAFEA100"
```
`#define HAVE_PK_CALLBACKS`
`#define WOLFSSL_STSAFEA100`
or in `user_settings.h`:
```c
#define HAVE_PK_CALLBACKS
#define WOLFSSL_STSAFEA100
```
For STSAFE-A120 with STSELib:
```
./configure --enable-pkcallbacks CFLAGS="-DWOLFSSL_STSAFEA120"
```
or in `user_settings.h`:
```c
#define HAVE_PK_CALLBACKS
#define WOLFSSL_STSAFEA120
```
To use Crypto Callbacks (recommended for wolfCrypt-level ECC operations):
```c
#define WOLF_CRYPTO_CB
#define WOLFSSL_STSAFEA120 /* or WOLFSSL_STSAFEA100 */
```
### Coding
#### Using PK Callbacks (TLS)
Setup the PK callbacks for TLS using:
```
/* Setup PK Callbacks for STSAFE-A100 */
```c
/* Setup PK Callbacks for STSAFE */
WOLFSSL_CTX* ctx;
SSL_STSAFE_SetupPkCallbacks(ctx);
/* Or manually: */
wolfSSL_CTX_SetEccKeyGenCb(ctx, SSL_STSAFE_CreateKeyCb);
wolfSSL_CTX_SetEccSignCb(ctx, SSL_STSAFE_SignCertificateCb);
wolfSSL_CTX_SetEccVerifyCb(ctx, SSL_STSAFE_VerifyPeerCertCb);
@@ -95,20 +137,131 @@ wolfSSL_CTX_SetEccSharedSecretCb(ctx, SSL_STSAFE_SharedSecretCb);
wolfSSL_CTX_SetDevId(ctx, 0); /* enables wolfCrypt `wc_ecc_*` ST-Safe use */
```
The reference STSAFE-A100 PK callback functions are located in the `wolfcrypt/src/port/st/stsafe.c` file.
The reference STSAFE PK callback functions are located in the `wolfcrypt/src/port/st/stsafe.c` file.
Adding a custom context to the callbacks:
```
```c
/* Setup PK Callbacks context */
WOLFSSL* ssl;
void* myOwnCtx;
wolfSSL_SetEccKeyGenCtx(ssl, myOwnCtx);
wolfSSL_SetEccVerifyCtx(ssl, myOwnCtx);
wolfSSL_SetEccSignCtx(ssl, myOwnCtx);
wolfSSL_SetEccSharedSecretCtx(ssl, myOwnCtx);
SSL_STSAFE_SetupPkCallbackCtx(ssl, myOwnCtx);
```
#### Using Crypto Callbacks (wolfCrypt)
For direct wolfCrypt ECC operations using the hardware:
```c
#include <wolfssl/wolfcrypt/port/st/stsafe.h>
/* Register the crypto callback */
wolfSTSAFE_CryptoCb_Ctx stsafeCtx;
stsafeCtx.devId = WOLF_STSAFE_DEVID;
wc_CryptoCb_RegisterDevice(WOLF_STSAFE_DEVID, wolfSSL_STSAFE_CryptoDevCb, &stsafeCtx);
/* Use with ECC operations */
ecc_key key;
wc_ecc_init_ex(&key, NULL, WOLF_STSAFE_DEVID);
/* ECC operations will now use STSAFE hardware */
```
### Implementation Details
The STSAFE support is self-contained in `wolfcrypt/src/port/st/stsafe.c` with SDK-specific implementations selected at compile time:
| Macro | SDK | Description |
|-------|-----|-------------|
| `WOLFSSL_STSAFEA100` | STSAFE-A1xx Middleware | ST's proprietary SDK for A100/A110 |
| `WOLFSSL_STSAFEA120` | [STSELib](https://github.com/STMicroelectronics/STSELib) | ST's open-source SDK for A120 (BSD-3) |
#### External Interface (Backwards Compatibility)
For customers with existing custom implementations, define `WOLFSSL_STSAFE_INTERFACE_EXTERNAL` to use an external `stsafe_interface.h` file instead of the built-in implementation:
```c
#define WOLFSSL_STSAFEA100 /* or WOLFSSL_STSAFEA120 */
#define WOLFSSL_STSAFE_INTERFACE_EXTERNAL
```
When `WOLFSSL_STSAFE_INTERFACE_EXTERNAL` is defined, the customer must provide a `stsafe_interface.h` header that defines:
| Item | Type | Description |
|------|------|-------------|
| `stsafe_curve_id_t` | typedef | Curve identifier type |
| `stsafe_slot_t` | typedef | Key slot identifier type |
| `STSAFE_ECC_CURVE_P256` | macro | P-256 curve ID value |
| `STSAFE_ECC_CURVE_P384` | macro | P-384 curve ID value |
| `STSAFE_KEY_SLOT_0/1/EPHEMERAL` | macros | Key slot values |
| `STSAFE_A_OK` | macro | Success return code |
| `STSAFE_MAX_KEY_LEN` | macro | Max key size in bytes (48) |
| `STSAFE_MAX_PUBKEY_RAW_LEN` | macro | Max public key size (96) |
| `STSAFE_MAX_SIG_LEN` | macro | Max signature size (96) |
And provide implementations for these internal interface functions:
- `int stsafe_interface_init(void)`
- `int stsafe_create_key(stsafe_slot_t*, stsafe_curve_id_t, uint8_t*)`
- `int stsafe_sign(stsafe_slot_t, stsafe_curve_id_t, uint8_t*, uint8_t*)`
- `int stsafe_verify(stsafe_curve_id_t, uint8_t*, uint8_t*, uint8_t*, uint8_t*, int32_t*)`
- `int stsafe_shared_secret(stsafe_slot_t, stsafe_curve_id_t, uint8_t*, uint8_t*, uint8_t*, int32_t*)`
- `int stsafe_read_certificate(uint8_t**, uint32_t*)`
- `int stsafe_get_random(uint8_t*, uint32_t)` (if `USE_STSAFE_RNG_SEED` defined)
When **NOT** defined (default behavior): All code is self-contained in `stsafe.c` using the appropriate SDK automatically.
The implementation provides these internal operations:
| Operation | Description |
|-----------|-------------|
| `stsafe_interface_init()` | Initialize the STSAFE device (called by `wolfCrypt_Init()`) |
| `stsafe_sign()` | ECDSA signature generation (P-256/P-384) |
| `stsafe_verify()` | ECDSA signature verification (P-256/P-384) |
| `stsafe_create_key()` | Generate ECC key pair on device |
| `stsafe_shared_secret()` | ECDH shared secret computation |
| `stsafe_read_certificate()` | Read device certificate from secure storage |
### STSELib Setup (A120)
For STSAFE-A120, you need to include the STSELib library:
1. Clone STSELib as a submodule or add to your project:
```bash
git submodule add https://github.com/STMicroelectronics/STSELib.git lib/stselib
```
2. Add STSELib headers to your include path
3. Implement the platform abstraction files required by STSELib:
- `stse_conf.h` - Configuration (target device, features)
- `stse_platform_generic.h` - Platform callbacks (I2C, timing)
4. See STSELib documentation for platform-specific integration details
### Raspberry Pi with STSAFE-A120
For testing on a Raspberry Pi with an STSAFE-A120 connected via I2C:
1. **Enable I2C** on the Raspberry Pi:
```bash
sudo raspi-config
# Navigate to: Interface Options -> I2C -> Enable
```
2. **Verify the STSAFE device is detected** (default I2C address is 0x20):
```bash
sudo i2cdetect -y 1
```
3. **Build wolfSSL with STSAFE-A120 support**:
```bash
./configure --enable-pkcallbacks --enable-cryptocb \
CFLAGS="-DWOLFSSL_STSAFEA120 -I/path/to/STSELib"
make
sudo make install
```
4. **Platform abstraction**: Implement the STSELib I2C callbacks using the Linux I2C driver (`/dev/i2c-1`).
### Benchmarks and Memory Use
Software only implementation (STM32L4 120Mhz, Cortex-M4, Fast Math):

1647
wolfcrypt/src/port/st/stsafe.c
View File

File diff suppressed because it is too large Load Diff

10
wolfcrypt/src/wc_port.c
View File

@@ -68,7 +68,7 @@
#if defined(WOLFSSL_RENESAS_RX64_HASH)
#include <wolfssl/wolfcrypt/port/Renesas/renesas-rx64-hw-crypt.h>
#endif
#if defined(WOLFSSL_STSAFEA100)
#if defined(WOLFSSL_STSAFEA100) || defined(WOLFSSL_STSAFEA120)
#include <wolfssl/wolfcrypt/port/st/stsafe.h>
#endif
@@ -303,8 +303,12 @@ int wolfCrypt_Init(void)
return ret;
}
#endif
#if defined(WOLFSSL_STSAFEA100)
stsafe_interface_init();
#if defined(WOLFSSL_STSAFEA100) || defined(WOLFSSL_STSAFEA120)
ret = stsafe_interface_init();
if (ret != 0) {
WOLFSSL_MSG("STSAFE init failed");
return ret;
}
#endif
#if defined(WOLFSSL_TROPIC01)
ret = Tropic01_Init();

130
wolfssl/wolfcrypt/port/st/stsafe.h
View File

@@ -23,6 +23,7 @@
#define _WOLFPORT_STSAFE_H_
#include <wolfssl/wolfcrypt/settings.h>
#include <wolfssl/wolfcrypt/types.h>
#include <wolfssl/wolfcrypt/ecc.h>
#include <wolfssl/wolfcrypt/error-crypt.h>
@@ -34,22 +35,135 @@
#include <wolfssl/ssl.h>
#endif
#ifdef WOLFSSL_STSAFEA100
/* Combined STSAFE macro - enables when either A100 or A120 is defined */
#if defined(WOLFSSL_STSAFEA100) || defined(WOLFSSL_STSAFEA120)
#undef WOLFSSL_STSAFE
#define WOLFSSL_STSAFE
#endif
/* The wolf STSAFE interface layer */
/* Please contact wolfSSL for the STSAFE port files */
#include "stsafe_interface.h"
#ifdef WOLFSSL_STSAFE
/* -------------------------------------------------------------------------- */
/* External Interface Support (Backwards Compatibility) */
/* -------------------------------------------------------------------------- */
/* Define WOLFSSL_STSAFE_INTERFACE_EXTERNAL to use an external stsafe_
* interface.h file that provides customer-specific implementations.
* This maintains backwards compatibility with older integrations that
* used a separate interface file.
*
* When NOT defined (default): All code is self-contained in stsafe.c using
* the appropriate SDK (STSELib for A120, STSAFE-A1xx SDK for A100/A110).
*
* When defined: Include customer-provided stsafe_interface.h which must define:
* - stsafe_curve_id_t, stsafe_slot_t types
* - STSAFE_ECC_CURVE_P256, STSAFE_ECC_CURVE_P384 macros
* - STSAFE_KEY_SLOT_0, STSAFE_KEY_SLOT_1, STSAFE_KEY_SLOT_EPHEMERAL macros
* - STSAFE_A_OK return code macro
* - STSAFE_MAX_KEY_LEN, STSAFE_MAX_PUBKEY_RAW_LEN, STSAFE_MAX_SIG_LEN macros
* - Function prototypes for interface functions (see stsafe.c)
*/
#ifdef WOLFSSL_STSAFE_INTERFACE_EXTERNAL
#include "stsafe_interface.h"
#else
/* -------------------------------------------------------------------------- */
/* STSAFE SDK Type Abstractions */
/* -------------------------------------------------------------------------- */
#ifdef WOLFSSL_STSAFEA120
/* STSAFE-A120 uses STSELib (open source BSD-3) */
/* Note: stselib.h is included in stsafe.c to avoid warnings in headers */
/* Type mappings for STSELib - using byte for curve ID to avoid
* including full STSELib headers which have strict-prototype warnings */
typedef byte stsafe_curve_id_t;
typedef byte stsafe_slot_t;
/* Curve ID mappings - values depend on stse_conf.h settings!
* With only NIST P-256 and P-384 enabled:
* STSE_ECC_KT_NIST_P_256 = 0, STSE_ECC_KT_NIST_P_384 = 1
* NOTE: If other curves are enabled, these values change! */
#define STSAFE_ECC_CURVE_P256 0 /* STSE_ECC_KT_NIST_P_256 */
#define STSAFE_ECC_CURVE_P384 1 /* STSE_ECC_KT_NIST_P_384 */
/* Brainpool curves - only defined when enabled in stse_conf.h */
/* #define STSAFE_ECC_CURVE_BP256 2 */ /* STSE_ECC_KT_BP_P_256 */
/* #define STSAFE_ECC_CURVE_BP384 3 */ /* STSE_ECC_KT_BP_P_384 */
/* Slot mappings */
#define STSAFE_KEY_SLOT_0 0
#define STSAFE_KEY_SLOT_1 1
#define STSAFE_KEY_SLOT_EPHEMERAL 0xFF
/* Return codes */
#define STSAFE_A_OK 0 /* STSE_OK */
/* Hash types - must match stse_hash_algorithm_t values in STSELib */
#define STSAFE_HASH_SHA256 0 /* STSE_SHA_256 */
#define STSAFE_HASH_SHA384 1 /* STSE_SHA_384 */
#else /* WOLFSSL_STSAFEA100 */
/* STSAFE-A100/A110 uses legacy ST STSAFE-A1xx SDK */
/* User must provide path to STSAFE-A1xx SDK headers */
#include <stsafe_a_types.h>
/* Type mappings for legacy SDK */
typedef StSafeA_CurveId stsafe_curve_id_t;
typedef StSafeA_KeySlotNumber stsafe_slot_t;
/* Curve ID mappings */
#define STSAFE_ECC_CURVE_P256 STSAFE_A_NIST_P_256
#define STSAFE_ECC_CURVE_P384 STSAFE_A_NIST_P_384
#define STSAFE_ECC_CURVE_BP256 STSAFE_A_BRAINPOOL_P_256
#define STSAFE_ECC_CURVE_BP384 STSAFE_A_BRAINPOOL_P_384
/* Slot mappings */
#define STSAFE_KEY_SLOT_0 STSAFE_A_SLOT_0
#define STSAFE_KEY_SLOT_1 STSAFE_A_SLOT_1
#define STSAFE_KEY_SLOT_EPHEMERAL STSAFE_A_SLOT_EPHEMERAL
/* Return codes - STSAFE_A_OK already defined in SDK */
/* Hash types */
#define STSAFE_HASH_SHA256 STSAFE_A_SHA_256
#define STSAFE_HASH_SHA384 STSAFE_A_SHA_384
#endif /* WOLFSSL_STSAFEA120 */
/* -------------------------------------------------------------------------- */
/* Common Definitions */
/* -------------------------------------------------------------------------- */
#ifndef STSAFE_MAX_KEY_LEN
#define STSAFE_MAX_KEY_LEN ((uint32_t)48) /* for up to 384-bit keys */
#define STSAFE_MAX_KEY_LEN 48 /* for up to 384-bit keys */
#endif
#ifndef STSAFE_MAX_PUBKEY_RAW_LEN
#define STSAFE_MAX_PUBKEY_RAW_LEN ((uint32_t)STSAFE_MAX_KEY_LEN * 2) /* x/y */
#define STSAFE_MAX_PUBKEY_RAW_LEN (STSAFE_MAX_KEY_LEN * 2) /* x/y */
#endif
#ifndef STSAFE_MAX_SIG_LEN
#define STSAFE_MAX_SIG_LEN ((uint32_t)STSAFE_MAX_KEY_LEN * 2) /* r/s */
#define STSAFE_MAX_SIG_LEN (STSAFE_MAX_KEY_LEN * 2) /* r/s */
#endif
/* Default I2C address */
#ifndef STSAFE_I2C_ADDR
#define STSAFE_I2C_ADDR 0x20
#endif
/* Default curve mode (for signing operations) */
#ifndef STSAFE_DEFAULT_CURVE
#define STSAFE_DEFAULT_CURVE STSAFE_ECC_CURVE_P256
#endif
#endif /* !WOLFSSL_STSAFE_INTERFACE_EXTERNAL */
/* -------------------------------------------------------------------------- */
/* Public API Functions */
/* -------------------------------------------------------------------------- */
/* Initialize STSAFE device - called automatically by wolfCrypt_Init() */
WOLFSSL_API int stsafe_interface_init(void);
/* Load device certificate from STSAFE secure storage */
WOLFSSL_API int SSL_STSAFE_LoadDeviceCertificate(byte** pRawCertificate,
word32* pRawCertificateLen);
@@ -94,6 +208,6 @@ WOLFSSL_API int wolfSSL_STSAFE_CryptoDevCb(int devId, wc_CryptoInfo* info,
#endif /* WOLF_CRYPTO_CB */
#endif /* WOLFSSL_STSAFEA100 */
#endif /* WOLFSSL_STSAFE */
#endif /* _WOLFPORT_STSAFE_H_ */