Coverage Report

Created: 2024-11-21 07:03

/src/mbedtls/library/psa_crypto_slot_management.h
Line
Count
Source (jump to first uncovered line)
1
/*
2
 *  PSA crypto layer on top of Mbed TLS crypto
3
 */
4
/*
5
 *  Copyright The Mbed TLS Contributors
6
 *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
7
 */
8
9
#ifndef PSA_CRYPTO_SLOT_MANAGEMENT_H
10
#define PSA_CRYPTO_SLOT_MANAGEMENT_H
11
12
#include "psa/crypto.h"
13
#include "psa_crypto_core.h"
14
#include "psa_crypto_se.h"
15
16
/** Range of volatile key identifiers.
17
 *
18
 *  The first #MBEDTLS_PSA_KEY_SLOT_COUNT identifiers of the implementation
19
 *  range of key identifiers are reserved for volatile key identifiers.
20
 *
21
 *  If \c id is a a volatile key identifier, #PSA_KEY_ID_VOLATILE_MIN - \c id
22
 *  indicates the key slot containing the volatile key definition. See
23
 *  psa_crypto_slot_management.c for details.
24
 */
25
26
/** The minimum value for a volatile key identifier.
27
 */
28
1.50k
#define PSA_KEY_ID_VOLATILE_MIN  PSA_KEY_ID_VENDOR_MIN
29
30
/** The maximum value for a volatile key identifier.
31
 */
32
#if defined(MBEDTLS_PSA_KEY_STORE_DYNAMIC)
33
1.50k
#define PSA_KEY_ID_VOLATILE_MAX (MBEDTLS_PSA_KEY_ID_BUILTIN_MIN - 1)
34
#else /* MBEDTLS_PSA_KEY_STORE_DYNAMIC */
35
#define PSA_KEY_ID_VOLATILE_MAX                                 \
36
    (PSA_KEY_ID_VOLATILE_MIN + MBEDTLS_PSA_KEY_SLOT_COUNT - 1)
37
#endif /* MBEDTLS_PSA_KEY_STORE_DYNAMIC */
38
39
/** Test whether a key identifier is a volatile key identifier.
40
 *
41
 * \param key_id  Key identifier to test.
42
 *
43
 * \retval 1
44
 *         The key identifier is a volatile key identifier.
45
 * \retval 0
46
 *         The key identifier is not a volatile key identifier.
47
 */
48
static inline int psa_key_id_is_volatile(psa_key_id_t key_id)
49
1.50k
{
50
1.50k
    return (key_id >= PSA_KEY_ID_VOLATILE_MIN) &&
51
1.50k
           (key_id <= PSA_KEY_ID_VOLATILE_MAX);
52
1.50k
}
Unexecuted instantiation: psa_crypto.c:psa_key_id_is_volatile
Unexecuted instantiation: psa_crypto_pake.c:psa_key_id_is_volatile
psa_crypto_slot_management.c:psa_key_id_is_volatile
Line
Count
Source
49
1.50k
{
50
1.50k
    return (key_id >= PSA_KEY_ID_VOLATILE_MIN) &&
51
1.50k
           (key_id <= PSA_KEY_ID_VOLATILE_MAX);
52
1.50k
}
53
54
/** Get the description of a key given its identifier and lock it.
55
 *
56
 * The descriptions of volatile keys and loaded persistent keys are stored in
57
 * key slots. This function returns a pointer to the key slot containing the
58
 * description of a key given its identifier.
59
 *
60
 * In case of a persistent key, the function loads the description of the key
61
 * into a key slot if not already done.
62
 *
63
 * On success, the returned key slot has been registered for reading.
64
 * It is the responsibility of the caller to call psa_unregister_read(slot)
65
 * when they have finished reading the contents of the slot.
66
 *
67
 * On failure, `*p_slot` is set to NULL. This ensures that it is always valid
68
 * to call psa_unregister_read on the returned slot.
69
 *
70
 * \param key           Key identifier to query.
71
 * \param[out] p_slot   On success, `*p_slot` contains a pointer to the
72
 *                      key slot containing the description of the key
73
 *                      identified by \p key.
74
 *
75
 * \retval #PSA_SUCCESS
76
 *         \p *p_slot contains a pointer to the key slot containing the
77
 *         description of the key identified by \p key.
78
 *         The key slot counter has been incremented.
79
 * \retval #PSA_ERROR_BAD_STATE
80
 *         The library has not been initialized.
81
 * \retval #PSA_ERROR_INVALID_HANDLE
82
 *         \p key is not a valid key identifier.
83
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
84
 *         \p key is a persistent key identifier. The implementation does not
85
 *         have sufficient resources to load the persistent key. This can be
86
 *         due to a lack of empty key slot, or available memory.
87
 * \retval #PSA_ERROR_DOES_NOT_EXIST
88
 *         There is no key with key identifier \p key.
89
 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
90
 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
91
 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
92
 */
