Branch data     Line data    Source code

       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                 :        374 : static inline int psa_key_id_is_volatile( psa_key_id_t key_id )
      55                 :            : {
      56                 :        374 :     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
      92                 :            :  * \retval #PSA_ERROR_STORAGE_FAILURE
      93                 :            :  * \retval #PSA_ERROR_DATA_CORRUPT
      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
     122                 :            :  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
     123                 :            :  * \retval #PSA_ERROR_BAD_STATE
     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                 :            :  */
     140                 :        546 : static inline psa_status_t psa_lock_key_slot( psa_key_slot_t *slot )
     141                 :            : {
     142         [ +  - ]:        546 :     if( slot->lock_count >= SIZE_MAX )
     143                 :            :         return( PSA_ERROR_CORRUPTION_DETECTED );
     144                 :            : 
     145                 :        546 :     slot->lock_count++;
     146                 :            : 
     147                 :        546 :     return( PSA_SUCCESS );
     148                 :            : }
     149                 :            : 
     150                 :            : /** Unlock a key slot.
     151                 :            :  *
     152                 :            :  * This function decrements the key slot lock counter by one.
     153                 :            :  *
     154                 :            :  * \note To ease the handling of errors in retrieving a key slot
     155                 :            :  *       a NULL input pointer is valid, and the function returns
     156                 :            :  *       successfully without doing anything in that case.
     157                 :            :  *
     158                 :            :  * \param[in] slot  The key slot.
     159                 :            :  * \retval #PSA_SUCCESS
     160                 :            :  *             \p slot is NULL or the key slot lock counter has been
     161                 :            :  *             decremented successfully.
     162                 :            :  * \retval #PSA_ERROR_CORRUPTION_DETECTED
     163                 :            :  *             The lock counter was equal to 0.
     164                 :            :  *
     165                 :            :  */
     166                 :            : psa_status_t psa_unlock_key_slot( psa_key_slot_t *slot );
     167                 :            : 
     168                 :            : /** Test whether a lifetime designates a key in an external cryptoprocessor.
     169                 :            :  *
     170                 :            :  * \param lifetime      The lifetime to test.
     171                 :            :  *
     172                 :            :  * \retval 1
     173                 :            :  *         The lifetime designates an external key. There should be a
     174                 :            :  *         registered driver for this lifetime, otherwise the key cannot
     175                 :            :  *         be created or manipulated.
     176                 :            :  * \retval 0
     177                 :            :  *         The lifetime designates a key that is volatile or in internal
     178                 :            :  *         storage.
     179                 :            :  */
     180                 :        348 : static inline int psa_key_lifetime_is_external( psa_key_lifetime_t lifetime )
     181                 :            : {
     182                 :        348 :     return( PSA_KEY_LIFETIME_GET_LOCATION( lifetime )
     183                 :        348 :                 != PSA_KEY_LOCATION_LOCAL_STORAGE );
     184                 :            : }
     185                 :            : 
     186                 :            : /** Validate a key's location.
     187                 :            :  *
     188                 :            :  * This function checks whether the key's attributes point to a location that
     189                 :            :  * is known to the PSA Core, and returns the driver function table if the key
     190                 :            :  * is to be found in an external location.
     191                 :            :  *
     192                 :            :  * \param[in] lifetime      The key lifetime attribute.
     193                 :            :  * \param[out] p_drv        On success, when a key is located in external
     194                 :            :  *                          storage, returns a pointer to the driver table
     195                 :            :  *                          associated with the key's storage location.
     196                 :            :  *
     197                 :            :  * \retval #PSA_SUCCESS
     198                 :            :  * \retval #PSA_ERROR_INVALID_ARGUMENT
     199                 :            :  */
     200                 :            : psa_status_t psa_validate_key_location( psa_key_lifetime_t lifetime,
     201                 :            :                                         psa_se_drv_table_entry_t **p_drv );
     202                 :            : 
     203                 :            : /** Validate the persistence of a key.
     204                 :            :  *
     205                 :            :  * \param[in] lifetime  The key lifetime attribute.
     206                 :            :  *
     207                 :            :  * \retval #PSA_SUCCESS
     208                 :            :  * \retval #PSA_ERROR_NOT_SUPPORTED The key is persistent but persistent keys
     209                 :            :  *             are not supported.
     210                 :            :  */
     211                 :            : psa_status_t psa_validate_key_persistence( psa_key_lifetime_t lifetime );
     212                 :            : 
     213                 :            : /** Validate a key identifier.
     214                 :            :  *
     215                 :            :  * \param[in] key           The key identifier.
     216                 :            :  * \param[in] vendor_ok     Non-zero to indicate that key identifiers in the
     217                 :            :  *                          vendor range are allowed, volatile key identifiers
     218                 :            :  *                          excepted \c 0 otherwise.
     219                 :            :  *
     220                 :            :  * \retval <> 0 if the key identifier is valid, 0 otherwise.
     221                 :            :  */
     222                 :            : int psa_is_valid_key_id( mbedtls_svc_key_id_t key, int vendor_ok );
     223                 :            : 
     224                 :            : #endif /* PSA_CRYPTO_SLOT_MANAGEMENT_H */