nRF5 SDK v17.0.2
Configuring nrf_crypto frontend and backends

The nrf_crypto frontend and multiple backends can be configured by editing the sdk_config.h file. For general information about nRF5 SDK configuration through sdk_config.h, refer to SDK configuration header file.

Configuring nrf_crypto through sdk_config.h

This chapter explains how to enable the nrf_crypto frontend and backends by controlling the defines in sdk_config.h.

Enabling the nrf_crypto frontend

Enabling nrf_crypto
//==========================================================
// <e> NRF_CRYPTO_ENABLED - nrf_crypto - Cryptography library
//==========================================================
#ifndef NRF_CRYPTO_ENABLED
#define NRF_CRYPTO_ENABLED 1
#endif

Enabling this define gives access to use the nrf_crypto frontend APIs. Keep in mind that at least one of the nrf_crypto backends is required to use the API functions.

Enabling an nrf_crypto backend

To enable an nrf_crypto backend, set the NRF_CRYPTO_<XXXX>_BACKEND_ENABLED define to 1.

Enabling NRF_CC310 backend (example)
// </e>
// <e> NRF_CRYPTO_BACKEND_CC310_ENABLED - Enable the ARM Cryptocell CC310 backend.
// <i> The CC310 hardware-accelerated cryptography backend (only available on nRF52840).
//==========================================================
#ifndef NRF_CRYPTO_BACKEND_CC310_ENABLED
#define NRF_CRYPTO_BACKEND_CC310_ENABLED 1
#endif

To disable an nrf_crypto backend, change the define to 0.

Note
Every cryptographic function mode available in an nrf_crypto backend will normally be enabled by default in the nRF5 SDK. This has no impact on the code size if the backend is not enabled.

Enabling multiple nrf_crypto backends

It is possible to mix and match support from multiple backends at the same time. Doing so may require disabling one or more cryptographic function modes in one or more of the backends.

You will get a compilation error if multiple backends that support the same cryptographic function mode are enabled at once:

Error message when enabling multiple backends that support a cryptographic function mode
|error: #35: #error directive: "More than one backend enabled for secp256r1 (NIST 256-bit).");

|

Note
The format of the error message may be different for different compilers.

Enabling a cryptographic function mode in an nrf_crypto backend

It is possible to enable or disable cryptographic function modes by controlling specific defines in sdk_config.h. The supported modes are grouped inside the backends that support them.

Enabling SHA-256 in the nrf_oberon backend
// <q> NRF_CRYPTO_BACKEND_OBERON_HASH_SHA256_ENABLED - Oberon SHA-256 hash functionality
// <i> Oberon backend implementation for SHA-256.
#ifndef NRF_CRYPTO_BACKEND_OBERON_HASH_SHA256_ENABLED
#define NRF_CRYPTO_BACKEND_OBERON_HASH_SHA256_ENABLED 1
#endif

To disable a cryptographic function mode in a backend, change the define to 0.

Note
There is no effect of having a specific mode enabled for a backend unless the backend itself is enabled. In the nRF5 SDK, the supported modes are generally enabled by default.

nrf_crypto automatic defines

When an nrf_crypto frontend and backend is enabled, there are automatic defines available for you to use. These are either on cryptographic family level (such as nrf_crypto_hash) or on cryptographic family mode (such as nrf_crypto_hash_sha256).

Note
Automatic defines are compile-time constructs that can be used to verify compilation. For usage information, refer to Compile-time verification of cryptographic support.

Defines for supported cryptographic family of functions

If a cryptograpic function is enabled by enabling an nrf_crypto frontend and one of the backends, a define is declared for the family of cryptographic routines. The define has the value 1 if the cryptographic function is available.

Note
This define cannot be traced to a single header file. The define is only set when NRF_CRYPTO_ENABLED is set to 1 and one of the backends that supports the given cryptographic family of functions is also set to 1.
Cryptographic family Define
AEAD NRF_CRYPTO_AEAD_ENABLED
AES NRF_CRYPTO_AES_ENABLED
ECC (ECDH and ECDSA) NRF_CRYPTO_ECC_ENABLED
HASH NRF_CRYPTO_HASH_ENABLED
HMAC (and HKDF) NRF_CRYPTO_HMAC_ENABLED
RNG NRF_CRYPTO_RNG_ENABLED

