RIOT/sys/psa_crypto/doc.md

@defgroup sys_psa_crypto PSA Cryptographic API @ingroup sys @brief Implements the PSA Crypto API specification. @see https://armmbed.github.io/mbed-crypto/html/

@warning This implementation is not complete and not yet thoroughly tested. Please do not use this module in production, as it may introduce security issues.

@note This implementation is not complete and will be successively expanded.

About

This module implements the PSA Cryptography API Version 1.1 as specified here and the PSA Status code API Version 1.0 as specified here. It provides an OS level access to cryptographic operations and supports software and hardware backends as well as the use of secure elements. The API automatically builds a hardware backend for an operation, if there's one available, otherwise it falls back to software. Specific backends can be configured, if needed. For configuration options see Configuration.

PSA Crypto has an integrated key management module, which stores keys internally without exposing them to applications. To learn how to use keys with PSA, read Using Keys.

A basic usage and configuration example can be found in examples/advanced/psa_crypto. For more usage instructions, please read the documentation.

If you want to add your own crypto backend, see Porting Guide.

Basic Usage

To use PSA Crypto, add psa/crypto.h to your includes. This will make all operations and macros available.

The library is automatically initialized on startup if @ref sys_auto_init is used (enabled by default). Otherwise, @ref psa_crypto_init needs to be called before any other operation.

Structure Initialization

Whenever you declare a PSA Crypto structure (e.g. operation contexts or key attributes), it needs to be initialized with zeroes. A structure that is not initialized will be interpreted by PSA as active and can not be used for a new operation. The example function and macro shown below result in the same thing: A new, inactive structure.

// Choose one of these options
psa_hash_operation_t hash_op = psa_hash_operation_init();
psa_hash_operation_t hash_op = PSA_HASH_OPERATION_INIT;

An already active operation can be set to zero by reinitializing it. It then becomes inactive again and can be used for a new operation.

When errors occur during execution, PSA resets the operation contexts and makes them inactive, to prevent unauthorized access to an operation's state. Users can also call psa_<operation>_abort() anytime in between function calls to do the same.

Using Keys

PSA can only operate on keys, that are registered with and stored within the internal key storage module. This means you need to either generate keys with PSA or import an existing key. For this purpose there are a number of key management functions (external link).

Key Attributes

When creating a key for PSA, the implementation needs to know what kind of key it is dealing with, what it can be used for, where it's supposed to be stored, etc. That information needs to be specified in a set of Key Attributes (external link).

The example below defines attributes for an AES-128 key, which can be used for CBC encryption and decryption and will be stored in local volatile memory.

// Initializes empty attributes structure
psa_key_attributes_t attributes = psa_key_attributes_init();

// Set all necessary attributes
psa_set_key_lifetime(&attributes, PSA_KEY_LIFETIME_VOLATILE);
psa_set_key_type(&attributes, PSA_KEY_TYPE_AES);
psa_set_key_bits(&attributes, 128);
psa_set_key_algorithm(&attributes, PSA_ALG_CBC_NO_PADDING);
psa_set_key_usage_flags(&attributes, (PSA_KEY_USAGE_ENCRYPT | PSA_KEY_USAGE_DECRYPT));

After setting the attributes, an exiting key can be imported:

uint8_t aes_key[] = { ... };
psa_key_id_t key_id = 0;     // Will be set by PSA Crypto
psa_status_t status = psa_import_key(&attributes, aes_key, sizeof(aes_key), &key_id);

The PSA Crypto implementation will assign an identifier to the key and return it via the key_id parameter. This identifier can then be used for operations with this specific key.

uint8_t PLAINTEXT[] = { ... };
// Buffer sizes can be calculated with macros
size_t output_buf_size = PSA_CIPHER_ENCRYPT_OUTPUT_SIZE(PSA_KEY_TYPE_AES, PSA_ALG_CBC_NO_PADDING,sizeof(PLAINTEXT));
uint8_t output_buffer[output_buf_size];

status = psa_cipher_encrypt(key_id, PSA_ALG_CBC_NO_PADDING, PLAINTEXT, sizeof(PLAINTEXT), output_buffer, sizeof(output_buffer), &output_length);

All the supported key types, algorithms and usage flags can be found in the documentation.

Key Lifetime

Volatile vs. Persistent

The PSA API specifies two ways of storing keys: volatile and persistent. Volatile keys will be stored only in RAM, which means they will be destroyed after application termination or a device reset. Persistent keys will also be written into flash memory for later access. To destroy them they must be explicitly deleted with the psa_destroy_key() function.

@note Persistent key storage can be optionally enabled on native and on the nRF52840dk. For this, add USEMODULE += psa_persistent_storage to your application makefile or CONFIG_MODULE_PSA_PERSISTENT_STORAGE=y to your app.config.test file. Example: tests/sys/psa_crypto_persistent_storage

@warning Be aware that the current implementation writes keys in plain text to flash memory. Anyone with hardware access can read them.

Lifetime Encoding

When creating a key, the user needs to specify a lifetime value, which actually consists of two values: persistence and location. The location defines the actual memory location of the key (e.g. whether the key will be stored in RAM, in a hardware protected memory slot or on an external device like a secure element).