93
psa_status_t psa_get_and_lock_key_slot(mbedtls_svc_key_id_t key,
94
                                       psa_key_slot_t **p_slot);
95
96
/** Initialize the key slot structures.
97
 *
98
 * \retval #PSA_SUCCESS
99
 *         Currently this function always succeeds.
100
 */
101
psa_status_t psa_initialize_key_slots(void);
102
103
#if defined(MBEDTLS_TEST_HOOKS) && defined(MBEDTLS_PSA_KEY_STORE_DYNAMIC)
104
/* Allow test code to customize the key slice length. We use this in tests
105
 * that exhaust the key store to reach a full key store in reasonable time
106
 * and memory.
107
 *
108
 * The length of each slice must be between 1 and
109
 * (1 << KEY_ID_SLOT_INDEX_WIDTH) inclusive.
110
 *
111
 * The length for a given slice index must not change while
112
 * the key store is initialized.
113
 */
114
extern size_t (*mbedtls_test_hook_psa_volatile_key_slice_length)(
115
    size_t slice_idx);
116
117
/* The number of volatile key slices. */
118
size_t psa_key_slot_volatile_slice_count(void);
119
#endif
120
121
/** Delete all data from key slots in memory.
122
 * This function is not thread safe, it wipes every key slot regardless of
123
 * state and reader count. It should only be called when no slot is in use.
124
 *
125
 * This does not affect persistent storage. */
126
void psa_wipe_all_key_slots(void);
127
128
/** Find a free key slot and reserve it to be filled with a key.
129
 *
130
 * This function finds a key slot that is free,
131
 * sets its state to PSA_SLOT_FILLING and then returns the slot.
132
 *
133
 * On success, the key slot's state is PSA_SLOT_FILLING.
134
 * It is the responsibility of the caller to change the slot's state to
135
 * PSA_SLOT_EMPTY/FULL once key creation has finished.
136
 *
137
 * If multi-threading is enabled, the caller must hold the
138
 * global key slot mutex.
139
 *
140
 * \param[out] volatile_key_id   - If null, reserve a cache slot for
141
 *                                 a persistent or built-in key.
142
 *                               - If non-null, allocate a slot for
143
 *                                 a volatile key. On success,
144
 *                                 \p *volatile_key_id is the
145
 *                                 identifier corresponding to the
146
 *                                 returned slot. It is the caller's
147
 *                                 responsibility to set this key identifier
148
 *                                 in the attributes.
149
 * \param[out] p_slot            On success, a pointer to the slot.
150
 *
151
 * \retval #PSA_SUCCESS \emptydescription
152
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
153
 *         There were no free key slots.
154
 *         When #MBEDTLS_PSA_KEY_STORE_DYNAMIC is enabled, there was not
155
 *         enough memory to allocate more slots.
156
 * \retval #PSA_ERROR_BAD_STATE \emptydescription
157
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
158
 *         This function attempted to operate on a key slot which was in an
159
 *         unexpected state.
160
 */
161
psa_status_t psa_reserve_free_key_slot(psa_key_id_t *volatile_key_id,
162
                                       psa_key_slot_t **p_slot);
163
164
#if defined(MBEDTLS_PSA_KEY_STORE_DYNAMIC)
165
/** Return a key slot to the free list.
166
 *
167
 * Call this function when a slot obtained from psa_reserve_free_key_slot()
168
 * is no longer in use.
169
 *
170
 * If multi-threading is enabled, the caller must hold the
171
 * global key slot mutex.
172
 *
173
 * \param slice_idx             The slice containing the slot.
174
 *                              This is `slot->slice_index` when the slot
175
 *                              is obtained from psa_reserve_free_key_slot().
176
 * \param slot                  The key slot.
177
 *
178
 * \retval #PSA_SUCCESS \emptydescription
179
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
180
 *         This function attempted to operate on a key slot which was in an
181
 *         unexpected state.
182
 */
183
psa_status_t psa_free_key_slot(size_t slice_idx,
184
                               psa_key_slot_t *slot);
