Configuring PSA Crypto API

The PSA Crypto in the nRF Connect SDK provides secure crypto operations through standardized Platform Security Architecture. Using one of the two available implementations of the PSA Crypto API, the SDK implements the cryptographic features in software or using hardware accelerators, or both.

Note

If you work with the Mbed TLS legacy crypto toolbox, see Configuring nRF Security with legacy crypto APIs.

Enabling PSA Crypto API

To use the PSA Crypto API in your application, enable the following Kconfig options depending on your chosen implementation:

• For the Oberon PSA Crypto implementation, enable the CONFIG_NRF_SECURITY Kconfig option.

• For the TF-M Crypto Service implementation, enable the CONFIG_NRF_SECURITY and CONFIG_BUILD_WITH_TFM Kconfig options. For more information, see Enabling secure services.

• For the IronSide Secure Enclave implementation, enable the CONFIG_NRF_SECURITY Kconfig option on the nRF54H20’s Application core.

Configuring single drivers

The nRF Security subsystem allows you to configure individual drivers for cryptographic operations. Each driver can be enabled or disabled independently through Kconfig options.

Enabling the Arm CryptoCell nrf_cc3xx driver

To enable the Arm CryptoCell nrf_cc3xx driver, set the CONFIG_PSA_CRYPTO_DRIVER_CC3XX Kconfig option.

Using the Arm CryptoCell nrf_cc3xx driver

To use the nrf_cc3xx_mbedcrypto library PSA driver, the Arm CryptoCell CC310/CC312 hardware must be first initialized.

The Arm CryptoCell hardware compatible with nrf_cc3xx is initialized in the hw_cc3xx.c file, located under nrf/drivers/hw_cc3xx/, and is controlled with the CONFIG_HW_CC3XX Kconfig option. The Kconfig option has a default value of y when nrf_cc3xx is available in the SoC.

Enabling the CRACEN driver

To enable the CRACEN driver, set the CONFIG_PSA_CRYPTO_DRIVER_CRACEN Kconfig option.

The nrf_oberon driver may then be disabled by using the Kconfig option CONFIG_PSA_CRYPTO_DRIVER_OBERON (CONFIG_PSA_CRYPTO_DRIVER_OBERON=n).

Note

• On nRF54L Series devices, CRACEN is the only source of entropy. Therefore, it is not possible to disable the CONFIG_PSA_CRYPTO_DRIVER_CRACEN Kconfig option when the Zephyr entropy driver is enabled.

• On nRF54H20, the IronSide Secure Enclave firmware relies on the CRACEN driver. However, you do not need to enable the CONFIG_PSA_CRYPTO_DRIVER_CRACEN Kconfig option when the program the firmware bundle onto the Secure Domain. For more information, see the IronSide Secure Enclave page.

Enabling the nrf_oberon driver

To enable the nrf_oberon driver, set the CONFIG_PSA_CRYPTO_DRIVER_OBERON Kconfig option to y. Enabling the nrf_oberon driver automatically enables the software fallback mechanism to nrf_oberon.

Disabling the software fallback

To disable the software fallback mechanism to nrf_oberon, set the CONFIG_PSA_CRYPTO_DRIVER_OBERON Kconfig option to n.

Configuring multiple drivers

The nRF Security subsystem supports multiple enabled PSA Crypto API drivers at the same time. If you do, you can fine-tune which drivers implement support for cryptographic features. This mechanism is intended to extend the available feature set of hardware-accelerated cryptography or to provide alternative implementations of the PSA Crypto APIs.

Enabling more than one PSA driver might add support for additional key sizes or modes of operation.

You can disable specific features on the PSA driver level to optimize the code size.

To enable a specific PSA Crypto API driver, set the respective Kconfig option, as listed in the following table:

PSA Crypto API driver	Configuration option	Notes
nrf_cc3xx	CONFIG_PSA_CRYPTO_DRIVER_CC3XX	Only on nRF52840, nRF91 Series, and nRF5340 devices
CRACEN	CONFIG_PSA_CRYPTO_DRIVER_CRACEN	Only on nRF54L Series devices
nrf_oberon	CONFIG_PSA_CRYPTO_DRIVER_OBERON

If you enable multiple drivers, the item higher in the list takes precedence for an enabled cryptographic feature, unless the driver does not enable or support it.

The nrf_cc3xx driver allows enabling or disabling of specific PSA APIs (such as psa_cipher_encrypt, psa_sign_hash), but not individual algorithms.

The nrf_oberon driver allows finer configuration granularity, allowing you to enable or disable individual algorithms as well.

When multiple enabled drivers support the same cryptographic feature, the configuration system attempts to include only one implementation to minimize code size.

Configuring cryptographic features

You can enable a cryptographic feature or algorithm using CONFIG_PSA_WANT_* and CONFIG_PSA_USE_* Kconfig options, which are specific to the feature selection mechanism of the PSA Crypto API. For a list of supported cryptographic features and algorithms and the Kconfig options to enable them, see Supported cryptographic operations in the nRF Connect SDK.

For example, to enable support for the Encrypted key usage scheme (CRACEN_KMU_KEY_USAGE_SCHEME_ENCRYPTED), set the following Kconfig options:

• CONFIG_PSA_WANT_KEY_TYPE_AES

• CONFIG_PSA_WANT_AES_KEY_SIZE_256

• CONFIG_PSA_WANT_ALG_ECB_NO_PADDING

• CONFIG_PSA_WANT_ALG_CMAC

• CONFIG_PSA_WANT_ALG_SP800_108_COUNTER_CMAC

• CONFIG_PSA_WANT_ALG_GCM

  CONFIG_PSA_WANT_KEY_TYPE_AES=y
  CONFIG_PSA_WANT_AES_KEY_SIZE_256=y
  CONFIG_PSA_WANT_ALG_ECB_NO_PADDING=y
  CONFIG_PSA_WANT_ALG_CMAC=y
  CONFIG_PSA_WANT_ALG_SP800_108_COUNTER_CMAC=y
  CONFIG_PSA_WANT_ALG_GCM=y
  

This configuration enables the key type (AES) and the key size (256 bits) supported by the Encrypted usage scheme, as explained in the Key types that can be stored in the KMU section. In addition, it enables the following cryptographic features supported by the CRACEN driver:

• Cipher mode: AES ECB (Electronic CodeBook) mode, no padding

• Message Authentication Code (MAC) cipher: Cipher-based MAC (CMAC) cipher

• Key derivation function (KDF) support: SP800-108 CMAC in counter mode

• Authenticated Encryption with Associated Data (AEAD) cipher: Galois Counter Mode (GCM) cipher

Configuring countermeasures

The CRACEN driver supports several side-channel countermeasures available on the CRACEN peripheral. You can enable or disable these countermeasures using Kconfig options for devices that support them. For the support breakdown and the Kconfig options, see Side-channel countermeasures.

Building PSA Crypto API

Depending on the implementation you are using, the nRF Connect SDK build system uses different versions of the PSA Crypto API.

PSA Crypto API versions by implementation

Implementation	PSA Crypto API version
Oberon PSA Crypto	v1.4.0
TF-M Crypto Service	v1.4.1
IronSide Secure Enclave	v1.3.1