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 /** 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 id The persistent identifier of the key.
77  * \param[out] key 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 id.
89  * \retval #PSA_ERROR_INVALID_ARGUMENT
90  * \p id 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
97  * \retval #PSA_ERROR_CORRUPTION_DETECTED
98  * \retval #PSA_ERROR_STORAGE_FAILURE
99  * \retval #PSA_ERROR_DATA_INVALID
100  * \retval #PSA_ERROR_DATA_CORRUPT
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  */
107  psa_key_id_t *key);
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 key The key 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
141  * \retval #PSA_ERROR_CORRUPTION_DETECTED
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  */
148 
149 #ifdef __cplusplus
150 }
151 #endif
152 
153 #endif /* PSA_CRYPTO_COMPAT_H */
psa_status_t psa_close_key(psa_key_handle_t handle)
Close a key handle.
uint32_t psa_key_id_t
Encoding of identifiers of persistent keys.
psa_status_t psa_open_key(psa_key_id_t id, psa_key_handle_t *handle)
Open a handle to an existing persistent key.
int32_t psa_status_t
Function return status.
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.