Mbed TLS v4.1.1
Loading...
Searching...
No Matches
pk.h
Go to the documentation of this file.
1
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_PK_H
12#define MBEDTLS_PK_H
13#define MBEDTLS_PK_HAVE_PRIVATE_HEADER
14
15#include "mbedtls/private_access.h"
16
19#include "mbedtls/md.h"
20#include "psa/crypto.h"
21
23#define MBEDTLS_ERR_PK_TYPE_MISMATCH -0x3F00
25#define MBEDTLS_ERR_PK_FILE_IO_ERROR -0x3E00
27#define MBEDTLS_ERR_PK_KEY_INVALID_VERSION -0x3D80
29#define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT -0x3D00
31#define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG -0x3C80
33#define MBEDTLS_ERR_PK_PASSWORD_REQUIRED -0x3C00
35#define MBEDTLS_ERR_PK_PASSWORD_MISMATCH -0x3B80
37#define MBEDTLS_ERR_PK_INVALID_PUBKEY -0x3B00
39#define MBEDTLS_ERR_PK_INVALID_ALG -0x3A80
41#define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE -0x3A00
43#define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980
44
45#ifdef __cplusplus
46extern "C" {
47#endif
48
49typedef enum {
51 MBEDTLS_PK_SIGALG_RSA_PKCS1V15, // PSA_ALG_RSA_PKCS1V15_SIGN
52 MBEDTLS_PK_SIGALG_RSA_PSS, // PSA_ALG_RSA_PSS_ANY_SALT
53 MBEDTLS_PK_SIGALG_ECDSA, // MBEDTLS_PK_ALG_ECDSA
55
60/* Start with PSA_SIGNATURE_MAX_SIZE. However in builds with only ECDSA, we need
61 * to account for the overhead the ASN.1 encoding used by PK. In builds with
62 * RSA, the maximum size for RSA is probably larger than ECDSA+overhead.
63 */
64#define MBEDTLS_PK_SIGNATURE_MAX_SIZE PSA_SIGNATURE_MAX_SIZE
65/* The Mbed TLS representation is different for ECDSA signatures:
66 * PSA uses the raw concatenation of r and s,
67 * whereas Mbed TLS uses the ASN.1 representation (SEQUENCE of two INTEGERs).
68 * Add the overhead of ASN.1: up to (1+2) + 2 * (1+2+1) for the
69 * types, lengths (represented by up to 2 bytes), and potential leading
70 * zeros of the INTEGERs and the SEQUENCE. */
71#if PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE + 11 > MBEDTLS_PK_SIGNATURE_MAX_SIZE
72#undef MBEDTLS_PK_SIGNATURE_MAX_SIZE
73#define MBEDTLS_PK_SIGNATURE_MAX_SIZE (PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE + 11)
74#endif
75
76/* These macros are no longer used in the library, but still used by some test
77 * code in the framework. Once 3.6 LTS branch will reach end-of-life framework's
78 * code can be adjusted and these defines removed. */
79#define MBEDTLS_PK_USE_PSA_EC_DATA
80#define MBEDTLS_PK_USE_PSA_RSA_DATA
81
82/* Opaque internal type */
84
85#define MBEDTLS_PK_MAX_EC_PUBKEY_RAW_LEN \
86 PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)
87
88#define MBEDTLS_PK_MAX_RSA_PUBKEY_RAW_LEN \
89 PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_RSA_MAX_KEY_BITS)
90
91#define MBEDTLS_PK_MAX_PUBKEY_RAW_LEN 0
92#if defined(PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY) && \
93 MBEDTLS_PK_MAX_EC_PUBKEY_RAW_LEN > MBEDTLS_PK_MAX_PUBKEY_RAW_LEN
94#undef MBEDTLS_PK_MAX_PUBKEY_RAW_LEN
95#define MBEDTLS_PK_MAX_PUBKEY_RAW_LEN MBEDTLS_PK_MAX_EC_PUBKEY_RAW_LEN
96#endif
97#if defined(PSA_WANT_KEY_TYPE_RSA_PUBLIC_KEY) && \
98 MBEDTLS_PK_MAX_RSA_PUBKEY_RAW_LEN > MBEDTLS_PK_MAX_PUBKEY_RAW_LEN
99#undef MBEDTLS_PK_MAX_PUBKEY_RAW_LEN
100#define MBEDTLS_PK_MAX_PUBKEY_RAW_LEN MBEDTLS_PK_MAX_RSA_PUBKEY_RAW_LEN
101#endif
102
106typedef struct mbedtls_pk_context {
107 /* Public key information. */
108 const mbedtls_pk_info_t *MBEDTLS_PRIVATE(pk_info);
109
110 /* The PSA key type of the key represented by the context.
111 *
112 * Note: Valid even for public keys, which are not backed by a PSA key. */
113 psa_key_type_t MBEDTLS_PRIVATE(psa_type);
114
115 /* The following field is used to store the ID of a private key.
116 *
117 * priv_id = MBEDTLS_SVC_KEY_ID_INIT when PK context wraps only the public
118 * key.
119 */
120 mbedtls_svc_key_id_t MBEDTLS_PRIVATE(priv_id);
121
122 /* Public EC or RSA key in raw format, where raw here means the format returned
123 * by psa_export_public_key(). */
124 uint8_t MBEDTLS_PRIVATE(pub_raw)[MBEDTLS_PK_MAX_PUBKEY_RAW_LEN];
125
126 /* Lenght of the raw key above in bytes. */
127 size_t MBEDTLS_PRIVATE(pub_raw_len);
128
129 /* Bits of the private/public key. */
130 size_t MBEDTLS_PRIVATE(bits);
131
132#if defined(PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY)
133 /* EC family. Only applies to EC keys. */
134 psa_ecc_family_t MBEDTLS_PRIVATE(ec_family);
135#endif /* PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY */
137
138#if defined(MBEDTLS_ECP_RESTARTABLE)
142typedef struct {
143 const mbedtls_pk_info_t *MBEDTLS_PRIVATE(pk_info); /* Public key information */
144 void *MBEDTLS_PRIVATE(rs_ctx); /* Underlying restart context */
146
147#else /* MBEDTLS_ECP_RESTARTABLE */
148/* Now we can declare functions that take a pointer to that */
150#endif /* MBEDTLS_ECP_RESTARTABLE */
151
158#if defined(PSA_WANT_ALG_DETERMINISTIC_ECDSA)
159#define MBEDTLS_PK_ALG_ECDSA(hash_alg) PSA_ALG_DETERMINISTIC_ECDSA(hash_alg)
160#else
161#define MBEDTLS_PK_ALG_ECDSA(hash_alg) PSA_ALG_ECDSA(hash_alg)
162#endif
163
181
196
197#if defined(MBEDTLS_ECP_RESTARTABLE)
204void mbedtls_pk_restart_init(mbedtls_pk_restart_ctx *ctx);
205
212void mbedtls_pk_restart_free(mbedtls_pk_restart_ctx *ctx);
213#endif /* MBEDTLS_ECP_RESTARTABLE */
214
240 const mbedtls_svc_key_id_t key);
241
250
293 psa_key_usage_t usage);
381 psa_key_usage_t usage,
382 psa_key_attributes_t *attributes);
397
398
440 const psa_key_attributes_t *attributes,
441 mbedtls_svc_key_id_t *key_id);
442
473
503
529 const unsigned char *hash, size_t hash_len,
530 const unsigned char *sig, size_t sig_len);
531
553 mbedtls_md_type_t md_alg,
554 const unsigned char *hash, size_t hash_len,
555 const unsigned char *sig, size_t sig_len,
556 mbedtls_pk_restart_ctx *rs_ctx);
557
581 const unsigned char *hash, size_t hash_len,
582 const unsigned char *sig, size_t sig_len);
583
612 const unsigned char *hash, size_t hash_len,
613 unsigned char *sig, size_t sig_size, size_t *sig_len);
614
650 mbedtls_md_type_t md_alg,
651 const unsigned char *hash, size_t hash_len,
652 unsigned char *sig, size_t sig_size, size_t *sig_len,
653 mbedtls_pk_restart_ctx *rs_ctx);
654
680 mbedtls_md_type_t md_alg,
681 const unsigned char *hash, size_t hash_len,
682 unsigned char *sig, size_t sig_size, size_t *sig_len);
683
695 const mbedtls_pk_context *prv);
696
697#if defined(MBEDTLS_PK_PARSE_C)
726 const unsigned char *key, size_t keylen,
727 const unsigned char *pwd, size_t pwdlen);
728
750 const unsigned char *key, size_t keylen);
751
752#if defined(MBEDTLS_FS_IO)
773 const char *path, const char *password);
774
790#endif /* MBEDTLS_FS_IO */
791#endif /* MBEDTLS_PK_PARSE_C */
792
793#if defined(MBEDTLS_PK_WRITE_C)
807int mbedtls_pk_write_key_der(const mbedtls_pk_context *ctx, unsigned char *buf, size_t size);
808
822int mbedtls_pk_write_pubkey_der(const mbedtls_pk_context *ctx, unsigned char *buf, size_t size);
823
824#if defined(MBEDTLS_PEM_WRITE_C)
835int mbedtls_pk_write_pubkey_pem(const mbedtls_pk_context *ctx, unsigned char *buf, size_t size);
836
847int mbedtls_pk_write_key_pem(const mbedtls_pk_context *ctx, unsigned char *buf, size_t size);
848#endif /* MBEDTLS_PEM_WRITE_C */
849
880int mbedtls_pk_write_pubkey_psa(const mbedtls_pk_context *ctx, unsigned char *buf,
881 size_t buf_size, size_t *buf_len);
882#endif /* MBEDTLS_PK_WRITE_C */
883
884#ifdef __cplusplus
885}
886#endif
887
888#endif /* MBEDTLS_PK_H */
Compatibility definitions for MbedTLS 3.x code built with MbedTLS 4.x or TF-PSA-Crypto 1....
Platform Security Architecture cryptography module.
struct psa_key_attributes_s psa_key_attributes_t
uint16_t psa_key_type_t
Encoding of a key type.
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
uint8_t psa_ecc_family_t
psa_key_id_t mbedtls_svc_key_id_t
uint32_t psa_key_usage_t
Encoding of permitted usage on a key.
This file contains the generic functions for message-digest (hashing) and HMAC.
mbedtls_md_type_t
Supported message digests.
Definition md.h:50
int mbedtls_pk_parse_key(mbedtls_pk_context *ctx, const unsigned char *key, size_t keylen, const unsigned char *pwd, size_t pwdlen)
Parse a private key in PEM or DER format.
int mbedtls_pk_sign(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, unsigned char *sig, size_t sig_size, size_t *sig_len)
Make signature.
int mbedtls_pk_write_pubkey_pem(const mbedtls_pk_context *ctx, unsigned char *buf, size_t size)
Write a public key to a PEM string.
int mbedtls_pk_copy_public_from_psa(mbedtls_svc_key_id_t key_id, mbedtls_pk_context *pk)
Populate a PK context with the public key material of a PSA key.
int mbedtls_pk_write_key_der(const mbedtls_pk_context *ctx, unsigned char *buf, size_t size)
Write a private key to a PKCS#1 or SEC1 DER structure Note: data is written at the end of the buffer!...
int mbedtls_pk_verify_ext(mbedtls_pk_sigalg_t type, mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, const unsigned char *sig, size_t sig_len)
Verify signature, selecting a specific algorithm.
size_t mbedtls_pk_get_bitlen(const mbedtls_pk_context *ctx)
Get the size in bits of the underlying key.
struct mbedtls_pk_info_t mbedtls_pk_info_t
Definition pk.h:83
int mbedtls_pk_can_do_psa(const mbedtls_pk_context *pk, psa_algorithm_t alg, psa_key_usage_t usage)
Tell if the key wrapped in the PK context is able to perform the usage operation using the alg algori...
int mbedtls_pk_sign_ext(mbedtls_pk_sigalg_t sig_type, mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, unsigned char *sig, size_t sig_size, size_t *sig_len)
Generate a signature, selecting a specific algorithm.
int mbedtls_pk_write_pubkey_der(const mbedtls_pk_context *ctx, unsigned char *buf, size_t size)
Write a public key to a SubjectPublicKeyInfo DER structure Note: data is written at the end of the bu...
#define MBEDTLS_PK_MAX_PUBKEY_RAW_LEN
Definition pk.h:91
int mbedtls_pk_write_pubkey_psa(const mbedtls_pk_context *ctx, unsigned char *buf, size_t buf_size, size_t *buf_len)
Write the public key of the provided PK context in "PSA friendly" format.
int mbedtls_pk_get_psa_attributes(const mbedtls_pk_context *pk, psa_key_usage_t usage, psa_key_attributes_t *attributes)
Determine valid PSA attributes that can be used to import a key into PSA.
int mbedtls_pk_wrap_psa(mbedtls_pk_context *ctx, const mbedtls_svc_key_id_t key)
Populate a PK context by wrapping a PSA key pair.
int mbedtls_pk_check_pair(const mbedtls_pk_context *pub, const mbedtls_pk_context *prv)
Check if a public-private pair of keys matches.
int mbedtls_pk_parse_keyfile(mbedtls_pk_context *ctx, const char *path, const char *password)
Load and parse a private key.
int mbedtls_pk_sign_restartable(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, unsigned char *sig, size_t sig_size, size_t *sig_len, mbedtls_pk_restart_ctx *rs_ctx)
Restartable version of mbedtls_pk_sign().
void mbedtls_pk_init(mbedtls_pk_context *ctx)
Initialize a mbedtls_pk_context (as empty).
int mbedtls_pk_verify_restartable(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, const unsigned char *sig, size_t sig_len, mbedtls_pk_restart_ctx *rs_ctx)
Restartable version of mbedtls_pk_verify().
psa_key_type_t mbedtls_pk_get_key_type(const mbedtls_pk_context *pk)
Get the PSA key type corresponding to the key represented by the given PK context.
int mbedtls_pk_copy_from_psa(mbedtls_svc_key_id_t key_id, mbedtls_pk_context *pk)
Populate a PK context with the key material from a PSA key.
int mbedtls_pk_verify(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, const unsigned char *sig, size_t sig_len)
Verify signature.
void mbedtls_pk_free(mbedtls_pk_context *ctx)
Empty a mbedtls_pk_context. After this, the context can be re-used as if it had been freshly initiali...
int mbedtls_pk_import_into_psa(const mbedtls_pk_context *pk, const psa_key_attributes_t *attributes, mbedtls_svc_key_id_t *key_id)
Import a key into the PSA key store.
void mbedtls_pk_restart_ctx
Definition pk.h:149
int mbedtls_pk_parse_public_key(mbedtls_pk_context *ctx, const unsigned char *key, size_t keylen)
Parse a public key in PEM or DER format.
int mbedtls_pk_parse_public_keyfile(mbedtls_pk_context *ctx, const char *path)
Load and parse a public key.
mbedtls_pk_sigalg_t
Definition pk.h:49
@ MBEDTLS_PK_SIGALG_RSA_PSS
Definition pk.h:52
@ MBEDTLS_PK_SIGALG_ECDSA
Definition pk.h:53
@ MBEDTLS_PK_SIGALG_NONE
Definition pk.h:50
@ MBEDTLS_PK_SIGALG_RSA_PKCS1V15
Definition pk.h:51
int mbedtls_pk_write_key_pem(const mbedtls_pk_context *ctx, unsigned char *buf, size_t size)
Write a private key to a PKCS#1 or SEC1 PEM string.
Public key container.
Definition pk.h:106
Build-time configuration info.