Branch data Line data Source code
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 : : */
41 : 0 : static inline int psa_key_handle_is_null(psa_key_handle_t handle)
42 : : {
43 : 0 : return mbedtls_svc_key_id_is_null(handle);
44 : : }
45 : :
46 : : /** Open a handle to an existing persistent key.
47 : : *
48 : : * Open a handle to a persistent key. A key is persistent if it was created
49 : : * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
50 : : * always has a nonzero key identifier, set with psa_set_key_id() when
51 : : * creating the key. Implementations may provide additional pre-provisioned
52 : : * keys that can be opened with psa_open_key(). Such keys have an application
53 : : * key identifier in the vendor range, as documented in the description of
54 : : * #psa_key_id_t.
55 : : *
56 : : * The application must eventually close the handle with psa_close_key() or
57 : : * psa_destroy_key() to release associated resources. If the application dies
58 : : * without calling one of these functions, the implementation should perform
59 : : * the equivalent of a call to psa_close_key().
60 : : *
61 : : * Some implementations permit an application to open the same key multiple
62 : : * times. If this is successful, each call to psa_open_key() will return a
63 : : * different key handle.
64 : : *
65 : : * \note This API is not part of the PSA Cryptography API Release 1.0.0
66 : : * specification. It was defined in the 1.0 Beta 3 version of the
67 : : * specification but was removed in the 1.0.0 released version. This API is
68 : : * kept for the time being to not break applications relying on it. It is not
69 : : * deprecated yet but will be in the near future.
70 : : *
71 : : * \note Applications that rely on opening a key multiple times will not be
72 : : * portable to implementations that only permit a single key handle to be
73 : : * opened. See also :ref:\`key-handles\`.
74 : : *
75 : : *
76 : : * \param key The persistent identifier of the key.
77 : : * \param[out] handle On success, a handle to the key.
78 : : *
79 : : * \retval #PSA_SUCCESS
80 : : * Success. The application can now use the value of `*handle`
81 : : * to access the key.
82 : : * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
83 : : * The implementation does not have sufficient resources to open the
84 : : * key. This can be due to reaching an implementation limit on the
85 : : * number of open keys, the number of open key handles, or available
86 : : * memory.
87 : : * \retval #PSA_ERROR_DOES_NOT_EXIST
88 : : * There is no persistent key with key identifier \p key.
89 : : * \retval #PSA_ERROR_INVALID_ARGUMENT
90 : : * \p key is not a valid persistent key identifier.
91 : : * \retval #PSA_ERROR_NOT_PERMITTED
92 : : * The specified key exists, but the application does not have the
93 : : * permission to access it. Note that this specification does not
94 : : * define any way to create such a key, but it may be possible
95 : : * through implementation-specific means.
96 : : * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
97 : : * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
98 : : * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
99 : : * \retval #PSA_ERROR_DATA_INVALID \emptydescription
100 : : * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
101 : : * \retval #PSA_ERROR_BAD_STATE
102 : : * The library has not been previously initialized by psa_crypto_init().
103 : : * It is implementation-dependent whether a failure to initialize
104 : : * results in this error code.
105 : : */
106 : : psa_status_t psa_open_key(mbedtls_svc_key_id_t key,
107 : : psa_key_handle_t *handle);
108 : :
109 : : /** Close a key handle.
110 : : *
111 : : * If the handle designates a volatile key, this will destroy the key material
112 : : * and free all associated resources, just like psa_destroy_key().
113 : : *
114 : : * If this is the last open handle to a persistent key, then closing the handle
115 : : * will free all resources associated with the key in volatile memory. The key
116 : : * data in persistent storage is not affected and can be opened again later
117 : : * with a call to psa_open_key().
118 : : *
119 : : * Closing the key handle makes the handle invalid, and the key handle
120 : : * must not be used again by the application.
121 : : *
122 : : * \note This API is not part of the PSA Cryptography API Release 1.0.0
123 : : * specification. It was defined in the 1.0 Beta 3 version of the
124 : : * specification but was removed in the 1.0.0 released version. This API is
125 : : * kept for the time being to not break applications relying on it. It is not
126 : : * deprecated yet but will be in the near future.
127 : : *
128 : : * \note If the key handle was used to set up an active
129 : : * :ref:\`multipart operation <multipart-operations>\`, then closing the
130 : : * key handle can cause the multipart operation to fail. Applications should
131 : : * maintain the key handle until after the multipart operation has finished.
132 : : *
133 : : * \param handle The key handle to close.
134 : : * If this is \c 0, do nothing and return \c PSA_SUCCESS.
135 : : *
136 : : * \retval #PSA_SUCCESS
137 : : * \p handle was a valid handle or \c 0. It is now closed.
138 : : * \retval #PSA_ERROR_INVALID_HANDLE
139 : : * \p handle is not a valid handle nor \c 0.
140 : : * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
141 : : * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
142 : : * \retval #PSA_ERROR_BAD_STATE
143 : : * The library has not been previously initialized by psa_crypto_init().
144 : : * It is implementation-dependent whether a failure to initialize
145 : : * results in this error code.
146 : : */
147 : : psa_status_t psa_close_key(psa_key_handle_t handle);
148 : :
149 : : /** \addtogroup attributes
150 : : * @{
151 : : */
152 : :
153 : : #if !defined(MBEDTLS_DEPRECATED_REMOVED)
154 : : /** Custom Diffie-Hellman group.
155 : : *
156 : : * Mbed TLS does not support custom DH groups.
157 : : *
158 : : * \deprecated This value is not useful, so this macro will be removed in
159 : : * a future version of the library.
160 : : */
161 : : #define PSA_DH_FAMILY_CUSTOM \
162 : : ((psa_dh_family_t) MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(0x7e))
163 : :
164 : : /**
165 : : * \brief Set domain parameters for a key.
166 : : *
167 : : * \deprecated Mbed TLS no longer supports any domain parameters.
168 : : * This function only does the equivalent of
169 : : * psa_set_key_type() and will be removed in a future version
170 : : * of the library.
171 : : *
172 : : * \param[in,out] attributes Attribute structure where \p type will be set.
173 : : * \param type Key type (a \c PSA_KEY_TYPE_XXX value).
174 : : * \param[in] data Ignored.
175 : : * \param data_length Must be 0.
176 : : *
177 : : * \retval #PSA_SUCCESS \emptydescription
178 : : * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
179 : : */
180 : : static inline psa_status_t MBEDTLS_DEPRECATED psa_set_key_domain_parameters(
181 : : psa_key_attributes_t *attributes,
182 : : psa_key_type_t type, const uint8_t *data, size_t data_length)
183 : : {
184 : : (void) data;
185 : : if (data_length != 0) {
186 : : return PSA_ERROR_NOT_SUPPORTED;
187 : : }
188 : : psa_set_key_type(attributes, type);
189 : : return PSA_SUCCESS;
190 : : }
191 : :
192 : : /**
193 : : * \brief Get domain parameters for a key.
194 : : *
195 : : * \deprecated Mbed TLS no longer supports any domain parameters.
196 : : * This function alwaya has an empty output and will be
197 : : * removed in a future version of the library.
198 : :
199 : : * \param[in] attributes Ignored.
200 : : * \param[out] data Ignored.
201 : : * \param data_size Ignored.
202 : : * \param[out] data_length Set to 0.
203 : : *
204 : : * \retval #PSA_SUCCESS \emptydescription
205 : : */
206 : : static inline psa_status_t MBEDTLS_DEPRECATED psa_get_key_domain_parameters(
207 : : const psa_key_attributes_t *attributes,
208 : : uint8_t *data, size_t data_size, size_t *data_length)
209 : : {
210 : : (void) attributes;
211 : : (void) data;
212 : : (void) data_size;
213 : : *data_length = 0;
214 : : return PSA_SUCCESS;
215 : : }
216 : :
217 : : /** Safe output buffer size for psa_get_key_domain_parameters().
218 : : *
219 : : */
220 : : #define PSA_KEY_DOMAIN_PARAMETERS_SIZE(key_type, key_bits) \
221 : : MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(1u)
222 : : #endif /* MBEDTLS_DEPRECATED_REMOVED */
223 : :
224 : : /**@}*/
225 : :
226 : : #ifdef __cplusplus
227 : : }
228 : : #endif
229 : :
230 : : #endif /* PSA_CRYPTO_COMPAT_H */
|
