Skip to content

Commit

Permalink
code review updates for ESP32 C3/C6/S2 HW Acceleration
Browse files Browse the repository at this point in the history
  • Loading branch information
@gojimmypi
gojimmypi committed Nov 22, 2023
1 parent 7e69030 commit 9227020
Show file tree
Hide file tree
Showing 7 changed files with 199 additions and 127 deletions.
1 change: 0 additions & 1 deletion IDE/Espressif/ESP-IDF/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@ Including the following examples:
* Simple [TLS client](./examples/wolfssl_client/)/[server](./examples/wolfssl_server/)
* Cryptographic [test](./examples/wolfssl_test/)
* Cryptographic [benchmark](./examples/wolfssl_benchmark/)
* Bare-bones [template](./examples/template/)

The *user_settings.h* file enables some of the hardened settings.

Expand Down
150 changes: 120 additions & 30 deletions IDE/Espressif/ESP-IDF/user_settings.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@
#define WOLFSSL_AES_DIRECT
#endif

/* when you want to use aes counter mode */
/* when you want to use AES counter mode */
/* #define WOLFSSL_AES_DIRECT */
/* #define WOLFSSL_AES_COUNTER */

Expand All @@ -102,10 +102,17 @@
/* Define USE_FAST_MATH and SMALL_STACK */
#define ESP32_USE_RSA_PRIMITIVE
/* threshold for performance adjustment for HW primitive use */
/* NOTE HW unreliable for small values on older original ESP32!*/
/* threshold for performance adjustment for HW primitive use */
/* X bits of G^X mod P greater than */
#define EPS_RSA_EXPT_XBTIS 36
#undef ESP_RSA_EXPT_XBITS
#define ESP_RSA_EXPT_XBITS 32

/* X and Y of X * Y mod P greater than */
#define ESP_RSA_MULM_BITS 2000
#undef ESP_RSA_MULM_BITS
#define ESP_RSA_MULM_BITS 16

#endif

/* debug options */
Expand All @@ -123,46 +130,129 @@
/* adjust wait-timeout count if you see timeout in RSA HW acceleration */
#define ESP_RSA_TIMEOUT_CNT 0x249F00

/* Default is HW enabled unless turned off.
** Uncomment these lines to force SW instead of HW acceleration */

#if defined(CONFIG_IDF_TARGET_ESP32)
/* when you want not to use HW acceleration on ESP32 (below for S3, etc */
/* #define NO_ESP32_CRYPT */
/* #define NO_WOLFSSL_ESP32_CRYPT_HASH */
/* #define NO_WOLFSSL_ESP32_CRYPT_AES */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI */
/* wolfSSL HW Acceleration supported on ESP32. Uncomment to disable: */
/* #define NO_ESP32_CRYPT */
/* #define NO_WOLFSSL_ESP32_CRYPT_HASH */
/* #define NO_WOLFSSL_ESP32_CRYPT_AES */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI_MP_MUL */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI_MULMOD */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI_EXPTMOD */

/* These are defined automatically in esp32-crypt.h, here for clarity: */
#define NO_WOLFSSL_ESP32_CRYPT_HASH_SHA224 /* no SHA224 HW on ESP32 */
/* end CONFIG_IDF_TARGET_ESP32 */
#undef ESP_RSA_MULM_BITS
#define ESP_RSA_MULM_BITS 16 /* TODO add compile-time warning */
/***** END CONFIG_IDF_TARGET_ESP32 *****/

#elif defined(CONFIG_IDF_TARGET_ESP32S2)
/* ESP32-S2 disabled by default; not implemented */
#define NO_ESP32_CRYPT
#define NO_WOLFSSL_ESP32_CRYPT_HASH
#define NO_WOLFSSL_ESP32_CRYPT_AES
#define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI
/* wolfSSL HW Acceleration supported on ESP32-S2. Uncomment to disable: */
/* #define NO_ESP32_CRYPT */
/* #define NO_WOLFSSL_ESP32_CRYPT_HASH */
/* Note: There's no AES192 HW on the ESP32-S2; falls back to SW */
/* #define NO_WOLFSSL_ESP32_CRYPT_AES */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI_MP_MUL */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI_MULMOD */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI_EXPTMOD */
/***** END CONFIG_IDF_TARGET_ESP32S2 *****/

#elif defined(CONFIG_IDF_TARGET_ESP32S3)
/* when you want not to use HW acceleration on ESP32-S3 */
/* #define NO_ESP32_CRYPT */
/* #define NO_WOLFSSL_ESP32_CRYPT_HASH */
/* #define NO_WOLFSSL_ESP32_CRYPT_AES */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI */
/* wolfSSL HW Acceleration supported on ESP32-S3. Uncomment to disable: */
/* #define NO_ESP32_CRYPT */
/* #define NO_WOLFSSL_ESP32_CRYPT_HASH */
/* Note: There's no AES192 HW on the ESP32-S3; falls back to SW */
/* #define NO_WOLFSSL_ESP32_CRYPT_AES */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI_MP_MUL */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI_MULMOD */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI_EXPTMOD */
/***** END CONFIG_IDF_TARGET_ESP32S3 *****/

