Mbed OS Reference
Loading...
Searching...
No Matches
psa_crypto_storage.h
Go to the documentation of this file.
1/**
2 * \file psa_crypto_storage.h
3 *
4 * \brief PSA cryptography module: Mbed TLS key storage
5 */
6/*
7 * Copyright The Mbed TLS Contributors
8 * SPDX-License-Identifier: Apache-2.0
9 *
10 * Licensed under the Apache License, Version 2.0 (the "License"); you may
11 * not use this file except in compliance with the License.
12 * You may obtain a copy of the License at
13 *
14 * http://www.apache.org/licenses/LICENSE-2.0
15 *
16 * Unless required by applicable law or agreed to in writing, software
17 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
18 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 * See the License for the specific language governing permissions and
20 * limitations under the License.
21 */
22
23#ifndef PSA_CRYPTO_STORAGE_H
24#define PSA_CRYPTO_STORAGE_H
25
26#ifdef __cplusplus
27extern "C" {
28#endif
29
30#include "psa/crypto.h"
32
33#include <stdint.h>
34#include <string.h>
35
36/* Limit the maximum key size in storage. This should have no effect
37 * since the key size is limited in memory. */
38#define PSA_CRYPTO_MAX_STORAGE_SIZE ( PSA_BITS_TO_BYTES( PSA_MAX_KEY_BITS ) )
39/* Sanity check: a file size must fit in 32 bits. Allow a generous
40 * 64kB of metadata. */
41#if PSA_CRYPTO_MAX_STORAGE_SIZE > 0xffff0000
42#error PSA_CRYPTO_MAX_STORAGE_SIZE > 0xffff0000
43#endif
44
45/** The maximum permitted persistent slot number.
46 *
47 * In Mbed Crypto 0.1.0b:
48 * - Using the file backend, all key ids are ok except 0.
49 * - Using the ITS backend, all key ids are ok except 0xFFFFFF52
50 * (#PSA_CRYPTO_ITS_RANDOM_SEED_UID) for which the file contains the
51 * device's random seed (if this feature is enabled).
52 * - Only key ids from 1 to #PSA_KEY_SLOT_COUNT are actually used.
53 *
54 * Since we need to preserve the random seed, avoid using that key slot.
55 * Reserve a whole range of key slots just in case something else comes up.
56 *
57 * This limitation will probably become moot when we implement client
58 * separation for key storage.
59 */
60#define PSA_MAX_PERSISTENT_KEY_IDENTIFIER PSA_KEY_ID_VENDOR_MAX
61
62/**
63 * \brief Checks if persistent data is stored for the given key slot number
64 *
65 * This function checks if any key data or metadata exists for the key slot in
66 * the persistent storage.
67 *
68 * \param key Persistent identifier to check.
69 *
70 * \retval 0
71 * No persistent data present for slot number
72 * \retval 1
73 * Persistent data present for slot number
74 */
76
77/**
78 * \brief Format key data and metadata and save to a location for given key
79 * slot.
80 *
81 * This function formats the key data and metadata and saves it to a
82 * persistent storage backend. The storage location corresponding to the
83 * key slot must be empty, otherwise this function will fail. This function
84 * should be called after loading the key into an internal slot to ensure the
85 * persistent key is not saved into a storage location corresponding to an
86 * already occupied non-persistent key, as well as ensuring the key data is
87 * validated.
88 *
89 *
90 * \param[in] attr The attributes of the key to save.
91 * The key identifier field in the attributes
92 * determines the key's location.
93 * \param[in] data Buffer containing the key data.
94 * \param data_length The number of bytes that make up the key data.
95 *
96 * \retval #PSA_SUCCESS
97 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
98 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
99 * \retval #PSA_ERROR_STORAGE_FAILURE
100 * \retval #PSA_ERROR_ALREADY_EXISTS
101 */
103 const uint8_t *data,
104 const size_t data_length );
105
106/**
107 * \brief Parses key data and metadata and load persistent key for given
108 * key slot number.
109 *
110 * This function reads from a storage backend, parses the key data and
111 * metadata and writes them to the appropriate output parameters.
112 *
113 * Note: This function allocates a buffer and returns a pointer to it through
114 * the data parameter. psa_free_persistent_key_data() must be called after
115 * this function to zeroize and free this buffer, regardless of whether this
116 * function succeeds or fails.
117 *
118 * \param[in,out] attr On input, the key identifier field identifies
119 * the key to load. Other fields are ignored.
120 * On success, the attribute structure contains
121 * the key metadata that was loaded from storage.
122 * \param[out] data Pointer to an allocated key data buffer on return.
123 * \param[out] data_length The number of bytes that make up the key data.
124 *
125 * \retval #PSA_SUCCESS
126 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
127 * \retval #PSA_ERROR_STORAGE_FAILURE
128 * \retval #PSA_ERROR_DOES_NOT_EXIST
129 */
131 uint8_t **data,
132 size_t *data_length );
133
134/**
135 * \brief Remove persistent data for the given key slot number.
136 *
137 * \param key Persistent identifier of the key to remove
138 * from persistent storage.
139 *
140 * \retval #PSA_SUCCESS
141 * The key was successfully removed,
142 * or the key did not exist.
143 * \retval #PSA_ERROR_STORAGE_FAILURE
144 */
146
147/**
148 * \brief Free the temporary buffer allocated by psa_load_persistent_key().
149 *
150 * This function must be called at some point after psa_load_persistent_key()
151 * to zeroize and free the memory allocated to the buffer in that function.
152 *
153 * \param key_data Buffer for the key data.
154 * \param key_data_length Size of the key data buffer.
155 *
156 */
157void psa_free_persistent_key_data( uint8_t *key_data, size_t key_data_length );
158
159/**
160 * \brief Formats key data and metadata for persistent storage
161 *
162 * \param[in] data Buffer containing the key data.
163 * \param data_length Length of the key data buffer.
164 * \param[in] attr The core attributes of the key.
165 * \param[out] storage_data Output buffer for the formatted data.
166 *
167 */
168void psa_format_key_data_for_storage( const uint8_t *data,
169 const size_t data_length,
170 const psa_core_key_attributes_t *attr,
171 uint8_t *storage_data );
172
173/**
174 * \brief Parses persistent storage data into key data and metadata
175 *
176 * \param[in] storage_data Buffer for the storage data.
177 * \param storage_data_length Length of the storage data buffer
178 * \param[out] key_data On output, pointer to a newly allocated buffer
179 * containing the key data. This must be freed
180 * using psa_free_persistent_key_data()
181 * \param[out] key_data_length Length of the key data buffer
182 * \param[out] attr On success, the attribute structure is filled
183 * with the loaded key metadata.
184 *
185 * \retval #PSA_SUCCESS
186 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
187 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
188 * \retval #PSA_ERROR_STORAGE_FAILURE
189 */
191 size_t storage_data_length,
192 uint8_t **key_data,
193 size_t *key_data_length,
195
196#if defined(MBEDTLS_PSA_CRYPTO_SE_C)
197/** This symbol is defined if transaction support is required. */
198#define PSA_CRYPTO_STORAGE_HAS_TRANSACTIONS
199#endif
200
201#if defined(PSA_CRYPTO_STORAGE_HAS_TRANSACTIONS)
202
203/** The type of transaction that is in progress.
204 */
205/* This is an integer type rather than an enum for two reasons: to support
206 * unknown values when loading a transaction file, and to ensure that the
207 * type has a known size.
208 */
209typedef uint16_t psa_crypto_transaction_type_t;
210
211/** No transaction is in progress.
212 *
213 * This has the value 0, so zero-initialization sets a transaction's type to
214 * this value.
215 */
216#define PSA_CRYPTO_TRANSACTION_NONE ( (psa_crypto_transaction_type_t) 0x0000 )
217
218/** A key creation transaction.
219 *
220 * This is only used for keys in an external cryptoprocessor (secure element).
221 * Keys in RAM or in internal storage are created atomically in storage
222 * (simple file creation), so they do not need a transaction mechanism.
223 */
224#define PSA_CRYPTO_TRANSACTION_CREATE_KEY ( (psa_crypto_transaction_type_t) 0x0001 )
225
226/** A key destruction transaction.
227 *
228 * This is only used for keys in an external cryptoprocessor (secure element).
229 * Keys in RAM or in internal storage are destroyed atomically in storage
230 * (simple file deletion), so they do not need a transaction mechanism.
231 */
232#define PSA_CRYPTO_TRANSACTION_DESTROY_KEY ( (psa_crypto_transaction_type_t) 0x0002 )
233
234/** Transaction data.
235 *
236 * This type is designed to be serialized by writing the memory representation
237 * and reading it back on the same device.
238 *
239 * \note The transaction mechanism is designed for a single active transaction
240 * at a time. The transaction object is #psa_crypto_transaction.
241 *
242 * \note If an API call starts a transaction, it must complete this transaction
243 * before returning to the application.
244 *
245 * The lifetime of a transaction is the following (note that only one
246 * transaction may be active at a time):
247 *
248 * -# Call psa_crypto_prepare_transaction() to initialize the transaction
249 * object in memory and declare the type of transaction that is starting.
250 * -# Fill in the type-specific fields of #psa_crypto_transaction.
251 * -# Call psa_crypto_save_transaction() to start the transaction. This
252 * saves the transaction data to internal storage.
253 * -# Perform the work of the transaction by modifying files, contacting
254 * external entities, or whatever needs doing. Note that the transaction
255 * may be interrupted by a power failure, so you need to have a way
256 * recover from interruptions either by undoing what has been done
257 * so far or by resuming where you left off.
258 * -# If there are intermediate stages in the transaction, update
259 * the fields of #psa_crypto_transaction and call
260 * psa_crypto_save_transaction() again when each stage is reached.
261 * -# When the transaction is over, call psa_crypto_stop_transaction() to
262 * remove the transaction data in storage and in memory.
263 *
264 * If the system crashes while a transaction is in progress, psa_crypto_init()
265 * calls psa_crypto_load_transaction() and takes care of completing or
266 * rewinding the transaction. This is done in psa_crypto_recover_transaction()
267 * in psa_crypto.c. If you add a new type of transaction, be
268 * sure to add code for it in psa_crypto_recover_transaction().
269 */
270typedef union
271{
272 /* Each element of this union must have the following properties
273 * to facilitate serialization and deserialization:
274 *
275 * - The element is a struct.
276 * - The first field of the struct is `psa_crypto_transaction_type_t type`.
277 * - Elements of the struct are arranged such a way that there is
278 * no padding.
279 */
280 struct psa_crypto_transaction_unknown_s
281 {
282 psa_crypto_transaction_type_t type;
283 uint16_t unused1;
284 uint32_t unused2;
285 uint64_t unused3;
286 uint64_t unused4;
287 } unknown;
288 /* ::type is #PSA_CRYPTO_TRANSACTION_CREATE_KEY or
289 * #PSA_CRYPTO_TRANSACTION_DESTROY_KEY. */
290 struct psa_crypto_transaction_key_s
291 {
292 psa_crypto_transaction_type_t type;
293 uint16_t unused1;
294 psa_key_lifetime_t lifetime;
297 } key;
298} psa_crypto_transaction_t;
299
300/** The single active transaction.
301 */
302extern psa_crypto_transaction_t psa_crypto_transaction;
303
304/** Prepare for a transaction.
305 *
306 * There must not be an ongoing transaction.
307 *
308 * \param type The type of transaction to start.
309 */
310static inline void psa_crypto_prepare_transaction(
311 psa_crypto_transaction_type_t type )
312{
313 psa_crypto_transaction.unknown.type = type;
314}
315
316/** Save the transaction data to storage.
317 *
318 * You may call this function multiple times during a transaction to
319 * atomically update the transaction state.
320 *
321 * \retval #PSA_SUCCESS
322 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
323 * \retval #PSA_ERROR_STORAGE_FAILURE
324 */
325psa_status_t psa_crypto_save_transaction( void );
326
327/** Load the transaction data from storage, if any.
328 *
329 * This function is meant to be called from psa_crypto_init() to recover
330 * in case a transaction was interrupted by a system crash.
331 *
332 * \retval #PSA_SUCCESS
333 * The data about the ongoing transaction has been loaded to
334 * #psa_crypto_transaction.
335 * \retval #PSA_ERROR_DOES_NOT_EXIST
336 * There is no ongoing transaction.
337 * \retval #PSA_ERROR_STORAGE_FAILURE
338 */
339psa_status_t psa_crypto_load_transaction( void );
340
341/** Indicate that the current transaction is finished.
342 *
343 * Call this function at the very end of transaction processing.
344 * This function does not "commit" or "abort" the transaction: the storage
345 * subsystem has no concept of "commit" and "abort", just saving and
346 * removing the transaction information in storage.
347 *
348 * This function erases the transaction data in storage (if any) and
349 * resets the transaction data in memory.
350 *
351 * \retval #PSA_SUCCESS
352 * There was transaction data in storage.
353 * \retval #PSA_ERROR_DOES_NOT_EXIST
354 * There was no transaction data in storage.
355 * \retval #PSA_ERROR_STORAGE_FAILURE
356 * It was impossible to determine whether there was transaction data
357 * in storage, or the transaction data could not be erased.
358 */
359psa_status_t psa_crypto_stop_transaction( void );
360
361/** The ITS file identifier for the transaction data.
362 *
363 * 0xffffffNN = special file; 0x74 = 't' for transaction.
364 */
365#define PSA_CRYPTO_ITS_TRANSACTION_UID ( (psa_key_id_t) 0xffffff74 )
366
367#endif /* PSA_CRYPTO_STORAGE_HAS_TRANSACTIONS */
368
369#if defined(MBEDTLS_PSA_INJECT_ENTROPY)
370/** Backend side of mbedtls_psa_inject_entropy().
371 *
372 * This function stores the supplied data into the entropy seed file.
373 *
374 * \retval #PSA_SUCCESS
375 * Success
376 * \retval #PSA_ERROR_STORAGE_FAILURE
377 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
378 * \retval #PSA_ERROR_NOT_PERMITTED
379 * The entropy seed file already exists.
380 */
381psa_status_t mbedtls_psa_storage_inject_entropy( const unsigned char *seed,
382 size_t seed_size );
383#endif /* MBEDTLS_PSA_INJECT_ENTROPY */
384
385#ifdef __cplusplus
386}
387#endif
388
389#endif /* PSA_CRYPTO_STORAGE_H */
Platform Security Architecture cryptography module.
PSA external cryptoprocessor driver module.
int32_t psa_status_t
Function return status.
Definition: crypto_types.h:55
uint32_t psa_key_lifetime_t
Encoding of key lifetimes.
Definition: crypto_types.h:141
psa_key_id_t mbedtls_svc_key_id_t
Identifier for persistent keys.
Definition: crypto_types.h:237
uint64_t psa_key_slot_number_t
An internal designation of a key slot between the core part of the PSA Crypto implementation and the ...
psa_status_t psa_destroy_persistent_key(const mbedtls_svc_key_id_t key)
Remove persistent data for the given key slot number.
psa_status_t psa_save_persistent_key(const psa_core_key_attributes_t *attr, const uint8_t *data, const size_t data_length)
Format key data and metadata and save to a location for given key slot.
int psa_is_key_present_in_storage(const mbedtls_svc_key_id_t key)
Checks if persistent data is stored for the given key slot number.
void psa_format_key_data_for_storage(const uint8_t *data, const size_t data_length, const psa_core_key_attributes_t *attr, uint8_t *storage_data)
Formats key data and metadata for persistent storage.
psa_status_t psa_parse_key_data_from_storage(const uint8_t *storage_data, size_t storage_data_length, uint8_t **key_data, size_t *key_data_length, psa_core_key_attributes_t *attr)
Parses persistent storage data into key data and metadata.
psa_status_t psa_load_persistent_key(psa_core_key_attributes_t *attr, uint8_t **data, size_t *data_length)
Parses key data and metadata and load persistent key for given key slot number.
void psa_free_persistent_key_data(uint8_t *key_data, size_t key_data_length)
Free the temporary buffer allocated by psa_load_persistent_key().