PSA Crypto
Overview
The PSA (Platform Security Architecture) Crypto API offers a portable programming interface for cryptographic operations and key storage across a wide range of hardware. It is designed to be user-friendly while still providing access to the low-level primitives essential for modern cryptography.
It is created and maintained by Arm. Arm developed the PSA as a comprehensive security framework to address the increasing security needs of connected devices.
In Zephyr, the PSA Crypto API is implemented using Mbed TLS, an open-source cryptographic library that provides the underlying cryptographic functions.
Design Goals
The interface is suitable for a vast range of devices: from special-purpose cryptographic processors that process data with a built-in key, to constrained devices running custom application code, such as microcontrollers, and multi-application devices, such as servers. It follows the principle of cryptographic agility.
- Algorithm Flexibility
The PSA Crypto API supports a wide range of cryptographic algorithms, allowing developers to switch between different cryptographic methods as needed. This flexibility is crucial for maintaining security as new algorithms emerge and existing ones become obsolete.
- Key Management
The PSA Crypto API includes robust key management features that support the creation, storage, and use of cryptographic keys in a secure and flexible manner. It uses opaque key identifiers, which allows for easy key replacement and updates without exposing key material.
- Implementation Independence
The PSA Crypto API abstracts the underlying cryptographic library, meaning that the specific implementation can be changed without affecting the application code. This abstraction supports cryptographic agility by enabling the use of different cryptographic libraries or hardware accelerators as needed.
- Future-Proofing
By adhering to cryptographic agility, PSA Crypto ensures that applications can quickly adapt to new cryptographic standards and practices, enhancing long-term security and compliance.
Examples of Applications
- Network Security (TLS)
The API provides all of the cryptographic primitives needed to establish TLS connections.
- Secure Storage
The API provides all primitives related to storage encryption, block or file-based, with master encryption keys stored inside a key store.
- Network Credentials
The API provides network credential management inside a key store, for example, for X.509-based authentication or pre-shared keys on enterprise networks.
- Device Pairing
The API provides support for key agreement protocols that are often used for secure pairing of devices over wireless channels. For example, the pairing of an NFC token or a Bluetooth device might use key agreement protocols upon first use.
- Secure Boot
The API provides primitives for use during firmware integrity and authenticity validation, during a secure or trusted boot process.
- Attestation
The API provides primitives used in attestation activities. Attestation is the ability for a device to sign an array of bytes with a device private key and return the result to the caller. There are several use cases; ranging from attestation of the device state, to the ability to generate a key pair and prove that it has been generated inside a secure key store. The API provides access to the algorithms commonly used for attestation.
- Factory Provisioning
Most IoT devices receive a unique identity during the factory provisioning process, or once they have been deployed to the field. This API provides the APIs necessary for populating a device with keys that represent that identity.
Usage considerations
- Always check for errors
Most functions in the PSA Crypto API can return errors. All functions that can fail have the return type
psa_status_t. A few functions cannot fail, and thus, return void or some other type.If an error occurs, unless otherwise specified, the content of the output parameters is undefined and must not be used.
Some common causes of errors include:
In implementations where the keys are stored and processed in a separate environment from the application, all functions that need to access the cryptography processing environment might fail due to an error in the communication between the two environments.
If an algorithm is implemented with a hardware accelerator, which is logically separate from the application processor, the accelerator might fail, even when the application processor keeps running normally.
Most functions might fail due to a lack of resources. However, some implementations guarantee that certain functions always have sufficient memory.
All functions that access persistent keys might fail due to a storage failure.
All functions that require randomness might fail due to a lack of entropy. Implementations are encouraged to seed the random generator with sufficient entropy during the execution of
psa_crypto_init(). However, some security standards require periodic reseeding from a hardware random generator, which can fail.
- Shared memory and concurrency
Some environments allow applications to be multithreaded, while others do not. In some environments, applications can share memory with a different security context. In environments with multithreaded applications or shared memory, applications must be written carefully to avoid data corruption or leakage. This specification requires the application to obey certain constraints.
In general, the PSA Crypto API allows either one writer or any number of simultaneous readers, on any given object. In other words, if two or more calls access the same object concurrently, then the behavior is only well-defined if all the calls are only reading from the object and do not modify it. Read accesses include reading memory by input parameters and reading keystore content by using a key. For more details, refer to Concurrent calls
If an application shares memory with another security context, it can pass shared memory blocks as input buffers or output buffers, but not as non-buffer parameters. For more details, refer to Stability of parameters.
- Cleaning up after use
To minimize impact if the system is compromised, it is recommended that applications wipe all sensitive data from memory when it is no longer used. That way, only data that is currently in use can be leaked, and past data is not compromised.
Wiping sensitive data includes:
Clearing temporary buffers in the stack or on the heap.
Aborting operations if they will not be finished.
Destroying keys that are no longer used.