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