Getting started with the Cryptographic Library

This page explains how to use the STM32 cryptographic firmware library software expansion for STM32Cube^[1] package as well as the CMOX library it includes, once they have been downloaded.

1. Package structure and content

After uncompressing the package, you get the following folder structure:

...\Drivers\STM32xx_HAL_Drivers
- Help on HAL/LL drivers
- HAL release notes
- Source files of HAL and LL drivers

...\Drivers\BSP
- BSP drivers for all supported boards
- Drivers for all the external components used in the supported boards

...\Drivers\CMSIS
- CMSIS files that define peripheral register declarations, bit definition and address mapping

...\Middlewares
- Middleware libraries
- Middleware release notes

...\Projects
- STM32CubeProjectsList.html, an exhaustive list of all the applications supported for each board
- Then organized by board / feature, a set of applications that demonstrate various cryptographic algorithms provided for several compatible IDEs.

Below the detailed structure of the Cryptographic Library middleware folder:

...\Middlewares\ST\STM32_Cryptographic\include
- Cryptographic library header files
...\Middlewares\ST\STM32_Cryptographic\interface
- Low-layer template files to implement in your project in order to use the Cryptographic Library
...\Middlewares\ST\STM32_Cryptographic\lib
- Cryptographic libraries to link into your project
...\Middlewares\ST\STM32_Cryptographic\legacy_v3
- Legacy Cryptographic library migration helpers (for more details, refer to Migration from previous Cryptographic Library version)
...\Middlewares\ST\STM32_Cryptographic\CMOX.chm
- Complete Cryptographic Library API documentation

2. Creating a project that embeds the Cryptographic Library

Follow the sequence below to create a project.

2.1. Select a library

Add to your project the library that corresponds to your needs.

Example: choose libSTM32Cryptographic_CM33.a to build a project for an Arm^® Cortex^®-M33 based STM32 MCU.

Information

NOTE: Arm^® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.

2.2. Include path

Add to your project settings the path to the include folder.

2.3. Interface files

Copy the cmox_low_level_template.c file from the interface folder to your project specific source folder, and rename it into cmox_low_level.c.
Add this copied file to your project.
Tune this file by including the right STM32 HAL driver header instead of the comment:
- ```
/* #include "stm32<series>xx_hal.h" */
```

As you can see, the cmox_low_level_template.c file includes two function implementations:

cmox_ll_init: CMOX library low level initialization
cmox_ll_deInit: CMOX library low level de-initialization

It is mandatory to keep both functions since they are called by the library upon cmox_initialize and cmox_finalize calls from user application.

CRC peripheral usage
The Cryptographic Library uses the STM32 CRC peripheral for some internal computing. To ensure proper operation of the library services, reset the CRC peripheral to its default configuration prior to calling any library service (except for cmox_initialize and cmox_finalize), .
As a summary:

If your application uses the CRC peripheral, reset the CRC peripheral before any call to the library services (except for cmox_initialize and cmox_finalize).

Otherwise, simply use the provided low-level implementation from cmox_low_level_template.c that will put the CRC peripheral in its reset state upon user application call to cmox_initialize.

2.4. Implement your application

Everything is ready, you can now write your own application calling the cryptographic library services.

Warning

Do not forget to include the header file cmox_crypto.h to your c files to call the Cryptographic Library services.

Information

NOTE: For more help, refer to the application examples provided or look into CMOX.chm file for a detailed description of the different APIs.

2.5. Usual errors

The project is building without errors, but the execution reports errors and wrong results. The most frequent causes are the following:
- CRC peripheral is not managed properly (see CRC Peripheral Usage).
- Stack depth is not sufficient.

During execution of the cryptographic library a Hardfault exception is raised: UsageFault reports Unaligned access.
- This may happen when a compiler maps input array of bytes at a non word-aligned address. To fix it, force word alignment for each input buffers that are declared as an array of bytes.

3. Library configuration

3.1. Link time configuration mechanism

Instead of being built under different configurations, the Cryptographic Library incorporates different implementations of the same service with different levels of performance and/or size.

The implementation to use is selected either in the service configuration through the Construct API or in the service Processing API.

Examples of configuration selection:

Cipher AES CBC encryption: shall be done either in the call to cmox_cbc_construct (when doing the encryption on several API calls) or in the call to cmox_cipher_encrypt (when doing the encryption on one single API call).

RSA: shall be done in the call to cmox_rsa_construct.

ECDSA signature: shall be done in the call to cmox_ecc_construct and in the call to cmox_ecdsa_sign.

Note: For more details on how to select the configuration using these APIs and others, refer to the CMOX.chm file.

Information

NOTE: To reduce the binary to the strict minimum needed, the toolchain linker only embeds in the generated binary the implementations that are called by the application.

3.2. Configurable library services

The configurable cryptographic services are the following:

AES computing
- CMOX_AES_SMALL: small implementation.
- CMOX_AES_FAST: fast implementation.
AES GCM computing (in addition to AES configuration, GCM part is also configurable):
- CMOX_GCM_SMALL: small implementation.
- CMOX_GCM_FAST: fast implementation.
RSA mathematics:
- CMOX_MATH_FUNCS_SMALL: small implementation.
- CMOX_MATH_FUNCS_FAST: fast implementation.
RSA modular exponentiation for private key:
- CMOX_MODEXP_PRIVATE_LOWMEM: low memory usage implementation.
- CMOX_MODEXP_PRIVATE_MIDMEM: intermediate memory usage implementation.
- CMOX_MODEXP_PRIVATE_HIGHMEM: high memory usage implementation.
ECC mathematics:
- CMOX_MATH_FUNCS_SMALL: small implementation.
- CMOX_MATH_FUNCS_FAST ^{[cfg 1]}: fast implementation.
- CMOX_MATH_FUNCS_SUPERFAST256 ^{[cfg 2]}: super-fast implementation.
ECC predefined curves:
- Edwards curves:
  - CMOX_ECC_ED448_LOWMEM: low memory usage implementation.
  - CMOX_ECC_ED448_HIGHMEM: high memory usage implementation.
  - CMOX_ECC_ED25519_OPT_LOWMEM: optimized low memory usage implementation.
  - CMOX_ECC_ED25519_HIGHMEM: high memory usage implementation.
  - CMOX_ECC_ED25519_OPT_HIGHMEM: optimized high memory usage implementation.