#elif defined(CONFIG_IDF_TARGET_ESP32C3)
/* ESP32-C3 disabled by default, not implemented */
#define NO_ESP32_CRYPT
#define NO_WOLFSSL_ESP32_CRYPT_HASH
#define NO_WOLFSSL_ESP32_CRYPT_AES
#define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI
/* wolfSSL HW Acceleration supported on ESP32-C2. Uncomment to disable: */

/* #define NO_ESP32_CRYPT */
/* #define NO_WOLFSSL_ESP32_CRYPT_HASH */ /* to disable all SHA HW */

/* These are defined automatically in esp32-crypt.h, here for clarity: */
#define NO_WOLFSSL_ESP32_CRYPT_HASH_SHA384 /* no SHA384 HW on C6 */
#define NO_WOLFSSL_ESP32_CRYPT_HASH_SHA512 /* no SHA512 HW on C6 */

/* #define NO_WOLFSSL_ESP32_CRYPT_AES */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI_MP_MUL */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI_MULMOD */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI_EXPTMOD */
/***** END CONFIG_IDF_TARGET_ESP32C3 *****/

#elif defined(CONFIG_IDF_TARGET_ESP32C6)
/* ESP32-C6 disabled by default, not implemented */
#define NO_ESP32_CRYPT
#define NO_WOLFSSL_ESP32_CRYPT_HASH
#define NO_WOLFSSL_ESP32_CRYPT_AES
#define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI
/* wolfSSL HW Acceleration supported on ESP32-C6. Uncomment to disable: */

/* #define NO_ESP32_CRYPT */
/* #define NO_WOLFSSL_ESP32_CRYPT_HASH */
/* These are defined automatically in esp32-crypt.h, here for clarity: */
#define NO_WOLFSSL_ESP32_CRYPT_HASH_SHA384 /* no SHA384 HW on C6 */
#define NO_WOLFSSL_ESP32_CRYPT_HASH_SHA512 /* no SHA512 HW on C6 */

/* #define NO_WOLFSSL_ESP32_CRYPT_AES */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI_MP_MUL */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI_MULMOD */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI_EXPTMOD */
/***** END CONFIG_IDF_TARGET_ESP32C6 *****/

#elif defined(CONFIG_IDF_TARGET_ESP32H2)
/* ESP32-H2 disabled by default, not implemented */
/* wolfSSL Hardware Acceleration not yet implemented */
#define NO_ESP32_CRYPT
#define NO_WOLFSSL_ESP32_CRYPT_HASH
#define NO_WOLFSSL_ESP32_CRYPT_AES
#define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI
/***** END CONFIG_IDF_TARGET_ESP32H2 *****/

#else
/* anything else unknown will have HW disabled by default */
/* Anything else encountered, disable HW accleration */
#define NO_ESP32_CRYPT
#define NO_WOLFSSL_ESP32_CRYPT_HASH
#define NO_WOLFSSL_ESP32_CRYPT_AES
#define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI
#endif /* CONFIG_IDF_TARGET Check */

/* optional SM4 Ciphers. See https://github.com/wolfSSL/wolfsm
#define WOLFSSL_SM2
#define WOLFSSL_SM3
#define WOLFSSL_SM4
*/

#if defined(WOLFSSL_SM2) || defined(WOLFSSL_SM3) || defined(WOLFSSL_SM4)
#include <wolfssl/certs_test_sm.h>
#define CTX_CA_CERT root_sm2
#define CTX_CA_CERT_SIZE sizeof_root_sm2
#define CTX_CA_CERT_TYPE WOLFSSL_FILETYPE_PEM
#define CTX_SERVER_CERT server_sm2
#define CTX_SERVER_CERT_SIZE sizeof_server_sm2
#define CTX_SERVER_CERT_TYPE WOLFSSL_FILETYPE_PEM
#define CTX_SERVER_KEY server_sm2_priv
#define CTX_SERVER_KEY_SIZE sizeof_server_sm2_priv
#define CTX_SERVER_KEY_TYPE WOLFSSL_FILETYPE_PEM

#undef WOLFSSL_BASE16
#define WOLFSSL_BASE16
#else
#define USE_CERT_BUFFERS_2048
#define USE_CERT_BUFFERS_256
#define CTX_CA_CERT ca_cert_der_2048
#define CTX_CA_CERT_SIZE sizeof_ca_cert_der_2048
#define CTX_CA_CERT_TYPE WOLFSSL_FILETYPE_ASN1
#define CTX_SERVER_CERT server_cert_der_2048
#define CTX_SERVER_CERT_SIZE sizeof_server_cert_der_2048
#define CTX_SERVER_CERT_TYPE WOLFSSL_FILETYPE_ASN1
#define CTX_SERVER_KEY server_key_der_2048
#define CTX_SERVER_KEY_SIZE sizeof_server_key_der_2048
#define CTX_SERVER_KEY_TYPE WOLFSSL_FILETYPE_ASN1
#endif
55 changes: 42 additions & 13 deletions wolfcrypt/src/port/Espressif/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,37 +1,66 @@
# ESP32 Port

