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
27 extern "C" {
28 #endif
29
30 #include "psa/crypto.h"
31 #include "psa/crypto_se_driver.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 #MBEDTLS_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 */
75 int psa_is_key_present_in_storage(const mbedtls_svc_key_id_t key);
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 * Note: This function will only succeed for key buffers which are not
90 * empty. If passed a NULL pointer or zero-length, the function will fail
91 * with #PSA_ERROR_INVALID_ARGUMENT.
92 *
93 * \param[in] attr The attributes of the key to save.
94 * The key identifier field in the attributes
95 * determines the key's location.
96 * \param[in] data Buffer containing the key data.
97 * \param data_length The number of bytes that make up the key data.
98 *
99 * \retval #PSA_SUCCESS \emptydescription
100 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
101 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
102 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription
103 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
104 * \retval #PSA_ERROR_ALREADY_EXISTS \emptydescription
105 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
106 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
107 */
108 psa_status_t psa_save_persistent_key(const psa_core_key_attributes_t *attr,
109 const uint8_t *data,
110 const size_t data_length);
111
112 /**
113 * \brief Parses key data and metadata and load persistent key for given
114 * key slot number.
115 *
116 * This function reads from a storage backend, parses the key data and
117 * metadata and writes them to the appropriate output parameters.
118 *
119 * Note: This function allocates a buffer and returns a pointer to it through
120 * the data parameter. On successful return, the pointer is guaranteed to be
121 * valid and the buffer contains at least one byte of data.
122 * psa_free_persistent_key_data() must be called on the data buffer
123 * afterwards to zeroize and free this buffer.
124 *
125 * \param[in,out] attr On input, the key identifier field identifies
126 * the key to load. Other fields are ignored.
127 * On success, the attribute structure contains
128 * the key metadata that was loaded from storage.
129 * \param[out] data Pointer to an allocated key data buffer on return.
130 * \param[out] data_length The number of bytes that make up the key data.
131 *
132 * \retval #PSA_SUCCESS \emptydescription
133 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
134 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
135 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
136 * \retval #PSA_ERROR_DOES_NOT_EXIST \emptydescription
137 */
138 psa_status_t psa_load_persistent_key(psa_core_key_attributes_t *attr,
139 uint8_t **data,
140 size_t *data_length);
141
142 /**
143 * \brief Remove persistent data for the given key slot number.
144 *
145 * \param key Persistent identifier of the key to remove
146 * from persistent storage.
147 *
148 * \retval #PSA_SUCCESS
149 * The key was successfully removed,
150 * or the key did not exist.
151 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
152 */
153 psa_status_t psa_destroy_persistent_key(const mbedtls_svc_key_id_t key);
154
155 /**
156 * \brief Free the temporary buffer allocated by psa_load_persistent_key().
157 *
158 * This function must be called at some point after psa_load_persistent_key()
159 * to zeroize and free the memory allocated to the buffer in that function.
160 *
161 * \param key_data Buffer for the key data.
162 * \param key_data_length Size of the key data buffer.
163 *
164 */
165 void psa_free_persistent_key_data(uint8_t *key_data, size_t key_data_length);
166
167 /**
168 * \brief Formats key data and metadata for persistent storage
169 *
170 * \param[in] data Buffer containing the key data.
171 * \param data_length Length of the key data buffer.
172 * \param[in] attr The core attributes of the key.
173 * \param[out] storage_data Output buffer for the formatted data.
174 *
175 */
176 void psa_format_key_data_for_storage(const uint8_t *data,
177 const size_t data_length,
178 const psa_core_key_attributes_t *attr,
179 uint8_t *storage_data);
180
181 /**
182 * \brief Parses persistent storage data into key data and metadata
183 *
184 * \param[in] storage_data Buffer for the storage data.
185 * \param storage_data_length Length of the storage data buffer
186 * \param[out] key_data On output, pointer to a newly allocated buffer
187 * containing the key data. This must be freed
188 * using psa_free_persistent_key_data()
189 * \param[out] key_data_length Length of the key data buffer
190 * \param[out] attr On success, the attribute structure is filled
191 * with the loaded key metadata.
192 *
193 * \retval #PSA_SUCCESS \emptydescription
194 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
195 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
196 */
197 psa_status_t psa_parse_key_data_from_storage(const uint8_t *storage_data,
198 size_t storage_data_length,
199 uint8_t **key_data,
200 size_t *key_data_length,
201 psa_core_key_attributes_t *attr);
202
203 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
204 /** This symbol is defined if transaction support is required. */
205 #define PSA_CRYPTO_STORAGE_HAS_TRANSACTIONS
206 #endif
207
208 #if defined(PSA_CRYPTO_STORAGE_HAS_TRANSACTIONS)
209
210 /** The type of transaction that is in progress.
211 */
212 /* This is an integer type rather than an enum for two reasons: to support
213 * unknown values when loading a transaction file, and to ensure that the
214 * type has a known size.
215 */
216 typedef uint16_t psa_crypto_transaction_type_t;
217
218 /** No transaction is in progress.
219 *
220 * This has the value 0, so zero-initialization sets a transaction's type to
221 * this value.
222 */
223 #define PSA_CRYPTO_TRANSACTION_NONE ((psa_crypto_transaction_type_t) 0x0000)
224
225 /** A key creation transaction.
226 *
227 * This is only used for keys in an external cryptoprocessor (secure element).
228 * Keys in RAM or in internal storage are created atomically in storage
229 * (simple file creation), so they do not need a transaction mechanism.
230 */
231 #define PSA_CRYPTO_TRANSACTION_CREATE_KEY ((psa_crypto_transaction_type_t) 0x0001)
232
233 /** A key destruction transaction.
234 *
235 * This is only used for keys in an external cryptoprocessor (secure element).
236 * Keys in RAM or in internal storage are destroyed atomically in storage
237 * (simple file deletion), so they do not need a transaction mechanism.
238 */
239 #define PSA_CRYPTO_TRANSACTION_DESTROY_KEY ((psa_crypto_transaction_type_t) 0x0002)
240
241 /** Transaction data.
242 *
243 * This type is designed to be serialized by writing the memory representation
244 * and reading it back on the same device.
245 *
246 * \note The transaction mechanism is designed for a single active transaction
247 * at a time. The transaction object is #psa_crypto_transaction.
248 *
249 * \note If an API call starts a transaction, it must complete this transaction
250 * before returning to the application.
251 *
252 * The lifetime of a transaction is the following (note that only one
253 * transaction may be active at a time):
254 *
255 * -# Call psa_crypto_prepare_transaction() to initialize the transaction
256 * object in memory and declare the type of transaction that is starting.
257 * -# Fill in the type-specific fields of #psa_crypto_transaction.
258 * -# Call psa_crypto_save_transaction() to start the transaction. This
259 * saves the transaction data to internal storage.
260 * -# Perform the work of the transaction by modifying files, contacting
261 * external entities, or whatever needs doing. Note that the transaction
262 * may be interrupted by a power failure, so you need to have a way
263 * recover from interruptions either by undoing what has been done
264 * so far or by resuming where you left off.
265 * -# If there are intermediate stages in the transaction, update
266 * the fields of #psa_crypto_transaction and call
267 * psa_crypto_save_transaction() again when each stage is reached.
268 * -# When the transaction is over, call psa_crypto_stop_transaction() to
269 * remove the transaction data in storage and in memory.
270 *
271 * If the system crashes while a transaction is in progress, psa_crypto_init()
272 * calls psa_crypto_load_transaction() and takes care of completing or
273 * rewinding the transaction. This is done in psa_crypto_recover_transaction()
274 * in psa_crypto.c. If you add a new type of transaction, be
275 * sure to add code for it in psa_crypto_recover_transaction().
276 */
277 typedef union {
278 /* Each element of this union must have the following properties
279 * to facilitate serialization and deserialization:
280 *
281 * - The element is a struct.
282 * - The first field of the struct is `psa_crypto_transaction_type_t type`.
283 * - Elements of the struct are arranged such a way that there is
284 * no padding.
285 */
286 struct psa_crypto_transaction_unknown_s {
287 psa_crypto_transaction_type_t type;
288 uint16_t unused1;
289 uint32_t unused2;
290 uint64_t unused3;
291 uint64_t unused4;
292 } unknown;
293 /* ::type is #PSA_CRYPTO_TRANSACTION_CREATE_KEY or
294 * #PSA_CRYPTO_TRANSACTION_DESTROY_KEY. */
295 struct psa_crypto_transaction_key_s {
296 psa_crypto_transaction_type_t type;
297 uint16_t unused1;
298 psa_key_lifetime_t lifetime;
299 psa_key_slot_number_t slot;
300 mbedtls_svc_key_id_t id;
301 } key;
302 } psa_crypto_transaction_t;
303
304 /** The single active transaction.
305 */
306 extern psa_crypto_transaction_t psa_crypto_transaction;
307
308 /** Prepare for a transaction.
309 *
310 * There must not be an ongoing transaction.
311 *
312 * \param type The type of transaction to start.
313 */
psa_crypto_prepare_transaction(psa_crypto_transaction_type_t type)314 static inline void psa_crypto_prepare_transaction(
315 psa_crypto_transaction_type_t type)
316 {
317 psa_crypto_transaction.unknown.type = type;
318 }
319
320 /** Save the transaction data to storage.
321 *
322 * You may call this function multiple times during a transaction to
323 * atomically update the transaction state.
324 *
325 * \retval #PSA_SUCCESS \emptydescription
326 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
327 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription
328 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
329 */
330 psa_status_t psa_crypto_save_transaction(void);
331
332 /** Load the transaction data from storage, if any.
333 *
334 * This function is meant to be called from psa_crypto_init() to recover
335 * in case a transaction was interrupted by a system crash.
336 *
337 * \retval #PSA_SUCCESS
338 * The data about the ongoing transaction has been loaded to
339 * #psa_crypto_transaction.
340 * \retval #PSA_ERROR_DOES_NOT_EXIST
341 * There is no ongoing transaction.
342 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
343 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
344 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
345 */
346 psa_status_t psa_crypto_load_transaction(void);
347
348 /** Indicate that the current transaction is finished.
349 *
350 * Call this function at the very end of transaction processing.
351 * This function does not "commit" or "abort" the transaction: the storage
352 * subsystem has no concept of "commit" and "abort", just saving and
353 * removing the transaction information in storage.
354 *
355 * This function erases the transaction data in storage (if any) and
356 * resets the transaction data in memory.
357 *
358 * \retval #PSA_SUCCESS
359 * There was transaction data in storage.
360 * \retval #PSA_ERROR_DOES_NOT_EXIST
361 * There was no transaction data in storage.
362 * \retval #PSA_ERROR_STORAGE_FAILURE
363 * It was impossible to determine whether there was transaction data
364 * in storage, or the transaction data could not be erased.
365 */
366 psa_status_t psa_crypto_stop_transaction(void);
367
368 /** The ITS file identifier for the transaction data.
369 *
370 * 0xffffffNN = special file; 0x74 = 't' for transaction.
371 */
372 #define PSA_CRYPTO_ITS_TRANSACTION_UID ((psa_key_id_t) 0xffffff74)
373
374 #endif /* PSA_CRYPTO_STORAGE_HAS_TRANSACTIONS */
375
376 #if defined(MBEDTLS_PSA_INJECT_ENTROPY)
377 /** Backend side of mbedtls_psa_inject_entropy().
378 *
379 * This function stores the supplied data into the entropy seed file.
380 *
381 * \retval #PSA_SUCCESS
382 * Success
383 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
384 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription
385 * \retval #PSA_ERROR_NOT_PERMITTED
386 * The entropy seed file already exists.
387 */
388 psa_status_t mbedtls_psa_storage_inject_entropy(const unsigned char *seed,
389 size_t seed_size);
390 #endif /* MBEDTLS_PSA_INJECT_ENTROPY */
391
392 #ifdef __cplusplus
393 }
394 #endif
395
396 #endif /* PSA_CRYPTO_STORAGE_H */
397
