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 */
psa_key_handle_is_null(psa_key_handle_t handle)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 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
47
48 /*
49 * Mechanism for declaring deprecated values
50 */
51 #if defined(MBEDTLS_DEPRECATED_WARNING) && !defined(MBEDTLS_PSA_DEPRECATED)
52 #define MBEDTLS_PSA_DEPRECATED __attribute__((deprecated))
53 #else
54 #define MBEDTLS_PSA_DEPRECATED
55 #endif
56
57 typedef MBEDTLS_PSA_DEPRECATED size_t mbedtls_deprecated_size_t;
58 typedef MBEDTLS_PSA_DEPRECATED psa_status_t mbedtls_deprecated_psa_status_t;
59 typedef MBEDTLS_PSA_DEPRECATED psa_key_usage_t mbedtls_deprecated_psa_key_usage_t;
60 typedef MBEDTLS_PSA_DEPRECATED psa_ecc_family_t mbedtls_deprecated_psa_ecc_family_t;
61 typedef MBEDTLS_PSA_DEPRECATED psa_dh_family_t mbedtls_deprecated_psa_dh_family_t;
62 typedef MBEDTLS_PSA_DEPRECATED psa_ecc_family_t psa_ecc_curve_t;
63 typedef MBEDTLS_PSA_DEPRECATED psa_dh_family_t psa_dh_group_t;
64 typedef MBEDTLS_PSA_DEPRECATED psa_algorithm_t mbedtls_deprecated_psa_algorithm_t;
65
66 #define PSA_KEY_TYPE_GET_CURVE PSA_KEY_TYPE_ECC_GET_FAMILY
67 #define PSA_KEY_TYPE_GET_GROUP PSA_KEY_TYPE_DH_GET_FAMILY
68
69 #define MBEDTLS_DEPRECATED_CONSTANT(type, value) \
70 ((mbedtls_deprecated_##type) (value))
71
72 /*
73 * Deprecated PSA Crypto error code definitions (PSA Crypto API <= 1.0 beta2)
74 */
75 #define PSA_ERROR_UNKNOWN_ERROR \
76 MBEDTLS_DEPRECATED_CONSTANT(psa_status_t, PSA_ERROR_GENERIC_ERROR)
77 #define PSA_ERROR_OCCUPIED_SLOT \
78 MBEDTLS_DEPRECATED_CONSTANT(psa_status_t, PSA_ERROR_ALREADY_EXISTS)
79 #define PSA_ERROR_EMPTY_SLOT \
80 MBEDTLS_DEPRECATED_CONSTANT(psa_status_t, PSA_ERROR_DOES_NOT_EXIST)
81 #define PSA_ERROR_INSUFFICIENT_CAPACITY \
82 MBEDTLS_DEPRECATED_CONSTANT(psa_status_t, PSA_ERROR_INSUFFICIENT_DATA)
83 #define PSA_ERROR_TAMPERING_DETECTED \
84 MBEDTLS_DEPRECATED_CONSTANT(psa_status_t, PSA_ERROR_CORRUPTION_DETECTED)
85
86 /*
87 * Deprecated PSA Crypto numerical encodings (PSA Crypto API <= 1.0 beta3)
88 */
89 #define PSA_KEY_USAGE_SIGN \
90 MBEDTLS_DEPRECATED_CONSTANT(psa_key_usage_t, PSA_KEY_USAGE_SIGN_HASH)
91 #define PSA_KEY_USAGE_VERIFY \
92 MBEDTLS_DEPRECATED_CONSTANT(psa_key_usage_t, PSA_KEY_USAGE_VERIFY_HASH)
93
94 /*
95 * Deprecated PSA Crypto size calculation macros (PSA Crypto API <= 1.0 beta3)
96 */
97 #define PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE \
98 MBEDTLS_DEPRECATED_CONSTANT(size_t, PSA_SIGNATURE_MAX_SIZE)
99 #define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \
100 MBEDTLS_DEPRECATED_CONSTANT(size_t, PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg))
101 #define PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits) \
102 MBEDTLS_DEPRECATED_CONSTANT(size_t, PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits))
103 #define PSA_BLOCK_CIPHER_BLOCK_SIZE(type) \
104 MBEDTLS_DEPRECATED_CONSTANT(size_t, PSA_BLOCK_CIPHER_BLOCK_LENGTH(type))
105 #define PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE \
106 MBEDTLS_DEPRECATED_CONSTANT(size_t, PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE)
107 #define PSA_HASH_SIZE(alg) \
108 MBEDTLS_DEPRECATED_CONSTANT(size_t, PSA_HASH_LENGTH(alg))
109 #define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg) \
110 MBEDTLS_DEPRECATED_CONSTANT(size_t, PSA_MAC_LENGTH(key_type, key_bits, alg))
111 #define PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN \
112 MBEDTLS_DEPRECATED_CONSTANT(size_t, PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE)
113
114 /*
115 * Deprecated PSA Crypto function names (PSA Crypto API <= 1.0 beta3)
116 */
psa_asymmetric_sign(psa_key_handle_t key,psa_algorithm_t alg,const uint8_t * hash,size_t hash_length,uint8_t * signature,size_t signature_size,size_t * signature_length)117 MBEDTLS_PSA_DEPRECATED static inline psa_status_t psa_asymmetric_sign(psa_key_handle_t key,
118 psa_algorithm_t alg,
119 const uint8_t *hash,
120 size_t hash_length,
121 uint8_t *signature,
122 size_t signature_size,
123 size_t *signature_length)
124 {
125 return psa_sign_hash(key, alg, hash, hash_length, signature, signature_size, signature_length);
126 }
127
psa_asymmetric_verify(psa_key_handle_t key,psa_algorithm_t alg,const uint8_t * hash,size_t hash_length,const uint8_t * signature,size_t signature_length)128 MBEDTLS_PSA_DEPRECATED static inline psa_status_t psa_asymmetric_verify(psa_key_handle_t key,
129 psa_algorithm_t alg,
130 const uint8_t *hash,
131 size_t hash_length,
132 const uint8_t *signature,
133 size_t signature_length)
134 {
135 return psa_verify_hash(key, alg, hash, hash_length, signature, signature_length);
136 }
137
138 /*
139 * Size-specific elliptic curve families.
140 */
141 #define PSA_ECC_CURVE_SECP160K1 \
142 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1)
143 #define PSA_ECC_CURVE_SECP192K1 \
144 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1)
145 #define PSA_ECC_CURVE_SECP224K1 \
146 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1)
147 #define PSA_ECC_CURVE_SECP256K1 \
148 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1)
149 #define PSA_ECC_CURVE_SECP160R1 \
150 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1)
151 #define PSA_ECC_CURVE_SECP192R1 \
152 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1)
153 #define PSA_ECC_CURVE_SECP224R1 \
154 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1)
155 #define PSA_ECC_CURVE_SECP256R1 \
156 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1)
157 #define PSA_ECC_CURVE_SECP384R1 \
158 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1)
159 #define PSA_ECC_CURVE_SECP521R1 \
160 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1)
161 #define PSA_ECC_CURVE_SECP160R2 \
162 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R2)
163 #define PSA_ECC_CURVE_SECT163K1 \
164 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1)
165 #define PSA_ECC_CURVE_SECT233K1 \
166 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1)
167 #define PSA_ECC_CURVE_SECT239K1 \
168 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1)
169 #define PSA_ECC_CURVE_SECT283K1 \
170 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1)
171 #define PSA_ECC_CURVE_SECT409K1 \
172 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1)
173 #define PSA_ECC_CURVE_SECT571K1 \
174 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1)
175 #define PSA_ECC_CURVE_SECT163R1 \
176 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1)
177 #define PSA_ECC_CURVE_SECT193R1 \
178 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1)
179 #define PSA_ECC_CURVE_SECT233R1 \
180 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1)
181 #define PSA_ECC_CURVE_SECT283R1 \
182 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1)
183 #define PSA_ECC_CURVE_SECT409R1 \
184 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1)
185 #define PSA_ECC_CURVE_SECT571R1 \
186 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1)
187 #define PSA_ECC_CURVE_SECT163R2 \
188 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R2)
189 #define PSA_ECC_CURVE_SECT193R2 \
190 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R2)
191 #define PSA_ECC_CURVE_BRAINPOOL_P256R1 \
192 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_BRAINPOOL_P_R1)
193 #define PSA_ECC_CURVE_BRAINPOOL_P384R1 \
194 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_BRAINPOOL_P_R1)
195 #define PSA_ECC_CURVE_BRAINPOOL_P512R1 \
196 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_BRAINPOOL_P_R1)
197 #define PSA_ECC_CURVE_CURVE25519 \
198 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_MONTGOMERY)
199 #define PSA_ECC_CURVE_CURVE448 \
200 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_MONTGOMERY)
201
202 /*
203 * Curves that changed name due to PSA specification.
204 */
205 #define PSA_ECC_CURVE_SECP_K1 \
206 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1)
207 #define PSA_ECC_CURVE_SECP_R1 \
208 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1)
209 #define PSA_ECC_CURVE_SECP_R2 \
210 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R2)
211 #define PSA_ECC_CURVE_SECT_K1 \
212 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1)
213 #define PSA_ECC_CURVE_SECT_R1 \
214 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1)
215 #define PSA_ECC_CURVE_SECT_R2 \
216 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R2)
217 #define PSA_ECC_CURVE_BRAINPOOL_P_R1 \
218 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_BRAINPOOL_P_R1)
219 #define PSA_ECC_CURVE_MONTGOMERY \
220 MBEDTLS_DEPRECATED_CONSTANT(psa_ecc_family_t, PSA_ECC_FAMILY_MONTGOMERY)
221
222 /*
223 * Finite-field Diffie-Hellman families.
224 */
225 #define PSA_DH_GROUP_FFDHE2048 \
226 MBEDTLS_DEPRECATED_CONSTANT(psa_dh_family_t, PSA_DH_FAMILY_RFC7919)
227 #define PSA_DH_GROUP_FFDHE3072 \
228 MBEDTLS_DEPRECATED_CONSTANT(psa_dh_family_t, PSA_DH_FAMILY_RFC7919)
229 #define PSA_DH_GROUP_FFDHE4096 \
230 MBEDTLS_DEPRECATED_CONSTANT(psa_dh_family_t, PSA_DH_FAMILY_RFC7919)
231 #define PSA_DH_GROUP_FFDHE6144 \
232 MBEDTLS_DEPRECATED_CONSTANT(psa_dh_family_t, PSA_DH_FAMILY_RFC7919)
233 #define PSA_DH_GROUP_FFDHE8192 \
234 MBEDTLS_DEPRECATED_CONSTANT(psa_dh_family_t, PSA_DH_FAMILY_RFC7919)
235
236 /*
237 * Diffie-Hellman families that changed name due to PSA specification.
238 */
239 #define PSA_DH_GROUP_RFC7919 \
240 MBEDTLS_DEPRECATED_CONSTANT(psa_dh_family_t, PSA_DH_FAMILY_RFC7919)
241 #define PSA_DH_GROUP_CUSTOM \
242 MBEDTLS_DEPRECATED_CONSTANT(psa_dh_family_t, PSA_DH_FAMILY_CUSTOM)
243
244 /*
245 * Deprecated PSA Crypto stream cipher algorithms (PSA Crypto API <= 1.0 beta3)
246 */
247 #define PSA_ALG_ARC4 \
248 MBEDTLS_DEPRECATED_CONSTANT(psa_algorithm_t, PSA_ALG_STREAM_CIPHER)
249 #define PSA_ALG_CHACHA20 \
250 MBEDTLS_DEPRECATED_CONSTANT(psa_algorithm_t, PSA_ALG_STREAM_CIPHER)
251
252 /*
253 * Renamed AEAD tag length macros (PSA Crypto API <= 1.0 beta3)
254 */
255 #define PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH(aead_alg) \
256 MBEDTLS_DEPRECATED_CONSTANT(psa_algorithm_t, PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG(aead_alg))
257 #define PSA_ALG_AEAD_WITH_TAG_LENGTH(aead_alg, tag_length) \
258 MBEDTLS_DEPRECATED_CONSTANT(psa_algorithm_t, \
259 PSA_ALG_AEAD_WITH_SHORTENED_TAG(aead_alg, tag_length))
260
261 /*
262 * Deprecated PSA AEAD output size macros (PSA Crypto API <= 1.0 beta3)
263 */
264
265 /** The tag size for an AEAD algorithm, in bytes.
266 *
267 * \param alg An AEAD algorithm
268 * (\c PSA_ALG_XXX value such that
269 * #PSA_ALG_IS_AEAD(\p alg) is true).
270 *
271 * \return The tag size for the specified algorithm.
272 * If the AEAD algorithm does not have an identified
273 * tag that can be distinguished from the rest of
274 * the ciphertext, return 0.
275 * If the AEAD algorithm is not recognized, return 0.
276 */
277 #define PSA_AEAD_TAG_LENGTH_1_ARG(alg) \
278 MBEDTLS_DEPRECATED_CONSTANT(size_t, \
279 PSA_ALG_IS_AEAD(alg) ? \
280 PSA_ALG_AEAD_GET_TAG_LENGTH(alg) : \
281 0)
282
283 /** The maximum size of the output of psa_aead_encrypt(), in bytes.
284 *
285 * If the size of the ciphertext buffer is at least this large, it is
286 * guaranteed that psa_aead_encrypt() will not fail due to an
287 * insufficient buffer size. Depending on the algorithm, the actual size of
288 * the ciphertext may be smaller.
289 *
290 * \warning This macro may evaluate its arguments multiple times or
291 * zero times, so you should not pass arguments that contain
292 * side effects.
293 *
294 * \param alg An AEAD algorithm
295 * (\c PSA_ALG_XXX value such that
296 * #PSA_ALG_IS_AEAD(\p alg) is true).
297 * \param plaintext_length Size of the plaintext in bytes.
298 *
299 * \return The AEAD ciphertext size for the specified
300 * algorithm.
301 * If the AEAD algorithm is not recognized, return 0.
302 */
303 #define PSA_AEAD_ENCRYPT_OUTPUT_SIZE_2_ARG(alg, plaintext_length) \
304 MBEDTLS_DEPRECATED_CONSTANT(size_t, \
305 PSA_ALG_IS_AEAD(alg) ? \
306 (plaintext_length) + PSA_ALG_AEAD_GET_TAG_LENGTH(alg) : \
307 0)
308
309 /** The maximum size of the output of psa_aead_decrypt(), in bytes.
310 *
311 * If the size of the plaintext buffer is at least this large, it is
312 * guaranteed that psa_aead_decrypt() will not fail due to an
313 * insufficient buffer size. Depending on the algorithm, the actual size of
314 * the plaintext may be smaller.
315 *
316 * \warning This macro may evaluate its arguments multiple times or
317 * zero times, so you should not pass arguments that contain
318 * side effects.
319 *
320 * \param alg An AEAD algorithm
321 * (\c PSA_ALG_XXX value such that
322 * #PSA_ALG_IS_AEAD(\p alg) is true).
323 * \param ciphertext_length Size of the plaintext in bytes.
324 *
325 * \return The AEAD ciphertext size for the specified
326 * algorithm.
327 * If the AEAD algorithm is not recognized, return 0.
328 */
329 #define PSA_AEAD_DECRYPT_OUTPUT_SIZE_2_ARG(alg, ciphertext_length) \
330 MBEDTLS_DEPRECATED_CONSTANT(size_t, \
331 PSA_ALG_IS_AEAD(alg) && \
332 (ciphertext_length) > PSA_ALG_AEAD_GET_TAG_LENGTH(alg) ? \
333 (ciphertext_length) - PSA_ALG_AEAD_GET_TAG_LENGTH(alg) : \
334 0)
335
336 /** A sufficient output buffer size for psa_aead_update().
337 *
338 * If the size of the output buffer is at least this large, it is
339 * guaranteed that psa_aead_update() will not fail due to an
340 * insufficient buffer size. The actual size of the output may be smaller
341 * in any given call.
342 *
343 * \warning This macro may evaluate its arguments multiple times or
344 * zero times, so you should not pass arguments that contain
345 * side effects.
346 *
347 * \param alg An AEAD algorithm
348 * (\c PSA_ALG_XXX value such that
349 * #PSA_ALG_IS_AEAD(\p alg) is true).
350 * \param input_length Size of the input in bytes.
351 *
352 * \return A sufficient output buffer size for the specified
353 * algorithm.
354 * If the AEAD algorithm is not recognized, return 0.
355 */
356 /* For all the AEAD modes defined in this specification, it is possible
357 * to emit output without delay. However, hardware may not always be
358 * capable of this. So for modes based on a block cipher, allow the
359 * implementation to delay the output until it has a full block. */
360 #define PSA_AEAD_UPDATE_OUTPUT_SIZE_2_ARG(alg, input_length) \
361 MBEDTLS_DEPRECATED_CONSTANT(size_t, \
362 PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
363 PSA_ROUND_UP_TO_MULTIPLE(PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE, \
364 (input_length)) : \
365 (input_length))
366
367 /** A sufficient ciphertext buffer size for psa_aead_finish().
368 *
369 * If the size of the ciphertext buffer is at least this large, it is
370 * guaranteed that psa_aead_finish() will not fail due to an
371 * insufficient ciphertext buffer size. The actual size of the output may
372 * be smaller in any given call.
373 *
374 * \param alg An AEAD algorithm
375 * (\c PSA_ALG_XXX value such that
376 * #PSA_ALG_IS_AEAD(\p alg) is true).
377 *
378 * \return A sufficient ciphertext buffer size for the
379 * specified algorithm.
380 * If the AEAD algorithm is not recognized, return 0.
381 */
382 #define PSA_AEAD_FINISH_OUTPUT_SIZE_1_ARG(alg) \
383 MBEDTLS_DEPRECATED_CONSTANT(size_t, \
384 PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
385 PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE : \
386 0)
387
388 /** A sufficient plaintext buffer size for psa_aead_verify().
389 *
390 * If the size of the plaintext buffer is at least this large, it is
391 * guaranteed that psa_aead_verify() will not fail due to an
392 * insufficient plaintext buffer size. The actual size of the output may
393 * be smaller in any given call.
394 *
395 * \param alg An AEAD algorithm
396 * (\c PSA_ALG_XXX value such that
397 * #PSA_ALG_IS_AEAD(\p alg) is true).
398 *
399 * \return A sufficient plaintext buffer size for the
400 * specified algorithm.
401 * If the AEAD algorithm is not recognized, return 0.
402 */
403 #define PSA_AEAD_VERIFY_OUTPUT_SIZE_1_ARG(alg) \
404 MBEDTLS_DEPRECATED_CONSTANT(size_t, \
405 PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
406 PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE : \
407 0)
408
409 #endif /* MBEDTLS_DEPRECATED_REMOVED */
410
411 /** Open a handle to an existing persistent key.
412 *
413 * Open a handle to a persistent key. A key is persistent if it was created
414 * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
415 * always has a nonzero key identifier, set with psa_set_key_id() when
416 * creating the key. Implementations may provide additional pre-provisioned
417 * keys that can be opened with psa_open_key(). Such keys have an application
418 * key identifier in the vendor range, as documented in the description of
419 * #psa_key_id_t.
420 *
421 * The application must eventually close the handle with psa_close_key() or
422 * psa_destroy_key() to release associated resources. If the application dies
423 * without calling one of these functions, the implementation should perform
424 * the equivalent of a call to psa_close_key().
425 *
426 * Some implementations permit an application to open the same key multiple
427 * times. If this is successful, each call to psa_open_key() will return a
428 * different key handle.
429 *
430 * \note This API is not part of the PSA Cryptography API Release 1.0.0
431 * specification. It was defined in the 1.0 Beta 3 version of the
432 * specification but was removed in the 1.0.0 released version. This API is
433 * kept for the time being to not break applications relying on it. It is not
434 * deprecated yet but will be in the near future.
435 *
436 * \note Applications that rely on opening a key multiple times will not be
437 * portable to implementations that only permit a single key handle to be
438 * opened. See also :ref:\`key-handles\`.
439 *
440 *
441 * \param key The persistent identifier of the key.
442 * \param[out] handle On success, a handle to the key.
443 *
444 * \retval #PSA_SUCCESS
445 * Success. The application can now use the value of `*handle`
446 * to access the key.
447 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
448 * The implementation does not have sufficient resources to open the
449 * key. This can be due to reaching an implementation limit on the
450 * number of open keys, the number of open key handles, or available
451 * memory.
452 * \retval #PSA_ERROR_DOES_NOT_EXIST
453 * There is no persistent key with key identifier \p key.
454 * \retval #PSA_ERROR_INVALID_ARGUMENT
455 * \p key is not a valid persistent key identifier.
456 * \retval #PSA_ERROR_NOT_PERMITTED
457 * The specified key exists, but the application does not have the
458 * permission to access it. Note that this specification does not
459 * define any way to create such a key, but it may be possible
460 * through implementation-specific means.
461 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
462 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
463 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
464 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
465 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
466 * \retval #PSA_ERROR_BAD_STATE
467 * The library has not been previously initialized by psa_crypto_init().
468 * It is implementation-dependent whether a failure to initialize
469 * results in this error code.
470 */
471 psa_status_t psa_open_key(mbedtls_svc_key_id_t key,
472 psa_key_handle_t *handle);
473
474 /** Close a key handle.
475 *
476 * If the handle designates a volatile key, this will destroy the key material
477 * and free all associated resources, just like psa_destroy_key().
478 *
479 * If this is the last open handle to a persistent key, then closing the handle
480 * will free all resources associated with the key in volatile memory. The key
481 * data in persistent storage is not affected and can be opened again later
482 * with a call to psa_open_key().
483 *
484 * Closing the key handle makes the handle invalid, and the key handle
485 * must not be used again by the application.
486 *
487 * \note This API is not part of the PSA Cryptography API Release 1.0.0
488 * specification. It was defined in the 1.0 Beta 3 version of the
489 * specification but was removed in the 1.0.0 released version. This API is
490 * kept for the time being to not break applications relying on it. It is not
491 * deprecated yet but will be in the near future.
492 *
493 * \note If the key handle was used to set up an active
494 * :ref:\`multipart operation <multipart-operations>\`, then closing the
495 * key handle can cause the multipart operation to fail. Applications should
496 * maintain the key handle until after the multipart operation has finished.
497 *
498 * \param handle The key handle to close.
499 * If this is \c 0, do nothing and return \c PSA_SUCCESS.
500 *
501 * \retval #PSA_SUCCESS
502 * \p handle was a valid handle or \c 0. It is now closed.
503 * \retval #PSA_ERROR_INVALID_HANDLE
504 * \p handle is not a valid handle nor \c 0.
505 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
506 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
507 * \retval #PSA_ERROR_BAD_STATE
508 * The library has not been previously initialized by psa_crypto_init().
509 * It is implementation-dependent whether a failure to initialize
510 * results in this error code.
511 */
512 psa_status_t psa_close_key(psa_key_handle_t handle);
513
514 #ifdef __cplusplus
515 }
516 #endif
517
518 #endif /* PSA_CRYPTO_COMPAT_H */
519