common/mbedtls/psa_crypto_slot_management.h

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