Defines for supported modes within a cryptographic family of functions

Cryptographic function modes are enabled by Enabling the nrf_crypto frontend, Enabling an nrf_crypto backend, and Enabling a cryptographic function mode in an nrf_crypto backend.


Cryptographic modes Define
AES - CBC NRF_CRYPTO_AES_CBC_ENABLED
AES - CBC MAC NRF_CRYPTO_AES_CBC_MAC_ENABLED
AES - CFB NRF_CRYPTO_AES_CFB_ENABLED
AES - CTR NRF_CRYPTO_AES_CTR_ENABLED
AES - CCM NRF_CRYPTO_AES_CCM_ENABLED
AES - CCM* NRF_CRYPTO_AES_CCM_STAR_ENABLED
AES - CMAC NRF_CRYPTO_AES_CMAC_ENABLED
AES - ECB NRF_CRYPTO_AES_ECB_ENABLED
AES - CMAC_PRF128 NRF_CRYPTO_AES_CMAC_PRF128_ENABLED
AES - EAX NRF_CRYPTO_AES_EAX_ENABLED
AES - GCM NRF_CRYPTO_AES_GCM_ENABLED
ECDH and ECDSA (secp160r1) NRF_CRYPTO_ECC_SECP160R1_ENABLED
ECDH and ECDSA (secp160r2) NRF_CRYPTO_ECC_SECP160R2_ENABLED
ECDH and ECDSA (secp192r1) NRF_CRYPTO_ECC_SECP192R1_ENABLED
ECDH and ECDSA (secp224r1) NRF_CRYPTO_ECC_SECP224R1_ENABLED
ECDH and ECDSA (secp256r1) NRF_CRYPTO_ECC_SECP256R1_ENABLED
ECDH and ECDSA (secp384r1) NRF_CRYPTO_ECC_SECP384R1_ENABLED
ECDH and ECDSA (secp512r1) NRF_CRYPTO_ECC_SECP521R1_ENABLED
ECDH and ECDSA (secp160k1) NRF_CRYPTO_ECC_SECP160K1_ENABLED
ECDH and ECDSA (secp192k1) NRF_CRYPTO_ECC_SECP192K1_ENABLED
ECDH and ECDSA (secp224k1) NRF_CRYPTO_ECC_SECP224K1_ENABLED
ECDH and ECDSA (secp256r1) NRF_CRYPTO_ECC_SECP256K1_ENABLED
ECDH and ECDSA (bp256r1) NRF_CRYPTO_ECC_BP256R1_ENABLED
ECDH and ECDSA (bp384r1) NRF_CRYPTO_ECC_BP384R1_ENABLED
ECDH and ECDSA (bp512r1) NRF_CRYPTO_ECC_BP512R1_ENABLED
ECDH (Curve25519) NRF_CRYPTO_ECC_CURVE25519_ENABLED
EdDSA (Ed25519) NRF_CRYPTO_ECC_ED25519_ENABLED
ChaCha-Poly NRF_CRYPTO_CHACHA_POLY_ENABLED
HASH - SHA-256 NRF_CRYPTO_HASH_SHA256_ENABLED
HASH - SHA-512 NRF_CRYPTO_HASH_SHA512_ENABLED
HMAC - SHA-256 NRF_CRYPTO_HMAC_SHA256_ENABLED
HMAC - SHA-512 NRF_CRYPTO_HMAC_SHA512_ENABLED
Note
If an nrf_crypto frontend and a backend supporting the given mode is not enabled, the defines are not available.

Compile-time verification of cryptographic support

You can use the defines in nrf_crypto automatic defines and Defines for supported modes within a cryptographic family of functions to get compile-time assertions for the required modes of operation.


If your application requires Hash support for SHA-512, you can use the following statement to ensure that SHA-512 is supported.

//Verifying that SHA-512 is enabled in sdk_config.hardware
#include sdk_common.h
#if !NRF_CRYPTO_HASH_SHA512_ENABLED
#error This program requires SHA-512. Enable it in sdk_config.h
#endif

Documentation feedback | Developer Zone | Subscribe | Updated