-
Notifications
You must be signed in to change notification settings - Fork 6.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
doc: crypto: Add PSA Crypto documentation
Add PSA Crypto in the cryptographic services section. Signed-off-by: Flavio Ceolin <[email protected]>
- Loading branch information
Flavio Ceolin
committed
May 24, 2024
1 parent
03ec6e6
commit a9746df
Showing
2 changed files
with
182 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
<https://arm-software.github.io/psa-api/crypto/1.2/overview/conventions.html#concurrency>`_ | ||
|
||
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 <https://arm-software.github.io/psa-api/crypto/1.1/overview/conventions.html#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/ |