/src/mbedtls/include/psa/crypto_compat.h

Source (jump to first uncovered line)
/**
 * \file psa/crypto_compat.h
 *
 * \brief PSA cryptography module: Backward compatibility aliases
 *
 * This header declares alternative names for macro and functions.
 * New application code should not use these names.
 * These names may be removed in a future version of Mbed TLS.
 *
 * \note This file may not be included directly. Applications must
 * include psa/crypto.h.
 */
/*
 *  Copyright The Mbed TLS Contributors
 *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
 */

#ifndef PSA_CRYPTO_COMPAT_H
#define PSA_CRYPTO_COMPAT_H

#ifdef __cplusplus
extern "C" {
#endif

/*
 * To support both openless APIs and psa_open_key() temporarily, define
 * psa_key_handle_t to be equal to mbedtls_svc_key_id_t. Do not mark the
 * type and its utility macros and functions deprecated yet. This will be done
 * in a subsequent phase.
 */
typedef mbedtls_svc_key_id_t psa_key_handle_t;

#define PSA_KEY_HANDLE_INIT MBEDTLS_SVC_KEY_ID_INIT

/** Check whether a handle is null.
 *
 * \param handle  Handle
 *
 * \return Non-zero if the handle is null, zero otherwise.
 */
static inline int psa_key_handle_is_null(psa_key_handle_t handle)
{
    return mbedtls_svc_key_id_is_null(handle);
}

/** Open a handle to an existing persistent key.
 *
 * Open a handle to a persistent key. A key is persistent if it was created
 * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
 * always has a nonzero key identifier, set with psa_set_key_id() when
 * creating the key. Implementations may provide additional pre-provisioned
 * keys that can be opened with psa_open_key(). Such keys have an application
 * key identifier in the vendor range, as documented in the description of
 * #psa_key_id_t.
 *
 * The application must eventually close the handle with psa_close_key() or
 * psa_destroy_key() to release associated resources. If the application dies
 * without calling one of these functions, the implementation should perform
 * the equivalent of a call to psa_close_key().
 *
 * Some implementations permit an application to open the same key multiple
 * times. If this is successful, each call to psa_open_key() will return a
 * different key handle.
 *
 * \note This API is not part of the PSA Cryptography API Release 1.0.0
 * specification. It was defined in the 1.0 Beta 3 version of the
 * specification but was removed in the 1.0.0 released version. This API is
 * kept for the time being to not break applications relying on it. It is not
 * deprecated yet but will be in the near future.
 *
 * \note Applications that rely on opening a key multiple times will not be
 * portable to implementations that only permit a single key handle to be
 * opened. See also :ref:\`key-handles\`.
 *
 *
 * \param key           The persistent identifier of the key.
 * \param[out] handle   On success, a handle to the key.
 *
 * \retval #PSA_SUCCESS
 *         Success. The application can now use the value of `*handle`
 *         to access the key.
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
 *         The implementation does not have sufficient resources to open the
 *         key. This can be due to reaching an implementation limit on the
 *         number of open keys, the number of open key handles, or available
 *         memory.
 * \retval #PSA_ERROR_DOES_NOT_EXIST
 *         There is no persistent key with key identifier \p key.
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         \p key is not a valid persistent key identifier.
 * \retval #PSA_ERROR_NOT_PERMITTED
 *         The specified key exists, but the application does not have the
 *         permission to access it. Note that this specification does not
 *         define any way to create such a key, but it may be possible
 *         through implementation-specific means.
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
 * \retval #PSA_ERROR_BAD_STATE
 *         The library has not been previously initialized by psa_crypto_init().
 *         It is implementation-dependent whether a failure to initialize
 *         results in this error code.
 */
psa_status_t psa_open_key(mbedtls_svc_key_id_t key,
                          psa_key_handle_t *handle);

/** Close a key handle.
 *
 * If the handle designates a volatile key, this will destroy the key material
 * and free all associated resources, just like psa_destroy_key().
 *
 * If this is the last open handle to a persistent key, then closing the handle
 * will free all resources associated with the key in volatile memory. The key
 * data in persistent storage is not affected and can be opened again later
 * with a call to psa_open_key().
 *
 * Closing the key handle makes the handle invalid, and the key handle
 * must not be used again by the application.
 *
 * \note This API is not part of the PSA Cryptography API Release 1.0.0
 * specification. It was defined in the 1.0 Beta 3 version of the
 * specification but was removed in the 1.0.0 released version. This API is
 * kept for the time being to not break applications relying on it. It is not
 * deprecated yet but will be in the near future.
 *
 * \note If the key handle was used to set up an active
 * :ref:\`multipart operation <multipart-operations>\`, then closing the
 * key handle can cause the multipart operation to fail. Applications should
 * maintain the key handle until after the multipart operation has finished.
 *
 * \param handle        The key handle to close.
 *                      If this is \c 0, do nothing and return \c PSA_SUCCESS.
 *
 * \retval #PSA_SUCCESS
 *         \p handle was a valid handle or \c 0. It is now closed.
 * \retval #PSA_ERROR_INVALID_HANDLE
 *         \p handle is not a valid handle nor \c 0.
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
 * \retval #PSA_ERROR_BAD_STATE
 *         The library has not been previously initialized by psa_crypto_init().
 *         It is implementation-dependent whether a failure to initialize
 *         results in this error code.
 */
psa_status_t psa_close_key(psa_key_handle_t handle);

/** \addtogroup attributes
 * @{
 */

#if !defined(MBEDTLS_DEPRECATED_REMOVED)
/** Custom Diffie-Hellman group.
 *
 * Mbed TLS does not support custom DH groups.
 *
 * \deprecated This value is not useful, so this macro will be removed in
 *             a future version of the library.
 */
#define PSA_DH_FAMILY_CUSTOM                                            \
    ((psa_dh_family_t) MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(0x7e))

/**
 * \brief Set domain parameters for a key.
 *
 * \deprecated  Mbed TLS no longer supports any domain parameters.
 *              This function only does the equivalent of
 *              psa_set_key_type() and will be removed in a future version
 *              of the library.
 *
 * \param[in,out] attributes    Attribute structure where \p type will be set.
 * \param type                  Key type (a \c PSA_KEY_TYPE_XXX value).
 * \param[in] data              Ignored.
 * \param data_length           Must be 0.
 *
 * \retval #PSA_SUCCESS \emptydescription
 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
 */
static inline psa_status_t MBEDTLS_DEPRECATED psa_set_key_domain_parameters(
    psa_key_attributes_t *attributes,
    psa_key_type_t type, const uint8_t *data, size_t data_length)
{
    (void) data;
    if (data_length != 0) {
        return PSA_ERROR_NOT_SUPPORTED;
    }
    psa_set_key_type(attributes, type);
    return PSA_SUCCESS;
}

/**
 * \brief Get domain parameters for a key.
 *
 * \deprecated  Mbed TLS no longer supports any domain parameters.
 *              This function alwaya has an empty output and will be
 *              removed in a future version of the library.

 * \param[in] attributes        Ignored.
 * \param[out] data             Ignored.
 * \param data_size             Ignored.
 * \param[out] data_length      Set to 0.
 *
 * \retval #PSA_SUCCESS \emptydescription
 */
static inline psa_status_t MBEDTLS_DEPRECATED psa_get_key_domain_parameters(
    const psa_key_attributes_t *attributes,
    uint8_t *data, size_t data_size, size_t *data_length)
{
    (void) attributes;
    (void) data;
    (void) data_size;
    *data_length = 0;
    return PSA_SUCCESS;
}

/** Safe output buffer size for psa_get_key_domain_parameters().
 *
 */
#define PSA_KEY_DOMAIN_PARAMETERS_SIZE(key_type, key_bits)      \
    MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(1u)
#endif /* MBEDTLS_DEPRECATED_REMOVED */

/**@}*/

#ifdef __cplusplus
}
#endif

