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 Crypto. 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 16 * 17 * Licensed under the Apache License, Version 2.0 (the "License"); you may 18 * not use this file except in compliance with the License. 19 * You may obtain a copy of the License at 20 * 21 * http://www.apache.org/licenses/LICENSE-2.0 22 * 23 * Unless required by applicable law or agreed to in writing, software 24 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 25 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 26 * See the License for the specific language governing permissions and 27 * limitations under the License. 28 */ 29 30 #ifndef PSA_CRYPTO_COMPAT_H 31 #define PSA_CRYPTO_COMPAT_H 32 33 #ifdef __cplusplus 34 extern "C" { 35 #endif 36 37 /* 38 * To support both openless APIs and psa_open_key() temporarily, define 39 * psa_key_handle_t to be equal to mbedtls_svc_key_id_t. Do not mark the 40 * type and its utility macros and functions deprecated yet. This will be done 41 * in a subsequent phase. 42 */ 43 typedef mbedtls_svc_key_id_t psa_key_handle_t; 44 45 #define PSA_KEY_HANDLE_INIT MBEDTLS_SVC_KEY_ID_INIT 46 47 /** Check whether a handle is null. 48 * 49 * \param handle Handle 50 * 51 * \return Non-zero if the handle is null, zero otherwise. 52 */ 53 static inline int psa_key_handle_is_null(psa_key_handle_t handle) 54 { 55 return mbedtls_svc_key_id_is_null(handle); 56 } 57 58 /** Open a handle to an existing persistent key. 59 * 60 * Open a handle to a persistent key. A key is persistent if it was created 61 * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key 62 * always has a nonzero key identifier, set with psa_set_key_id() when 63 * creating the key. Implementations may provide additional pre-provisioned 64 * keys that can be opened with psa_open_key(). Such keys have an application 65 * key identifier in the vendor range, as documented in the description of 66 * #psa_key_id_t. 67 * 68 * The application must eventually close the handle with psa_close_key() or 69 * psa_destroy_key() to release associated resources. If the application dies 70 * without calling one of these functions, the implementation should perform 71 * the equivalent of a call to psa_close_key(). 72 * 73 * Some implementations permit an application to open the same key multiple 74 * times. If this is successful, each call to psa_open_key() will return a 75 * different key handle. 76 * 77 * \note This API is not part of the PSA Cryptography API Release 1.0.0 78 * specification. It was defined in the 1.0 Beta 3 version of the 79 * specification but was removed in the 1.0.0 released version. This API is 80 * kept for the time being to not break applications relying on it. It is not 81 * deprecated yet but will be in the near future. 82 * 83 * \note Applications that rely on opening a key multiple times will not be 84 * portable to implementations that only permit a single key handle to be 85 * opened. See also :ref:\`key-handles\`. 86 * 87 * 88 * \param key The persistent identifier of the key. 89 * \param[out] handle On success, a handle to the key. 90 * 91 * \retval #PSA_SUCCESS 92 * Success. The application can now use the value of `*handle` 93 * to access the key. 94 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 95 * The implementation does not have sufficient resources to open the 96 * key. This can be due to reaching an implementation limit on the 97 * number of open keys, the number of open key handles, or available 98 * memory. 99 * \retval #PSA_ERROR_DOES_NOT_EXIST 100 * There is no persistent key with key identifier \p key. 101 * \retval #PSA_ERROR_INVALID_ARGUMENT 102 * \p key is not a valid persistent key identifier. 103 * \retval #PSA_ERROR_NOT_PERMITTED 104 * The specified key exists, but the application does not have the 105 * permission to access it. Note that this specification does not 106 * define any way to create such a key, but it may be possible 107 * through implementation-specific means. 108 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 109 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 110 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 111 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 112 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 113 * \retval #PSA_ERROR_BAD_STATE 114 * The library has not been previously initialized by psa_crypto_init(). 115 * It is implementation-dependent whether a failure to initialize 116 * results in this error code. 117 */ 118 psa_status_t psa_open_key(mbedtls_svc_key_id_t key, 119 psa_key_handle_t *handle); 120 121 /** Close a key handle. 122 * 123 * If the handle designates a volatile key, this will destroy the key material 124 * and free all associated resources, just like psa_destroy_key(). 125 * 126 * If this is the last open handle to a persistent key, then closing the handle 127 * will free all resources associated with the key in volatile memory. The key 128 * data in persistent storage is not affected and can be opened again later 129 * with a call to psa_open_key(). 130 * 131 * Closing the key handle makes the handle invalid, and the key handle 132 * must not be used again by the application. 133 * 134 * \note This API is not part of the PSA Cryptography API Release 1.0.0 135 * specification. It was defined in the 1.0 Beta 3 version of the 136 * specification but was removed in the 1.0.0 released version. This API is 137 * kept for the time being to not break applications relying on it. It is not 138 * deprecated yet but will be in the near future. 139 * 140 * \note If the key handle was used to set up an active 141 * :ref:\`multipart operation <multipart-operations>\`, then closing the 142 * key handle can cause the multipart operation to fail. Applications should 143 * maintain the key handle until after the multipart operation has finished. 144 * 145 * \param handle The key handle to close. 146 * If this is \c 0, do nothing and return \c PSA_SUCCESS. 147 * 148 * \retval #PSA_SUCCESS 149 * \p handle was a valid handle or \c 0. It is now closed. 150 * \retval #PSA_ERROR_INVALID_HANDLE 151 * \p handle is not a valid handle nor \c 0. 152 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 153 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 154 * \retval #PSA_ERROR_BAD_STATE 155 * The library has not been previously initialized by psa_crypto_init(). 156 * It is implementation-dependent whether a failure to initialize 157 * results in this error code. 158 */ 159 psa_status_t psa_close_key(psa_key_handle_t handle); 160 161 #ifdef __cplusplus 162 } 163 #endif 164 165 #endif /* PSA_CRYPTO_COMPAT_H */ 166