/work/mbedtls-3.6.6/include/mbedtls/psa_util.h

Source
/**
 * \file psa_util.h
 *
 * \brief Utility functions for the use of the PSA Crypto library.
 */
/*
 *  Copyright The Mbed TLS Contributors
 *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
 */

#ifndef MBEDTLS_PSA_UTIL_H
#define MBEDTLS_PSA_UTIL_H
#include "mbedtls/private_access.h"

#include "mbedtls/build_info.h"

#include "psa/crypto.h"

/* ASN1 defines used in the ECDSA conversion functions.
 * Note: intentionally not adding MBEDTLS_ASN1_[PARSE|WRITE]_C guards here
 * otherwise error codes would be unknown in test_suite_psa_crypto_util.data.*/
#include <mbedtls/asn1write.h>

#if defined(MBEDTLS_PSA_CRYPTO_CLIENT)

/** The random generator function for the PSA subsystem.
 *
 * This function is suitable as the `f_rng` random generator function
 * parameter of many `mbedtls_xxx` functions.
 *
 * The implementation of this function depends on the configuration of the
 * library.
 *
 * \note This function may only be used if the PSA crypto subsystem is active.
 *       This means that you must call psa_crypto_init() before any call to
 *       this function, and you must not call this function after calling
 *       mbedtls_psa_crypto_free().
 *
 * \param p_rng         This parameter is only kept for backward compatibility
 *                      reasons with legacy `f_rng` functions and it's ignored.
 *                      Set to #MBEDTLS_PSA_RANDOM_STATE or NULL.
 * \param output        The buffer to fill. It must have room for
 *                      \c output_size bytes.
 * \param output_size   The number of bytes to write to \p output.
 *                      This function may fail if \p output_size is too
 *                      large. It is guaranteed to accept any output size
 *                      requested by Mbed TLS library functions. The
 *                      maximum request size depends on the library
 *                      configuration.
 *
 * \return              \c 0 on success.
 * \return              An `MBEDTLS_ERR_ENTROPY_xxx`,
 *                      `MBEDTLS_ERR_PLATFORM_xxx,
 *                      `MBEDTLS_ERR_CTR_DRBG_xxx` or
 *                      `MBEDTLS_ERR_HMAC_DRBG_xxx` on error.
 */
int mbedtls_psa_get_random(void *p_rng,
                           unsigned char *output,
                           size_t output_size);

/** The random generator state for the PSA subsystem.
 *
 * This macro always expands to NULL because the `p_rng` parameter is unused
 * in mbedtls_psa_get_random(), but it's kept for interface's backward
 * compatibility.
 */
#define MBEDTLS_PSA_RANDOM_STATE    NULL

/** \defgroup psa_tls_helpers TLS helper functions
 * @{
 */
#if defined(PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY)
#include <mbedtls/ecp.h>

/** Convert an ECC curve identifier from the Mbed TLS encoding to PSA.
 *
 * \param grpid         An Mbed TLS elliptic curve identifier
 *                      (`MBEDTLS_ECP_DP_xxx`).
 * \param[out] bits     On success the bit size of the curve; 0 on failure.
 *
 * \return              If the curve is supported in the PSA API, this function
 *                      returns the proper PSA curve identifier
 *                      (`PSA_ECC_FAMILY_xxx`). This holds even if the curve is
 *                      not supported by the ECP module.
 * \return              \c 0 if the curve is not supported in the PSA API.
 */
psa_ecc_family_t mbedtls_ecc_group_to_psa(mbedtls_ecp_group_id grpid,
                                          size_t *bits);

/** Convert an ECC curve identifier from the PSA encoding to Mbed TLS.
 *
 * \param family        A PSA elliptic curve family identifier
 *                      (`PSA_ECC_FAMILY_xxx`).
 * \param bits          The bit-length of a private key on \p curve.
 *
 * \return              If the curve is supported in the PSA API, this function
 *                      returns the corresponding Mbed TLS elliptic curve
 *                      identifier (`MBEDTLS_ECP_DP_xxx`).
 * \return              #MBEDTLS_ECP_DP_NONE if the combination of \c curve
 *                      and \p bits is not supported.
 */
