Configuring nRF Security with legacy crypto APIs
The legacy crypto is a subsystem for software that requires Mbed TLS crypto toolbox API functions that are prefixed with mbedtls_.
It provides TLS and DTLS support and backwards compatibility with older applications that do not use PSA Crypto APIs.
The legacy crypto uses alternative implementations (called backends) of the drivers that are also used for the PSA Crypto API support.
To enable the legacy crypto support mode of nRF Security:
Set the
CONFIG_NRF_SECURITYKconfig option.
Deprecation of legacy crypto support
Caution
Legacy crypto toolbox APIs are marked as deprecated in the nRF Connect SDK version 2.8.0, and will be removed in a future version.
Do not use the legacy crypto toolbox APIs prefixed with mbedtls_ and the related configurations in any new designs.
Instead, use the equivalent functionality from PSA Crypto APIs.
For information about configuring PSA Crypto API support, see Configuring PSA Crypto API.
The following changes have been made to the legacy crypto support with the deprecation announcement:
The legacy Mbed TLS APIs no longer support the glued functionality.
Legacy configurations no longer have an effect on the configurations for the secure image of a TF-M build.
Configuring the legacy crypto backend
The legacy crypto backend is a term describing a set of configurations that provide low-level integration with Mbed TLS that were used before the adoption of PSA Crypto APIs in the nRF Connect SDK. These legacy crypto backends are provided as alternative implementations of the drivers that are also used for the PSA Crypto API support.
The legacy crypto configuration only allows one backend to be enabled at the same time.
AES configuration
The AES core is enabled with the Kconfig option CONFIG_MBEDTLS_AES_C.
This enables AES ECB cipher mode and allows the following ciphers and modes to be configured:
CTR
CBC
XTS
CMAC
CCM/CCM*
GCM
Feature support
Cipher mode |
Backend |
Key size |
|---|---|---|
ECB |
nrf_cc310 |
128-bit key |
nrf_cc312 |
128-bit key |
|
192-bit key |
||
256-bit key |
||
nrf_oberon |
128-bit key |
|
192-bit key |
||
256-bit key |
Note
The Configuring the legacy crypto backend uses some functionality from the original Mbed TLS for AES operations.
Note
Whenever this documentation mentions ‘original’ Mbed TLS, it refers to the open-source Arm Mbed TLS project, not the customized version available in Zephyr. There is an option to utilize a ‘built-in’ driver, which corresponds to the software-implemented cryptography from the ‘original’ Mbed TLS deliverables. This is provided to ensure that the cryptographic toolbox supports all requested features.
AES cipher configuration
To configure AES cipher modes, set the following Kconfig options:
Cipher mode |
Configurations |
Note |
|---|---|---|
CTR |
||
CBC |
Note
AES cipher modes are dependent on enabling AES core support according to AES configuration.
Feature support
Cipher mode |
Backend |
Key size |
Note |
|---|---|---|---|
CTR |
nrf_cc310 |
128-bit key |
|
nrf_cc312 |
128-bit key |
||
192-bit key |
|||
256-bit key |
|||
nrf_oberon |
128-bit key |
||
192-bit key |
|||
256-bit key |
|||
CBC |
nrf_cc310 |
128-bit key |
|
nrf_cc312 |
128-bit key |
||
192-bit key |
|||
256-bit key |
|||
nrf_oberon |
128-bit key |
||
192-bit key |
|||
256-bit key |
|||
XTS |
nrf_cc310 |
N/A |
Backend not supported |
nrf_cc312 |
N/A |
Backend not supported |
|
nrf_oberon |
128-bit key |
||
192-bit key |
|||
256-bit key |
CMAC configuration
Feature support
Algorithm |
Backend |
Key size |
|---|---|---|
CMAC |
nrf_cc310 |
128-bit key |
nrf_cc312 |
128-bit key |
|
192-bit key |
||
256-bit key |
||
nrf_oberon |
128-bit key |
|
192-bit key |
||
256-bit key |
AEAD configurations
To configure Authenticated Encryption with Associated Data (AEAD), set the following Kconfig options:
AEAD cipher |
Configurations |
Note |
|---|---|---|
AES CCM/CCM* |
||
AES GCM |
nrf_oberon or nrf_cc312 |
Note
AEAD AES cipher modes are dependent on enabling AES core support according to AES configuration.
When the
nrf_cc310backend is used, AES GCM is provided by the original Mbed TLS implementation.The ChaCha-Poly implemented by the
nrf_cc3xxbackend does not support incremental operations.The ChaCha-Poly implemented by the Configuring the legacy crypto backend does not support incremental operations.
Feature support
AEAD cipher |
Backend |
Key size |
Note |
|---|---|---|---|
AES CCM/CCM* |
nrf_cc310 |
128-bit key |
|
nrf_cc312 |
128-bit key |
||
192-bit key |
|||
256-bit key |
|||
nrf_oberon |
128-bit key |
||
192-bit key |
|||
256-bit key |
|||
AES GCM |
nrf_cc312 |
128-bit key |
|
192-bit key |
|||
256-bit key |
|||
nrf_oberon |
128-bit key |
||
192-bit key |
|||
256-bit key |
|||
ChaCha20 |
nrf_cc3xx |
256-bit key |
|
nrf_oberon |
256-bit key |
||
Poly1305 |
nrf_cc3xx |
256-bit key |
|
nrf_oberon |
256-bit key |
||
ChaCha-Poly |
nrf_cc3xx |
256-bit key |
The ChaCha-Poly implementation in Configuring the legacy crypto backend does not support incremental operations. |
nrf_oberon |
256-bit key |
DHM configurations
Feature support
Algorithm |
Backend |
Key size |
Note |
|---|---|---|---|
DHM |
nrf_cc3xx | Limited to 2048 bits | |
||
nrf_oberon |
N/A |
Backend not supported |
|
Note
The Configuring the legacy crypto backend uses functionality from the original Mbed TLS for DHM operations.
ECC configurations
Elliptic Curve Cryptography (ECC) configuration provides support for Elliptic Curve over GF(p).
To configure ECC core support, set the CONFIG_MBEDTLS_ECP_C Kconfig option.
Enabling CONFIG_MBEDTLS_ECP_C will activate configuration options that depend on ECC, such as ECDH, ECDSA, ECJPAKE, and a selection of ECC curves to support in the system.
Feature support
Algorithm |
Backend |
Curve group |
Curve type |
|---|---|---|---|
ECP |
nrf_cc3xx |
NIST |
secp192r1 |
secp224r1 |
|||
secp256r1 |
|||
secp384r1 |
|||
secp521r1 |
|||
Koblitz |
secp192k1 |
||
secp224k1 |
|||
secp256k1 |
|||
Curve25519 |
Curve25519 |
||
nrf_oberon |
NIST |
secp256r1 |
|
secp224r1 |
|||
Curve25519 |
Curve25519 |
ECDH configurations
Note
ECDH support depends on ECC Configurations being enabled.
The nrf_cc3xx_mbedcrypto library does not integrate on ECP layer. Only the top-level APIs for ECDH are replaced.
Feature support
Algorithm |
Backend |
Curve group |
Curve type |
|---|---|---|---|
ECDH |
nrf_cc3xx |
NIST |
secp192r1 |
secp224r1 |
|||
secp256r1 |
|||
secp384r1 |
|||
secp521r1 |
|||
Koblitz |
secp192k1 |
||
secp224k1 |
|||
secp256k1 |
|||
Curve25519 |
Curve25519 |
||
nrf_oberon |
NIST |
secp256r1 |
|
secp224r1 |
|||
Curve25519 |
Curve25519 |
ECDSA configurations
To configure Elliptic Curve Digital Signature Algorithm (ECDSA) support, set the CONFIG_MBEDTLS_ECDSA_C Kconfig option.
Algorithm |
Configurations |
|---|---|
ECDSA |
Note
ECDSA support depends on ECC Configurations being enabled.
The nrf_cc3xx_mbedcrypto library does not integrate on ECP layer. Only the top-level APIs for ECDSA are replaced.
Feature support
Algorithm |
Backend |
Curve group |
Curve type |
|---|---|---|---|
ECDSA |
nrf_cc3xx |
NIST |
secp192r1 |
secp224r1 |
|||
secp256r1 |
|||
secp384r1 |
|||
secp521r1 |
|||
Koblitz |
secp192k1 |
||
secp224k1 |
|||
secp256k1 |
|||
Curve25519 |
Curve25519 |
||
nrf_oberon |
NIST |
secp256r1 |
|
secp224r1 |
|||
Curve25519 |
Curve25519 |
ECJPAKE configurations
Note
ECJPAKE support depends upon ECC Configurations being enabled.
Feature support
Algorithm |
Backend |
Curve group |
Curve type |
|---|---|---|---|
ECJPAKE |
nrf_cc3xx |
NIST |
secp256r1 |
nrf_oberon |
NIST |
secp256r1 |
ECC curves configurations
It is possible to configure the curves that should be supported in the system depending on the backend selected.
Note
The nrf_oberon crypto library only supports ECC curve secp224r1 and secp256r1.
Choosing the nrf_oberon backend does not allow enabling the rest of the ECC curve types.
RSA configurations
To configure Rivest-Shamir-Adleman (RSA) support, set the CONFIG_MBEDTLS_RSA_C Kconfig option.
Feature support
Algorithm |
Backend |
Key size |
|---|---|---|
RSA |
nrf_cc310 |
1024-bit key |
1536-bit key |
||
2048-bit key |
||
nrf_cc312 |
1024-bit key |
|
1536-bit key |
||
2048-bit key |
||
3072-bit key |
||
nrf_oberon |
1024-bit key |
|
1536-bit key |
||
2048-bit key |
||
3072-bit key |
Note
The Configuring the legacy crypto backend uses functionality from the original Mbed TLS for RSA operations.
Secure Hash configurations
To configure the Secure Hash algorithms, set the following Kconfig options:
Algorithm |
Support |
Backend selection |
|---|---|---|
SHA-256 |
||
SHA-512 |
Feature support
Algorithm |
Supported backends |
Note |
|---|---|---|
SHA-1 |
nrf_cc3xx |
|
nrf_oberon |
||
SHA-224 |
nrf_cc3xx |
SHA-224 must be enabled when enabling SHA-256 |
nrf_oberon |
||
SHA-256 |
nrf_cc3xx |
|
nrf_oberon |
||
SHA-384 |
nrf_cc3xx |
|
nrf_oberon |
||
SHA-512 |
nrf_cc3xx |
|
nrf_oberon |