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) || defined(MCUBOOT_USE_PSA_CRYPTO)
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 #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 */
mbedtls_md_psa_alg_from_type(mbedtls_md_type_t md_type)121 static inline psa_algorithm_t mbedtls_md_psa_alg_from_type(mbedtls_md_type_t md_type)
122 {
123 return PSA_ALG_CATEGORY_HASH | (psa_algorithm_t) md_type;
124 }
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 */
mbedtls_md_type_from_psa_alg(psa_algorithm_t psa_alg)138 static inline mbedtls_md_type_t mbedtls_md_type_from_psa_alg(psa_algorithm_t psa_alg)
139 {
140 return (mbedtls_md_type_t) (psa_alg & PSA_ALG_HASH_MASK);
141 }
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 int mbedtls_ecdsa_raw_to_der(size_t bits, const unsigned char *raw, size_t raw_len,
166 unsigned char *der, size_t der_size, size_t *der_len);
167
168 /** Convert an ECDSA signature from DER ASN.1 format to raw format.
169 *
170 * \param bits Size of each coordinate in bits.
171 * \param der Buffer that contains the signature in DER format.
172 * \param der_len Size of \p der in bytes.
173 * \param[out] raw Buffer that will be filled with the converted raw
174 * signature. It can overlap with der buffer.
175 * \param raw_size Size of \p raw in bytes. Must be at least
176 * 2 * PSA_BITS_TO_BYTES(bits) bytes.
177 * \param[out] raw_len On success it is updated with the amount of valid
178 * data (in bytes) written to \p raw. It's undefined
179 * in case of failure.
180 */
181 int mbedtls_ecdsa_der_to_raw(size_t bits, const unsigned char *der, size_t der_len,
182 unsigned char *raw, size_t raw_size, size_t *raw_len);
183
184 #endif /* MBEDTLS_PSA_UTIL_HAVE_ECDSA */
185
186 /**@}*/
187
188 #endif /* MBEDTLS_PSA_UTIL_H */
189
