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