mbedtls_ecp_group_id mbedtls_ecc_group_from_psa(psa_ecc_family_t family,
                                                size_t bits);
#endif /* PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY */

/**
 * \brief           This function returns the PSA algorithm identifier
 *                  associated with the given digest type.
 *
 * \param md_type   The type of digest to search for. Must not be NONE.
 *
 * \warning         If \p md_type is \c MBEDTLS_MD_NONE, this function will
 *                  not return \c PSA_ALG_NONE, but an invalid algorithm.
 *
 * \warning         This function does not check if the algorithm is
 *                  supported, it always returns the corresponding identifier.
 *
 * \return          The PSA algorithm identifier associated with \p md_type,
 *                  regardless of whether it is supported or not.
 */
static inline psa_algorithm_t mbedtls_md_psa_alg_from_type(mbedtls_md_type_t md_type)
{
    return PSA_ALG_CATEGORY_HASH | (psa_algorithm_t) md_type;
}

/**
 * \brief           This function returns the given digest type
 *                  associated with the PSA algorithm identifier.
 *
 * \param psa_alg   The PSA algorithm identifier to search for.
 *
 * \warning         This function does not check if the algorithm is
 *                  supported, it always returns the corresponding identifier.
 *
 * \return          The MD type associated with \p psa_alg,
 *                  regardless of whether it is supported or not.
 */
static inline mbedtls_md_type_t mbedtls_md_type_from_psa_alg(psa_algorithm_t psa_alg)
{
    return (mbedtls_md_type_t) (psa_alg & PSA_ALG_HASH_MASK);
}
#endif /* MBEDTLS_PSA_CRYPTO_CLIENT */

#if defined(MBEDTLS_PSA_UTIL_HAVE_ECDSA)

/** Convert an ECDSA signature from raw format to DER ASN.1 format.
 *
 * \param       bits        Size of each coordinate in bits.
 * \param       raw         Buffer that contains the signature in raw format.
 * \param       raw_len     Length of \p raw in bytes. This must be
 *                          PSA_BITS_TO_BYTES(bits) bytes.
 * \param[out]  der         Buffer that will be filled with the converted DER
 *                          output. It can overlap with raw buffer.
 * \param       der_size    Size of \p der in bytes. It is enough if \p der_size
 *                          is at least the size of the actual output. (The size
 *                          of the output can vary depending on the presence of
 *                          leading zeros in the data.) You can use
 *                          #MBEDTLS_ECDSA_MAX_SIG_LEN(\p bits) to determine a
 *                          size that is large enough for all signatures for a
 *                          given value of \p bits.
 * \param[out]  der_len     On success it contains the amount of valid data
 *                          (in bytes) written to \p der. It's undefined
 *                          in case of failure.
 *
 * \note                    The behavior is undefined if \p der is null,
 *                          even if \p der_size is 0.
 *
 * \return                  0 if successful.
 * \return                  #MBEDTLS_ERR_ASN1_BUF_TOO_SMALL if \p der_size
 *                          is too small or if \p bits is larger than the
 *                          largest supported curve.
 * \return                  #MBEDTLS_ERR_ASN1_INVALID_DATA if one of the
 *                          numbers in the signature is 0.
 */
int mbedtls_ecdsa_raw_to_der(size_t bits, const unsigned char *raw, size_t raw_len,
                             unsigned char *der, size_t der_size, size_t *der_len);

