Getting started with the Cryptographic Library

This page explains how to use the STM32 cryptographic firmware library software expansion for STM32Cube package once you've downloaded it, and the CMOX library it includes.

1. Package Structure & Contents

After uncompressing the package, you'll have this usual folder structure:

• ...\Drivers\STM32xx_HAL_Drivers
  • Help on HAL/LL drivers
  • HAL release notes
  • HAL and LL drivers source files

• ...\Drivers\BSP
  • BSP drivers for all supported boards
  • Drivers for all the external components used on the supported boards

• ...\Drivers\CMSIS
  • CMSIS files that define peripherals register declaration, bit definition and address mapping
    

• ...\Middlewares
  • Middleware libraries
    
  • Middleware release notes
    

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

The Cryptographic Library middleware folder in details:

• ...\Middlewares\ST\STM32_Cryptographic\include
  • Cryptographic library header files
• ...\Middlewares\ST\STM32_Cryptographic\interface
  • Low layer template files to implement in your project 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
  • The complete Cryptographic Library API documentation

2. Creating a project that embeds the Cryptographic Library

2.1. Select a library

Add to your project the library corresponding to your needs.

Example: choose libSTM32Cryptographic_CM33.a to build a project for a 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, renaming 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 this cmox_low_level_template.c file includes 2 functions implementations:

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

It is mandatory to keep both these functions that 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. In order for the library services to work well, it is required that, prior to call any of them (excluding the cmox_initialize and cmox_finalize ones), the CRC peripheral is reset to its default configuration.

In concrete:

• If your application is using the CRC peripheral, you need to perform a reset of the CRC peripheral before any call to the library services (excluding the cmox_initialize and cmox_finalize ones).
• Else, 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 that will call the Cryptographic Library services.

Information

NOTE: To help you in this process, you can refer to the application examples provided or looking at the CMOX.chm file for a detailed description of the different APIs.

2.5. Usual errors

• The project is building without errors, but execution reports error and wrong results. Most usual causes are:
  • CRC peripheral not managed properly see CRC Peripheral Usage
  • Stack depth is not enough

3. Library configuration

3.1. Link time configuration mechanism

The Cryptographic Library, instead of being built under different configurations, 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 signle 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 the way to select the configuration with these APIs and others, refer to the CMOX.chm file.

Information

NOTE: The toolchain linker will only embed in the generated binary the implementations that are called by the application, thus reducing the binary to the strict minimum needed.

3.2. Configurable library services

Configurable cryptographic services are:

• 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 : fast implementation.
  • CMOX_MATH_FUNCS_SUPERFAST256 : 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.

Information

NOTE: To ease the configuration selection some performances figures are available, to give configuration impacts on performance and size indicators.

3.3. Default configuration usage

The default configuration file used by the Library is cmox_default_config.h which is provided into the include folder of the Cryptographic Library middleware.

User 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 using the defines listed above, simply use the “meta defines” specified into the default file in use when applicable.

Meta defines list:

• 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
  • CMOX_ECC256_MATH_FUNCS
• 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, selecting for each meta define, the configuration that suits your need.