185
#endif /* MBEDTLS_PSA_KEY_STORE_DYNAMIC */
186
187
/** Change the state of a key slot.
188
 *
189
 * This function changes the state of the key slot from expected_state to
190
 * new state. If the state of the slot was not expected_state, the state is
191
 * unchanged.
192
 *
193
 * If multi-threading is enabled, the caller must hold the
194
 * global key slot mutex.
195
 *
196
 * \param[in] slot            The key slot.
197
 * \param[in] expected_state  The current state of the slot.
198
 * \param[in] new_state       The new state of the slot.
199
 *
200
 * \retval #PSA_SUCCESS
201
               The key slot's state variable is new_state.
202
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
203
 *             The slot's state was not expected_state.
204
 */
205
static inline psa_status_t psa_key_slot_state_transition(
206
    psa_key_slot_t *slot, psa_key_slot_state_t expected_state,
207
    psa_key_slot_state_t new_state)
208
2.51k
{
209
2.51k
    if (slot->state != expected_state) {
210
0
        return PSA_ERROR_CORRUPTION_DETECTED;
211
0
    }
212
2.51k
    slot->state = new_state;
213
2.51k
    return PSA_SUCCESS;
214
2.51k
}
psa_crypto.c:psa_key_slot_state_transition
Line
Count
Source
208
1.65k
{
209
1.65k
    if (slot->state != expected_state) {
210
0
        return PSA_ERROR_CORRUPTION_DETECTED;
211
0
    }
212
1.65k
    slot->state = new_state;
213
1.65k
    return PSA_SUCCESS;
214
1.65k
}
Unexecuted instantiation: psa_crypto_pake.c:psa_key_slot_state_transition
psa_crypto_slot_management.c:psa_key_slot_state_transition
Line
Count
Source
208
861
{
209
861
    if (slot->state != expected_state) {
210
0
        return PSA_ERROR_CORRUPTION_DETECTED;
211
0
    }
212
861
    slot->state = new_state;
213
861
    return PSA_SUCCESS;
214
861
}
215
216
/** Register as a reader of a key slot.
217
 *
218
 * This function increments the key slot registered reader counter by one.
219
 * If multi-threading is enabled, the caller must hold the
220
 * global key slot mutex.
221
 *
222
 * \param[in] slot  The key slot.
223
 *
224
 * \retval #PSA_SUCCESS
225
               The key slot registered reader counter was incremented.
226
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
227
 *             The reader counter already reached its maximum value and was not
228
 *             increased, or the slot's state was not PSA_SLOT_FULL.
229
 */
230
static inline psa_status_t psa_register_read(psa_key_slot_t *slot)
231
1.47k
{
232
1.47k
    if ((slot->state != PSA_SLOT_FULL) ||
233
1.47k
        (slot->var.occupied.registered_readers >= SIZE_MAX)) {
234
0
        return PSA_ERROR_CORRUPTION_DETECTED;
235
0
    }
236
1.47k
    slot->var.occupied.registered_readers++;
237
238
1.47k
    return PSA_SUCCESS;
239
1.47k
}
Unexecuted instantiation: psa_crypto.c:psa_register_read
Unexecuted instantiation: psa_crypto_pake.c:psa_register_read
psa_crypto_slot_management.c:psa_register_read
Line
Count
Source
231
1.47k
{
232
1.47k
    if ((slot->state != PSA_SLOT_FULL) ||
233
1.47k
        (slot->var.occupied.registered_readers >= SIZE_MAX)) {
234
0
        return PSA_ERROR_CORRUPTION_DETECTED;
235
0
    }
236
1.47k
    slot->var.occupied.registered_readers++;
237
238
1.47k
    return PSA_SUCCESS;
239
1.47k
}
240
241
/** Unregister from reading a key slot.
242
 *
243
 * This function decrements the key slot registered reader counter by one.
244
 * If the state of the slot is PSA_SLOT_PENDING_DELETION,
245
 * and there is only one registered reader (the caller),
246
 * this function will call psa_wipe_key_slot().
247
 * If multi-threading is enabled, the caller must hold the
248
 * global key slot mutex.
249
 *
250
 * \note To ease the handling of errors in retrieving a key slot
251
 *       a NULL input pointer is valid, and the function returns
252
 *       successfully without doing anything in that case.
253
 *
254
 * \param[in] slot  The key slot.
255
 * \retval #PSA_SUCCESS
256
 *             \p slot is NULL or the key slot reader counter has been
257
 *             decremented (and potentially wiped) successfully.
258
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
259
 *             The slot's state was neither PSA_SLOT_FULL nor
260
 *             PSA_SLOT_PENDING_DELETION.
261
 *             Or a wipe was attempted and the slot's state was not
262
 *             PSA_SLOT_PENDING_DELETION.
263
 *             Or registered_readers was equal to 0.
264
 */