/** Convert an ECDSA signature from DER ASN.1 format to raw format.
 *
 * \param       bits        Size of each coordinate in bits.
 * \param       der         Buffer that contains the signature in DER format.
 * \param       der_len     Size of \p der in bytes.
 * \param[out]  raw         Buffer that will be filled with the converted raw
 *                          signature. It can overlap with der buffer.
 * \param       raw_size    Size of \p raw in bytes. Must be at least
 *                          2 * PSA_BITS_TO_BYTES(bits) bytes.
 * \param[out]  raw_len     On success it is updated with the amount of valid
 *                          data (in bytes) written to \p raw. It's undefined
 *                          in case of failure.
 *
 * \return                  0 if successful.
 * \return                  #MBEDTLS_ERR_ASN1_BUF_TOO_SMALL if \p raw_size
 *                          is too small or if \p bits is larger than the
 *                          largest supported curve.
 * \return                  #MBEDTLS_ERR_ASN1_INVALID_DATA if the data in
 *                          \p der is inconsistent with \p bits.
 * \return                  An \c MBEDTLS_ERR_ASN1_xxx error code if
 *                          \p der is malformed.
 */
int mbedtls_ecdsa_der_to_raw(size_t bits, const unsigned char *der, size_t der_len,
                             unsigned char *raw, size_t raw_size, size_t *raw_len);

#endif /* MBEDTLS_PSA_UTIL_HAVE_ECDSA */

/**@}*/

#endif /* MBEDTLS_PSA_UTIL_H */

Coverage Report

Created: 2026-10-17 06:10