Support for the ESP32-WROOM-32 on-board crypto hardware acceleration for symmetric AES, SHA1/SHA256/SHA384/SHA512 and RSA primitive including mul, mulmod and exptmod.
Support for the ESP32 on-board cryptographic hardware acceleration for symmetric AES, SHA1/SHA256/SHA384/SHA512 and RSA primitive including mul, mulmod and exptmod.

* ESP32 - Supported
* ESP32S2 - Supported
* ESP32S3 - Supported
* ESP32C2 - Software only (contact support to request hardware acceleration)
* ESP32C3 - Supported
* ESP32C6 - Supported
* ESP32H2 - Software only (contact support to request hardware acceleration)

## ESP32 Acceleration

For detail about ESP32 HW Acceleration, you can find in [Technical Reference Manual](https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf)
More details about ESP32 HW Accelerationcan be found in:

* [ESP32 Technical Reference Manual](https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf)
* [ESP32-S2 Technical Reference Manual](https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf)
* [ESP32-S3 Technical Reference Manual](https://www.espressif.com/sites/default/files/documentation/esp32-s3_technical_reference_manual_en.pdf)
* [ESP32-C2 (aka ESP8684 Technical Reference Manual](https://www.espressif.com/sites/default/files/documentation/esp8684_technical_reference_manual_en.pdf)
* [ESP32-C3 Technical Reference Manual](https://www.espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_en.pdf)
* [ESP32-C6 Technical Reference Manual](https://www.espressif.com/sites/default/files/documentation/esp32-c6_technical_reference_manual_en.pdf)
* [ESP32-H2 Technical Reference Manual](https://www.espressif.com/sites/default/files/documentation/esp32-h2_technical_reference_manual_en.pdf)

### Building

```
git clone --recurse-submodules -j8 https://github.com/espressif/esp-idf master
```
Simply run `ESP-IDF.py` in any of the [Espressif/ESP-IDF/Examples](https://github.com/wolfSSL/wolfssl/tree/master/IDE/Espressif/ESP-IDF/examples).
See the respective project README files. Examples are also available using wolfssl as a [Managed Component](https://components.espressif.com/components/wolfssl/wolfssl).

Hardware acceleration is enabled by default. All settings should be adjusted in the respective project component
`user_settings.h` file. See the example in [template example](https://github.com/wolfSSL/wolfssl/blob/master/IDE/Espressif/ESP-IDF/examples/template/components/wolfssl/include/user_settings.h).
In particular, comment out the `NO_[feature_name]` macros to enable hardware encryption:

Hardware acceleration is enabled by default.
/* #define NO_ESP32_CRYPT */
/* #define NO_WOLFSSL_ESP32_CRYPT_HASH */
/* #define NO_WOLFSSL_ESP32_CRYPT_AES */
/* #define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI */

To disable portions of the hardware acceleration you can optionally define:
To disable specific portions of the hardware acceleration you can optionally define:

```c
/* Disabled SHA, AES and RSA acceleration */
/* Disable all SHA, AES and RSA acceleration */
#define NO_ESP32_CRYPT
/* Disabled AES acceleration */

/* Disable only AES acceleration */
#define NO_WOLFSSL_ESP32_CRYPT_AES
/* Disabled SHA acceleration */

/* Disabled only SHA acceleration */
#define NO_WOLFSSL_ESP32_CRYPT_HASH
/* Disabled RSA Primitive acceleration */

/* Disabled only RSA Primitive acceleration */
#define NO_WOLFSSL_ESP32_CRYPT_RSA_PRI
```

See the [wolfcrypt/port/Espressif/esp32-crypt.h](https://github.com/wolfSSL/wolfssl/blob/master/wolfssl/wolfcrypt/port/Espressif/esp32-crypt.h)
for more details on fine tuning and debugging options.

### Coding

In 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`.
If building the sources directly we recommend defining `WOLFSSL_USER_SETTINGS` (typically defined in the `CMakeLists.txt`)
and adding your own `user_settings.h` file. You can find a good reference in the [Espressif examples](https://github.com/wolfSSL/wolfssl/tree/master/IDE/Espressif/ESP-IDF/examples)
as well as other examples such as [IDE/GCC-ARM/Header/user_settings.h](https://github.com/wolfSSL/wolfssl/blob/master/IDE/GCC-ARM/Header/user_settings.h).

To view disassembly, add `__attribute__((section(".iram1")))` decorator. Foe example:

Expand Down
Loading

0 comments on commit 9227020

Please sign in to comment.