265
psa_status_t psa_unregister_read(psa_key_slot_t *slot);
266
267
/** Wrap a call to psa_unregister_read in the global key slot mutex.
268
 *
269
 * If threading is disabled, this simply calls psa_unregister_read.
270
 *
271
 * \note To ease the handling of errors in retrieving a key slot
272
 *       a NULL input pointer is valid, and the function returns
273
 *       successfully without doing anything in that case.
274
 *
275
 * \param[in] slot  The key slot.
276
 * \retval #PSA_SUCCESS
277
 *             \p slot is NULL or the key slot reader counter has been
278
 *             decremented (and potentially wiped) successfully.
279
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
280
 *             The slot's state was neither PSA_SLOT_FULL nor
281
 *             PSA_SLOT_PENDING_DELETION.
282
 *             Or a wipe was attempted and the slot's state was not
283
 *             PSA_SLOT_PENDING_DELETION.
284
 *             Or registered_readers was equal to 0.
285
 */
286
psa_status_t psa_unregister_read_under_mutex(psa_key_slot_t *slot);
287
288
/** Test whether a lifetime designates a key in an external cryptoprocessor.
289
 *
290
 * \param lifetime      The lifetime to test.
291
 *
292
 * \retval 1
293
 *         The lifetime designates an external key. There should be a
294
 *         registered driver for this lifetime, otherwise the key cannot
295
 *         be created or manipulated.
296
 * \retval 0
297
 *         The lifetime designates a key that is volatile or in internal
298
 *         storage.
299
 */
300
static inline int psa_key_lifetime_is_external(psa_key_lifetime_t lifetime)
301
1.65k
{
302
1.65k
    return PSA_KEY_LIFETIME_GET_LOCATION(lifetime)
303
1.65k
           != PSA_KEY_LOCATION_LOCAL_STORAGE;
304
1.65k
}
psa_crypto.c:psa_key_lifetime_is_external
Line
Count
Source
301
826
{
302
826
    return PSA_KEY_LIFETIME_GET_LOCATION(lifetime)
303
826
           != PSA_KEY_LOCATION_LOCAL_STORAGE;
304
826
}
Unexecuted instantiation: psa_crypto_pake.c:psa_key_lifetime_is_external
psa_crypto_slot_management.c:psa_key_lifetime_is_external
Line
Count
Source
301
826
{
302
826
    return PSA_KEY_LIFETIME_GET_LOCATION(lifetime)
303
826
           != PSA_KEY_LOCATION_LOCAL_STORAGE;
304
826
}
305
306
/** Validate a key's location.
307
 *
308
 * This function checks whether the key's attributes point to a location that
309
 * is known to the PSA Core, and returns the driver function table if the key
310
 * is to be found in an external location.
311
 *
312
 * \param[in] lifetime      The key lifetime attribute.
313
 * \param[out] p_drv        On success, when a key is located in external
314
 *                          storage, returns a pointer to the driver table
315
 *                          associated with the key's storage location.
316
 *
317
 * \retval #PSA_SUCCESS \emptydescription
318
 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
319
 */
320
psa_status_t psa_validate_key_location(psa_key_lifetime_t lifetime,
321
                                       psa_se_drv_table_entry_t **p_drv);
322
323
/** Validate the persistence of a key.
324
 *
325
 * \param[in] lifetime  The key lifetime attribute.
326
 *
327
 * \retval #PSA_SUCCESS \emptydescription
328
 * \retval #PSA_ERROR_NOT_SUPPORTED The key is persistent but persistent keys
329
 *             are not supported.
330
 */
331
psa_status_t psa_validate_key_persistence(psa_key_lifetime_t lifetime);
332
333
/** Validate a key identifier.
334
 *
335
 * \param[in] key           The key identifier.
336
 * \param[in] vendor_ok     Non-zero to indicate that key identifiers in the
337
 *                          vendor range are allowed, volatile key identifiers
338
 *                          excepted \c 0 otherwise.
339
 *
340
 * \retval <> 0 if the key identifier is valid, 0 otherwise.
341
 */
342
int psa_is_valid_key_id(mbedtls_svc_key_id_t key, int vendor_ok);
343
344
#endif /* PSA_CRYPTO_SLOT_MANAGEMENT_H */