#endif /* PSA_CRYPTO_COMPAT_H */

Coverage Report

Created: 2024-11-21 07:03

Line	Count	Source (jump to first uncovered line)
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	0	#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		static inline int psa_key_handle_is_null(psa_key_handle_t handle)
42	0	{
43	0	return mbedtls_svc_key_id_is_null(handle);
44	0	} Unexecuted instantiation: module.cpp:psa_key_handle_is_null(unsigned int) Unexecuted instantiation: psa_crypto.c:psa_key_handle_is_null Unexecuted instantiation: psa_crypto_aead.c:psa_key_handle_is_null Unexecuted instantiation: psa_crypto_cipher.c:psa_key_handle_is_null Unexecuted instantiation: psa_crypto_client.c:psa_key_handle_is_null Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:psa_key_handle_is_null Unexecuted instantiation: psa_crypto_ecp.c:psa_key_handle_is_null Unexecuted instantiation: psa_crypto_ffdh.c:psa_key_handle_is_null Unexecuted instantiation: psa_crypto_hash.c:psa_key_handle_is_null Unexecuted instantiation: psa_crypto_mac.c:psa_key_handle_is_null Unexecuted instantiation: psa_crypto_pake.c:psa_key_handle_is_null Unexecuted instantiation: psa_crypto_rsa.c:psa_key_handle_is_null Unexecuted instantiation: psa_crypto_slot_management.c:psa_key_handle_is_null Unexecuted instantiation: psa_crypto_storage.c:psa_key_handle_is_null Unexecuted instantiation: psa_util.c:psa_key_handle_is_null Unexecuted instantiation: rsa.c:psa_key_handle_is_null Unexecuted instantiation: md.c:psa_key_handle_is_null Unexecuted instantiation: oid.c:psa_key_handle_is_null Unexecuted instantiation: pkcs12.c:psa_key_handle_is_null Unexecuted instantiation: pkcs5.c:psa_key_handle_is_null
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	0	{
184	0	(void) data;
185	0	if (data_length != 0) {
186	0	return PSA_ERROR_NOT_SUPPORTED;
187	0	}
188	0	psa_set_key_type(attributes, type);
189	0	return PSA_SUCCESS;
190	0	} Unexecuted instantiation: module.cpp:psa_set_key_domain_parameters(psa_key_attributes_s, unsigned short, unsigned char const, unsigned long) Unexecuted instantiation: psa_crypto.c:psa_set_key_domain_parameters Unexecuted instantiation: psa_crypto_aead.c:psa_set_key_domain_parameters Unexecuted instantiation: psa_crypto_cipher.c:psa_set_key_domain_parameters Unexecuted instantiation: psa_crypto_client.c:psa_set_key_domain_parameters Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:psa_set_key_domain_parameters Unexecuted instantiation: psa_crypto_ecp.c:psa_set_key_domain_parameters Unexecuted instantiation: psa_crypto_ffdh.c:psa_set_key_domain_parameters Unexecuted instantiation: psa_crypto_hash.c:psa_set_key_domain_parameters Unexecuted instantiation: psa_crypto_mac.c:psa_set_key_domain_parameters Unexecuted instantiation: psa_crypto_pake.c:psa_set_key_domain_parameters Unexecuted instantiation: psa_crypto_rsa.c:psa_set_key_domain_parameters Unexecuted instantiation: psa_crypto_slot_management.c:psa_set_key_domain_parameters Unexecuted instantiation: psa_crypto_storage.c:psa_set_key_domain_parameters Unexecuted instantiation: psa_util.c:psa_set_key_domain_parameters Unexecuted instantiation: rsa.c:psa_set_key_domain_parameters Unexecuted instantiation: md.c:psa_set_key_domain_parameters Unexecuted instantiation: oid.c:psa_set_key_domain_parameters Unexecuted instantiation: pkcs12.c:psa_set_key_domain_parameters Unexecuted instantiation: pkcs5.c:psa_set_key_domain_parameters
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	0	{
210	0	(void) attributes;
211	0	(void) data;
212	0	(void) data_size;
213	0	*data_length = 0;
214	0	return PSA_SUCCESS;
215	0	} Unexecuted instantiation: module.cpp:psa_get_key_domain_parameters(psa_key_attributes_s const, unsigned char, unsigned long, unsigned long*) Unexecuted instantiation: psa_crypto.c:psa_get_key_domain_parameters Unexecuted instantiation: psa_crypto_aead.c:psa_get_key_domain_parameters Unexecuted instantiation: psa_crypto_cipher.c:psa_get_key_domain_parameters Unexecuted instantiation: psa_crypto_client.c:psa_get_key_domain_parameters Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:psa_get_key_domain_parameters Unexecuted instantiation: psa_crypto_ecp.c:psa_get_key_domain_parameters Unexecuted instantiation: psa_crypto_ffdh.c:psa_get_key_domain_parameters Unexecuted instantiation: psa_crypto_hash.c:psa_get_key_domain_parameters Unexecuted instantiation: psa_crypto_mac.c:psa_get_key_domain_parameters Unexecuted instantiation: psa_crypto_pake.c:psa_get_key_domain_parameters Unexecuted instantiation: psa_crypto_rsa.c:psa_get_key_domain_parameters Unexecuted instantiation: psa_crypto_slot_management.c:psa_get_key_domain_parameters Unexecuted instantiation: psa_crypto_storage.c:psa_get_key_domain_parameters Unexecuted instantiation: psa_util.c:psa_get_key_domain_parameters Unexecuted instantiation: rsa.c:psa_get_key_domain_parameters Unexecuted instantiation: md.c:psa_get_key_domain_parameters Unexecuted instantiation: oid.c:psa_get_key_domain_parameters Unexecuted instantiation: pkcs12.c:psa_get_key_domain_parameters Unexecuted instantiation: pkcs5.c:psa_get_key_domain_parameters
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 */