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 a 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 /** Open a handle to an existing persistent key.
59 *
60 * Open a handle to a persistent key. A key is persistent if it was created
61 * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
62 * always has a nonzero key identifier, set with psa_set_key_id() when
63 * creating the key. Implementations may provide additional pre-provisioned
64 * keys that can be opened with psa_open_key(). Such keys have an application
65 * key identifier in the vendor range, as documented in the description of
66 * #psa_key_id_t.
67 *
68 * The application must eventually close the handle with psa_close_key() or
69 * psa_destroy_key() to release associated resources. If the application dies
70 * without calling one of these functions, the implementation should perform
71 * the equivalent of a call to psa_close_key().
72 *
73 * Some implementations permit an application to open the same key multiple
74 * times. If this is successful, each call to psa_open_key() will return a
75 * different key handle.
76 *
77 * \note This API is not part of the PSA Cryptography API Release 1.0.0
78 * specification. It was defined in the 1.0 Beta 3 version of the
79 * specification but was removed in the 1.0.0 released version. This API is
80 * kept for the time being to not break applications relying on it. It is not
81 * deprecated yet but will be in the near future.
82 *
83 * \note Applications that rely on opening a key multiple times will not be
84 * portable to implementations that only permit a single key handle to be
85 * opened. See also :ref:\`key-handles\`.
86 *
87 *
88 * \param key The persistent identifier of the key.
89 * \param[out] handle On success, a handle to the key.
90 *
91 * \retval #PSA_SUCCESS
92 * Success. The application can now use the value of `*handle`
93 * to access the key.
94 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
95 * The implementation does not have sufficient resources to open the
96 * key. This can be due to reaching an implementation limit on the
97 * number of open keys, the number of open key handles, or available
98 * memory.
99 * \retval #PSA_ERROR_DOES_NOT_EXIST
100 * There is no persistent key with key identifier \p key.
101 * \retval #PSA_ERROR_INVALID_ARGUMENT
102 * \p key is not a valid persistent key identifier.
103 * \retval #PSA_ERROR_NOT_PERMITTED
104 * The specified key exists, but the application does not have the
105 * permission to access it. Note that this specification does not
106 * define any way to create such a key, but it may be possible
107 * through implementation-specific means.
108 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
109 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
110 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
111 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
112 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
113 * \retval #PSA_ERROR_BAD_STATE
114 * The library has not been previously initialized by psa_crypto_init().
115 * It is implementation-dependent whether a failure to initialize
116 * results in this error code.
117 */
118 psa_status_t psa_open_key(mbedtls_svc_key_id_t key,
119 psa_key_handle_t *handle);
120
121 /** Close a key handle.
122 *
123 * If the handle designates a volatile key, this will destroy the key material
124 * and free all associated resources, just like psa_destroy_key().
125 *
126 * If this is the last open handle to a persistent key, then closing the handle
127 * will free all resources associated with the key in volatile memory. The key
128 * data in persistent storage is not affected and can be opened again later
129 * with a call to psa_open_key().
130 *
131 * Closing the key handle makes the handle invalid, and the key handle
132 * must not be used again by the application.
133 *
134 * \note This API is not part of the PSA Cryptography API Release 1.0.0
135 * specification. It was defined in the 1.0 Beta 3 version of the
136 * specification but was removed in the 1.0.0 released version. This API is
137 * kept for the time being to not break applications relying on it. It is not
138 * deprecated yet but will be in the near future.
139 *
140 * \note If the key handle was used to set up an active
141 * :ref:\`multipart operation <multipart-operations>\`, then closing the
142 * key handle can cause the multipart operation to fail. Applications should
143 * maintain the key handle until after the multipart operation has finished.
144 *
145 * \param handle The key handle to close.
146 * If this is \c 0, do nothing and return \c PSA_SUCCESS.
147 *
148 * \retval #PSA_SUCCESS
149 * \p handle was a valid handle or \c 0. It is now closed.
150 * \retval #PSA_ERROR_INVALID_HANDLE
151 * \p handle is not a valid handle nor \c 0.
152 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
153 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
154 * \retval #PSA_ERROR_BAD_STATE
155 * The library has not been previously initialized by psa_crypto_init().
156 * It is implementation-dependent whether a failure to initialize
157 * results in this error code.
158 */
159 psa_status_t psa_close_key(psa_key_handle_t handle);
160
161 #ifdef __cplusplus
162 }
163 #endif
164
165 #endif /* PSA_CRYPTO_COMPAT_H */
166