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