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