The persistence value defines whether the key will be stored in RAM (volatile) in flash (persistent). Some default values that exist are:

• @ref PSA_KEY_LIFETIME_VOLATILE (stored in local, volatile memory)
• @ref PSA_KEY_LIFETIME_PERSISTENT (stored in local, persistent memory)

Other lifetime values can be constructed with the macro PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(persistence, location). All supported PSA_KEY_PERSISTENCE_* and PSA_KEY_LOCATION_* values can be combined.

In addition to the location values defined by the specification, this implementation also supports values for Secure Elements.

Configuration

Currently there are two ways to configure PSA Crypto: Kconfig and Makefiles. An example for both can be found in RIOT/examples/advanced/psa_crypto.

Kconfig

We recommend using Kconfig and choosing your features in menuconfig. You can access the GUI by calling

TEST_KCONFIG=1 BOARD=<your board> make menuconfig

from your application directory. There you can find the available PSA features and options under System->PSA Crypto. If you only select the operations you want to use (e.g. PSA Ciphers->AES-128 CBC), Kconfig will automatically select the best backend for you depending on the board (e.g. a hardware accelerator if it is available). Optionally you can force a custom backend.

Further you can specify the exact number of keys you need to store (section PSA Key Management Configuration in menuconfig), or choose your Secure Element configurations.

Alternatively you can create an app.config.test file in your application folder and choose your symbols there (see examples/advanced/psa_crypto).

In the app.config.test file, modules can be chosen with the following syntax: CONFIG_MODULE_<MODULENAME>=y, as shown below.

CONFIG_MODULE_PSA_CRYPTO=y
CONFIG_MODULE_PSA_CIPHER=y
CONFIG_MODULE_PSA_CIPHER_AES_128_CBC=y

Makefiles

If you don't want to use Kconfig, you can use the traditional way in RIOT of selecting modules in your application Makefile.

Here you need to set the base module and individual modules for each operation you need. The example below also chooses a default backend depending on your board.

// Base module: this is required!
USEMODULE += psa_crypto

USEMODULE += psa_cipher
USEMODULE += psa_cipher_aes_128_cbc

If desired, you can choose a specific backend at compile time. For this you need to specify that you want to set a custom backend and then explicitly choose the one you want (see below).

USEMODULE += psa_cipher_aes_128_cbc_custom_backend
USEMODULE += psa_cipher_aes_128_cbc_backend_riot

The currently available modules, are listed below.

Key Slot Types

The key management of PSA keeps track of keys by storing them in virtual key slot representations, along with their attributes. Since keys can come in various sizes, it would be inefficient to allocate the same amount of memory for all keys. To reduce the amount of memory used for key storage, PSA internally differentiates between three types of key slots (see below). Depending on the operations your application uses, PSA will automatically detect the key sizes needed and will allocate the required memory. The number of key slots allocated of each type is set to five per default, but can be changed by the user depending on their requirements.

Single Key Slot	Asymmetric Key Slot	Protected Key Slot
Single keys or unstructured data, e.g. AES keys or asymmetric public keys in local memory	Asymmetric key pairs (private and public parts) in local memory	Any keys stored on a secure element or on-chip in hardware protected memory

If you want to change the default number of allocated key slots you can do so by updating the number in menuconfig, or adding them to the app.config.test file like so:

CONFIG_PSA_SINGLE_KEY_COUNT=3
CONFIG_PSA_ASYMMETRIC_KEYPAIR_COUNT=1
CONFIG_PSA_PROTECTED_KEY_COUNT=2

When using Makefiles, you can pass CFLAGS as shown below.

CFLAGS += -DCONFIG_PSA_SINGLE_KEY_COUNT=3
CFLAGS += -DCONFIG_PSA_ASYMMETRIC_KEYPAIR_COUNT=1
CFLAGS += -DCONFIG_PSA_PROTECTED_KEY_COUNT=2

@note The key slot count defines the maximum number of keys that can be cached in RAM at runtime. It does not limit the number of persistent keys that can be stored in flash memory. It is the user's responsibility to keep track of the number of persistently stored keys.

Available Modules

Below are the currently available modules. No matter which operation you need, you always have to choose the base module. If you want to specify a backend other than the default, you need to select psa_<operation>_custom_backend in addition to the actual backend module.

The names listed are are the version used in makefiles with the USEMODULE += <modulename> syntax. In Kconfig you don't need to know the exact names, you can simply choose the features in menuconfig. When using app.config.test files in your application directory, you need to write the names in uppercase and add the prefix CONFIG_MODULE_ to all of them.

Key Storage

• Persistent Key Storage: psa_persistent_storage

Asymmetric Crypto

• Base: psa_asymmetric

NIST ECC P192

• psa_asymmetric_ecc_p192r1
• psa_asymmetric_ecc_p192r1_backend_periph
• psa_asymmetric_ecc_p192r1_custom_backend
• psa_asymmetric_ecc_p192r1_backend_microecc

NIST ECC P256

• psa_asymmetric_ecc_p256r1
• psa_asymmetric_ecc_p256r1_backend_periph

