diff --git a/doc/services/crypto/index.rst b/doc/services/crypto/index.rst index 652d209feb8b7e6..2ac0f534208c14b 100644 --- a/doc/services/crypto/index.rst +++ b/doc/services/crypto/index.rst @@ -13,5 +13,6 @@ The following crypto libraries have been included: .. toctree:: :maxdepth: 1 + psa_crypto.rst random/index.rst api/index.rst diff --git a/doc/services/crypto/psa_crypto.rst b/doc/services/crypto/psa_crypto.rst new file mode 100644 index 000000000000000..08a2df8ae8ba097 --- /dev/null +++ b/doc/services/crypto/psa_crypto.rst @@ -0,0 +1,181 @@ +.. _psa_crypto: + +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, 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 + 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 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. + +References +********** + +* `PSA Crypto`_ + +.. _PSA Crypto: + https://arm-software.github.io/psa-api/crypto/ + +* `Mbed TLS`_ + +.. _Mbed TLS: + https://www.trustedfirmware.org/projects/mbed-tls/