- NIST R/K curves:
  - CMOX_ECC_SECPxxxR/K1_LOWMEM: low memory usage implementation.
  - CMOX_ECC_SECPxxxR/K1_HIGHMEM: high memory usage implementation.
- BRAINPOOL R/T curves:
  - CMOX_ECC_BPPxxxR/T1_LOWMEM: low memory usage implementation.
  - CMOX_ECC_BPPxxxR/T1_HIGHMEM: high memory usage implementation.
- ANSSI P-256 curves:
  - CMOX_ECC_FRP256V1_LOWMEM: low memory usage implementation.
  - CMOX_ECC_FRP256V1_HIGHMEM: high memory usage implementation.
- OSCCA 256-bit curves:
  - CMOX_ECC_SM2_LOWMEM: low memory usage implementation.
  - CMOX_ECC_SM2_HIGHMEM: high memory usage implementation.
  - CMOX_ECC_SM2TEST_LOWMEM: low memory usage implementation.
  - CMOX_ECC_SM2TEST_HIGHMEM: high memory usage implementation.

↑ Only applicable to 128-bit multiple elliptic curves, or any curves if running on Cortex^®-M0/M0+ based STM32 MCU
↑ Only applicable to 256-bit elliptic curves

Information

NOTE: To help selecting the appropriate configuration, some performances figures are available. They show the configuration impacts on performance and size.

IMPORTANT
It may happens that, when using the AES Computing Fast implementation, the observed performances are below the Small implementation ones.
To perform AES Computing, the Cryptographic Library uses some specific tables. The Fast implementation uses a bigger table than the Small one allowing less computing. These tables are declared as const, so placed in the flash memory by the toolchain linker. Thus, the access to these tables are impacted by various flash access factors like the read access latency and cache configuration.
In these cases, it is advised to use the Small implementation. But, if you want more performances there is a possibility to change these tables location:

These tables are defined to be located into the CMOX_CTA_PROTECTED_DATA section, you can change the placement of this section by following the procedure described in How to enable CTA resistance in the Cryptographic Library.

3.3. Default configuration usage

The default configuration file used by the library is cmox_default_config.h. It is located in the include folder of the Cryptographic Library middleware.

You can change the default configuration file by defining the preprocessor user definition CMOX_DEFAULT_FILE. This change must be done globally on to the project or at least defined prior to any inclusion of cmox_crypto.h.

Two additional configurations are provided:

cmox_small_config.h: smallest configurations possible
cmox_fast_config.h: fasted configurations possible

To use the configuration selected in the included default configuration file instead of the defines listed above, simply use the “meta defines” specified into the default file in use when applicable.

The list of meta defines is the following:

AES & AES GCM computing:
- Definitions are located in the file “cmox_default_defs.h”
  - CMOX_AES_XXX_ENC/DEC : with XXX in CBC, CCM, CFB, CTR, ECB, GCM, OFB, XTS, KEYWRAP
  - CMOX_CTR_DRBG_AES128/192/256
  - CMOX_CMAC_AES
- All these defines are configured based on the CMOX default file defines: CMOX_AES_IMPLEMENTATION & CMOX_GCM_IMPLEMENTATION
RSA mathematics:' CMOX_RSA_MATH_FUNCS
RSA Modular exponentiation for Private key: CMOX_MODEXP_PRIVATE
ECC mathematics:
- CMOX_ECC_MATH_FUNCS
- CMOX_ECC128MULT_MATH_FUNCS ^{[def 1]}
- CMOX_ECC256_MATH_FUNCS ^{[def 2]}
ECC predefined curves:
- Edwards curves: CMOX_ECC_CURVE_ED448, CMOX_ECC_CURVE_ED25519
- NIST R/K curves: CMOX_ECC_SECPxxxR/K1
- BRAINPOOL R/T curves: CMOX_ECC_BPPxxxR/T1
- ANSSI P-256 curves: CMOX_ECC_FRP256V1
- OSCCA 256-bit curves: CMOX_ECC_CURVE_SM2, CMOX_ECC_CURVE_SM2TEST

Information

NOTE: You can implement your own default configuration file by selecting, for each meta define, the configuration that suits your need.

4. References and Notes

↑ Only applicable to 128-bit multiple elliptic curves, or any curves if running on Cortex^®-M0/M0+ based STM32 MCU
↑ Only applicable to 256-bit elliptic curves

↑ STM32 cryptographic firmware library software expansion for STM32Cube

[2] Only applicable to 128-bit multiple elliptic curves, or any curves if running on Cortex^®-M0/M0+ based STM32 MCU

[3] Only applicable to 256-bit elliptic curves

[4] Only applicable to 128-bit multiple elliptic curves, or any curves if running on Cortex^®-M0/M0+ based STM32 MCU

[5] Only applicable to 256-bit elliptic curves

[1] STM32 cryptographic firmware library software expansion for STM32Cube

[1]

[cfg 1]

[cfg 2]

[def 1]

[def 2]