README.md
1# ST Ports
2
3Support for the STM32 L4, F1, F2, F4 and F7 on-board crypto hardware acceleration:
4 - symmetric AES (ECB/CBC/CTR/GCM)
5 - MD5/SHA1/SHA224/SHA256
6
7Support for the STM32 PKA on WB55, H7 and other devices with on-board public-key acceleration:
8 - ECC192/ECC224/ECC256/ECC384
9
10Support 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 wolf stsafe_interface.c/.h files. Please contact ST for these.
11
12
13For details see our [wolfSSL ST](https://www.wolfssl.com/docs/stm32/) page.
14
15
16## STM32 Symmetric Acceleration
17
18We support using the STM32 CubeMX and Standard Peripheral Library.
19
20### Building
21
22To enable support define one of the following:
23
24```
25#define WOLFSSL_STM32L4
26#define WOLFSSL_STM32F1
27#define WOLFSSL_STM32F2
28#define WOLFSSL_STM32F4
29#define WOLFSSL_STM32F7
30```
31
32To use CubeMX define `WOLFSSL_STM32_CUBEMX` otherwise StdPeriLib is used.
33
34To disable portions of the hardware acceleration you can optionally define:
35
36```
37#define NO_STM32_RNG
38#define NO_STM32_CRYPTO
39#define NO_STM32_HASH
40```
41
42### Coding
43
44In your application you must include <wolfssl/wolfcrypt/settings.h> before any other wolfSSL headers. If building the sources directly we recommend defining `WOLFSSL_USER_SETTINGS` and adding your own `user_settings.h` file. You can find a good reference for this in `IDE/GCC-ARM/Header/user_settings.h`.
45
46
47### Benchmarks
48
49See our [benchmarks](https://www.wolfssl.com/docs/benchmarks/) on the wolfSSL website.
50
51
52## STM32 PKA (Public Key Acceleration)
53
54STM32 PKA is present in STM32WB55 as well as STM32H7 series.
55
56### Building
57
58To enable support define the following
59
60`WOLFSSL_STM32_PKA`
61
62### Using
63
64When the support is enabled, the ECC operations will be accelerated using the PKA crypto co-processor.
65
66## STSAFE-A100 ECC Acceleration
67
68Using 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.
69
70At the wolfCrypt level we also support ECC native API's for `wc_ecc_*` using the ST-Safe.
71
72### Building
73
74`./configure --enable-pkcallbacks CFLAGS="-DWOLFSSL_STSAFEA100"`
75
76or
77
78`#define HAVE_PK_CALLBACKS`
79`#define WOLFSSL_STSAFEA100`
80
81
82### Coding
83
84Setup the PK callbacks for TLS using:
85
86```
87/* Setup PK Callbacks for STSAFE-A100 */
88WOLFSSL_CTX* ctx;
89wolfSSL_CTX_SetEccKeyGenCb(ctx, SSL_STSAFE_CreateKeyCb);
90wolfSSL_CTX_SetEccSignCb(ctx, SSL_STSAFE_SignCertificateCb);
91wolfSSL_CTX_SetEccVerifyCb(ctx, SSL_STSAFE_VerifyPeerCertCb);
92wolfSSL_CTX_SetEccSharedSecretCb(ctx, SSL_STSAFE_SharedSecretCb);
93wolfSSL_CTX_SetDevId(ctx, 0); /* enables wolfCrypt `wc_ecc_*` ST-Safe use */
94```
95
96The reference STSAFE-A100 PK callback functions are located in the `wolfcrypt/src/port/st/stsafe.c` file.
97
98Adding a custom context to the callbacks:
99
100```
101/* Setup PK Callbacks context */
102WOLFSSL* ssl;
103void* myOwnCtx;
104wolfSSL_SetEccKeyGenCtx(ssl, myOwnCtx);
105wolfSSL_SetEccVerifyCtx(ssl, myOwnCtx);
106wolfSSL_SetEccSignCtx(ssl, myOwnCtx);
107wolfSSL_SetEccSharedSecretCtx(ssl, myOwnCtx);
108```
109
110### Benchmarks and Memory Use
111
112Software only implementation (STM32L4 120Mhz, Cortex-M4, Fast Math):
113
114```
115ECDHE 256 key gen SW 4 ops took 1.278 sec, avg 319.500 ms, 3.130 ops/sec
116ECDHE 256 agree SW 4 ops took 1.306 sec, avg 326.500 ms, 3.063 ops/sec
117ECDSA 256 sign SW 4 ops took 1.298 sec, avg 324.500 ms, 3.082 ops/sec
118ECDSA 256 verify SW 2 ops took 1.283 sec, avg 641.500 ms, 1.559 ops/sec
119```
120
121Memory Use:
122
123```
124Peak Stack: 18456
125Peak Heap: 2640
126Total: 21096
127```
128
129
130STSAFE-A100 acceleration:
131
132```
133ECDHE 256 key gen HW 8 ops took 1.008 sec, avg 126.000 ms, 7.937 ops/sec
134ECDHE 256 agree HW 6 ops took 1.051 sec, avg 175.167 ms, 5.709 ops/sec
135ECDSA 256 sign HW 14 ops took 1.161 sec, avg 82.929 ms, 12.059 ops/sec
136ECDSA 256 verify HW 8 ops took 1.184 sec, avg 148.000 ms, 6.757 ops/sec
137```
138
139Memory Use:
140
141```
142Peak Stack: 9592
143Peak Heap: 170
144Total: 9762
145```
146
147
148## Support
149
150Email us at [support@wolfssl.com](mailto:support@wolfssl.com).
151