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 last #MBEDTLS_PSA_KEY_SLOT_COUNT identifiers of the implementation
19 * range of key identifiers are reserved for volatile key identifiers.
20 * A volatile key identifier is equal to #PSA_KEY_ID_VOLATILE_MIN plus the
21 * index of the key slot containing the volatile key definition.
22 */
23
24 /** The minimum value for a volatile key identifier.
25 */
26 #define PSA_KEY_ID_VOLATILE_MIN (PSA_KEY_ID_VENDOR_MAX - \
27 MBEDTLS_PSA_KEY_SLOT_COUNT + 1)
28
29 /** The maximum value for a volatile key identifier.
30 */
31 #define PSA_KEY_ID_VOLATILE_MAX PSA_KEY_ID_VENDOR_MAX
32
33 /** Test whether a key identifier is a volatile key identifier.
34 *
35 * \param key_id Key identifier to test.
36 *
37 * \retval 1
38 * The key identifier is a volatile key identifier.
39 * \retval 0
40 * The key identifier is not a volatile key identifier.
41 */
psa_key_id_is_volatile(psa_key_id_t key_id)42 static inline int psa_key_id_is_volatile(psa_key_id_t key_id)
43 {
44 return (key_id >= PSA_KEY_ID_VOLATILE_MIN) &&
45 (key_id <= PSA_KEY_ID_VOLATILE_MAX);
46 }
47
48 /** Get the description of a key given its identifier and lock it.
49 *
50 * The descriptions of volatile keys and loaded persistent keys are stored in
51 * key slots. This function returns a pointer to the key slot containing the
52 * description of a key given its identifier.
53 *
54 * In case of a persistent key, the function loads the description of the key
55 * into a key slot if not already done.
56 *
57 * On success, the returned key slot is locked. It is the responsibility of
58 * the caller to unlock the key slot when it does not access it anymore.
59 *
60 * \param key Key identifier to query.
61 * \param[out] p_slot On success, `*p_slot` contains a pointer to the
62 * key slot containing the description of the key
63 * identified by \p key.
64 *
65 * \retval #PSA_SUCCESS
66 * \p *p_slot contains a pointer to the key slot containing the
67 * description of the key identified by \p key.
68 * The key slot counter has been incremented.
69 * \retval #PSA_ERROR_BAD_STATE
70 * The library has not been initialized.
71 * \retval #PSA_ERROR_INVALID_HANDLE
72 * \p key is not a valid key identifier.
73 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
74 * \p key is a persistent key identifier. The implementation does not
75 * have sufficient resources to load the persistent key. This can be
76 * due to a lack of empty key slot, or available memory.
77 * \retval #PSA_ERROR_DOES_NOT_EXIST
78 * There is no key with key identifier \p key.
79 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
80 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
81 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
82 */
83 psa_status_t psa_get_and_lock_key_slot(mbedtls_svc_key_id_t key,
84 psa_key_slot_t **p_slot);
85
86 /** Initialize the key slot structures.
87 *
88 * \retval #PSA_SUCCESS
89 * Currently this function always succeeds.
90 */
91 psa_status_t psa_initialize_key_slots(void);
92
93 /** Delete all data from key slots in memory.
94 *
95 * This does not affect persistent storage. */
96 void psa_wipe_all_key_slots(void);
97
98 /** Find a free key slot.
99 *
100 * This function returns a key slot that is available for use and is in its
101 * ground state (all-bits-zero). On success, the key slot is locked. It is
102 * the responsibility of the caller to unlock the key slot when it does not
103 * access it anymore.
104 *
105 * \param[out] volatile_key_id On success, volatile key identifier
106 * associated to the returned slot.
107 * \param[out] p_slot On success, a pointer to the slot.
108 *
109 * \retval #PSA_SUCCESS \emptydescription
110 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
111 * \retval #PSA_ERROR_BAD_STATE \emptydescription
112 */
113 psa_status_t psa_get_empty_key_slot(psa_key_id_t *volatile_key_id,
114 psa_key_slot_t **p_slot);
115
116 /** Lock a key slot.
117 *
118 * This function increments the key slot lock counter by one.
119 *
120 * \param[in] slot The key slot.
121 *
122 * \retval #PSA_SUCCESS
123 The key slot lock counter was incremented.
124 * \retval #PSA_ERROR_CORRUPTION_DETECTED
125 * The lock counter already reached its maximum value and was not
126 * increased.
127 */
psa_lock_key_slot(psa_key_slot_t * slot)128 static inline psa_status_t psa_lock_key_slot(psa_key_slot_t *slot)
129 {
130 if (slot->lock_count >= SIZE_MAX) {
131 return PSA_ERROR_CORRUPTION_DETECTED;
132 }
133
134 slot->lock_count++;
135
136 return PSA_SUCCESS;
137 }
138
139 /** Unlock a key slot.
140 *
141 * This function decrements the key slot lock counter by one.
142 *
143 * \note To ease the handling of errors in retrieving a key slot
144 * a NULL input pointer is valid, and the function returns
145 * successfully without doing anything in that case.
146 *
147 * \param[in] slot The key slot.
148 * \retval #PSA_SUCCESS
149 * \p slot is NULL or the key slot lock counter has been
150 * decremented successfully.
151 * \retval #PSA_ERROR_CORRUPTION_DETECTED
152 * The lock counter was equal to 0.
153 *
154 */
155 psa_status_t psa_unlock_key_slot(psa_key_slot_t *slot);
156
157 /** Test whether a lifetime designates a key in an external cryptoprocessor.
158 *
159 * \param lifetime The lifetime to test.
160 *
161 * \retval 1
162 * The lifetime designates an external key. There should be a
163 * registered driver for this lifetime, otherwise the key cannot
164 * be created or manipulated.
165 * \retval 0
166 * The lifetime designates a key that is volatile or in internal
167 * storage.
168 */
psa_key_lifetime_is_external(psa_key_lifetime_t lifetime)169 static inline int psa_key_lifetime_is_external(psa_key_lifetime_t lifetime)
170 {
171 return PSA_KEY_LIFETIME_GET_LOCATION(lifetime)
172 != PSA_KEY_LOCATION_LOCAL_STORAGE;
173 }
174
175 /** Validate a key's location.
176 *
177 * This function checks whether the key's attributes point to a location that
178 * is known to the PSA Core, and returns the driver function table if the key
179 * is to be found in an external location.
180 *
181 * \param[in] lifetime The key lifetime attribute.
182 * \param[out] p_drv On success, when a key is located in external
183 * storage, returns a pointer to the driver table
184 * associated with the key's storage location.
185 *
186 * \retval #PSA_SUCCESS \emptydescription
187 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
188 */
189 psa_status_t psa_validate_key_location(psa_key_lifetime_t lifetime,
190 psa_se_drv_table_entry_t **p_drv);
191
192 /** Validate the persistence of a key.
193 *
194 * \param[in] lifetime The key lifetime attribute.
195 *
196 * \retval #PSA_SUCCESS \emptydescription
197 * \retval #PSA_ERROR_NOT_SUPPORTED The key is persistent but persistent keys
198 * are not supported.
199 */
200 psa_status_t psa_validate_key_persistence(psa_key_lifetime_t lifetime);
201
202 /** Validate a key identifier.
203 *
204 * \param[in] key The key identifier.
205 * \param[in] vendor_ok Non-zero to indicate that key identifiers in the
206 * vendor range are allowed, volatile key identifiers
207 * excepted \c 0 otherwise.
208 *
209 * \retval <> 0 if the key identifier is valid, 0 otherwise.
210 */
211 int psa_is_valid_key_id(mbedtls_svc_key_id_t key, int vendor_ok);
212
213 #endif /* PSA_CRYPTO_SLOT_MANAGEMENT_H */
214
