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
100  * \retval #PSA_ERROR_INVALID_ARGUMENT
101  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
102  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
103  * \retval #PSA_ERROR_STORAGE_FAILURE
104  * \retval #PSA_ERROR_ALREADY_EXISTS
105  * \retval #PSA_ERROR_DATA_INVALID
106  * \retval #PSA_ERROR_DATA_CORRUPT
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
133  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
134  * \retval #PSA_ERROR_DATA_INVALID
135  * \retval #PSA_ERROR_DATA_CORRUPT
136  * \retval #PSA_ERROR_DOES_NOT_EXIST
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
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
194  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
195  * \retval #PSA_ERROR_DATA_INVALID
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 {
279     /* Each element of this union must have the following properties
280      * to facilitate serialization and deserialization:
281      *
282      * - The element is a struct.
283      * - The first field of the struct is `psa_crypto_transaction_type_t type`.
284      * - Elements of the struct are arranged such a way that there is
285      *   no padding.
286      */
287     struct psa_crypto_transaction_unknown_s
288     {
289         psa_crypto_transaction_type_t type;
290         uint16_t unused1;
291         uint32_t unused2;
292         uint64_t unused3;
293         uint64_t unused4;
294     } unknown;
295     /* ::type is #PSA_CRYPTO_TRANSACTION_CREATE_KEY or
296      * #PSA_CRYPTO_TRANSACTION_DESTROY_KEY. */
297     struct psa_crypto_transaction_key_s
298     {
299         psa_crypto_transaction_type_t type;
300         uint16_t unused1;
301         psa_key_lifetime_t lifetime;
302         psa_key_slot_number_t slot;
303         mbedtls_svc_key_id_t id;
304     } key;
305 } psa_crypto_transaction_t;
306 
307 /** The single active transaction.
308  */
309 extern psa_crypto_transaction_t psa_crypto_transaction;
310 
311 /** Prepare for a transaction.
312  *
313  * There must not be an ongoing transaction.
314  *
315  * \param type          The type of transaction to start.
316  */
psa_crypto_prepare_transaction(psa_crypto_transaction_type_t type)317 static inline void psa_crypto_prepare_transaction(
318     psa_crypto_transaction_type_t type )
319 {
320     psa_crypto_transaction.unknown.type = type;
321 }
322 
323 /** Save the transaction data to storage.
324  *
325  * You may call this function multiple times during a transaction to
326  * atomically update the transaction state.
327  *
328  * \retval #PSA_SUCCESS
329  * \retval #PSA_ERROR_DATA_CORRUPT
330  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
331  * \retval #PSA_ERROR_STORAGE_FAILURE
332  */
333 psa_status_t psa_crypto_save_transaction( void );
334 
335 /** Load the transaction data from storage, if any.
336  *
337  * This function is meant to be called from psa_crypto_init() to recover
338  * in case a transaction was interrupted by a system crash.
339  *
340  * \retval #PSA_SUCCESS
341  *         The data about the ongoing transaction has been loaded to
342  *         #psa_crypto_transaction.
343  * \retval #PSA_ERROR_DOES_NOT_EXIST
344  *         There is no ongoing transaction.
345  * \retval #PSA_ERROR_STORAGE_FAILURE
346  * \retval #PSA_ERROR_DATA_INVALID
347  * \retval #PSA_ERROR_DATA_CORRUPT
348  */
349 psa_status_t psa_crypto_load_transaction( void );
350 
351 /** Indicate that the current transaction is finished.
352  *
353  * Call this function at the very end of transaction processing.
354  * This function does not "commit" or "abort" the transaction: the storage
355  * subsystem has no concept of "commit" and "abort", just saving and
356  * removing the transaction information in storage.
357  *
358  * This function erases the transaction data in storage (if any) and
359  * resets the transaction data in memory.
360  *
361  * \retval #PSA_SUCCESS
362  *         There was transaction data in storage.
363  * \retval #PSA_ERROR_DOES_NOT_EXIST
364  *         There was no transaction data in storage.
365  * \retval #PSA_ERROR_STORAGE_FAILURE
366  *         It was impossible to determine whether there was transaction data
367  *         in storage, or the transaction data could not be erased.
368  */
369 psa_status_t psa_crypto_stop_transaction( void );
370 
371 /** The ITS file identifier for the transaction data.
372  *
373  * 0xffffffNN = special file; 0x74 = 't' for transaction.
374  */
375 #define PSA_CRYPTO_ITS_TRANSACTION_UID ( (psa_key_id_t) 0xffffff74 )
376 
377 #endif /* PSA_CRYPTO_STORAGE_HAS_TRANSACTIONS */
378 
379 #if defined(MBEDTLS_PSA_INJECT_ENTROPY)
380 /** Backend side of mbedtls_psa_inject_entropy().
381  *
382  * This function stores the supplied data into the entropy seed file.
383  *
384  * \retval #PSA_SUCCESS
385  *         Success
386  * \retval #PSA_ERROR_STORAGE_FAILURE
387  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
388  * \retval #PSA_ERROR_NOT_PERMITTED
389  *         The entropy seed file already exists.
390  */
391 psa_status_t mbedtls_psa_storage_inject_entropy( const unsigned char *seed,
392                                                  size_t seed_size );
393 #endif /* MBEDTLS_PSA_INJECT_ENTROPY */
394 
395 #ifdef __cplusplus
396 }
397 #endif
398 
399 #endif /* PSA_CRYPTO_STORAGE_H */
400