michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: crypto: Add PSA Crypto documentation

Browse source 
Add PSA Crypto in the cryptographic services
section.

Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
This commit is contained in:
Flavio Ceolin 2024-05-23 12:34:19 -07:00 • committed by Anas Nashif
commit 1a6bdb2e3e
2 changed files with 182 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

1
doc/services/crypto/index.rst
View file

@ -13,5 +13,6 @@ The following crypto libraries have been included:
.. toctree::
:maxdepth: 1
psa_crypto.rst
random/index.rst
api/index.rst

181
doc/services/crypto/psa_crypto.rst Normal file
View file

@ -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, 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
<https://arm-software.github.io/psa-api/crypto/1.2/overview/conventions.html#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 <https://arm-software.github.io/psa-api/crypto/1.2/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/