crypto_compat.h (8750B)
1 /** 2 * \file psa/crypto_compat.h 3 * 4 * \brief PSA cryptography module: Backward compatibility aliases 5 * 6 * This header declares alternative names for macro and functions. 7 * New application code should not use these names. 8 * These names may be removed in a future version of Mbed TLS. 9 * 10 * \note This file may not be included directly. Applications must 11 * include psa/crypto.h. 12 */ 13 /* 14 * Copyright The Mbed TLS Contributors 15 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 16 */ 17 18 #ifndef PSA_CRYPTO_COMPAT_H 19 #define PSA_CRYPTO_COMPAT_H 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 /* 26 * To support both openless APIs and psa_open_key() temporarily, define 27 * psa_key_handle_t to be equal to mbedtls_svc_key_id_t. Do not mark the 28 * type and its utility macros and functions deprecated yet. This will be done 29 * in a subsequent phase. 30 */ 31 typedef mbedtls_svc_key_id_t psa_key_handle_t; 32 33 #define PSA_KEY_HANDLE_INIT MBEDTLS_SVC_KEY_ID_INIT 34 35 /** Check whether a handle is null. 36 * 37 * \param handle Handle 38 * 39 * \return Non-zero if the handle is null, zero otherwise. 40 */ 41 static inline int psa_key_handle_is_null(psa_key_handle_t handle) 42 { 43 return mbedtls_svc_key_id_is_null(handle); 44 } 45 46 /** Open a handle to an existing persistent key. 47 * 48 * Open a handle to a persistent key. A key is persistent if it was created 49 * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key 50 * always has a nonzero key identifier, set with psa_set_key_id() when 51 * creating the key. Implementations may provide additional pre-provisioned 52 * keys that can be opened with psa_open_key(). Such keys have an application 53 * key identifier in the vendor range, as documented in the description of 54 * #psa_key_id_t. 55 * 56 * The application must eventually close the handle with psa_close_key() or 57 * psa_destroy_key() to release associated resources. If the application dies 58 * without calling one of these functions, the implementation should perform 59 * the equivalent of a call to psa_close_key(). 60 * 61 * Some implementations permit an application to open the same key multiple 62 * times. If this is successful, each call to psa_open_key() will return a 63 * different key handle. 64 * 65 * \note This API is not part of the PSA Cryptography API Release 1.0.0 66 * specification. It was defined in the 1.0 Beta 3 version of the 67 * specification but was removed in the 1.0.0 released version. This API is 68 * kept for the time being to not break applications relying on it. It is not 69 * deprecated yet but will be in the near future. 70 * 71 * \note Applications that rely on opening a key multiple times will not be 72 * portable to implementations that only permit a single key handle to be 73 * opened. See also :ref:\`key-handles\`. 74 * 75 * 76 * \param key The persistent identifier of the key. 77 * \param[out] handle On success, a handle to the key. 78 * 79 * \retval #PSA_SUCCESS 80 * Success. The application can now use the value of `*handle` 81 * to access the key. 82 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 83 * The implementation does not have sufficient resources to open the 84 * key. This can be due to reaching an implementation limit on the 85 * number of open keys, the number of open key handles, or available 86 * memory. 87 * \retval #PSA_ERROR_DOES_NOT_EXIST 88 * There is no persistent key with key identifier \p key. 89 * \retval #PSA_ERROR_INVALID_ARGUMENT 90 * \p key is not a valid persistent key identifier. 91 * \retval #PSA_ERROR_NOT_PERMITTED 92 * The specified key exists, but the application does not have the 93 * permission to access it. Note that this specification does not 94 * define any way to create such a key, but it may be possible 95 * through implementation-specific means. 96 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 97 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 98 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 99 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 100 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 101 * \retval #PSA_ERROR_BAD_STATE 102 * The library has not been previously initialized by psa_crypto_init(). 103 * It is implementation-dependent whether a failure to initialize 104 * results in this error code. 105 */ 106 psa_status_t psa_open_key(mbedtls_svc_key_id_t key, 107 psa_key_handle_t *handle); 108 109 /** Close a key handle. 110 * 111 * If the handle designates a volatile key, this will destroy the key material 112 * and free all associated resources, just like psa_destroy_key(). 113 * 114 * If this is the last open handle to a persistent key, then closing the handle 115 * will free all resources associated with the key in volatile memory. The key 116 * data in persistent storage is not affected and can be opened again later 117 * with a call to psa_open_key(). 118 * 119 * Closing the key handle makes the handle invalid, and the key handle 120 * must not be used again by the application. 121 * 122 * \note This API is not part of the PSA Cryptography API Release 1.0.0 123 * specification. It was defined in the 1.0 Beta 3 version of the 124 * specification but was removed in the 1.0.0 released version. This API is 125 * kept for the time being to not break applications relying on it. It is not 126 * deprecated yet but will be in the near future. 127 * 128 * \note If the key handle was used to set up an active 129 * :ref:\`multipart operation <multipart-operations>\`, then closing the 130 * key handle can cause the multipart operation to fail. Applications should 131 * maintain the key handle until after the multipart operation has finished. 132 * 133 * \param handle The key handle to close. 134 * If this is \c 0, do nothing and return \c PSA_SUCCESS. 135 * 136 * \retval #PSA_SUCCESS 137 * \p handle was a valid handle or \c 0. It is now closed. 138 * \retval #PSA_ERROR_INVALID_HANDLE 139 * \p handle is not a valid handle nor \c 0. 140 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 141 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 142 * \retval #PSA_ERROR_BAD_STATE 143 * The library has not been previously initialized by psa_crypto_init(). 144 * It is implementation-dependent whether a failure to initialize 145 * results in this error code. 146 */ 147 psa_status_t psa_close_key(psa_key_handle_t handle); 148 149 /** \addtogroup attributes 150 * @{ 151 */ 152 153 #if !defined(MBEDTLS_DEPRECATED_REMOVED) 154 /** Custom Diffie-Hellman group. 155 * 156 * Mbed TLS does not support custom DH groups. 157 * 158 * \deprecated This value is not useful, so this macro will be removed in 159 * a future version of the library. 160 */ 161 #define PSA_DH_FAMILY_CUSTOM \ 162 ((psa_dh_family_t) MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(0x7e)) 163 164 /** 165 * \brief Set domain parameters for a key. 166 * 167 * \deprecated Mbed TLS no longer supports any domain parameters. 168 * This function only does the equivalent of 169 * psa_set_key_type() and will be removed in a future version 170 * of the library. 171 * 172 * \param[in,out] attributes Attribute structure where \p type will be set. 173 * \param type Key type (a \c PSA_KEY_TYPE_XXX value). 174 * \param[in] data Ignored. 175 * \param data_length Must be 0. 176 * 177 * \retval #PSA_SUCCESS \emptydescription 178 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 179 */ 180 static inline psa_status_t MBEDTLS_DEPRECATED psa_set_key_domain_parameters( 181 psa_key_attributes_t *attributes, 182 psa_key_type_t type, const uint8_t *data, size_t data_length) 183 { 184 (void) data; 185 if (data_length != 0) { 186 return PSA_ERROR_NOT_SUPPORTED; 187 } 188 psa_set_key_type(attributes, type); 189 return PSA_SUCCESS; 190 } 191 192 /** 193 * \brief Get domain parameters for a key. 194 * 195 * \deprecated Mbed TLS no longer supports any domain parameters. 196 * This function alwaya has an empty output and will be 197 * removed in a future version of the library. 198 199 * \param[in] attributes Ignored. 200 * \param[out] data Ignored. 201 * \param data_size Ignored. 202 * \param[out] data_length Set to 0. 203 * 204 * \retval #PSA_SUCCESS \emptydescription 205 */ 206 static inline psa_status_t MBEDTLS_DEPRECATED psa_get_key_domain_parameters( 207 const psa_key_attributes_t *attributes, 208 uint8_t *data, size_t data_size, size_t *data_length) 209 { 210 (void) attributes; 211 (void) data; 212 (void) data_size; 213 *data_length = 0; 214 return PSA_SUCCESS; 215 } 216 217 /** Safe output buffer size for psa_get_key_domain_parameters(). 218 * 219 */ 220 #define PSA_KEY_DOMAIN_PARAMETERS_SIZE(key_type, key_bits) \ 221 MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(1u) 222 #endif /* MBEDTLS_DEPRECATED_REMOVED */ 223 224 /**@}*/ 225 226 #ifdef __cplusplus 227 } 228 #endif 229 230 #endif /* PSA_CRYPTO_COMPAT_H */