@warning Cryptocell 310 does not support public key derivation from a private key.

• psa_asymmetric_ecc_p256r1_custom_backend
• psa_asymmetric_ecc_p256r1_backend_microecc

Ed25519

• psa_asymmetric_ecc_ed25519
• psa_asymmetric_ecc_ed25519_backend_periph
• psa_asymmetric_ecc_ed25519_custom_backend
• psa_asymmetric_ecc_ed25519_backend_c25519

AEAD

• Base: psa_aead

AES CCM

• psa_aead_aes_128_ccm
• psa_aead_aes_128_ccm_backend_periph
• psa_aead_aes_128_ccm_backend_cifra
• psa_aead_aes_128_ccm_backend_tinycrypt

@note Be aware that the tinycrypt only allows a nonce size of 13.

• psa_aead_aes_128_ccm_custom_backend
• psa_aead_aes_192_ccm
• psa_aead_aes_192_ccm_backend_cifra
• psa_aead_aes_192_ccm_custom_backend
• psa_aead_aes_256_ccm
• psa_aead_aes_256_ccm_backend_cifra
• psa_aead_aes_256_ccm_custom_backend

Ciphers

• Base: psa_cipher

AES ECB

• psa_cipher_aes_128_ecb
• psa_cipher_aes_128_ecb_backend_riot

AES CBC

• psa_cipher_aes_128_cbc
• psa_cipher_aes_128_cbc_backend_periph
• psa_cipher_aes_128_cbc_custom_backend
• psa_cipher_aes_128_cbc_backend_riot
• psa_cipher_aes_192_cbc
• psa_cipher_aes_192_cbc_custom_backend
• psa_cipher_aes_192_cbc_backend_riot
• psa_cipher_aes_256_cbc
• psa_cipher_aes_256_cbc_custom_backend
• psa_cipher_aes_256_cbc_backend_riot

CHACHA20

• psa_cipher_chacha20
• psa_cipher_chacha20_backend_periph
• psa_cipher_chacha20_custom_backend
• psa_cipher_chacha20_backend_riot

Hashes

• Base: psa_hash

MD5

• psa_hash_md5
• psa_hash_md5_custom_backend
• psa_hash_md5_backend_riot

SHA 1

• psa_hash_sha_1
• psa_hash_sha_1_backend_periph
• psa_hash_sha_1_custom_backend
• psa_hash_sha_1_backend_riot

SHA 224

• psa_hash_sha_224
• psa_hash_sha_224_backend_periph
• psa_hash_sha_224_custom_backend
• psa_hash_sha_224_backend_riot

SHA 256

• psa_hash_sha_256
• psa_hash_sha_256_backend_periph
• psa_hash_sha_256_custom_backend
• psa_hash_sha_256_backend_riot

SHA 384

• psa_hash_sha_384
• psa_hash_sha_384_backend_periph
• psa_hash_sha_384_custom_backend
• psa_hash_sha_384_backend_riot

SHA 512

• psa_hash_sha_512
• psa_hash_sha_512_backend_periph
• psa_hash_sha_512_custom_backend
• psa_hash_sha_512_backend_riot

SHA 512/224

• psa_hash_sha_512_224
• psa_hash_sha_512_224_backend_periph
• psa_hash_sha_512_224_custom_backend
• psa_hash_sha_512_224_backend_riot

SHA 512/256

• psa_hash_sha_512_256
• psa_hash_sha_512_256_backend_periph
• psa_hash_sha_512_256_custom_backend
• psa_hash_sha_512_256_backend_riot

SHA 3/256

• psa_hash_sha3_256
• psa_hash_sha3_256_backend_periph
• psa_hash_sha3_256_custom_backend
• psa_hash_sha3_256_backend_riot

SHA 3/384

• psa_hash_sha3_384
• psa_hash_sha3_384_backend_periph
• psa_hash_sha3_384_custom_backend
• psa_hash_sha3_384_backend_riot

SHA 3/512

• psa_hash_sha3_512
• psa_hash_sha3_512_backend_periph
• psa_hash_sha3_512_custom_backend
• psa_hash_sha3_512_backend_riot

MAC

• Base: psa_mac

HMAC SHA 256

• psa_mac_hmac_sha_256
• psa_mac_hmac_sha_256_backend_periph
• psa_mac_hmac_sha_256_custom_backend
• psa_mac_hmac_sha_256_backend_riot

Secure Elements

Base:

• psa_secure_element
• psa_secure_element_multiple

SE Types

• psa_secure_element_ateccx08a
• psa_secure_element_ateccx08a_cipher_aes_128
• psa_secure_element_ateccx08a_ecc_p256
• psa_secure_element_ateccx08a_hmac_sha256

Random Number Generation

Currently uses the RIOT Random Module as a backend. See the documentation for configuration options.

Secure Elements

An example showing the use of SEs can be found in examples/advanced/psa_crypto.

To use secure elements, you first need to assign a static location value to each device, so PSA can find it. If you only use one device, you can use PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT. For additional devices this value must be within the range of PSA_KEY_LOCATION_SE_MIN and PSA_KEY_LOCATION_SE_MAX. When booting the system, the auto_init module in RIOT will automatically register the device with the location with PSA Crypto.

