Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
TARGET_TFM/TARGET_TFM_LATEST/include/psa/crypto_compat.h
1 /*
2  * Copyright (c) 2019-2021, Arm Limited. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  */
7 /**
8  * \file psa/crypto_compat.h
9  *
10  * \brief PSA cryptography module: Backward compatibility aliases
11  *
12  * This header declares alternative names for macro and functions.
13  * New application code should not use these names.
14  * These names may be removed in a future version of Mbed Crypto.
15  *
16  * \note This file may not be included directly. Applications must
17  * include psa/crypto.h.
18  */
19 
20 #ifndef PSA_CRYPTO_COMPAT_H
21 #define PSA_CRYPTO_COMPAT_H
22 
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26 
27 /*
28  * To support both openless APIs and psa_open_key() temporarily, define
29  * psa_key_handle_t to be equal to psa_key_id_t. Do not mark the
30  * type and its utility macros and functions deprecated yet. This will be done
31  * in a subsequent phase.
32  */
33 typedef psa_key_id_t psa_key_handle_t;
34 
35 /** Check whether an handle is null.
36  *
37  * \param handle Handle
38  *
39  * \return Non-zero if the handle is null, zero otherwise.
40  */
41 static inline int psa_key_handle_is_null(psa_key_handle_t handle)
42 {
43  return(handle == 0);
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 
102 /*
103  * Deprecated PSA Crypto function names (PSA Crypto API <= 1.0 beta3)
104  */
105 MBEDTLS_PSA_DEPRECATED psa_status_t psa_asymmetric_sign( psa_key_handle_t key,
106  psa_algorithm_t alg,
107  const uint8_t *hash,
108  size_t hash_length,
109  uint8_t *signature,
110  size_t signature_size,
111  size_t *signature_length );
112 
113 MBEDTLS_PSA_DEPRECATED psa_status_t psa_asymmetric_verify( psa_key_handle_t key,
114  psa_algorithm_t alg,
115  const uint8_t *hash,
116  size_t hash_length,
117  const uint8_t *signature,
118  size_t signature_length );
119 
120 
121 /*
122  * Size-specific elliptic curve families.
123  */
124 #define PSA_ECC_CURVE_SECP160K1 \
125  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1 )
126 #define PSA_ECC_CURVE_SECP192K1 \
127  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1 )
128 #define PSA_ECC_CURVE_SECP224K1 \
129  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1 )
130 #define PSA_ECC_CURVE_SECP256K1 \
131  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1 )
132 #define PSA_ECC_CURVE_SECP160R1 \
133  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
134 #define PSA_ECC_CURVE_SECP192R1 \
135  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
136 #define PSA_ECC_CURVE_SECP224R1 \
137  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
138 #define PSA_ECC_CURVE_SECP256R1 \
139  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
140 #define PSA_ECC_CURVE_SECP384R1 \
141  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
142 #define PSA_ECC_CURVE_SECP521R1 \
143  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
144 #define PSA_ECC_CURVE_SECP160R2 \
145  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R2 )
146 #define PSA_ECC_CURVE_SECT163K1 \
147  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
148 #define PSA_ECC_CURVE_SECT233K1 \
149  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
150 #define PSA_ECC_CURVE_SECT239K1 \
151  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
152 #define PSA_ECC_CURVE_SECT283K1 \
153  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
154 #define PSA_ECC_CURVE_SECT409K1 \
155  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
156 #define PSA_ECC_CURVE_SECT571K1 \
157  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
158 #define PSA_ECC_CURVE_SECT163R1 \
159  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
160 #define PSA_ECC_CURVE_SECT193R1 \
161  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
162 #define PSA_ECC_CURVE_SECT233R1 \
163  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
164 #define PSA_ECC_CURVE_SECT283R1 \
165  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
166 #define PSA_ECC_CURVE_SECT409R1 \
167  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
168 #define PSA_ECC_CURVE_SECT571R1 \
169  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
170 #define PSA_ECC_CURVE_SECT163R2 \
171  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R2 )
172 #define PSA_ECC_CURVE_SECT193R2 \
173  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R2 )
174 #define PSA_ECC_CURVE_BRAINPOOL_P256R1 \
175  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_BRAINPOOL_P_R1 )
176 #define PSA_ECC_CURVE_BRAINPOOL_P384R1 \
177  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_BRAINPOOL_P_R1 )
178 #define PSA_ECC_CURVE_BRAINPOOL_P512R1 \
179  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_BRAINPOOL_P_R1 )
180 #define PSA_ECC_CURVE_CURVE25519 \
181  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_MONTGOMERY )
182 #define PSA_ECC_CURVE_CURVE448 \
183  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_MONTGOMERY )
184 
185 /*
186  * Curves that changed name due to PSA specification.
187  */
188 #define PSA_ECC_CURVE_SECP_K1 \
189  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1 )
190 #define PSA_ECC_CURVE_SECP_R1 \
191  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
192 #define PSA_ECC_CURVE_SECP_R2 \
193  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R2 )
194 #define PSA_ECC_CURVE_SECT_K1 \
195  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
196 #define PSA_ECC_CURVE_SECT_R1 \
197  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
198 #define PSA_ECC_CURVE_SECT_R2 \
199  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R2 )
200 #define PSA_ECC_CURVE_BRAINPOOL_P_R1 \
201  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_BRAINPOOL_P_R1 )
202 #define PSA_ECC_CURVE_MONTGOMERY \
203  MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_MONTGOMERY )
204 
205 /*
206  * Finite-field Diffie-Hellman families.
207  */
208 #define PSA_DH_GROUP_FFDHE2048 \
209  MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
210 #define PSA_DH_GROUP_FFDHE3072 \
211  MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
212 #define PSA_DH_GROUP_FFDHE4096 \
213  MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
214 #define PSA_DH_GROUP_FFDHE6144 \
215  MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
216 #define PSA_DH_GROUP_FFDHE8192 \
217  MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
218 
219 /*
220  * Diffie-Hellman families that changed name due to PSA specification.
221  */
222 #define PSA_DH_GROUP_RFC7919 \
223  MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
224 #define PSA_DH_GROUP_CUSTOM \
225  MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_CUSTOM )
226 
227 /*
228  * Deprecated PSA Crypto stream cipher algorithms (PSA Crypto API <= 1.0 beta3)
229  */
230 #define PSA_ALG_ARC4 \
231  MBEDTLS_DEPRECATED_CONSTANT(psa_algorithm_t, PSA_ALG_STREAM_CIPHER)
232 #define PSA_ALG_CHACHA20 \
233  MBEDTLS_DEPRECATED_CONSTANT(psa_algorithm_t, PSA_ALG_STREAM_CIPHER)
234 
235 #endif /* MBEDTLS_DEPRECATED_REMOVED */
236 
237 /** Open a handle to an existing persistent key.
238  *
239  * Open a handle to a persistent key. A key is persistent if it was created
240  * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
241  * always has a nonzero key identifier, set with psa_set_key_id() when
242  * creating the key. Implementations may provide additional pre-provisioned
243  * keys that can be opened with psa_open_key(). Such keys have an application
244  * key identifier in the vendor range, as documented in the description of
245  * #psa_key_id_t.
246  *
247  * The application must eventually close the handle with psa_close_key() or
248  * psa_destroy_key() to release associated resources. If the application dies
249  * without calling one of these functions, the implementation should perform
250  * the equivalent of a call to psa_close_key().
251  *
252  * Some implementations permit an application to open the same key multiple
253  * times. If this is successful, each call to psa_open_key() will return a
254  * different key handle.
255  *
256  * \note This API is not part of the PSA Cryptography API Release 1.0.0
257  * specification. It was defined in the 1.0 Beta 3 version of the
258  * specification but was removed in the 1.0.0 released version. This API is
259  * kept for the time being to not break applications relying on it. It is not
260  * deprecated yet but will be in the near future.
261  *
262  * \note Applications that rely on opening a key multiple times will not be
263  * portable to implementations that only permit a single key handle to be
264  * opened. See also :ref:\`key-handles\`.
265  *
266  *
267  * \param id The persistent identifier of the key.
268  * \param[out] key On success, a handle to the key.
269  *
270  * \retval #PSA_SUCCESS
271  * Success. The application can now use the value of `*handle`
272  * to access the key.
273  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
274  * The implementation does not have sufficient resources to open the
275  * key. This can be due to reaching an implementation limit on the
276  * number of open keys, the number of open key handles, or available
277  * memory.
278  * \retval #PSA_ERROR_DOES_NOT_EXIST
279  * There is no persistent key with key identifier \p id.
280  * \retval #PSA_ERROR_INVALID_ARGUMENT
281  * \p id is not a valid persistent key identifier.
282  * \retval #PSA_ERROR_NOT_PERMITTED
283  * The specified key exists, but the application does not have the
284  * permission to access it. Note that this specification does not
285  * define any way to create such a key, but it may be possible
286  * through implementation-specific means.
287  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
288  * \retval #PSA_ERROR_CORRUPTION_DETECTED
289  * \retval #PSA_ERROR_STORAGE_FAILURE
290  * \retval #PSA_ERROR_BAD_STATE
291  * The library has not been previously initialized by psa_crypto_init().
292  * It is implementation-dependent whether a failure to initialize
293  * results in this error code.
294  */
295 psa_status_t psa_open_key(psa_key_id_t id,
296  psa_key_id_t *key);
297 
298 /** Close a key handle.
299  *
300  * If the handle designates a volatile key, this will destroy the key material
301  * and free all associated resources, just like psa_destroy_key().
302  *
303  * If this is the last open handle to a persistent key, then closing the handle
304  * will free all resources associated with the key in volatile memory. The key
305  * data in persistent storage is not affected and can be opened again later
306  * with a call to psa_open_key().
307  *
308  * Closing the key handle makes the handle invalid, and the key handle
309  * must not be used again by the application.
310  *
311  * \note This API is not part of the PSA Cryptography API Release 1.0.0
312  * specification. It was defined in the 1.0 Beta 3 version of the
313  * specification but was removed in the 1.0.0 released version. This API is
314  * kept for the time being to not break applications relying on it. It is not
315  * deprecated yet but will be in the near future.
316  *
317  * \note If the key handle was used to set up an active
318  * :ref:\`multipart operation <multipart-operations>\`, then closing the
319  * key handle can cause the multipart operation to fail. Applications should
320  * maintain the key handle until after the multipart operation has finished.
321  *
322  * \param key The key to close.
323  * If this is \c 0, do nothing and return \c PSA_SUCCESS.
324  *
325  * \retval #PSA_SUCCESS
326  * \p handle was a valid handle or \c 0. It is now closed.
327  * \retval #PSA_ERROR_INVALID_HANDLE
328  * \p handle is not a valid handle nor \c 0.
329  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
330  * \retval #PSA_ERROR_CORRUPTION_DETECTED
331  * \retval #PSA_ERROR_BAD_STATE
332  * The library has not been previously initialized by psa_crypto_init().
333  * It is implementation-dependent whether a failure to initialize
334  * results in this error code.
335  */
336 psa_status_t psa_close_key(psa_key_id_t key);
337 
338 #ifdef __cplusplus
339 }
340 #endif
341 
342 #endif /* PSA_CRYPTO_COMPAT_H */
psa_close_key
psa_status_t psa_close_key(psa_key_handle_t handle)
Close a key handle.
psa_ecc_curve_t
uint16_t psa_ecc_curve_t
The type of PSA elliptic curve identifiers.
Definition: TARGET_TFM/TARGET_TFM_V1_0/include/psa/crypto_types.h:91
psa_key_id_t
uint32_t psa_key_id_t
Encoding of identifiers of persistent keys.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:231
psa_dh_family_t
uint8_t psa_dh_family_t
The type of PSA Diffie-Hellman group family identifiers.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:88
psa_dh_group_t
uint16_t psa_dh_group_t
The type of PSA Diffie-Hellman group identifiers.
Definition: TARGET_TFM/TARGET_TFM_V1_0/include/psa/crypto_types.h:143
psa_algorithm_t
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:98
psa_key_usage_t
uint32_t psa_key_usage_t
Encoding of permitted usage on a key.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:257
psa_open_key
psa_status_t psa_open_key(psa_key_id_t id, psa_key_handle_t *handle)
Open a handle to an existing persistent key.
psa_ecc_family_t
uint8_t psa_ecc_family_t
The type of PSA elliptic curve family identifiers.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:77
psa_status_t
int32_t psa_status_t
Function return status.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:55
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.