2 * Public Key abstraction layer
4 * Copyright The Mbed TLS Contributors
5 * SPDX-License-Identifier: Apache-2.0
7 * Licensed under the Apache License, Version 2.0 (the "License"); you may
8 * not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
15 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
22 #if defined(MBEDTLS_PK_C)
23 #include "mbedtls/pk.h"
24 #include "mbedtls/pk_internal.h"
26 #include "mbedtls/platform_util.h"
27 #include "mbedtls/error.h"
29 #if defined(MBEDTLS_RSA_C)
30 #include "mbedtls/rsa.h"
32 #if defined(MBEDTLS_ECP_C)
33 #include "mbedtls/ecp.h"
35 #if defined(MBEDTLS_ECDSA_C)
36 #include "mbedtls/ecdsa.h"
39 #if defined(MBEDTLS_USE_PSA_CRYPTO)
40 #include "mbedtls/psa_util.h"
46 /* Parameter validation macros based on platform_util.h */
47 #define PK_VALIDATE_RET( cond ) \
48 MBEDTLS_INTERNAL_VALIDATE_RET( cond, MBEDTLS_ERR_PK_BAD_INPUT_DATA )
49 #define PK_VALIDATE( cond ) \
50 MBEDTLS_INTERNAL_VALIDATE( cond )
53 * Initialise a mbedtls_pk_context
55 void mbedtls_pk_init(mbedtls_pk_context
*ctx
) {
56 PK_VALIDATE(ctx
!= NULL
);
63 * Free (the components of) a mbedtls_pk_context
65 void mbedtls_pk_free(mbedtls_pk_context
*ctx
) {
69 if (ctx
->pk_info
!= NULL
)
70 ctx
->pk_info
->ctx_free_func(ctx
->pk_ctx
);
72 mbedtls_platform_zeroize(ctx
, sizeof(mbedtls_pk_context
));
75 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
77 * Initialize a restart context
79 void mbedtls_pk_restart_init(mbedtls_pk_restart_ctx
*ctx
) {
80 PK_VALIDATE(ctx
!= NULL
);
86 * Free the components of a restart context
88 void mbedtls_pk_restart_free(mbedtls_pk_restart_ctx
*ctx
) {
89 if (ctx
== NULL
|| ctx
->pk_info
== NULL
||
90 ctx
->pk_info
->rs_free_func
== NULL
) {
94 ctx
->pk_info
->rs_free_func(ctx
->rs_ctx
);
99 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
102 * Get pk_info structure from type
104 const mbedtls_pk_info_t
*mbedtls_pk_info_from_type(mbedtls_pk_type_t pk_type
) {
106 #if defined(MBEDTLS_RSA_C)
108 return (&mbedtls_rsa_info
);
110 #if defined(MBEDTLS_ECP_C)
111 case MBEDTLS_PK_ECKEY
:
112 return (&mbedtls_eckey_info
);
113 case MBEDTLS_PK_ECKEY_DH
:
114 return (&mbedtls_eckeydh_info
);
116 #if defined(MBEDTLS_ECDSA_C)
117 case MBEDTLS_PK_ECDSA
:
118 return (&mbedtls_ecdsa_info
);
120 /* MBEDTLS_PK_RSA_ALT omitted on purpose */
129 int mbedtls_pk_setup(mbedtls_pk_context
*ctx
, const mbedtls_pk_info_t
*info
) {
130 PK_VALIDATE_RET(ctx
!= NULL
);
131 if (info
== NULL
|| ctx
->pk_info
!= NULL
)
132 return (MBEDTLS_ERR_PK_BAD_INPUT_DATA
);
134 if ((ctx
->pk_ctx
= info
->ctx_alloc_func()) == NULL
)
135 return (MBEDTLS_ERR_PK_ALLOC_FAILED
);
142 #if defined(MBEDTLS_USE_PSA_CRYPTO)
144 * Initialise a PSA-wrapping context
146 int mbedtls_pk_setup_opaque(mbedtls_pk_context
*ctx
,
147 const psa_key_id_t key
) {
148 const mbedtls_pk_info_t
*const info
= &mbedtls_pk_opaque_info
;
149 psa_key_attributes_t attributes
= PSA_KEY_ATTRIBUTES_INIT
;
150 psa_key_id_t
*pk_ctx
;
153 if (ctx
== NULL
|| ctx
->pk_info
!= NULL
)
154 return (MBEDTLS_ERR_PK_BAD_INPUT_DATA
);
156 if (PSA_SUCCESS
!= psa_get_key_attributes(key
, &attributes
))
157 return (MBEDTLS_ERR_PK_BAD_INPUT_DATA
);
158 type
= psa_get_key_type(&attributes
);
159 psa_reset_key_attributes(&attributes
);
161 /* Current implementation of can_do() relies on this. */
162 if (! PSA_KEY_TYPE_IS_ECC_KEY_PAIR(type
))
163 return (MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE
) ;
165 if ((ctx
->pk_ctx
= info
->ctx_alloc_func()) == NULL
)
166 return (MBEDTLS_ERR_PK_ALLOC_FAILED
);
170 pk_ctx
= (psa_key_id_t
*) ctx
->pk_ctx
;
175 #endif /* MBEDTLS_USE_PSA_CRYPTO */
177 #if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
179 * Initialize an RSA-alt context
181 int mbedtls_pk_setup_rsa_alt(mbedtls_pk_context
*ctx
, void *key
,
182 mbedtls_pk_rsa_alt_decrypt_func decrypt_func
,
183 mbedtls_pk_rsa_alt_sign_func sign_func
,
184 mbedtls_pk_rsa_alt_key_len_func key_len_func
) {
185 mbedtls_rsa_alt_context
*rsa_alt
;
186 const mbedtls_pk_info_t
*info
= &mbedtls_rsa_alt_info
;
188 PK_VALIDATE_RET(ctx
!= NULL
);
189 if (ctx
->pk_info
!= NULL
)
190 return (MBEDTLS_ERR_PK_BAD_INPUT_DATA
);
192 if ((ctx
->pk_ctx
= info
->ctx_alloc_func()) == NULL
)
193 return (MBEDTLS_ERR_PK_ALLOC_FAILED
);
197 rsa_alt
= (mbedtls_rsa_alt_context
*) ctx
->pk_ctx
;
200 rsa_alt
->decrypt_func
= decrypt_func
;
201 rsa_alt
->sign_func
= sign_func
;
202 rsa_alt
->key_len_func
= key_len_func
;
206 #endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
209 * Tell if a PK can do the operations of the given type
211 int mbedtls_pk_can_do(const mbedtls_pk_context
*ctx
, mbedtls_pk_type_t type
) {
212 /* A context with null pk_info is not set up yet and can't do anything.
213 * For backward compatibility, also accept NULL instead of a context
215 if (ctx
== NULL
|| ctx
->pk_info
== NULL
)
218 return (ctx
->pk_info
->can_do(type
));
222 * Helper for mbedtls_pk_sign and mbedtls_pk_verify
224 static inline int pk_hashlen_helper(mbedtls_md_type_t md_alg
, size_t *hash_len
) {
225 const mbedtls_md_info_t
*md_info
;
230 if ((md_info
= mbedtls_md_info_from_type(md_alg
)) == NULL
)
233 *hash_len
= mbedtls_md_get_size(md_info
);
237 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
239 * Helper to set up a restart context if needed
241 static int pk_restart_setup(mbedtls_pk_restart_ctx
*ctx
,
242 const mbedtls_pk_info_t
*info
) {
243 /* Don't do anything if already set up or invalid */
244 if (ctx
== NULL
|| ctx
->pk_info
!= NULL
)
247 /* Should never happen when we're called */
248 if (info
->rs_alloc_func
== NULL
|| info
->rs_free_func
== NULL
)
249 return (MBEDTLS_ERR_PK_BAD_INPUT_DATA
);
251 if ((ctx
->rs_ctx
= info
->rs_alloc_func()) == NULL
)
252 return (MBEDTLS_ERR_PK_ALLOC_FAILED
);
258 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
261 * Verify a signature (restartable)
263 int mbedtls_pk_verify_restartable(mbedtls_pk_context
*ctx
,
264 mbedtls_md_type_t md_alg
,
265 const unsigned char *hash
, size_t hash_len
,
266 const unsigned char *sig
, size_t sig_len
,
267 mbedtls_pk_restart_ctx
*rs_ctx
) {
268 PK_VALIDATE_RET(ctx
!= NULL
);
269 PK_VALIDATE_RET((md_alg
== MBEDTLS_MD_NONE
&& hash_len
== 0) ||
271 PK_VALIDATE_RET(sig
!= NULL
);
273 if (ctx
->pk_info
== NULL
||
274 pk_hashlen_helper(md_alg
, &hash_len
) != 0)
275 return (MBEDTLS_ERR_PK_BAD_INPUT_DATA
);
277 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
278 /* optimization: use non-restartable version if restart disabled */
279 if (rs_ctx
!= NULL
&&
280 mbedtls_ecp_restart_is_enabled() &&
281 ctx
->pk_info
->verify_rs_func
!= NULL
) {
282 int ret
= MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED
;
284 if ((ret
= pk_restart_setup(rs_ctx
, ctx
->pk_info
)) != 0)
287 ret
= ctx
->pk_info
->verify_rs_func(ctx
->pk_ctx
,
288 md_alg
, hash
, hash_len
, sig
, sig_len
, rs_ctx
->rs_ctx
);
290 if (ret
!= MBEDTLS_ERR_ECP_IN_PROGRESS
)
291 mbedtls_pk_restart_free(rs_ctx
);
295 #else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
297 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
299 if (ctx
->pk_info
->verify_func
== NULL
)
300 return (MBEDTLS_ERR_PK_TYPE_MISMATCH
);
302 return (ctx
->pk_info
->verify_func(ctx
->pk_ctx
, md_alg
, hash
, hash_len
,
309 int mbedtls_pk_verify(mbedtls_pk_context
*ctx
, mbedtls_md_type_t md_alg
,
310 const unsigned char *hash
, size_t hash_len
,
311 const unsigned char *sig
, size_t sig_len
) {
312 return (mbedtls_pk_verify_restartable(ctx
, md_alg
, hash
, hash_len
,
313 sig
, sig_len
, NULL
));
317 * Verify a signature with options
319 int mbedtls_pk_verify_ext(mbedtls_pk_type_t type
, const void *options
,
320 mbedtls_pk_context
*ctx
, mbedtls_md_type_t md_alg
,
321 const unsigned char *hash
, size_t hash_len
,
322 const unsigned char *sig
, size_t sig_len
) {
323 PK_VALIDATE_RET(ctx
!= NULL
);
324 PK_VALIDATE_RET((md_alg
== MBEDTLS_MD_NONE
&& hash_len
== 0) ||
326 PK_VALIDATE_RET(sig
!= NULL
);
328 if (ctx
->pk_info
== NULL
)
329 return (MBEDTLS_ERR_PK_BAD_INPUT_DATA
);
331 if (! mbedtls_pk_can_do(ctx
, type
))
332 return (MBEDTLS_ERR_PK_TYPE_MISMATCH
);
334 if (type
== MBEDTLS_PK_RSASSA_PSS
) {
335 #if defined(MBEDTLS_RSA_C) && defined(MBEDTLS_PKCS1_V21)
336 int ret
= MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED
;
337 const mbedtls_pk_rsassa_pss_options
*pss_opts
;
339 #if SIZE_MAX > UINT_MAX
340 if (md_alg
== MBEDTLS_MD_NONE
&& UINT_MAX
< hash_len
)
341 return (MBEDTLS_ERR_PK_BAD_INPUT_DATA
);
342 #endif /* SIZE_MAX > UINT_MAX */
345 return (MBEDTLS_ERR_PK_BAD_INPUT_DATA
);
347 pss_opts
= (const mbedtls_pk_rsassa_pss_options
*) options
;
349 if (sig_len
< mbedtls_pk_get_len(ctx
))
350 return (MBEDTLS_ERR_RSA_VERIFY_FAILED
);
352 ret
= mbedtls_rsa_rsassa_pss_verify_ext(mbedtls_pk_rsa(*ctx
),
353 NULL
, NULL
, MBEDTLS_RSA_PUBLIC
,
354 md_alg
, (unsigned int) hash_len
, hash
,
355 pss_opts
->mgf1_hash_id
,
356 pss_opts
->expected_salt_len
,
361 if (sig_len
> mbedtls_pk_get_len(ctx
))
362 return (MBEDTLS_ERR_PK_SIG_LEN_MISMATCH
);
366 return (MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE
);
367 #endif /* MBEDTLS_RSA_C && MBEDTLS_PKCS1_V21 */
370 /* General case: no options */
372 return (MBEDTLS_ERR_PK_BAD_INPUT_DATA
);
374 return (mbedtls_pk_verify(ctx
, md_alg
, hash
, hash_len
, sig
, sig_len
));
378 * Make a signature (restartable)
380 int mbedtls_pk_sign_restartable(mbedtls_pk_context
*ctx
,
381 mbedtls_md_type_t md_alg
,
382 const unsigned char *hash
, size_t hash_len
,
383 unsigned char *sig
, size_t *sig_len
,
384 int (*f_rng
)(void *, unsigned char *, size_t), void *p_rng
,
385 mbedtls_pk_restart_ctx
*rs_ctx
) {
386 PK_VALIDATE_RET(ctx
!= NULL
);
387 PK_VALIDATE_RET((md_alg
== MBEDTLS_MD_NONE
&& hash_len
== 0) ||
389 PK_VALIDATE_RET(sig
!= NULL
);
391 if (ctx
->pk_info
== NULL
||
392 pk_hashlen_helper(md_alg
, &hash_len
) != 0)
393 return (MBEDTLS_ERR_PK_BAD_INPUT_DATA
);
395 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
396 /* optimization: use non-restartable version if restart disabled */
397 if (rs_ctx
!= NULL
&&
398 mbedtls_ecp_restart_is_enabled() &&
399 ctx
->pk_info
->sign_rs_func
!= NULL
) {
400 int ret
= MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED
;
402 if ((ret
= pk_restart_setup(rs_ctx
, ctx
->pk_info
)) != 0)
405 ret
= ctx
->pk_info
->sign_rs_func(ctx
->pk_ctx
, md_alg
,
406 hash
, hash_len
, sig
, sig_len
, f_rng
, p_rng
, rs_ctx
->rs_ctx
);
408 if (ret
!= MBEDTLS_ERR_ECP_IN_PROGRESS
)
409 mbedtls_pk_restart_free(rs_ctx
);
413 #else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
415 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
417 if (ctx
->pk_info
->sign_func
== NULL
)
418 return (MBEDTLS_ERR_PK_TYPE_MISMATCH
);
420 return (ctx
->pk_info
->sign_func(ctx
->pk_ctx
, md_alg
, hash
, hash_len
,
421 sig
, sig_len
, f_rng
, p_rng
));
427 int mbedtls_pk_sign(mbedtls_pk_context
*ctx
, mbedtls_md_type_t md_alg
,
428 const unsigned char *hash
, size_t hash_len
,
429 unsigned char *sig
, size_t *sig_len
,
430 int (*f_rng
)(void *, unsigned char *, size_t), void *p_rng
) {
431 return (mbedtls_pk_sign_restartable(ctx
, md_alg
, hash
, hash_len
,
432 sig
, sig_len
, f_rng
, p_rng
, NULL
));
438 int mbedtls_pk_decrypt(mbedtls_pk_context
*ctx
,
439 const unsigned char *input
, size_t ilen
,
440 unsigned char *output
, size_t *olen
, size_t osize
,
441 int (*f_rng
)(void *, unsigned char *, size_t), void *p_rng
) {
442 PK_VALIDATE_RET(ctx
!= NULL
);
443 PK_VALIDATE_RET(input
!= NULL
|| ilen
== 0);
444 PK_VALIDATE_RET(output
!= NULL
|| osize
== 0);
445 PK_VALIDATE_RET(olen
!= NULL
);
447 if (ctx
->pk_info
== NULL
)
448 return (MBEDTLS_ERR_PK_BAD_INPUT_DATA
);
450 if (ctx
->pk_info
->decrypt_func
== NULL
)
451 return (MBEDTLS_ERR_PK_TYPE_MISMATCH
);
453 return (ctx
->pk_info
->decrypt_func(ctx
->pk_ctx
, input
, ilen
,
454 output
, olen
, osize
, f_rng
, p_rng
));
460 int mbedtls_pk_encrypt(mbedtls_pk_context
*ctx
,
461 const unsigned char *input
, size_t ilen
,
462 unsigned char *output
, size_t *olen
, size_t osize
,
463 int (*f_rng
)(void *, unsigned char *, size_t), void *p_rng
) {
464 PK_VALIDATE_RET(ctx
!= NULL
);
465 PK_VALIDATE_RET(input
!= NULL
|| ilen
== 0);
466 PK_VALIDATE_RET(output
!= NULL
|| osize
== 0);
467 PK_VALIDATE_RET(olen
!= NULL
);
469 if (ctx
->pk_info
== NULL
)
470 return (MBEDTLS_ERR_PK_BAD_INPUT_DATA
);
472 if (ctx
->pk_info
->encrypt_func
== NULL
)
473 return (MBEDTLS_ERR_PK_TYPE_MISMATCH
);
475 return (ctx
->pk_info
->encrypt_func(ctx
->pk_ctx
, input
, ilen
,
476 output
, olen
, osize
, f_rng
, p_rng
));
480 * Check public-private key pair
482 int mbedtls_pk_check_pair(const mbedtls_pk_context
*pub
, const mbedtls_pk_context
*prv
) {
483 PK_VALIDATE_RET(pub
!= NULL
);
484 PK_VALIDATE_RET(prv
!= NULL
);
486 if (pub
->pk_info
== NULL
||
487 prv
->pk_info
== NULL
) {
488 return (MBEDTLS_ERR_PK_BAD_INPUT_DATA
);
491 if (prv
->pk_info
->check_pair_func
== NULL
)
492 return (MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE
);
494 if (prv
->pk_info
->type
== MBEDTLS_PK_RSA_ALT
) {
495 if (pub
->pk_info
->type
!= MBEDTLS_PK_RSA
)
496 return (MBEDTLS_ERR_PK_TYPE_MISMATCH
);
498 if (pub
->pk_info
!= prv
->pk_info
)
499 return (MBEDTLS_ERR_PK_TYPE_MISMATCH
);
502 return (prv
->pk_info
->check_pair_func(pub
->pk_ctx
, prv
->pk_ctx
));
506 * Get key size in bits
508 size_t mbedtls_pk_get_bitlen(const mbedtls_pk_context
*ctx
) {
509 /* For backward compatibility, accept NULL or a context that
510 * isn't set up yet, and return a fake value that should be safe. */
511 if (ctx
== NULL
|| ctx
->pk_info
== NULL
)
514 return (ctx
->pk_info
->get_bitlen(ctx
->pk_ctx
));
518 * Export debug information
520 int mbedtls_pk_debug(const mbedtls_pk_context
*ctx
, mbedtls_pk_debug_item
*items
) {
521 PK_VALIDATE_RET(ctx
!= NULL
);
522 if (ctx
->pk_info
== NULL
)
523 return (MBEDTLS_ERR_PK_BAD_INPUT_DATA
);
525 if (ctx
->pk_info
->debug_func
== NULL
)
526 return (MBEDTLS_ERR_PK_TYPE_MISMATCH
);
528 ctx
->pk_info
->debug_func(ctx
->pk_ctx
, items
);
533 * Access the PK type name
535 const char *mbedtls_pk_get_name(const mbedtls_pk_context
*ctx
) {
536 if (ctx
== NULL
|| ctx
->pk_info
== NULL
)
537 return ("invalid PK");
539 return (ctx
->pk_info
->name
);
545 mbedtls_pk_type_t
mbedtls_pk_get_type(const mbedtls_pk_context
*ctx
) {
546 if (ctx
== NULL
|| ctx
->pk_info
== NULL
)
547 return (MBEDTLS_PK_NONE
);
549 return (ctx
->pk_info
->type
);
552 #if defined(MBEDTLS_USE_PSA_CRYPTO)
554 * Load the key to a PSA key slot,
555 * then turn the PK context into a wrapper for that key slot.
557 * Currently only works for EC private keys.
559 int mbedtls_pk_wrap_as_opaque(mbedtls_pk_context
*pk
,
561 psa_algorithm_t hash_alg
) {
562 #if !defined(MBEDTLS_ECP_C)
566 return (MBEDTLS_ERR_PK_TYPE_MISMATCH
);
568 const mbedtls_ecp_keypair
*ec
;
569 unsigned char d
[MBEDTLS_ECP_MAX_BYTES
];
571 psa_ecc_family_t curve_id
;
572 psa_key_attributes_t attributes
= PSA_KEY_ATTRIBUTES_INIT
;
573 psa_key_type_t key_type
;
575 int ret
= MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED
;
577 /* export the private key material in the format PSA wants */
578 if (mbedtls_pk_get_type(pk
) != MBEDTLS_PK_ECKEY
)
579 return (MBEDTLS_ERR_PK_TYPE_MISMATCH
);
581 ec
= mbedtls_pk_ec(*pk
);
582 d_len
= (ec
->grp
.nbits
+ 7) / 8;
583 if ((ret
= mbedtls_mpi_write_binary(&ec
->d
, d
, d_len
)) != 0)
586 curve_id
= mbedtls_ecc_group_to_psa(ec
->grp
.id
, &bits
);
587 key_type
= PSA_KEY_TYPE_ECC_KEY_PAIR(curve_id
);
589 /* prepare the key attributes */
590 psa_set_key_type(&attributes
, key_type
);
591 psa_set_key_bits(&attributes
, bits
);
592 psa_set_key_usage_flags(&attributes
, PSA_KEY_USAGE_SIGN_HASH
);
593 psa_set_key_algorithm(&attributes
, PSA_ALG_ECDSA(hash_alg
));
595 /* import private key into PSA */
596 if (PSA_SUCCESS
!= psa_import_key(&attributes
, d
, d_len
, key
))
597 return (MBEDTLS_ERR_PK_HW_ACCEL_FAILED
);
599 /* make PK context wrap the key slot */
603 return (mbedtls_pk_setup_opaque(pk
, *key
));
604 #endif /* MBEDTLS_ECP_C */
606 #endif /* MBEDTLS_USE_PSA_CRYPTO */
607 #endif /* MBEDTLS_PK_C */