blob: fea2923114c732907aa77f6c2d9e6b0e0172d956 [file] [log] [blame]
Gilles Peskine7a894f22019-11-26 16:06:46 +01001/**
2 * \file psa/crypto_compat.h
3 *
4 * \brief PSA cryptography module: Backward compatibility aliases
5 *
Gilles Peskine0168f2f2019-11-29 12:22:32 +01006 * 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 *
Gilles Peskine7a894f22019-11-26 16:06:46 +010010 * \note This file may not be included directly. Applications must
11 * include psa/crypto.h.
12 */
13/*
Bence Szépkúti1e148272020-08-07 13:07:28 +020014 * Copyright The Mbed TLS Contributors
Gilles Peskine7a894f22019-11-26 16:06:46 +010015 * 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.
Gilles Peskine7a894f22019-11-26 16:06:46 +010028 */
29
30#ifndef PSA_CRYPTO_COMPAT_H
31#define PSA_CRYPTO_COMPAT_H
32
Gilles Peskine7a894f22019-11-26 16:06:46 +010033#ifdef __cplusplus
34extern "C" {
35#endif
36
Ronald Croncf56a0a2020-08-04 09:51:30 +020037/*
38 * To support temporary both openless APIs and psa_open_key(), 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 */
43typedef mbedtls_svc_key_id_t psa_key_handle_t;
44
45#define PSA_KEY_HANDLE_INIT MBEDTLS_SVC_KEY_ID_INIT
46
47/** Compare two handles.
48 *
49 * \param handle1 First handle.
50 * \param handle2 Second handle.
51 *
52 * \return Non-zero if the two handles are equal, zero otherwise.
53 */
54static inline int psa_key_handle_equal( psa_key_handle_t handle1,
55 psa_key_handle_t handle2 )
56{
57 return( mbedtls_svc_key_id_equal( handle1, handle2 ) );
58}
59
60/** Check wether an handle is null.
61 *
62 * \param handle Handle
63 *
64 * \return Non-zero if the handle is null, zero otherwise.
65 */
66static inline int psa_key_handle_is_null( psa_key_handle_t handle )
67{
68 return( mbedtls_svc_key_id_is_null( handle ) );
69}
70
Gilles Peskine7b0ab6d2019-11-26 16:32:12 +010071#if !defined(MBEDTLS_DEPRECATED_REMOVED)
72
Gilles Peskine0168f2f2019-11-29 12:22:32 +010073/*
74 * Mechanism for declaring deprecated values
75 */
Gilles Peskine7b0ab6d2019-11-26 16:32:12 +010076#if defined(MBEDTLS_DEPRECATED_WARNING) && !defined(MBEDTLS_PSA_DEPRECATED)
77#define MBEDTLS_PSA_DEPRECATED __attribute__((deprecated))
78#else
79#define MBEDTLS_PSA_DEPRECATED
80#endif
81
Gilles Peskine41510942019-11-26 16:10:58 +010082typedef MBEDTLS_PSA_DEPRECATED size_t mbedtls_deprecated_size_t;
Gilles Peskine7b0ab6d2019-11-26 16:32:12 +010083typedef MBEDTLS_PSA_DEPRECATED psa_status_t mbedtls_deprecated_psa_status_t;
Gilles Peskine41510942019-11-26 16:10:58 +010084typedef MBEDTLS_PSA_DEPRECATED psa_key_usage_t mbedtls_deprecated_psa_key_usage_t;
Paul Elliott8ff510a2020-06-02 17:19:28 +010085typedef MBEDTLS_PSA_DEPRECATED psa_ecc_family_t mbedtls_deprecated_psa_ecc_family_t;
Paul Elliott75e27032020-06-03 15:17:39 +010086typedef MBEDTLS_PSA_DEPRECATED psa_dh_family_t mbedtls_deprecated_psa_dh_family_t;
Paul Elliott8ff510a2020-06-02 17:19:28 +010087typedef MBEDTLS_PSA_DEPRECATED psa_ecc_family_t psa_ecc_curve_t;
Paul Elliott75e27032020-06-03 15:17:39 +010088typedef MBEDTLS_PSA_DEPRECATED psa_dh_family_t psa_dh_group_t;
Paul Elliott8ff510a2020-06-02 17:19:28 +010089
90#define PSA_KEY_TYPE_GET_CURVE PSA_KEY_TYPE_ECC_GET_FAMILY
Paul Elliott75e27032020-06-03 15:17:39 +010091#define PSA_KEY_TYPE_GET_GROUP PSA_KEY_TYPE_DH_GET_FAMILY
Gilles Peskine7b0ab6d2019-11-26 16:32:12 +010092
93#define MBEDTLS_DEPRECATED_CONSTANT( type, value ) \
94 ( (mbedtls_deprecated_##type) ( value ) )
95
Gilles Peskine7a894f22019-11-26 16:06:46 +010096/*
Gilles Peskine0168f2f2019-11-29 12:22:32 +010097 * Deprecated PSA Crypto error code definitions (PSA Crypto API <= 1.0 beta2)
Gilles Peskine7a894f22019-11-26 16:06:46 +010098 */
Gilles Peskine7a894f22019-11-26 16:06:46 +010099#define PSA_ERROR_UNKNOWN_ERROR \
Gilles Peskine7b0ab6d2019-11-26 16:32:12 +0100100 MBEDTLS_DEPRECATED_CONSTANT( psa_status_t, PSA_ERROR_GENERIC_ERROR )
Gilles Peskine7a894f22019-11-26 16:06:46 +0100101#define PSA_ERROR_OCCUPIED_SLOT \
Gilles Peskine7b0ab6d2019-11-26 16:32:12 +0100102 MBEDTLS_DEPRECATED_CONSTANT( psa_status_t, PSA_ERROR_ALREADY_EXISTS )
Gilles Peskine7a894f22019-11-26 16:06:46 +0100103#define PSA_ERROR_EMPTY_SLOT \
Gilles Peskine7b0ab6d2019-11-26 16:32:12 +0100104 MBEDTLS_DEPRECATED_CONSTANT( psa_status_t, PSA_ERROR_DOES_NOT_EXIST )
Gilles Peskine7a894f22019-11-26 16:06:46 +0100105#define PSA_ERROR_INSUFFICIENT_CAPACITY \
Gilles Peskine7b0ab6d2019-11-26 16:32:12 +0100106 MBEDTLS_DEPRECATED_CONSTANT( psa_status_t, PSA_ERROR_INSUFFICIENT_DATA )
Gilles Peskine7a894f22019-11-26 16:06:46 +0100107#define PSA_ERROR_TAMPERING_DETECTED \
Gilles Peskine7b0ab6d2019-11-26 16:32:12 +0100108 MBEDTLS_DEPRECATED_CONSTANT( psa_status_t, PSA_ERROR_CORRUPTION_DETECTED )
109
Gilles Peskine41510942019-11-26 16:10:58 +0100110/*
Gilles Peskine0168f2f2019-11-29 12:22:32 +0100111 * Deprecated PSA Crypto numerical encodings (PSA Crypto API <= 1.0 beta3)
Gilles Peskine41510942019-11-26 16:10:58 +0100112 */
113#define PSA_KEY_USAGE_SIGN \
114 MBEDTLS_DEPRECATED_CONSTANT( psa_key_usage_t, PSA_KEY_USAGE_SIGN_HASH )
115#define PSA_KEY_USAGE_VERIFY \
116 MBEDTLS_DEPRECATED_CONSTANT( psa_key_usage_t, PSA_KEY_USAGE_VERIFY_HASH )
117
118/*
Gilles Peskine0168f2f2019-11-29 12:22:32 +0100119 * Deprecated PSA Crypto size calculation macros (PSA Crypto API <= 1.0 beta3)
Gilles Peskine41510942019-11-26 16:10:58 +0100120 */
121#define PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE \
122 MBEDTLS_DEPRECATED_CONSTANT( size_t, PSA_SIGNATURE_MAX_SIZE )
123#define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE( key_type, key_bits, alg ) \
124 MBEDTLS_DEPRECATED_CONSTANT( size_t, PSA_SIGN_OUTPUT_SIZE( key_type, key_bits, alg ) )
125
126/*
Gilles Peskine0168f2f2019-11-29 12:22:32 +0100127 * Deprecated PSA Crypto function names (PSA Crypto API <= 1.0 beta3)
Gilles Peskine41510942019-11-26 16:10:58 +0100128 */
Soby Mathew0a4270d2020-02-10 15:20:39 +0000129MBEDTLS_PSA_DEPRECATED static inline psa_status_t psa_asymmetric_sign( psa_key_handle_t key,
130 psa_algorithm_t alg,
131 const uint8_t *hash,
132 size_t hash_length,
133 uint8_t *signature,
134 size_t signature_size,
135 size_t *signature_length )
136{
137 return psa_sign_hash( key, alg, hash, hash_length, signature, signature_size, signature_length );
138}
139
140MBEDTLS_PSA_DEPRECATED static inline psa_status_t psa_asymmetric_verify( psa_key_handle_t key,
141 psa_algorithm_t alg,
142 const uint8_t *hash,
143 size_t hash_length,
144 const uint8_t *signature,
145 size_t signature_length )
146{
147 return psa_verify_hash( key, alg, hash, hash_length, signature, signature_length );
148}
149
150
Gilles Peskine41510942019-11-26 16:10:58 +0100151
Gilles Peskine7b0ab6d2019-11-26 16:32:12 +0100152#endif /* MBEDTLS_DEPRECATED_REMOVED */
Gilles Peskine7a894f22019-11-26 16:06:46 +0100153
Gilles Peskine45c29ce2019-12-03 17:56:11 +0100154/*
Paul Elliott75e27032020-06-03 15:17:39 +0100155 * Size-specific elliptic curve families.
Gilles Peskine45c29ce2019-12-03 17:56:11 +0100156 */
Gilles Peskineb87b7192019-12-04 16:24:10 +0100157#define PSA_ECC_CURVE_SECP160K1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100158 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100159#define PSA_ECC_CURVE_SECP192K1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100160 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100161#define PSA_ECC_CURVE_SECP224K1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100162 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100163#define PSA_ECC_CURVE_SECP256K1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100164 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100165#define PSA_ECC_CURVE_SECP160R1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100166 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100167#define PSA_ECC_CURVE_SECP192R1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100168 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100169#define PSA_ECC_CURVE_SECP224R1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100170 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100171#define PSA_ECC_CURVE_SECP256R1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100172 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100173#define PSA_ECC_CURVE_SECP384R1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100174 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100175#define PSA_ECC_CURVE_SECP521R1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100176 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100177#define PSA_ECC_CURVE_SECP160R2 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100178 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R2 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100179#define PSA_ECC_CURVE_SECT163K1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100180 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100181#define PSA_ECC_CURVE_SECT233K1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100182 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100183#define PSA_ECC_CURVE_SECT239K1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100184 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100185#define PSA_ECC_CURVE_SECT283K1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100186 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100187#define PSA_ECC_CURVE_SECT409K1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100188 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100189#define PSA_ECC_CURVE_SECT571K1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100190 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100191#define PSA_ECC_CURVE_SECT163R1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100192 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100193#define PSA_ECC_CURVE_SECT193R1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100194 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100195#define PSA_ECC_CURVE_SECT233R1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100196 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100197#define PSA_ECC_CURVE_SECT283R1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100198 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100199#define PSA_ECC_CURVE_SECT409R1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100200 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100201#define PSA_ECC_CURVE_SECT571R1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100202 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100203#define PSA_ECC_CURVE_SECT163R2 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100204 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R2 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100205#define PSA_ECC_CURVE_SECT193R2 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100206 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R2 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100207#define PSA_ECC_CURVE_BRAINPOOL_P256R1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100208 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_BRAINPOOL_P_R1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100209#define PSA_ECC_CURVE_BRAINPOOL_P384R1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100210 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_BRAINPOOL_P_R1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100211#define PSA_ECC_CURVE_BRAINPOOL_P512R1 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100212 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_BRAINPOOL_P_R1 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100213#define PSA_ECC_CURVE_CURVE25519 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100214 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_MONTGOMERY )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100215#define PSA_ECC_CURVE_CURVE448 \
Paul Elliott8ff510a2020-06-02 17:19:28 +0100216 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_MONTGOMERY )
217
218/*
219 * Curves that changed name due to PSA specification.
220 */
221#define PSA_ECC_CURVE_SECP_K1 \
222 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1 )
223#define PSA_ECC_CURVE_SECP_R1 \
224 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
225#define PSA_ECC_CURVE_SECP_R2 \
226 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R2 )
227#define PSA_ECC_CURVE_SECT_K1 \
228 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
229#define PSA_ECC_CURVE_SECT_R1 \
230 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
231#define PSA_ECC_CURVE_SECT_R2 \
232 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R2 )
233#define PSA_ECC_CURVE_BRAINPOOL_P_R1 \
234 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_BRAINPOOL_P_R1 )
235#define PSA_ECC_CURVE_MONTGOMERY \
236 MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_MONTGOMERY )
Gilles Peskine45c29ce2019-12-03 17:56:11 +0100237
Paul Elliott75e27032020-06-03 15:17:39 +0100238/*
239 * Finite-field Diffie-Hellman families.
240 */
Gilles Peskineb87b7192019-12-04 16:24:10 +0100241#define PSA_DH_GROUP_FFDHE2048 \
Paul Elliott75e27032020-06-03 15:17:39 +0100242 MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100243#define PSA_DH_GROUP_FFDHE3072 \
Paul Elliott75e27032020-06-03 15:17:39 +0100244 MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100245#define PSA_DH_GROUP_FFDHE4096 \
Paul Elliott75e27032020-06-03 15:17:39 +0100246 MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100247#define PSA_DH_GROUP_FFDHE6144 \
Paul Elliott75e27032020-06-03 15:17:39 +0100248 MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
Gilles Peskineb87b7192019-12-04 16:24:10 +0100249#define PSA_DH_GROUP_FFDHE8192 \
Paul Elliott75e27032020-06-03 15:17:39 +0100250 MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
251
252/*
253 * Diffie-Hellman families that changed name due to PSA specification.
254 */
255#define PSA_DH_GROUP_RFC7919 \
256 MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
257#define PSA_DH_GROUP_CUSTOM \
258 MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_CUSTOM )
Gilles Peskine45c29ce2019-12-03 17:56:11 +0100259
Ronald Croncf56a0a2020-08-04 09:51:30 +0200260/** Open a handle to an existing persistent key.
261 *
262 * Open a handle to a persistent key. A key is persistent if it was created
263 * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
264 * always has a nonzero key identifier, set with psa_set_key_id() when
265 * creating the key. Implementations may provide additional pre-provisioned
266 * keys that can be opened with psa_open_key(). Such keys have an application
267 * key identifier in the vendor range, as documented in the description of
268 * #psa_key_id_t.
269 *
270 * The application must eventually close the handle with psa_close_key() or
271 * psa_destroy_key() to release associated resources. If the application dies
272 * without calling one of these functions, the implementation should perform
273 * the equivalent of a call to psa_close_key().
274 *
275 * Some implementations permit an application to open the same key multiple
276 * times. If this is successful, each call to psa_open_key() will return a
277 * different key handle.
278 *
279 * \note This API is not part of the PSA Cryptography API Release 1.0.0
280 * specification. It was defined in the 1.0 Beta 3 version of the
281 * specification but was removed in the 1.0.0 released version. This API is
282 * kept for the time being to not break applications relying on it. It is not
283 * deprecated yet but will be in the near future.
284 *
285 * \note Applications that rely on opening a key multiple times will not be
286 * portable to implementations that only permit a single key handle to be
287 * opened. See also :ref:\`key-handles\`.
288 *
289 *
290 * \param key The persistent identifier of the key.
291 * \param[out] handle On success, a handle to the key.
292 *
293 * \retval #PSA_SUCCESS
294 * Success. The application can now use the value of `*handle`
295 * to access the key.
296 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
297 * The implementation does not have sufficient resources to open the
298 * key. This can be due to reaching an implementation limit on the
299 * number of open keys, the number of open key handles, or available
300 * memory.
301 * \retval #PSA_ERROR_DOES_NOT_EXIST
302 * There is no persistent key with key identifier \p id.
303 * \retval #PSA_ERROR_INVALID_ARGUMENT
304 * \p id is not a valid persistent key identifier.
305 * \retval #PSA_ERROR_NOT_PERMITTED
306 * The specified key exists, but the application does not have the
307 * permission to access it. Note that this specification does not
308 * define any way to create such a key, but it may be possible
309 * through implementation-specific means.
310 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
311 * \retval #PSA_ERROR_CORRUPTION_DETECTED
312 * \retval #PSA_ERROR_STORAGE_FAILURE
313 * \retval #PSA_ERROR_BAD_STATE
314 * The library has not been previously initialized by psa_crypto_init().
315 * It is implementation-dependent whether a failure to initialize
316 * results in this error code.
317 */
318psa_status_t psa_open_key( mbedtls_svc_key_id_t key,
319 psa_key_handle_t *handle );
320
321/** Close a key handle.
322 *
323 * If the handle designates a volatile key, this will destroy the key material
324 * and free all associated resources, just like psa_destroy_key().
325 *
326 * If this is the last open handle to a persistent key, then closing the handle
327 * will free all resources associated with the key in volatile memory. The key
328 * data in persistent storage is not affected and can be opened again later
329 * with a call to psa_open_key().
330 *
331 * Closing the key handle makes the handle invalid, and the key handle
332 * must not be used again by the application.
333 *
334 * \note This API is not part of the PSA Cryptography API Release 1.0.0
335 * specification. It was defined in the 1.0 Beta 3 version of the
336 * specification but was removed in the 1.0.0 released version. This API is
337 * kept for the time being to not break applications relying on it. It is not
338 * deprecated yet but will be in the near future.
339 *
340 * \note If the key handle was used to set up an active
341 * :ref:\`multipart operation <multipart-operations>\`, then closing the
342 * key handle can cause the multipart operation to fail. Applications should
343 * maintain the key handle until after the multipart operation has finished.
344 *
345 * \param handle The key handle to close.
346 * If this is \c 0, do nothing and return \c PSA_SUCCESS.
347 *
348 * \retval #PSA_SUCCESS
349 * \p handle was a valid handle or \c 0. It is now closed.
350 * \retval #PSA_ERROR_INVALID_HANDLE
351 * \p handle is not a valid handle nor \c 0.
352 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
353 * \retval #PSA_ERROR_CORRUPTION_DETECTED
354 * \retval #PSA_ERROR_BAD_STATE
355 * The library has not been previously initialized by psa_crypto_init().
356 * It is implementation-dependent whether a failure to initialize
357 * results in this error code.
358 */
359psa_status_t psa_close_key(psa_key_handle_t handle);
360
Gilles Peskine7a894f22019-11-26 16:06:46 +0100361#ifdef __cplusplus
362}
363#endif
364
365#endif /* PSA_CRYPTO_COMPAT_H */