Line	Count	Source
1		/**
2		* \file psa_util.h
3		*
4		* \brief Utility functions for the use of the PSA Crypto library.
5		*/
6		/*
7		* Copyright The Mbed TLS Contributors
8		* SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
9		*/
10
11		#ifndef MBEDTLS_PSA_UTIL_H
12		#define MBEDTLS_PSA_UTIL_H
13		#include "mbedtls/private_access.h"
14
15		#include "mbedtls/build_info.h"
16
17		#include "psa/crypto.h"
18
19		/* ASN1 defines used in the ECDSA conversion functions.
20		* Note: intentionally not adding MBEDTLS_ASN1_[PARSE\|WRITE]_C guards here
21		* otherwise error codes would be unknown in test_suite_psa_crypto_util.data.*/
22		#include <mbedtls/asn1write.h>
23
24		#if defined(MBEDTLS_PSA_CRYPTO_CLIENT)
25
26		/** The random generator function for the PSA subsystem.
27		*
28		* This function is suitable as the `f_rng` random generator function
29		* parameter of many `mbedtls_xxx` functions.
30		*
31		* The implementation of this function depends on the configuration of the
32		* library.
33		*
34		* \note This function may only be used if the PSA crypto subsystem is active.
35		* This means that you must call psa_crypto_init() before any call to
36		* this function, and you must not call this function after calling
37		* mbedtls_psa_crypto_free().
38		*
39		* \param p_rng This parameter is only kept for backward compatibility
40		* reasons with legacy `f_rng` functions and it's ignored.
41		* Set to #MBEDTLS_PSA_RANDOM_STATE or NULL.
42		* \param output The buffer to fill. It must have room for
43		* \c output_size bytes.
44		* \param output_size The number of bytes to write to \p output.
45		* This function may fail if \p output_size is too
46		* large. It is guaranteed to accept any output size
47		* requested by Mbed TLS library functions. The
48		* maximum request size depends on the library
49		* configuration.
50		*
51		* \return \c 0 on success.
52		* \return An `MBEDTLS_ERR_ENTROPY_xxx`,
53		* `MBEDTLS_ERR_PLATFORM_xxx,
54		* `MBEDTLS_ERR_CTR_DRBG_xxx` or
55		* `MBEDTLS_ERR_HMAC_DRBG_xxx` on error.
56		*/
57		int mbedtls_psa_get_random(void *p_rng,
58		unsigned char *output,
59		size_t output_size);
60
61		/** The random generator state for the PSA subsystem.
62		*
63		* This macro always expands to NULL because the `p_rng` parameter is unused
64		* in mbedtls_psa_get_random(), but it's kept for interface's backward
65		* compatibility.
66		*/
67	0	#define MBEDTLS_PSA_RANDOM_STATE NULL
68
69		/** \defgroup psa_tls_helpers TLS helper functions
70		* @{
71		*/
72		#if defined(PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY)
73		#include <mbedtls/ecp.h>
74
75		/** Convert an ECC curve identifier from the Mbed TLS encoding to PSA.
76		*
77		* \param grpid An Mbed TLS elliptic curve identifier
78		* (`MBEDTLS_ECP_DP_xxx`).
79		* \param[out] bits On success the bit size of the curve; 0 on failure.
80		*
81		* \return If the curve is supported in the PSA API, this function
82		* returns the proper PSA curve identifier
83		* (`PSA_ECC_FAMILY_xxx`). This holds even if the curve is
84		* not supported by the ECP module.
85		* \return \c 0 if the curve is not supported in the PSA API.
86		*/
87		psa_ecc_family_t mbedtls_ecc_group_to_psa(mbedtls_ecp_group_id grpid,
88		size_t *bits);
89
90		/** Convert an ECC curve identifier from the PSA encoding to Mbed TLS.
91		*
92		* \param family A PSA elliptic curve family identifier
93		* (`PSA_ECC_FAMILY_xxx`).
94		* \param bits The bit-length of a private key on \p curve.
95		*
96		* \return If the curve is supported in the PSA API, this function
97		* returns the corresponding Mbed TLS elliptic curve
98		* identifier (`MBEDTLS_ECP_DP_xxx`).
99		* \return #MBEDTLS_ECP_DP_NONE if the combination of \c curve
100		* and \p bits is not supported.
101		*/
102		mbedtls_ecp_group_id mbedtls_ecc_group_from_psa(psa_ecc_family_t family,
103		size_t bits);
104		#endif /* PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY */
105
106		/**
107		* \brief This function returns the PSA algorithm identifier
108		* associated with the given digest type.
109		*
110		* \param md_type The type of digest to search for. Must not be NONE.
111		*
112		* \warning If \p md_type is \c MBEDTLS_MD_NONE, this function will
113		* not return \c PSA_ALG_NONE, but an invalid algorithm.
114		*
115		* \warning This function does not check if the algorithm is
116		* supported, it always returns the corresponding identifier.
117		*
118		* \return The PSA algorithm identifier associated with \p md_type,
119		* regardless of whether it is supported or not.
120		*/
121		static inline psa_algorithm_t mbedtls_md_psa_alg_from_type(mbedtls_md_type_t md_type)
122	0	{
123	0	return PSA_ALG_CATEGORY_HASH \| (psa_algorithm_t) md_type;
124	0	} Unexecuted instantiation: x509.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: x509_crl.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: x509_crt.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: x509write_csr.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: x509_create.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: x509write.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: md.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: pk.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: pk_ecc.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: pk_wrap.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: pkparse.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: pkwrite.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: psa_crypto.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: psa_crypto_cipher.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: psa_crypto_ecp.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: psa_crypto_ffdh.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: psa_crypto_pake.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: psa_crypto_rsa.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: psa_crypto_random.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: psa_util.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: pkcs12.c:mbedtls_md_psa_alg_from_type Unexecuted instantiation: pkcs5.c:mbedtls_md_psa_alg_from_type
125
126		/**
127		* \brief This function returns the given digest type
128		* associated with the PSA algorithm identifier.
129		*
130		* \param psa_alg The PSA algorithm identifier to search for.
131		*
132		* \warning This function does not check if the algorithm is
133		* supported, it always returns the corresponding identifier.
134		*
135		* \return The MD type associated with \p psa_alg,
136		* regardless of whether it is supported or not.
137		*/
138		static inline mbedtls_md_type_t mbedtls_md_type_from_psa_alg(psa_algorithm_t psa_alg)
139	0	{
140	0	return (mbedtls_md_type_t) (psa_alg & PSA_ALG_HASH_MASK);
141	0	} Unexecuted instantiation: x509.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: x509_crl.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: x509_crt.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: x509write_csr.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: x509_create.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: x509write.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: md.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: pk.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: pk_ecc.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: pk_wrap.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: pkparse.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: pkwrite.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: psa_crypto.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: psa_crypto_cipher.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: psa_crypto_ecp.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: psa_crypto_ffdh.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: psa_crypto_pake.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: psa_crypto_rsa.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: psa_crypto_random.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: psa_util.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: pkcs12.c:mbedtls_md_type_from_psa_alg Unexecuted instantiation: pkcs5.c:mbedtls_md_type_from_psa_alg
142		#endif /* MBEDTLS_PSA_CRYPTO_CLIENT */
143
144		#if defined(MBEDTLS_PSA_UTIL_HAVE_ECDSA)
145
146		/** Convert an ECDSA signature from raw format to DER ASN.1 format.
147		*
148		* \param bits Size of each coordinate in bits.
149		* \param raw Buffer that contains the signature in raw format.
150		* \param raw_len Length of \p raw in bytes. This must be
151		* PSA_BITS_TO_BYTES(bits) bytes.
152		* \param[out] der Buffer that will be filled with the converted DER
153		* output. It can overlap with raw buffer.
154		* \param der_size Size of \p der in bytes. It is enough if \p der_size
155		* is at least the size of the actual output. (The size
156		* of the output can vary depending on the presence of
157		* leading zeros in the data.) You can use
158		* #MBEDTLS_ECDSA_MAX_SIG_LEN(\p bits) to determine a
159		* size that is large enough for all signatures for a
160		* given value of \p bits.
161		* \param[out] der_len On success it contains the amount of valid data
162		* (in bytes) written to \p der. It's undefined
163		* in case of failure.
164		*
165		* \note The behavior is undefined if \p der is null,
166		* even if \p der_size is 0.
167		*
168		* \return 0 if successful.
169		* \return #MBEDTLS_ERR_ASN1_BUF_TOO_SMALL if \p der_size
170		* is too small or if \p bits is larger than the
171		* largest supported curve.
172		* \return #MBEDTLS_ERR_ASN1_INVALID_DATA if one of the
173		* numbers in the signature is 0.
174		*/
175		int mbedtls_ecdsa_raw_to_der(size_t bits, const unsigned char *raw, size_t raw_len,
176		unsigned char der, size_t der_size, size_t der_len);
177
178		/** Convert an ECDSA signature from DER ASN.1 format to raw format.
179		*
180		* \param bits Size of each coordinate in bits.
181		* \param der Buffer that contains the signature in DER format.
182		* \param der_len Size of \p der in bytes.
183		* \param[out] raw Buffer that will be filled with the converted raw
184		* signature. It can overlap with der buffer.
185		* \param raw_size Size of \p raw in bytes. Must be at least
186		* 2 * PSA_BITS_TO_BYTES(bits) bytes.
187		* \param[out] raw_len On success it is updated with the amount of valid
188		* data (in bytes) written to \p raw. It's undefined
189		* in case of failure.
190		*
191		* \return 0 if successful.
192		* \return #MBEDTLS_ERR_ASN1_BUF_TOO_SMALL if \p raw_size
193		* is too small or if \p bits is larger than the
194		* largest supported curve.
195		* \return #MBEDTLS_ERR_ASN1_INVALID_DATA if the data in
196		* \p der is inconsistent with \p bits.
197		* \return An \c MBEDTLS_ERR_ASN1_xxx error code if
198		* \p der is malformed.
199		*/
200		int mbedtls_ecdsa_der_to_raw(size_t bits, const unsigned char *der, size_t der_len,
201		unsigned char raw, size_t raw_size, size_t raw_len);
202
203		#endif /* MBEDTLS_PSA_UTIL_HAVE_ECDSA */
204
205		/*@}/
206
207		#endif /* MBEDTLS_PSA_UTIL_H */