blob: c38876d3ddea2e818a78ab5b4748887aa70d4e44 [file] [log] [blame]
Gilles Peskine961849f2018-11-30 18:54:54 +01001/*
2 * PSA crypto layer on top of Mbed TLS crypto
3 */
Bence Szépkúti86974652020-06-15 11:59:37 +02004/*
Bence Szépkúti1e148272020-08-07 13:07:28 +02005 * Copyright The Mbed TLS Contributors
Dave Rodgman16799db2023-11-02 19:47:20 +00006 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Gilles Peskine961849f2018-11-30 18:54:54 +01007 */
8
9#ifndef PSA_CRYPTO_SLOT_MANAGEMENT_H
10#define PSA_CRYPTO_SLOT_MANAGEMENT_H
11
Gilles Peskine011e4282019-06-26 18:34:38 +020012#include "psa/crypto.h"
Ronald Cronc4d1b512020-07-31 11:26:37 +020013#include "psa_crypto_core.h"
Gilles Peskine011e4282019-06-26 18:34:38 +020014#include "psa_crypto_se.h"
15
Ronald Cron2a993152020-07-17 14:13:26 +020016/** Range of volatile key identifiers.
17 *
Steven Cooreman863470a2021-02-15 14:03:19 +010018 * The last #MBEDTLS_PSA_KEY_SLOT_COUNT identifiers of the implementation
19 * range of key identifiers are reserved for volatile key identifiers.
Ronald Cron96783552020-10-19 12:06:30 +020020 * A volatile key identifier is equal to #PSA_KEY_ID_VOLATILE_MIN plus the
Ronald Cron2a993152020-07-17 14:13:26 +020021 * index of the key slot containing the volatile key definition.
22 */
23
24/** The minimum value for a volatile key identifier.
25 */
Gilles Peskine449bd832023-01-11 14:50:10 +010026#define PSA_KEY_ID_VOLATILE_MIN (PSA_KEY_ID_VENDOR_MAX - \
27 MBEDTLS_PSA_KEY_SLOT_COUNT + 1)
Ronald Cron2a993152020-07-17 14:13:26 +020028
29/** The maximum value for a volatile key identifier.
30 */
31#define PSA_KEY_ID_VOLATILE_MAX PSA_KEY_ID_VENDOR_MAX
32
Ronald Cron97c8ad52020-10-15 11:17:11 +020033/** 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 */
Gilles Peskine449bd832023-01-11 14:50:10 +010042static inline int psa_key_id_is_volatile(psa_key_id_t key_id)
Ronald Cron97c8ad52020-10-15 11:17:11 +020043{
Gilles Peskine449bd832023-01-11 14:50:10 +010044 return (key_id >= PSA_KEY_ID_VOLATILE_MIN) &&
45 (key_id <= PSA_KEY_ID_VOLATILE_MAX);
Ronald Cron97c8ad52020-10-15 11:17:11 +020046}
47
Ronald Cron5c522922020-11-14 16:35:34 +010048/** Get the description of a key given its identifier and lock it.
Gilles Peskine09829032018-12-10 17:00:38 +010049 *
Ronald Cron5c522922020-11-14 16:35:34 +010050 * 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.
Ronald Cronc4d1b512020-07-31 11:26:37 +020053 *
Ronald Cron5c522922020-11-14 16:35:34 +010054 * In case of a persistent key, the function loads the description of the key
55 * into a key slot if not already done.
Ronald Cronc4d1b512020-07-31 11:26:37 +020056 *
Ronald Cron5c522922020-11-14 16:35:34 +010057 * 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.
Ronald Cronf95a2b12020-10-22 15:24:49 +020059 *
Ronald Cronc4d1b512020-07-31 11:26:37 +020060 * \param key Key identifier to query.
Gilles Peskine09829032018-12-10 17:00:38 +010061 * \param[out] p_slot On success, `*p_slot` contains a pointer to the
Ronald Cronc4d1b512020-07-31 11:26:37 +020062 * key slot containing the description of the key
63 * identified by \p key.
Gilles Peskine09829032018-12-10 17:00:38 +010064 *
Ronald Cronc4d1b512020-07-31 11:26:37 +020065 * \retval #PSA_SUCCESS
Ronald Cron1d12d872020-11-18 17:21:22 +010066 * \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.
Ronald Cronc4d1b512020-07-31 11:26:37 +020069 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine09829032018-12-10 17:00:38 +010070 * The library has not been initialized.
Ronald Cronc4d1b512020-07-31 11:26:37 +020071 * \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.
Gilles Peskineed733552023-02-14 19:21:09 +010079 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
80 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
81 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
Gilles Peskine09829032018-12-10 17:00:38 +010082 */
Gilles Peskine449bd832023-01-11 14:50:10 +010083psa_status_t psa_get_and_lock_key_slot(mbedtls_svc_key_id_t key,
84 psa_key_slot_t **p_slot);
Gilles Peskine66fb1262018-12-10 16:29:04 +010085
Gilles Peskine09829032018-12-10 17:00:38 +010086/** Initialize the key slot structures.
87 *
Ronald Cron96783552020-10-19 12:06:30 +020088 * \retval #PSA_SUCCESS
Gilles Peskine09829032018-12-10 17:00:38 +010089 * Currently this function always succeeds.
90 */
Gilles Peskine449bd832023-01-11 14:50:10 +010091psa_status_t psa_initialize_key_slots(void);
Gilles Peskine66fb1262018-12-10 16:29:04 +010092
Gilles Peskine09829032018-12-10 17:00:38 +010093/** Delete all data from key slots in memory.
94 *
95 * This does not affect persistent storage. */
Gilles Peskine449bd832023-01-11 14:50:10 +010096void psa_wipe_all_key_slots(void);
Gilles Peskine66fb1262018-12-10 16:29:04 +010097
Gilles Peskine41e50d22019-07-31 15:01:55 +020098/** Find a free key slot.
99 *
100 * This function returns a key slot that is available for use and is in its
Ronald Cron5c522922020-11-14 16:35:34 +0100101 * 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.
Gilles Peskinef46f81c2019-05-27 14:53:10 +0200104 *
Ronald Cron2a993152020-07-17 14:13:26 +0200105 * \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.
Gilles Peskinef46f81c2019-05-27 14:53:10 +0200108 *
Gilles Peskineed733552023-02-14 19:21:09 +0100109 * \retval #PSA_SUCCESS \emptydescription
110 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
111 * \retval #PSA_ERROR_BAD_STATE \emptydescription
Gilles Peskinef46f81c2019-05-27 14:53:10 +0200112 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100113psa_status_t psa_get_empty_key_slot(psa_key_id_t *volatile_key_id,
114 psa_key_slot_t **p_slot);
Gilles Peskinef46f81c2019-05-27 14:53:10 +0200115
Ryan Everett39cc9d72023-12-21 17:57:14 +0000116/** Register as a reader of a key slot.
Ronald Cronf95a2b12020-10-22 15:24:49 +0200117 *
Ryan Everett39cc9d72023-12-21 17:57:14 +0000118 * This function increments the key slot registered reader counter by one.
Ronald Cronf95a2b12020-10-22 15:24:49 +0200119 *
120 * \param[in] slot The key slot.
Ronald Croncbf6a1d2020-11-13 15:59:59 +0100121 *
122 * \retval #PSA_SUCCESS
Ryan Everett39cc9d72023-12-21 17:57:14 +0000123 The key slot registered reader counter was incremented.
Ronald Croncbf6a1d2020-11-13 15:59:59 +0100124 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Ryan Everett39cc9d72023-12-21 17:57:14 +0000125 * The reader counter already reached its maximum value and was not
Ronald Croncbf6a1d2020-11-13 15:59:59 +0100126 * increased.
Ryan Everett39cc9d72023-12-21 17:57:14 +0000127 * \retval #PSA_ERROR_BAD_STATE
128 * The slot's state was not PSA_SLOT_FULL.
Ronald Cronf95a2b12020-10-22 15:24:49 +0200129 */
Ryan Everett39cc9d72023-12-21 17:57:14 +0000130static inline psa_status_t psa_register_read(psa_key_slot_t *slot)
Ronald Cronf95a2b12020-10-22 15:24:49 +0200131{
Ryan Everett39cc9d72023-12-21 17:57:14 +0000132 if (slot->state != PSA_SLOT_FULL) {
133 return PSA_ERROR_BAD_STATE;
134 }
135 if (slot->registered_readers >= SIZE_MAX) {
Gilles Peskine449bd832023-01-11 14:50:10 +0100136 return PSA_ERROR_CORRUPTION_DETECTED;
137 }
Ryan Everett39cc9d72023-12-21 17:57:14 +0000138 slot->registered_readers++;
Ronald Croncbf6a1d2020-11-13 15:59:59 +0100139
Gilles Peskine449bd832023-01-11 14:50:10 +0100140 return PSA_SUCCESS;
Ronald Cronf95a2b12020-10-22 15:24:49 +0200141}
142
Ryan Everett39cc9d72023-12-21 17:57:14 +0000143/** Unregister from reading a key slot.
Ronald Cronf95a2b12020-10-22 15:24:49 +0200144 *
Ryan Everett39cc9d72023-12-21 17:57:14 +0000145 * This function decrements the key slot registered reader counter by one.
146 * If the state of the slot is PSA_SLOT_PENDING_DELETION,
147 * and there is only one registered reader (the caller),
148 * this function will call psa_wipe_slot().
Ronald Cronf95a2b12020-10-22 15:24:49 +0200149 *
150 * \note To ease the handling of errors in retrieving a key slot
151 * a NULL input pointer is valid, and the function returns
152 * successfully without doing anything in that case.
153 *
154 * \param[in] slot The key slot.
155 * \retval #PSA_SUCCESS
Ryan Everett39cc9d72023-12-21 17:57:14 +0000156 * \p slot is NULL or the key slot reader counter has been
157 * decremented (and potentially wiped) successfully.
Ronald Cronf95a2b12020-10-22 15:24:49 +0200158 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Ryan Everett39cc9d72023-12-21 17:57:14 +0000159 * registered_readers was equal to 0.
160 * \retval #PSA_ERROR_BAD_STATE
161 * The slot's state was neither PSA_SLOT_FULL nor
162 * PSA_SLOT_PENDING_DELETION, or a wipe was attempted and
163 * the slot's state was not PSA_SLOT_PENDING_DELETION.
Ronald Cronf95a2b12020-10-22 15:24:49 +0200164 */
Ryan Everett39cc9d72023-12-21 17:57:14 +0000165psa_status_t psa_unregister_read(psa_key_slot_t *slot);
Ronald Cronf95a2b12020-10-22 15:24:49 +0200166
Gilles Peskine011e4282019-06-26 18:34:38 +0200167/** Test whether a lifetime designates a key in an external cryptoprocessor.
168 *
169 * \param lifetime The lifetime to test.
170 *
171 * \retval 1
172 * The lifetime designates an external key. There should be a
173 * registered driver for this lifetime, otherwise the key cannot
174 * be created or manipulated.
175 * \retval 0
176 * The lifetime designates a key that is volatile or in internal
177 * storage.
178 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100179static inline int psa_key_lifetime_is_external(psa_key_lifetime_t lifetime)
Gilles Peskine011e4282019-06-26 18:34:38 +0200180{
Gilles Peskine449bd832023-01-11 14:50:10 +0100181 return PSA_KEY_LIFETIME_GET_LOCATION(lifetime)
182 != PSA_KEY_LOCATION_LOCAL_STORAGE;
Gilles Peskine011e4282019-06-26 18:34:38 +0200183}
184
Steven Cooreman8c1e7592020-06-17 14:52:05 +0200185/** Validate a key's location.
Gilles Peskined167b942019-04-19 18:19:40 +0200186 *
Steven Cooreman81fe7c32020-06-08 18:37:19 +0200187 * This function checks whether the key's attributes point to a location that
188 * is known to the PSA Core, and returns the driver function table if the key
189 * is to be found in an external location.
Gilles Peskined167b942019-04-19 18:19:40 +0200190 *
Steven Cooreman8c1e7592020-06-17 14:52:05 +0200191 * \param[in] lifetime The key lifetime attribute.
Steven Cooreman81fe7c32020-06-08 18:37:19 +0200192 * \param[out] p_drv On success, when a key is located in external
193 * storage, returns a pointer to the driver table
194 * associated with the key's storage location.
Gilles Peskine011e4282019-06-26 18:34:38 +0200195 *
Gilles Peskineed733552023-02-14 19:21:09 +0100196 * \retval #PSA_SUCCESS \emptydescription
197 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
Gilles Peskined167b942019-04-19 18:19:40 +0200198 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100199psa_status_t psa_validate_key_location(psa_key_lifetime_t lifetime,
200 psa_se_drv_table_entry_t **p_drv);
Steven Cooreman81fe7c32020-06-08 18:37:19 +0200201
Ronald Crond2ed4812020-07-17 16:11:30 +0200202/** Validate the persistence of a key.
Steven Cooreman81fe7c32020-06-08 18:37:19 +0200203 *
Ronald Cron27238fc2020-07-23 12:30:41 +0200204 * \param[in] lifetime The key lifetime attribute.
Steven Cooreman81fe7c32020-06-08 18:37:19 +0200205 *
Gilles Peskineed733552023-02-14 19:21:09 +0100206 * \retval #PSA_SUCCESS \emptydescription
Ronald Cronde825e62021-04-01 13:59:10 +0200207 * \retval #PSA_ERROR_NOT_SUPPORTED The key is persistent but persistent keys
208 * are not supported.
Steven Cooreman81fe7c32020-06-08 18:37:19 +0200209 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100210psa_status_t psa_validate_key_persistence(psa_key_lifetime_t lifetime);
Ronald Crond2ed4812020-07-17 16:11:30 +0200211
212/** Validate a key identifier.
213 *
Ronald Cronfc9c5562020-10-15 19:24:49 +0200214 * \param[in] key The key identifier.
215 * \param[in] vendor_ok Non-zero to indicate that key identifiers in the
216 * vendor range are allowed, volatile key identifiers
217 * excepted \c 0 otherwise.
Ronald Crond2ed4812020-07-17 16:11:30 +0200218 *
Ronald Cron77e412c2021-03-31 17:36:31 +0200219 * \retval <> 0 if the key identifier is valid, 0 otherwise.
Ronald Crond2ed4812020-07-17 16:11:30 +0200220 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100221int psa_is_valid_key_id(mbedtls_svc_key_id_t key, int vendor_ok);
Gilles Peskined167b942019-04-19 18:19:40 +0200222
Gilles Peskine961849f2018-11-30 18:54:54 +0100223#endif /* PSA_CRYPTO_SLOT_MANAGEMENT_H */