NCBI C++ ToolKit
crypto_compat.h
Go to the documentation of this file.

Go to the SVN repository for this file.

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  */
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 #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 
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  */
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 
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, \
271  PSA_ALG_AEAD_WITH_SHORTENED_TAG(aead_alg, tag_length))
272 
273 /*
274  * Deprecated PSA AEAD output size macros (PSA Crypto API <= 1.0 beta3)
275  */
276 
277 /** The tag size for an AEAD algorithm, in bytes.
278  *
279  * \param alg An AEAD algorithm
280  * (\c PSA_ALG_XXX value such that
281  * #PSA_ALG_IS_AEAD(\p alg) is true).
282  *
283  * \return The tag size for the specified algorithm.
284  * If the AEAD algorithm does not have an identified
285  * tag that can be distinguished from the rest of
286  * the ciphertext, return 0.
287  * If the AEAD algorithm is not recognized, return 0.
288  */
289 #define PSA_AEAD_TAG_LENGTH_1_ARG(alg) \
290  MBEDTLS_DEPRECATED_CONSTANT(size_t, \
291  PSA_ALG_IS_AEAD(alg) ? \
292  PSA_ALG_AEAD_GET_TAG_LENGTH(alg) : \
293  0)
294 
295 /** The maximum size of the output of psa_aead_encrypt(), in bytes.
296  *
297  * If the size of the ciphertext buffer is at least this large, it is
298  * guaranteed that psa_aead_encrypt() will not fail due to an
299  * insufficient buffer size. Depending on the algorithm, the actual size of
300  * the ciphertext may be smaller.
301  *
302  * \warning This macro may evaluate its arguments multiple times or
303  * zero times, so you should not pass arguments that contain
304  * side effects.
305  *
306  * \param alg An AEAD algorithm
307  * (\c PSA_ALG_XXX value such that
308  * #PSA_ALG_IS_AEAD(\p alg) is true).
309  * \param plaintext_length Size of the plaintext in bytes.
310  *
311  * \return The AEAD ciphertext size for the specified
312  * algorithm.
313  * If the AEAD algorithm is not recognized, return 0.
314  */
315 #define PSA_AEAD_ENCRYPT_OUTPUT_SIZE_2_ARG(alg, plaintext_length) \
316  MBEDTLS_DEPRECATED_CONSTANT(size_t, \
317  PSA_ALG_IS_AEAD(alg) ? \
318  (plaintext_length) + PSA_ALG_AEAD_GET_TAG_LENGTH(alg) : \
319  0)
320 
321 /** The maximum size of the output of psa_aead_decrypt(), in bytes.
322  *
323  * If the size of the plaintext buffer is at least this large, it is
324  * guaranteed that psa_aead_decrypt() will not fail due to an
325  * insufficient buffer size. Depending on the algorithm, the actual size of
326  * the plaintext may be smaller.
327  *
328  * \warning This macro may evaluate its arguments multiple times or
329  * zero times, so you should not pass arguments that contain
330  * side effects.
331  *
332  * \param alg An AEAD algorithm
333  * (\c PSA_ALG_XXX value such that
334  * #PSA_ALG_IS_AEAD(\p alg) is true).
335  * \param ciphertext_length Size of the plaintext in bytes.
336  *
337  * \return The AEAD ciphertext size for the specified
338  * algorithm.
339  * If the AEAD algorithm is not recognized, return 0.
340  */
341 #define PSA_AEAD_DECRYPT_OUTPUT_SIZE_2_ARG(alg, ciphertext_length) \
342  MBEDTLS_DEPRECATED_CONSTANT(size_t, \
343  PSA_ALG_IS_AEAD(alg) && \
344  (ciphertext_length) > PSA_ALG_AEAD_GET_TAG_LENGTH(alg) ? \
345  (ciphertext_length) - PSA_ALG_AEAD_GET_TAG_LENGTH(alg) : \
346  0)
347 
348 /** A sufficient output buffer size for psa_aead_update().
349  *
350  * If the size of the output buffer is at least this large, it is
351  * guaranteed that psa_aead_update() will not fail due to an
352  * insufficient buffer size. The actual size of the output may be smaller
353  * in any given call.
354  *
355  * \warning This macro may evaluate its arguments multiple times or
356  * zero times, so you should not pass arguments that contain
357  * side effects.
358  *
359  * \param alg An AEAD algorithm
360  * (\c PSA_ALG_XXX value such that
361  * #PSA_ALG_IS_AEAD(\p alg) is true).
362  * \param input_length Size of the input in bytes.
363  *
364  * \return A sufficient output buffer size for the specified
365  * algorithm.
366  * If the AEAD algorithm is not recognized, return 0.
367  */
368 /* For all the AEAD modes defined in this specification, it is possible
369  * to emit output without delay. However, hardware may not always be
370  * capable of this. So for modes based on a block cipher, allow the
371  * implementation to delay the output until it has a full block. */
372 #define PSA_AEAD_UPDATE_OUTPUT_SIZE_2_ARG(alg, input_length) \
373  MBEDTLS_DEPRECATED_CONSTANT(size_t, \
374  PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
375  PSA_ROUND_UP_TO_MULTIPLE(PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE, \
376  (input_length)) : \
377  (input_length))
378 
379 /** A sufficient ciphertext buffer size for psa_aead_finish().
380  *
381  * If the size of the ciphertext buffer is at least this large, it is
382  * guaranteed that psa_aead_finish() will not fail due to an
383  * insufficient ciphertext buffer size. The actual size of the output may
384  * be smaller in any given call.
385  *
386  * \param alg An AEAD algorithm
387  * (\c PSA_ALG_XXX value such that
388  * #PSA_ALG_IS_AEAD(\p alg) is true).
389  *
390  * \return A sufficient ciphertext buffer size for the
391  * specified algorithm.
392  * If the AEAD algorithm is not recognized, return 0.
393  */
394 #define PSA_AEAD_FINISH_OUTPUT_SIZE_1_ARG(alg) \
395  MBEDTLS_DEPRECATED_CONSTANT(size_t, \
396  PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
397  PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE : \
398  0)
399 
400 /** A sufficient plaintext buffer size for psa_aead_verify().
401  *
402  * If the size of the plaintext buffer is at least this large, it is
403  * guaranteed that psa_aead_verify() will not fail due to an
404  * insufficient plaintext buffer size. The actual size of the output may
405  * be smaller in any given call.
406  *
407  * \param alg An AEAD algorithm
408  * (\c PSA_ALG_XXX value such that
409  * #PSA_ALG_IS_AEAD(\p alg) is true).
410  *
411  * \return A sufficient plaintext buffer size for the
412  * specified algorithm.
413  * If the AEAD algorithm is not recognized, return 0.
414  */
415 #define PSA_AEAD_VERIFY_OUTPUT_SIZE_1_ARG(alg) \
416  MBEDTLS_DEPRECATED_CONSTANT(size_t, \
417  PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
418  PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE : \
419  0)
420 
421 #endif /* MBEDTLS_DEPRECATED_REMOVED */
422 
423 /** Open a handle to an existing persistent key.
424  *
425  * Open a handle to a persistent key. A key is persistent if it was created
426  * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
427  * always has a nonzero key identifier, set with psa_set_key_id() when
428  * creating the key. Implementations may provide additional pre-provisioned
429  * keys that can be opened with psa_open_key(). Such keys have an application
430  * key identifier in the vendor range, as documented in the description of
431  * #psa_key_id_t.
432  *
433  * The application must eventually close the handle with psa_close_key() or
434  * psa_destroy_key() to release associated resources. If the application dies
435  * without calling one of these functions, the implementation should perform
436  * the equivalent of a call to psa_close_key().
437  *
438  * Some implementations permit an application to open the same key multiple
439  * times. If this is successful, each call to psa_open_key() will return a
440  * different key handle.
441  *
442  * \note This API is not part of the PSA Cryptography API Release 1.0.0
443  * specification. It was defined in the 1.0 Beta 3 version of the
444  * specification but was removed in the 1.0.0 released version. This API is
445  * kept for the time being to not break applications relying on it. It is not
446  * deprecated yet but will be in the near future.
447  *
448  * \note Applications that rely on opening a key multiple times will not be
449  * portable to implementations that only permit a single key handle to be
450  * opened. See also :ref:\`key-handles\`.
451  *
452  *
453  * \param key The persistent identifier of the key.
454  * \param[out] handle On success, a handle to the key.
455  *
456  * \retval #PSA_SUCCESS
457  * Success. The application can now use the value of `*handle`
458  * to access the key.
459  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
460  * The implementation does not have sufficient resources to open the
461  * key. This can be due to reaching an implementation limit on the
462  * number of open keys, the number of open key handles, or available
463  * memory.
464  * \retval #PSA_ERROR_DOES_NOT_EXIST
465  * There is no persistent key with key identifier \p key.
466  * \retval #PSA_ERROR_INVALID_ARGUMENT
467  * \p key is not a valid persistent key identifier.
468  * \retval #PSA_ERROR_NOT_PERMITTED
469  * The specified key exists, but the application does not have the
470  * permission to access it. Note that this specification does not
471  * define any way to create such a key, but it may be possible
472  * through implementation-specific means.
473  * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
474  * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
475  * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
476  * \retval #PSA_ERROR_DATA_INVALID \emptydescription
477  * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
478  * \retval #PSA_ERROR_BAD_STATE
479  * The library has not been previously initialized by psa_crypto_init().
480  * It is implementation-dependent whether a failure to initialize
481  * results in this error code.
482  */
484  psa_key_handle_t *handle);
485 
486 /** Close a key handle.
487  *
488  * If the handle designates a volatile key, this will destroy the key material
489  * and free all associated resources, just like psa_destroy_key().
490  *
491  * If this is the last open handle to a persistent key, then closing the handle
492  * will free all resources associated with the key in volatile memory. The key
493  * data in persistent storage is not affected and can be opened again later
494  * with a call to psa_open_key().
495  *
496  * Closing the key handle makes the handle invalid, and the key handle
497  * must not be used again by the application.
498  *
499  * \note This API is not part of the PSA Cryptography API Release 1.0.0
500  * specification. It was defined in the 1.0 Beta 3 version of the
501  * specification but was removed in the 1.0.0 released version. This API is
502  * kept for the time being to not break applications relying on it. It is not
503  * deprecated yet but will be in the near future.
504  *
505  * \note If the key handle was used to set up an active
506  * :ref:\`multipart operation <multipart-operations>\`, then closing the
507  * key handle can cause the multipart operation to fail. Applications should
508  * maintain the key handle until after the multipart operation has finished.
509  *
510  * \param handle The key handle to close.
511  * If this is \c 0, do nothing and return \c PSA_SUCCESS.
512  *
513  * \retval #PSA_SUCCESS
514  * \p handle was a valid handle or \c 0. It is now closed.
515  * \retval #PSA_ERROR_INVALID_HANDLE
516  * \p handle is not a valid handle nor \c 0.
517  * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
518  * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
519  * \retval #PSA_ERROR_BAD_STATE
520  * The library has not been previously initialized by psa_crypto_init().
521  * It is implementation-dependent whether a failure to initialize
522  * results in this error code.
523  */
525 
526 #ifdef __cplusplus
527 }
528 #endif
529 
530 #endif /* PSA_CRYPTO_COMPAT_H */
mbedtls_svc_key_id_t psa_key_handle_t
Definition: crypto_compat.h:43
psa_algorithm_t mbedtls_deprecated_psa_algorithm_t
Definition: crypto_compat.h:76
psa_key_usage_t mbedtls_deprecated_psa_key_usage_t
Definition: crypto_compat.h:71
#define MBEDTLS_PSA_DEPRECATED
Definition: crypto_compat.h:66
psa_ecc_family_t psa_ecc_curve_t
Definition: crypto_compat.h:74
psa_status_t mbedtls_deprecated_psa_status_t
Definition: crypto_compat.h:70
psa_dh_family_t psa_dh_group_t
Definition: crypto_compat.h:75
static psa_status_t 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)
psa_status_t psa_open_key(mbedtls_svc_key_id_t key, psa_key_handle_t *handle)
Open a handle to an existing persistent key.
psa_status_t psa_close_key(psa_key_handle_t handle)
Close a key handle.
psa_ecc_family_t mbedtls_deprecated_psa_ecc_family_t
Definition: crypto_compat.h:72
static int psa_key_handle_is_null(psa_key_handle_t handle)
Check whether a handle is null.
Definition: crypto_compat.h:53
psa_dh_family_t mbedtls_deprecated_psa_dh_family_t
Definition: crypto_compat.h:73
static psa_status_t 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)
size_t mbedtls_deprecated_size_t
Definition: crypto_compat.h:69
unsigned char uint8_t
psa_status_t psa_sign_hash(mbedtls_svc_key_id_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)
Sign a hash or short message with a private key.
psa_status_t psa_verify_hash(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, const uint8_t *signature, size_t signature_length)
Verify the signature of a hash or short message using a public key.
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
Definition: crypto_types.h:137
uint8_t psa_ecc_family_t
The type of PSA elliptic curve family identifiers.
Definition: crypto_types.h:100
uint8_t psa_dh_family_t
The type of PSA Diffie-Hellman group family identifiers.
Definition: crypto_types.h:119
int32_t psa_status_t
Function return status.
Definition: crypto_types.h:62
static int mbedtls_svc_key_id_is_null(mbedtls_svc_key_id_t key)
Check whether a key identifier is null.
psa_key_id_t mbedtls_svc_key_id_t
Encoding of key identifiers as seen inside the PSA Crypto implementation.
Definition: crypto_types.h:295
uint32_t psa_key_usage_t
Encoding of permitted usage on a key.
Definition: crypto_types.h:326
const struct ncbi::grid::netcache::search::fields::KEY key
Definition: _hash_fun.h:40
Modified on Sun Apr 14 05:29:42 2024 by modify_doxy.py rev. 669887