You can now import or create keys on the secure element by constructing a key lifetime containing a device's location value.

psa_key_lifetime_t lifetime =
     PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION (PSA_KEY_LIFETIME_VOLATILE,
                                                        PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT);

Some secure elements come with their own key management and device configurations. In this case the configuration parameters must be passed to PSA Crypto during the registration. For this, you need to define a psa_se_config_t structure containing the configuration. PSA Crypto will use this structure to keep track of what types of keys are allowed on the device and how much storage is available. Where this structure should be placed, how it looks and what parameters are required depends on the type of your device.

A good place to define that structure and the location values is a drivers <driver>_params.h file, but this may vary depending on how your device is integrated in RIOT.

For detailed, device specific information, please check the device driver documentation or the example.

Available Devices and Drivers

• ATECCX08A: Microchip Cryptoauthlib as a PSA backend

Main SE Configuration

To use SEs, the appropriate modules must be chosen in Kconfig:

CONFIG_PSA_SECURE_ELEMENT=y
CONFIG_PSA_SECURE_ELEMENT_ATECCX08A=y        // device example
CONFIG_PSA_SECURE_ELEMENT_ATECCX08A_ECC_P256=y

or added to the Makefile:

USEMODULE += psa_secure_element
USEMODULE += psa_secure_element_ateccx08a        // device example
USEMODULE += psa_secure_element_ateccx08a_ecc_p256

This implementation supports the use of one or more secure elements (SE) as backends. In this case the number of used secure elements must be specified (must be at least 2 and at most 255). When using more than one SE, add

CONFIG_PSA_SECURE_ELEMENT_MULTIPLE=y
CONFIG_PSA_MAX_SE_COUNT=2                    // or any other number between 2 and 255

or, respectively,

USEMODULE += psa_secure_element_multiple
CFLAGS += -DCONFIG_PSA_MAX_SE_COUNT=2        // or any other number between 2 and 255

Porting Guide

This porting guide focuses on how to add your software library or hardware driver as a backend to PSA Crypto without actually touching the PSA implementation. We will provide some general information and then some case examples for different kinds of backends:

• Software Libraries
• Hardware Drivers
• Secure Elements

Some examples to look at are:

• RIOT hash module
• RIOT cipher module
• Micro-ECC
• CryptoCell 310 driver.

An example integrating a secure element can be found in the Cryptoauthlib Package.

General Information

Error Values

You should always check the status of your function calls and translate your library's or driver's errors to PSA error values (please be as thorough as possible). The PSA Crypto specification describes exactly what kind of error values should be returned by which function. Please read the API documentation and comply with the instructions. We recommend writing a<mylibrary>_to_psa_error() function right in the beginning (see for example CRYS_to_psa_error() in pkg/driver_cryptocell_310/psa_cryptocell_310/error_conversion.c).

The Build System

As mentioned before, there are two ways of selecting build time configurations in RIOT: Kconfig and Makefiles. Kconfig dependency resolution is currently an experimental feature and will at some point replace Makefiles. Until then, our implementation needs to support both, which means we need to define features and symbols in multiple places. Luckily, the modules have the exact same names in both systems, which makes the transfer easier. The examples below show both ways.

Modules

In RIOT, module names are generated from path names, so if you create a directory for your sourcefiles, the module name will be the same as the directory name. It is possible to change that by declaring a new module name in the Makefile by adding the line MODULE := your_module_name.

If you leave it like this, all sourcefiles in the path corresponding to the module name will be built (e.g. if you choose the module hashes, all files in sys/hashes will be included). For better configurability it is possible to add submodules (see sys/hashes/psa_riot_hashes for example). In that case the base module name will be the directory name and each file inside the directory becomes its own submodule that must be explicitly chosen. The module name will then be the directory name with the file name as a postfix. For example:

USEMODULE += hashes
USEMODULE += psa_riot_hashes
USEMODULE += psa_riot_hashes_sha_256

will build the file at sys/hashes/psa_riot_hashes/sha_256.c, but none of the other files in the directory.

To enable submodules for your implementation add the following to the directory makefile:

BASE_MODULE := psa_<modulename>
SUBMODULES := 1

We also need to create so-called pseudomodules for each available submodule. Those must follow the scheme psa_<modulename>_<filename>. Where they are declared depends on where your module is located. Pseudomodules in RIOT/sys must be added in pseudomodules.inc.mk. When integrating packages or drivers, the pseudomodules can be added in the Makefile.include file of the individual module's directory (see pkg/micro-ecc/Makefile.include).

When adding backends to PSA Crypto, please name your modules in ways that fit within the current naming scheme: psa_<library>_<algorithm>. Also, when adding software libraries and hardware drivers, use the submodule approach. That makes PSA Crypto more configurable.

The drawback of the submodule approach is, that if one of our sourcefiles depends on another sourcefile in the same folder, we need to select it explicitly. For example, in pkg/driver_cryptocell_310/psa_cryptocell_310 you can see that there are some common source files that all the others use (e.g. for hashes there is a hashes_common.c file).

