1 /**
2 * \file psa_util.h
3 *
4 * \brief Utility functions for the use of the PSA Crypto library.
5 *
6 * \warning This function is not part of the public API and may
7 * change at any time.
8 */
9 /*
10 * Copyright The Mbed TLS Contributors
11 * SPDX-License-Identifier: Apache-2.0
12 *
13 * Licensed under the Apache License, Version 2.0 (the "License"); you may
14 * not use this file except in compliance with the License.
15 * You may obtain a copy of the License at
16 *
17 * http://www.apache.org/licenses/LICENSE-2.0
18 *
19 * Unless required by applicable law or agreed to in writing, software
20 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
21 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
22 * See the License for the specific language governing permissions and
23 * limitations under the License.
24 */
25
26 #ifndef MBEDTLS_PSA_UTIL_H
27 #define MBEDTLS_PSA_UTIL_H
28 #include "mbedtls/private_access.h"
29
30 #include "mbedtls/build_info.h"
31
32 #if defined(MBEDTLS_PSA_CRYPTO_C)
33
34 #include "psa/crypto.h"
35
36 #include "mbedtls/ecp.h"
37 #include "mbedtls/md.h"
38 #include "mbedtls/pk.h"
39 #include "mbedtls/oid.h"
40 #include "mbedtls/error.h"
41
42 #include <string.h>
43
44 /* Translations for symmetric crypto. */
45
mbedtls_psa_translate_cipher_type(mbedtls_cipher_type_t cipher)46 static inline psa_key_type_t mbedtls_psa_translate_cipher_type(
47 mbedtls_cipher_type_t cipher)
48 {
49 switch (cipher) {
50 case MBEDTLS_CIPHER_AES_128_CCM:
51 case MBEDTLS_CIPHER_AES_192_CCM:
52 case MBEDTLS_CIPHER_AES_256_CCM:
53 case MBEDTLS_CIPHER_AES_128_CCM_STAR_NO_TAG:
54 case MBEDTLS_CIPHER_AES_192_CCM_STAR_NO_TAG:
55 case MBEDTLS_CIPHER_AES_256_CCM_STAR_NO_TAG:
56 case MBEDTLS_CIPHER_AES_128_GCM:
57 case MBEDTLS_CIPHER_AES_192_GCM:
58 case MBEDTLS_CIPHER_AES_256_GCM:
59 case MBEDTLS_CIPHER_AES_128_CBC:
60 case MBEDTLS_CIPHER_AES_192_CBC:
61 case MBEDTLS_CIPHER_AES_256_CBC:
62 case MBEDTLS_CIPHER_AES_128_ECB:
63 case MBEDTLS_CIPHER_AES_192_ECB:
64 case MBEDTLS_CIPHER_AES_256_ECB:
65 return PSA_KEY_TYPE_AES;
66
67 /* ARIA not yet supported in PSA. */
68 /* case MBEDTLS_CIPHER_ARIA_128_CCM:
69 case MBEDTLS_CIPHER_ARIA_192_CCM:
70 case MBEDTLS_CIPHER_ARIA_256_CCM:
71 case MBEDTLS_CIPHER_ARIA_128_CCM_STAR_NO_TAG:
72 case MBEDTLS_CIPHER_ARIA_192_CCM_STAR_NO_TAG:
73 case MBEDTLS_CIPHER_ARIA_256_CCM_STAR_NO_TAG:
74 case MBEDTLS_CIPHER_ARIA_128_GCM:
75 case MBEDTLS_CIPHER_ARIA_192_GCM:
76 case MBEDTLS_CIPHER_ARIA_256_GCM:
77 case MBEDTLS_CIPHER_ARIA_128_CBC:
78 case MBEDTLS_CIPHER_ARIA_192_CBC:
79 case MBEDTLS_CIPHER_ARIA_256_CBC:
80 return( PSA_KEY_TYPE_ARIA ); */
81
82 default:
83 return 0;
84 }
85 }
86
mbedtls_psa_translate_cipher_mode(mbedtls_cipher_mode_t mode,size_t taglen)87 static inline psa_algorithm_t mbedtls_psa_translate_cipher_mode(
88 mbedtls_cipher_mode_t mode, size_t taglen)
89 {
90 switch (mode) {
91 case MBEDTLS_MODE_ECB:
92 return PSA_ALG_ECB_NO_PADDING;
93 case MBEDTLS_MODE_GCM:
94 return PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_GCM, taglen);
95 case MBEDTLS_MODE_CCM:
96 return PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_CCM, taglen);
97 case MBEDTLS_MODE_CCM_STAR_NO_TAG:
98 return PSA_ALG_CCM_STAR_NO_TAG;
99 case MBEDTLS_MODE_CBC:
100 if (taglen == 0) {
101 return PSA_ALG_CBC_NO_PADDING;
102 } else {
103 return 0;
104 }
105 default:
106 return 0;
107 }
108 }
109
mbedtls_psa_translate_cipher_operation(mbedtls_operation_t op)110 static inline psa_key_usage_t mbedtls_psa_translate_cipher_operation(
111 mbedtls_operation_t op)
112 {
113 switch (op) {
114 case MBEDTLS_ENCRYPT:
115 return PSA_KEY_USAGE_ENCRYPT;
116 case MBEDTLS_DECRYPT:
117 return PSA_KEY_USAGE_DECRYPT;
118 default:
119 return 0;
120 }
121 }
122
123 /* Translations for hashing. */
124
125 /* Note: this function should not be used from inside the library, use
126 * mbedtls_hash_info_psa_from_md() from the internal hash_info.h instead.
127 * It is kept only for compatibility in case applications were using it. */
mbedtls_psa_translate_md(mbedtls_md_type_t md_alg)128 static inline psa_algorithm_t mbedtls_psa_translate_md(mbedtls_md_type_t md_alg)
129 {
130 switch (md_alg) {
131 #if defined(MBEDTLS_MD5_C) || defined(PSA_WANT_ALG_MD5)
132 case MBEDTLS_MD_MD5:
133 return PSA_ALG_MD5;
134 #endif
135 #if defined(MBEDTLS_SHA1_C) || defined(PSA_WANT_ALG_SHA_1)
136 case MBEDTLS_MD_SHA1:
137 return PSA_ALG_SHA_1;
138 #endif
139 #if defined(MBEDTLS_SHA224_C) || defined(PSA_WANT_ALG_SHA_224)
140 case MBEDTLS_MD_SHA224:
141 return PSA_ALG_SHA_224;
142 #endif
143 #if defined(MBEDTLS_SHA256_C) || defined(PSA_WANT_ALG_SHA_256)
144 case MBEDTLS_MD_SHA256:
145 return PSA_ALG_SHA_256;
146 #endif
147 #if defined(MBEDTLS_SHA384_C) || defined(PSA_WANT_ALG_SHA_384)
148 case MBEDTLS_MD_SHA384:
149 return PSA_ALG_SHA_384;
150 #endif
151 #if defined(MBEDTLS_SHA512_C) || defined(PSA_WANT_ALG_SHA_512)
152 case MBEDTLS_MD_SHA512:
153 return PSA_ALG_SHA_512;
154 #endif
155 #if defined(MBEDTLS_RIPEMD160_C) || defined(PSA_WANT_ALG_RIPEMD160)
156 case MBEDTLS_MD_RIPEMD160:
157 return PSA_ALG_RIPEMD160;
158 #endif
159 case MBEDTLS_MD_NONE:
160 return 0;
161 default:
162 return 0;
163 }
164 }
165
166 /* Translations for ECC. */
167
mbedtls_psa_get_ecc_oid_from_id(psa_ecc_family_t curve,size_t bits,char const ** oid,size_t * oid_len)168 static inline int mbedtls_psa_get_ecc_oid_from_id(
169 psa_ecc_family_t curve, size_t bits,
170 char const **oid, size_t *oid_len)
171 {
172 switch (curve) {
173 case PSA_ECC_FAMILY_SECP_R1:
174 switch (bits) {
175 #if defined(MBEDTLS_ECP_DP_SECP192R1_ENABLED)
176 case 192:
177 *oid = MBEDTLS_OID_EC_GRP_SECP192R1;
178 *oid_len = MBEDTLS_OID_SIZE(MBEDTLS_OID_EC_GRP_SECP192R1);
179 return 0;
180 #endif /* MBEDTLS_ECP_DP_SECP192R1_ENABLED */
181 #if defined(MBEDTLS_ECP_DP_SECP224R1_ENABLED)
182 case 224:
183 *oid = MBEDTLS_OID_EC_GRP_SECP224R1;
184 *oid_len = MBEDTLS_OID_SIZE(MBEDTLS_OID_EC_GRP_SECP224R1);
185 return 0;
186 #endif /* MBEDTLS_ECP_DP_SECP224R1_ENABLED */
187 #if defined(MBEDTLS_ECP_DP_SECP256R1_ENABLED)
188 case 256:
189 *oid = MBEDTLS_OID_EC_GRP_SECP256R1;
190 *oid_len = MBEDTLS_OID_SIZE(MBEDTLS_OID_EC_GRP_SECP256R1);
191 return 0;
192 #endif /* MBEDTLS_ECP_DP_SECP256R1_ENABLED */
193 #if defined(MBEDTLS_ECP_DP_SECP384R1_ENABLED)
194 case 384:
195 *oid = MBEDTLS_OID_EC_GRP_SECP384R1;
196 *oid_len = MBEDTLS_OID_SIZE(MBEDTLS_OID_EC_GRP_SECP384R1);
197 return 0;
198 #endif /* MBEDTLS_ECP_DP_SECP384R1_ENABLED */
199 #if defined(MBEDTLS_ECP_DP_SECP521R1_ENABLED)
200 case 521:
201 *oid = MBEDTLS_OID_EC_GRP_SECP521R1;
202 *oid_len = MBEDTLS_OID_SIZE(MBEDTLS_OID_EC_GRP_SECP521R1);
203 return 0;
204 #endif /* MBEDTLS_ECP_DP_SECP521R1_ENABLED */
205 }
206 break;
207 case PSA_ECC_FAMILY_SECP_K1:
208 switch (bits) {
209 #if defined(MBEDTLS_ECP_DP_SECP192K1_ENABLED)
210 case 192:
211 *oid = MBEDTLS_OID_EC_GRP_SECP192K1;
212 *oid_len = MBEDTLS_OID_SIZE(MBEDTLS_OID_EC_GRP_SECP192K1);
213 return 0;
214 #endif /* MBEDTLS_ECP_DP_SECP192K1_ENABLED */
215 #if defined(MBEDTLS_ECP_DP_SECP224K1_ENABLED)
216 case 224:
217 *oid = MBEDTLS_OID_EC_GRP_SECP224K1;
218 *oid_len = MBEDTLS_OID_SIZE(MBEDTLS_OID_EC_GRP_SECP224K1);
219 return 0;
220 #endif /* MBEDTLS_ECP_DP_SECP224K1_ENABLED */
221 #if defined(MBEDTLS_ECP_DP_SECP256K1_ENABLED)
222 case 256:
223 *oid = MBEDTLS_OID_EC_GRP_SECP256K1;
224 *oid_len = MBEDTLS_OID_SIZE(MBEDTLS_OID_EC_GRP_SECP256K1);
225 return 0;
226 #endif /* MBEDTLS_ECP_DP_SECP256K1_ENABLED */
227 }
228 break;
229 case PSA_ECC_FAMILY_BRAINPOOL_P_R1:
230 switch (bits) {
231 #if defined(MBEDTLS_ECP_DP_BP256R1_ENABLED)
232 case 256:
233 *oid = MBEDTLS_OID_EC_GRP_BP256R1;
234 *oid_len = MBEDTLS_OID_SIZE(MBEDTLS_OID_EC_GRP_BP256R1);
235 return 0;
236 #endif /* MBEDTLS_ECP_DP_BP256R1_ENABLED */
237 #if defined(MBEDTLS_ECP_DP_BP384R1_ENABLED)
238 case 384:
239 *oid = MBEDTLS_OID_EC_GRP_BP384R1;
240 *oid_len = MBEDTLS_OID_SIZE(MBEDTLS_OID_EC_GRP_BP384R1);
241 return 0;
242 #endif /* MBEDTLS_ECP_DP_BP384R1_ENABLED */
243 #if defined(MBEDTLS_ECP_DP_BP512R1_ENABLED)
244 case 512:
245 *oid = MBEDTLS_OID_EC_GRP_BP512R1;
246 *oid_len = MBEDTLS_OID_SIZE(MBEDTLS_OID_EC_GRP_BP512R1);
247 return 0;
248 #endif /* MBEDTLS_ECP_DP_BP512R1_ENABLED */
249 }
250 break;
251 }
252 (void) oid;
253 (void) oid_len;
254 return -1;
255 }
256
257 #define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH \
258 PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)
259
260 #define MBEDTLS_PSA_MAX_EC_KEY_PAIR_LENGTH \
261 PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)
262
263 /* Expose whatever RNG the PSA subsystem uses to applications using the
264 * mbedtls_xxx API. The declarations and definitions here need to be
265 * consistent with the implementation in library/psa_crypto_random_impl.h.
266 * See that file for implementation documentation. */
267
268
269 /* The type of a `f_rng` random generator function that many library functions
270 * take.
271 *
272 * This type name is not part of the Mbed TLS stable API. It may be renamed
273 * or moved without warning.
274 */
275 typedef int mbedtls_f_rng_t(void *p_rng, unsigned char *output, size_t output_size);
276
277 #if defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)
278
279 /** The random generator function for the PSA subsystem.
280 *
281 * This function is suitable as the `f_rng` random generator function
282 * parameter of many `mbedtls_xxx` functions. Use #MBEDTLS_PSA_RANDOM_STATE
283 * to obtain the \p p_rng parameter.
284 *
285 * The implementation of this function depends on the configuration of the
286 * library.
287 *
288 * \note Depending on the configuration, this may be a function or
289 * a pointer to a function.
290 *
291 * \note This function may only be used if the PSA crypto subsystem is active.
292 * This means that you must call psa_crypto_init() before any call to
293 * this function, and you must not call this function after calling
294 * mbedtls_psa_crypto_free().
295 *
296 * \param p_rng The random generator context. This must be
297 * #MBEDTLS_PSA_RANDOM_STATE. No other state is
298 * supported.
299 * \param output The buffer to fill. It must have room for
300 * \c output_size bytes.
301 * \param output_size The number of bytes to write to \p output.
302 * This function may fail if \p output_size is too
303 * large. It is guaranteed to accept any output size
304 * requested by Mbed TLS library functions. The
305 * maximum request size depends on the library
306 * configuration.
307 *
308 * \return \c 0 on success.
309 * \return An `MBEDTLS_ERR_ENTROPY_xxx`,
310 * `MBEDTLS_ERR_PLATFORM_xxx,
311 * `MBEDTLS_ERR_CTR_DRBG_xxx` or
312 * `MBEDTLS_ERR_HMAC_DRBG_xxx` on error.
313 */
314 int mbedtls_psa_get_random(void *p_rng,
315 unsigned char *output,
316 size_t output_size);
317
318 /** The random generator state for the PSA subsystem.
319 *
320 * This macro expands to an expression which is suitable as the `p_rng`
321 * random generator state parameter of many `mbedtls_xxx` functions.
322 * It must be used in combination with the random generator function
323 * mbedtls_psa_get_random().
324 *
325 * The implementation of this macro depends on the configuration of the
326 * library. Do not make any assumption on its nature.
327 */
328 #define MBEDTLS_PSA_RANDOM_STATE NULL
329
330 #else /* !defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) */
331
332 #if defined(MBEDTLS_CTR_DRBG_C)
333 #include "mbedtls/ctr_drbg.h"
334 typedef mbedtls_ctr_drbg_context mbedtls_psa_drbg_context_t;
335 static mbedtls_f_rng_t *const mbedtls_psa_get_random = mbedtls_ctr_drbg_random;
336 #elif defined(MBEDTLS_HMAC_DRBG_C)
337 #include "mbedtls/hmac_drbg.h"
338 typedef mbedtls_hmac_drbg_context mbedtls_psa_drbg_context_t;
339 static mbedtls_f_rng_t *const mbedtls_psa_get_random = mbedtls_hmac_drbg_random;
340 #endif
341 extern mbedtls_psa_drbg_context_t *const mbedtls_psa_random_state;
342
343 #define MBEDTLS_PSA_RANDOM_STATE mbedtls_psa_random_state
344
345 #endif /* !defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) */
346
347 typedef struct {
348 psa_status_t psa_status;
349 int16_t mbedtls_error;
350 } mbedtls_error_pair_t;
351
352 #if !defined(MBEDTLS_MD_C) || !defined(MBEDTLS_MD5_C) || defined(MBEDTLS_USE_PSA_CRYPTO)
353 extern const mbedtls_error_pair_t psa_to_md_errors[4];
354 #endif
355
356 #if defined(MBEDTLS_LMS_C)
357 extern const mbedtls_error_pair_t psa_to_lms_errors[3];
358 #endif
359
360 #if defined(MBEDTLS_USE_PSA_CRYPTO) || defined(MBEDTLS_SSL_PROTO_TLS1_3)
361 extern const mbedtls_error_pair_t psa_to_ssl_errors[7];
362 #endif
363
364 #if defined(PSA_WANT_KEY_TYPE_RSA_PUBLIC_KEY) || \
365 defined(PSA_WANT_KEY_TYPE_RSA_KEY_PAIR)
366 extern const mbedtls_error_pair_t psa_to_pk_rsa_errors[8];
367 #endif
368
369 #if defined(MBEDTLS_USE_PSA_CRYPTO) && \
370 defined(PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY)
371 extern const mbedtls_error_pair_t psa_to_pk_ecdsa_errors[7];
372 #endif
373
374 /* Generic fallback function for error translation,
375 * when the received state was not module-specific. */
376 int psa_generic_status_to_mbedtls(psa_status_t status);
377
378 /* This function iterates over provided local error translations,
379 * and if no match was found - calls the fallback error translation function. */
380 int psa_status_to_mbedtls(psa_status_t status,
381 const mbedtls_error_pair_t *local_translations,
382 size_t local_errors_num,
383 int (*fallback_f)(psa_status_t));
384
385 /* The second out of three-stage error handling functions of the pk module,
386 * acts as a fallback after RSA / ECDSA error translation, and if no match
387 * is found, it itself calls psa_generic_status_to_mbedtls. */
388 int psa_pk_status_to_mbedtls(psa_status_t status);
389
390 /* Utility macro to shorten the defines of error translator in modules. */
391 #define PSA_TO_MBEDTLS_ERR_LIST(status, error_list, fallback_f) \
392 psa_status_to_mbedtls(status, error_list, \
393 sizeof(error_list)/sizeof(error_list[0]), \
394 fallback_f)
395
396 #endif /* MBEDTLS_PSA_CRYPTO_C */
397 #endif /* MBEDTLS_PSA_UTIL_H */
398