1.. _psa_crypto:
2
3PSA Crypto
4##########
5
6Overview
7********
8
9The PSA (Platform Security Architecture) Crypto API offers a portable
10programming interface for cryptographic operations and key storage
11across a wide range of hardware. It is designed to be user-friendly
12while still providing access to the low-level primitives essential for
13modern cryptography.
14
15It is created and maintained by Arm. Arm developed the PSA as a
16comprehensive security framework to address the increasing security
17needs of connected devices.
18
19In Zephyr, the PSA Crypto API is implemented using Mbed TLS, an
20open-source cryptographic library that provides the underlying
21cryptographic functions.
22
23Design Goals
24************
25
26The interface is suitable for a vast range of devices: from
27special-purpose cryptographic processors that process data with a
28built-in key, to constrained devices running custom application code,
29such as microcontrollers, and multi-application devices, such as
30servers. It follows the principle of cryptographic agility.
31
32Algorithm Flexibility
33  The PSA Crypto API supports a wide range of cryptographic algorithms,
34  allowing developers to switch between different cryptographic
35  methods as needed. This flexibility is crucial for maintaining
36  security as new algorithms emerge and existing ones become obsolete.
37
38Key Management
39  The PSA Crypto API includes robust key management features that
40  support the creation, storage, and use of cryptographic keys in a
41  secure and flexible manner. It uses opaque key identifiers, which
42  allows for easy key replacement and updates without exposing key
43  material.
44
45Implementation Independence
46  The PSA Crypto API abstracts the underlying cryptographic library,
47  meaning that the specific implementation can be changed without
48  affecting the application code. This abstraction supports
49  cryptographic agility by enabling the use of different cryptographic
50  libraries or hardware accelerators as needed.
51
52Future-Proofing
53  By adhering to cryptographic agility, PSA Crypto ensures that
54  applications can quickly adapt to new cryptographic standards and
55  practices, enhancing long-term security and compliance.
56
57Examples of Applications
58************************
59
60Network Security (TLS)
61  The API provides all of the cryptographic primitives needed to establish TLS connections.
62
63Secure Storage
64  The API provides all primitives related to storage encryption, block
65  or file-based, with master encryption keys stored inside a key store.
66
67Network Credentials
68  The API provides network credential management inside a key store,
69  for example, for X.509-based authentication or pre-shared keys on
70  enterprise networks.
71
72Device Pairing
73  The API provides support for key agreement protocols that are often
74  used for secure pairing of devices over wireless channels. For
75  example, the pairing of an NFC token or a Bluetooth device might use
76  key agreement protocols upon first use.
77
78Secure Boot
79  The API provides primitives for use during firmware integrity and
80  authenticity validation, during a secure or trusted boot process.
81
82Attestation
83  The API provides primitives used in attestation
84  activities. Attestation is the ability for a device to sign an array
85  of bytes with a device private key and return the result to the
86  caller. There are several use cases; ranging from attestation of the
87  device state, to the ability to generate a key pair and prove that it
88  has been generated inside a secure key store. The API provides access
89  to the algorithms commonly used for attestation.
90
91Factory Provisioning
92  Most IoT devices receive a unique identity during the factory
93  provisioning process, or once they have been deployed to the
94  field. This API provides the APIs necessary for populating a device
95  with keys that represent that identity.
96
97Usage considerations
98********************
99
100Always check for errors
101  Most functions in the PSA Crypto API can return errors. All functions
102  that can fail have the return type ``psa_status_t``. A few functions
103  cannot fail, and thus, return void or some other type.
104
105  If an error occurs, unless otherwise specified, the content of the
106  output parameters is undefined and must not be used.
107
108  Some common causes of errors include:
109
110  * In implementations where the keys are stored and processed in a
111    separate environment from the application, all functions that need
112    to access the cryptography processing environment might fail due
113    to an error in the communication between the two environments.
114
115  * If an algorithm is implemented with a hardware accelerator, which
116    is logically separate from the application processor, the
117    accelerator might fail, even when the application processor keeps
118    running normally.
119
120  * Most functions might fail due to a lack of resources. However,
121    some implementations guarantee that certain functions always have
122    sufficient memory.
123
124  * All functions that access persistent keys might fail due to a
125    storage failure.
126
127  * All functions that require randomness might fail due to a lack of
128    entropy. Implementations are encouraged to seed the random
129    generator with sufficient entropy during the execution of
130    ``psa_crypto_init()``. However, some security standards require
131    periodic reseeding from a hardware random generator, which can
132    fail.
133
134Shared memory and concurrency
135  Some environments allow applications to be multithreaded, while
136  others do not. In some environments, applications can share memory
137  with a different security context. In environments with
138  multithreaded applications or shared memory, applications must be
139  written carefully to avoid data corruption or leakage. This
140  specification requires the application to obey certain constraints.
141
142  In general, the PSA Crypto API allows either one writer or any number of
143  simultaneous readers, on any given object. In other words, if two or
144  more calls access the same object concurrently, then the behavior is
145  only well-defined if all the calls are only reading from the object
146  and do not modify it. Read accesses include reading memory by input
147  parameters and reading keystore content by using a key. For more
148  details, refer to `Concurrent calls
149  <https://arm-software.github.io/psa-api/crypto/1.2/overview/conventions.html#concurrent-calls>`_
150
151  If an application shares memory with another security context, it
152  can pass shared memory blocks as input buffers or output buffers,
153  but not as non-buffer parameters. For more details, refer to
154  `Stability of parameters <https://arm-software.github.io/psa-api/crypto/1.2/overview/conventions.html#stability-of-parameters>`_.
155
156Cleaning up after use
157  To minimize impact if the system is compromised, it is recommended
158  that applications wipe all sensitive data from memory when it is no
159  longer used. That way, only data that is currently in use can be
160  leaked, and past data is not compromised.
161
162  Wiping sensitive data includes:
163
164  * Clearing temporary buffers in the stack or on the heap.
165
166  * Aborting operations if they will not be finished.
167
168  * Destroying keys that are no longer used.
169
170References
171**********
172
173* `PSA Crypto`_
174
175.. _PSA Crypto:
176   https://arm-software.github.io/psa-api/crypto/
177
178* `Mbed TLS`_
179
180.. _Mbed TLS:
181   https://www.trustedfirmware.org/projects/mbed-tls/
182