If that is the case for your driver, you need to make sure the modules are selected in the Kconfig file as well as the Makefile.dep file (see psa_cryptocell_310/Makefile.dep or psa_cryptocell_310/Kconfig).

Adding Glue Code

We define a number of wrapper APIs, which are called by PSA to invoke crypto backends. Software libraries and hardware drivers use the same methods, secure elements are handled in a different way (see Case Example – Secure Elements for details).

The names, parameters and return values for wrapper methods are defined in header files in sys/psa_crypto/include/psa_<algorithm>.h. The functions declared in those files are the ones that are currently supported by this PSA implementation. They will be extended in the future.

You need to implement those functions with glue code calling your library or driver code and converting types and error values between PSA and your backend. Below is an example of how this might look (it's very reduced, your library may need much more glue code).

psa_status_t psa_ecc_p256r1_sign_hash(const psa_key_attributes_t *attributes,
                                      psa_algorithm_t alg, const uint8_t *key_buffer,
                                      size_t key_buffer_size, const uint8_t *hash,
                                      size_t hash_length, uint8_t *signature,
                                      size_t signature_size, size_t *signature_length)
{
    int status = <libraryname>_<sign_hash_func>(key_buffer, hash, hash_length,
                                           signature, signature_length, curve);

    if (status != SUCCESS) {
        return <libraryname>_status_to_psa_error(status);
    }

    (void)alg;
    (void)attributes;
    (void)key_buffer_size;
    return PSA_SUCCESS;
}

Operation Contexts

Some cryptographic operations use driver specific context to store the operation state in between function calls. These must be defined somewhere. Examples can be found in pkg/driver_cryptocell_310/include/psa_periph_hashes_ctx.h and sys/include/hashes/psa/riot_hashes.h.

When defining the contexts for a hardware driver, all you need to do is add a file called psa_periph_<algorithm>_ctx.h to your driver's include folder and define the available types (see supported types below). Those files are automatically included in crypto_includes.h and it is important that they always have the same name for each algorithm.

When defining the contexts for a software library, the headerfile should be called <library>_<algorithm>.h (e.g. riot_hashes.h) and must be added to crypto_includes.h as shown below:

#if IS_USED(MODULE_PSA_<LIBRARY>_<ALGORITHM>)
#include "<library>/<library>_<algorithm>.h"
#endif

When defining the context types, those must always depend on the specific algorithm module, for example

#if IS_USED(MODULE_PSA_<LIBRARY>_HASHES_SHA_256)
#include "path/to/headerfile_containing_the_driver_context_definition"

typedef <library_context_type_t> psa_hashes_sha256_ctx_t;
#endif

Hashes

• psa_hashes_md5_ctx_t
• psa_hashes_sha1_ctx_t
• psa_hashes_sha224_ctx_t
• psa_hashes_sha256_ctx_t
• psa_hashes_sha384_ctx_t
• psa_hashes_sha512_ctx_t
• psa_hashes_sha512_224_ctx_t
• psa_hashes_sha512_256_ctx_t

Ciphers

• psa_cipher_aes_128_ctx_t
• psa_cipher_aes_192_ctx_t
• psa_cipher_aes_256_ctx_t

Secure Elements need their own contexts. For this, see Case Example – Secure Elements.

Adding a Backend

The integration of hardware drivers, software libraries and secure element drivers differs a bit. Below we describe the necessary steps for each of them.

Case Example – A Software Library

Software libraries are the easiest backends, because they are not platform or hardware specific. They can generally run on all platforms in RIOT and we can combine different software backends for different operations (we could, for example, use the Micro-ECC package for ECC NIST curves and the C25519 package for operations with the Curve25519).

Let's say we have an imaginary software library called FancyCrypt and want to use it as a backend of PSA. We've already added it to RIOT as a third party package in pkg/fancycrypt. Our library provides hashes and elliptic curve operations and to make it accessible to PSA Crypto we need to write wrappers for our API calls.

First we create a folder called psa_fancycrypt in the package directory. Inside we create a file with the name of each operation you want to integrate, e.g. p256.c and hashes_sha_224.c (when adding operations, remember that the path of the files will also be the module name, so please comply with the current naming scheme).

In these files we need to implement the methods that are called by PSA as described above.

Adding Makefiles

We add a Makefile to the psa_fancycrypt folder with the following content:

BASE_MODULE := psa_fancycrypt
SUBMODULES := 1

include $(RIOTBASE)/Makefile.base

This tells RIOT that the psa_fancycrypt module has submodules, which can be selected individually.

In pkg/fancycrypt we now need to declare explicit pseudomodules in Makefile.include and add the psa_fancycrypt folder to the source files and the sys/psa_crypto/include folder to the includes. These should be dependent on the PSA Crypto module as shown below.

ifneq (,$(filter psa_fancycrypt_%, $(USEMODULE)))
    PSEUDOMODULES += psa_fancycrypt_hashes_sha_256
    PSEUDOMODULES += psa_fancycrypt_p256
    DIRS += $(RIOTPKG)/fancycrypt/psa_fancycrypt
    INCLUDES += -I$(RIOTBASE)/sys/psa_crypto/include
endif

If the implementation has any dependencies, they need to be added in Makefile.dep, for example:

USEMODULE += psa_fancycrypt
USEMODULE += psa_fancycrypt_error_conversion

ifneq (,$(filter psa_fancycrypt_hashes_sha1,$(USEMODULE)))
  USEMODULE += psa_fancycrypt_hashes_common
endif

Adding a Kconfig file

We add a file called Kconfig to the psa_fancycrypt folder. Here we declare the modules for Kconfig like so:

config MODULE_PSA_FANCYCRYPT_HASHES_SHA_256
    bool
    depends on MODULE_PSA_CRYPTO
    select MODULE_PSA_FANCYCRYPT

config MODULE_PSA_FANCYCRYPT_P256
    bool
    depends on MODULE_PSA_CRYPTO
    select MODULE_PSA_FANCYCRYPT

config MODULE_PSA_FANCYCRYPT
    bool

If the implementation has any dependencies, we can select them in this Kconfig file:

config MODULE_PSA_FANCYCRYPT_HASHES_SHA_256
    bool
    depends on MODULE_PSA_CRYPTO
    select MODULE_PSA_FANCYCRYPT
    select MODULE_PSA_FANCYCRYPT_HASHES_COMMON
    select MODULE_PSA_FANCYCRYPT_ERROR_CONVERSION

In pkg/fancycrypt/Kconfig we need to add the line

rsource "psa_fancycrypt/Kconfig"

at the bottom.

Telling PSA Crypto about it

To be able to choose fancycrypt as a PSA backend, we need to add the option to the Kconfig and Makefiles of the PSA Crypto Module.

In sys/psa_crypto/ we need to modify Kconfig.asymmetric, sys/psa_crypto/Kconfig.hashes, Makefile.dep and Makefile.include.

To Kconfig.asymmetric we need to add

config MODULE_PSA_ASYMMETRIC_ECC_P256R1_BACKEND_FANCYCRYPT
    bool "FancyCrypt Package"
    select PACKAGE_FANCYCRYPT
    select MODULE_PSA_FANCYCRYPT_P256

This will expose FancyCrypt as a backend option in PSA and then enable all the necessary features, when users select it. You need to do the same thing for the hash operation in Kconfig.hashes.

To achieve the same thing with Makefiles we need to do this in two places: In Makefile.include there are some existing pseudomodules for asymmetric crypto and hashes. There we need to create the backend modules for FancyCrypt by adding

PSEUDOMODULES += psa_asymmetric_ecc_p256r1_backend_fancycrypt

and

PSEUDOMODULES += psa_hash_sha_256_backend_fancycrypt

The automatic module selection happens in Makefile.dep. To the place where exiting P256 curves and hashes are selected we add cases for our backend modules:

ifneq (,$(filter psa_asymmetric_ecc_p256r1_backend_fancycrypt,$(USEMODULE)))
    USEPKG += fancycrypt
    USEMODULE += psa_fancycrypt
    USEMODULE += psa_fancycrypt_p256
endif

Now you should be able to select your package as a backend for PSA Crypto and use it to perform operations.

Case Example – A Hardware Driver

The first steps of porting a hardware driver are the same as for the software library. Only we skip the last part where we add the modules to the PSA Crypto Kconfig and Makefiles and do something else instead.

Hardware drivers are treated a little differently, mostly because they are tied to a specific platform and users can not just choose a different driver for their accelerator. Therefore we just want PSA Crypto to automatically use this driver whenever it runs on the corresponding platform, which means that we have to add some additional options and features, not only to the driver but also to the CPU it belongs to. A good example for this is the CryptoCell 310 driver for the accelerator on the nRF52840 CPU.

Now, let's say we have a CPU called myCPU with an on-chip accelerator called speedycrypt. Let's say that speedycrypt provides hashes and ECC curves. The vendor provides a driver, which we already have included in RIOT as a package. Also we've followed the steps in the glue code section and provide a folder called pkg/driver_speedycrypt/psa_speedycrypt with the required wrapper files. We have also added the module names in a Kconfig file and in the Makefiles.

Telling PSA Crypto about it

This is where we diverge from the software library example. If you take a look at the available backends in PSA, you'll notice one with the postfix *_BACKEND_PERIPH for each available algorithm. Periph here is short for peripheral hardware accelerator. The *_BACKEND_PERIPH modules depend on the presence of such an accelerator. They are a generic module for all crypto hardware accelerators and will automatically resolve to the driver that is associated with the available accelerator.

Before we're able to use it we need to tell RIOT that those hardware features exist for our myCPU (see cpu/nrf52/Kconfig and cpu/nrf52/Makefile.features as an example). In cpu/myCPU we add all the provided features as shown below.

Files we need to touch:

• cpu/myCPU/Makefile.features
• cpu/myCPU/Kconfig
• cpu/myCPU/periph/Makefile.dep
• cpu/myCPU/periph/Kconfig
• When defining new features: RIOT/kconfigs/Kconfig.features

cpu/myCPU/Makefile.features:

FEATURES_PROVIDED += periph_speedycrypt      // General feature for the accelerator
FEATURES_PROVIDED += periph_hash_sha_256
FEATURES_PROVIDED += periph_ecc_p256r1

cpu/myCPU/Kconfig:

config CPU_FAM_MYCPU
    bool
    select CPU_SOME_FEATURES
     ...
    select HAS_PERIPH_HASH_SHA_256
    select HAS_PERIPH_ECC_P256R1
    select HAS_PERIPH_SPEEDYCRYPT

The HAS_PERIPH_* symbols are defined in ``. If your device provides capabilities that are not yet defined, you can add them to that file.

Next we need to define selectable modules for this in the cpu/myCPU/periph folder, which then automatically enable the driver. An example for this is cpu/nrf52/periph. We add the following to the cpu/myCPU/periph/Kconfig file and cpu/myCPU/periph/Makefile.dep:

cpu/myCPU/periph/Makefile.dep:

ifneq (,$(filter periph_hash_sha_256,$(USEMODULE)))
    USEPKG += driver_speedycrypt
    USEMODULE += psa_speedycrypt_hashes_sha256
endif

cpu/myCPU/periph/Kconfig:

config MODULE_PERIPH_FANCYCRYPT
    bool
    depends on HAS_PERIPH_FANCYCRYPT
    select PACKAGE_DRIVER_FANCYCRYPT

config MODULE_PERIPH_HASH_SHA_256
    bool
    depends on HAS_PERIPH_HASH_SHA_256
    select MODULE_PERIPH_SPEEDYCRYPT
    select MODULE_PSA_SPEEDYCRYPT_HASHES_SHA256

Here we basically say "If the user chooses the periph_hash_sha_256 module, also select the periph_speedycrypt feature, which will then enable the speedycrypt driver". Of course you need to do this for all your available features.

Now, if you build PSA Crypto with default configurations, it should automatically detect that your board has a hardware accelerator for hashes and ECC operations and build the hardware driver as a backend.

Case Example – A Secure Element Driver

Secure elements (SEs) are handled almost completely separate from the other backends. When we use software libraries or hardware drivers, we only build one implementation per algorithm. When it comes to secure elements we want to be able to build them in addition to the other backends and we may want to connect and use more than one of them at the same time. Another difference is that when using software libraries and hardware drivers, PSA handles the storage of key material. When using SEs, keys are stored on the SE, which means, we need additional functionality for the key management.

An existing example in RIOT is the Microchip ATECCX08A device family, whose driver can be found in pkg/cryptoauthlib.

PSA Crypto has an integrated SE driver registry, which stores all registered drivers in a list. When an application calls a cryptographic operation that's supposed to be performed by a secure element, the registry will find the correct driver in the list and PSA will invoke the operation. Each driver is stored with a context that contains persistent as well as transient driver data. Transient driver data can be anything the driver needs to function. Persistent data is supposed to be used to keep track of how many keys are stored on the device and if there is still some free space available.

@note Currently PSA does not support persistent storage, so the persistent driver data is not really persistent, yet. Once persistent storage is implemented, this data will be stored, so the implementation can find already existing keys again after a reboot.

For this example we integrate an imaginary SE called superSE, which comes with a driver called superSE_lib. Again, we assume that we have already added the driver as a package in RIOT and it can be found at pkg/superse_lib.

Adding the Glue Code

Secure element drivers need to implement a different API than the other backends. It is defined here. In our package folder we now create a new folder called psa_superse_driver and add a source file called psa_superse_lib_driver.c. Here we now implement glue code for all the cryptographic operations our SE supports.

You will notice that the SE interface also provides some key management functions. This is because keys are stored on the device and PSA can not access the memory and key data itself, but needs to tell the driver to do it.

Operation Contexts

Some operations need driver specific contexts. For secure elements these are wrapped in types defined in crypto_contexts.h (currently only psa_se_cipher_context_t is supported). In this header file add operation contexts that belong to your driver to the available SE context unions as shown in the example below:

typedef struct {
    union driver_context {
        unsigned dummy;
    #if IS_USED(MODULE_PSA_SECURE_ELEMENT_ATECCX08A) || defined(DOXYGEN)
        atca_aes_cbc_ctx_t atca_aes_cbc;
    #endif
    #if IS_USED(MODULE_PSA_SECURE_ELEMENT_SUPERSE) || defined(DOXYGEN)
        superse_cipher_ctx_t superse_aes_cbc;
    #endif
    } drv_ctx;
} psa_se_cipher_context_t;

Allocation

The first thing PSA will do, when an application creates a key on an SE, is ask the driver to find a free key slot on the device. This is what the allocate function is for. How exactly the slot is allocated, depends on the driver. It may be possible to query that information directly from the device. If that is not possible, we can use the persistent data stored in the driver context. An example for this can be found in pkg/cryptoauthlib/psa_atca_driver/psa_atca_se_driver.c. This example requires the user to provide information about the configurations for each key slot, which is then stored in the persistent driver data and used for key management (for a better description read Using Cryptoauthlib as a backend for PSA Crypto). At this point you can decide what the best approach for your device is.

The allocate function should then return some reference to the slot it has allocated for the key (possibly a pointer or a slot number). Next PSA Crypto will invoke the import or generate function to store a key.

Using Persistent Data

When you want to use persistent data to keep track of keys, you should utilize the psa_se_config_t structure, which is declared in crypto_se_config.h. You can define a structure that can hold your device configuration and make sure it is available then your SE is used.

Making the Methods Available

At the bottom of the wrapper code, define structures with pointers to the available methods. For example if you have implemented a superse_allocate and superse_generate_key function, you need to add a psa_drv_se_key_management_t structure as shown below. Fill the unimplemented methods with NULL pointers. The last structure should be a psa_drv_se_t struct containing pointers to the other structures. That one will be stored during driver registration to get access to all the implemented functions.

static psa_drv_se_key_management_t superse_key_management = {
    .p_allocate = superse_allocate,
    .p_validate_slot_number = NULL,
    .p_import = NULL,
    .p_generate = superse_generate_key,
    .p_destroy = NULL,
    .p_export = NULL,
    .p_export_public = NULL
};

psa_drv_se_t superse_methods = {
    .hal_version = PSA_DRV_SE_HAL_VERSION,
    .persistent_data_size = 0,
    .p_init = NULL,
    .key_management = &superse_key_management,
    .mac = NULL,
    .cipher = NULL,
    .aead = NULL,
    .asymmetric = NULL,
    .derivation = NULL
};

You should do this for all available functions. The structures for the functions are declared in sys/psa_crypto/include/psa_crypto_se_driver.h.

Driver Registration

At start-up all secure element drivers need to be registered with the PSA SE management module. This happens by calling psa_register_secure_element() during the automatic driver initialization in RIOT. When you added support for our device to RIOT, you should have implemented an auto_init_<device> function, which initializes the connected devices. In this function, after initializing a device, you should call psa_register_secure_element() and pass the device's location value, and pointers to the psa_drv_se_t structure, the persistent data and some device specific context. An example implementation of this can be seen in sys/auto_init/security/auto_init_atca.c.

Telling PSA Crypto about it

To be able to choose our superSE during configuration, we need to define the corresponding modules in the Kconfig files and Makefiles.

To pkg/super_se_lib/Kconfig we add something like

config MODULE_PSA_SUPERSE_DRIVER
    bool
    depends on PACKAGE_SUPERSE_LIB
    default y if MODULE_PSA_CRYPTO
    select PSA_KEY_MANAGEMENT

This tells the build system that whenever this driver and PSA Crypto are used at the same time, the wrapper and the PSA key management module are needed, too.

To sys/psa_crypto/psa_se_mgmt/Kconfig we add a menu for the SE like so:

menuconfig MODULE_PSA_SECURE_ELEMENT_SUPERSE
    bool "Our Vendor's SuperSE"
    select PACKAGE_SUPERSE_LIB
    depends on <whatever protocol is needed for communication, e.g. HAS_PERIPH_I2C>
    help
        <Some helpful information about this module>

This makes our driver selectable whenever an application configuration selects the PSA secure element module.

As described in the Configuration Section, references to keys on secure elements are stored by PSA in a different type of key slot than other keys. The slot for protected keys usually only contains a slot number or address and not the actual key, which requires a lot less memory space.

BUT: If your secure element supports asymmetric cryptography and exports a public key part during key generation, that key part must be stored somewhere. So when you choose an asymmetric operation, the protected key slots will have the space to store a public key.

Dependencies

Secure Element operations also depend on the PSA modules. E.g. when you want to use an ECC operation, you need to make sure that you also build the asymmetric PSA functions.

For this we need to add the following to the superSE menu:

config MODULE_PSA_SECURE_ELEMENT_SUPERSE_ECC_P256
    bool "Our Vendor's Elliptic Curve P256"
    select PSA_KEY_SIZE_256
    select MODULE_PSA_ASYMMETRIC
    depends on MODULE_PSA_SECURE_ELEMENT_SUPERSE

This tells us, what size a key slot should have to store the public key. If your SE supports other curves, you need to modify this accordingly or add more of them.

Now we need to add the same to the Makefiles. In Makefile.include we add the source file path and the PSA include folders and define the new available pseudomodules:

ifneq (,$(filter psa_crypto,$(USEMODULE)))
    DIRS += $(RIOTPKG)/superse_lib/psa_superse_driver
    INCLUDES += -I$(RIOTBASE)/sys/psa_crypto/include
    PSEUDOMODULES += psa_secure_element_superse
    PSEUDOMODULES += psa_secure_element_superse_ecc_p256
endif

In Makefile.dep we automatically add required modules when PSA Crypto and the ECC curve module are chosen:

ifneq (,$(filter psa_crypto,$(USEMODULE)))
  USEMODULE += psa_superse_driver
endif

ifneq (,$(filter psa_secure_element_superse_ecc_p256, $(USEMODULE)))
  USEMODULE += psa_asymmetric
endif

This needs to be done for all other supported operations (e.g. ATECCX08 operations in pkg/cryptoauthlib/Makefile.include, pkg/cryptoauthlib/Makefile.dep and sys/psa_crypto/psa_se_mgmt/Kconfig). Now the secure element should be available for use with PSA Crypto.