File pk.h

Public Key abstraction layer.

Defines

MBEDTLS_ERR_PK_ALLOC_FAILED: Memory allocation failed.

MBEDTLS_ERR_PK_TYPE_MISMATCH: Type mismatch, eg attempt to encrypt with an ECDSA key

MBEDTLS_ERR_PK_BAD_INPUT_DATA: Bad input parameters to function.

MBEDTLS_ERR_PK_FILE_IO_ERROR: Read/write of file failed.

MBEDTLS_ERR_PK_KEY_INVALID_VERSION: Unsupported key version

MBEDTLS_ERR_PK_KEY_INVALID_FORMAT: Invalid key tag or value.

MBEDTLS_ERR_PK_UNKNOWN_PK_ALG: Key algorithm is unsupported (only RSA and EC are supported).

MBEDTLS_ERR_PK_PASSWORD_REQUIRED: Private key password can’t be empty.

MBEDTLS_ERR_PK_PASSWORD_MISMATCH: Given private key password does not allow for correct decryption.

MBEDTLS_ERR_PK_INVALID_PUBKEY: The pubkey tag or value is invalid (only RSA and EC are supported).

MBEDTLS_ERR_PK_INVALID_ALG: The algorithm tag or value is invalid.

MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE: Elliptic curve is unsupported (only NIST curves are supported).

MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE: Unavailable feature, e.g. RSA disabled for RSA key.

MBEDTLS_ERR_PK_SIG_LEN_MISMATCH: The buffer contains a valid signature followed by more data.

MBEDTLS_ERR_PK_BUFFER_TOO_SMALL: The output buffer is too small.

MBEDTLS_PK_SIGNATURE_MAX_SIZE: Maximum size of a signature made by mbedtls_pk_sign().

MBEDTLS_PK_SIGNATURE_MAX_SIZE: Maximum size of a signature made by mbedtls_pk_sign().

MBEDTLS_PK_DEBUG_MAX_ITEMS: Maximum number of item send for debugging, plus 1

MBEDTLS_PK_MAX_EC_PUBKEY_RAW_LEN

Typedefs

typedef struct mbedtls_pk_rsassa_pss_options mbedtls_pk_rsassa_pss_options: Options for RSASSA-PSS signature verification. See mbedtls_rsa_rsassa_pss_verify_ext()

typedef struct mbedtls_pk_debug_item mbedtls_pk_debug_item: Item to send to the debug module.

typedef struct mbedtls_pk_info_t mbedtls_pk_info_t: Public key information and operations.

Note

The library does not support custom pk info structures, only built-in structures returned by mbedtls_cipher_info_from_type().

typedef struct mbedtls_pk_context mbedtls_pk_context: Public key container.

typedef int (*mbedtls_pk_rsa_alt_decrypt_func)(void *ctx, size_t *olen, const unsigned char *input, unsigned char *output, size_t output_max_len): Types for RSA-alt abstraction.

typedef int (*mbedtls_pk_rsa_alt_sign_func)(void *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, mbedtls_md_type_t md_alg, unsigned int hashlen, const unsigned char *hash, unsigned char *sig)

typedef size_t (*mbedtls_pk_rsa_alt_key_len_func)(void *ctx)

Enums

enum mbedtls_pk_type_t

Public key types.

Values:

enumerator MBEDTLS_PK_NONE

enumerator MBEDTLS_PK_RSA

enumerator MBEDTLS_PK_ECKEY

enumerator MBEDTLS_PK_ECKEY_DH

enumerator MBEDTLS_PK_ECDSA

enumerator MBEDTLS_PK_RSA_ALT

enumerator MBEDTLS_PK_RSASSA_PSS

enumerator MBEDTLS_PK_OPAQUE

enum mbedtls_pk_debug_type

Types for interfacing with the debug module.

Values:

enumerator MBEDTLS_PK_DEBUG_NONE

enumerator MBEDTLS_PK_DEBUG_MPI

enumerator MBEDTLS_PK_DEBUG_ECP

enumerator MBEDTLS_PK_DEBUG_PSA_EC

Functions

const mbedtls_pk_info_t *mbedtls_pk_info_from_type(mbedtls_pk_type_t pk_type)

Return information associated with the given PK type.

Parameters: pk_type – PK type to search for.
Returns: The PK info associated with the type or NULL if not found.

void mbedtls_pk_init(mbedtls_pk_context *ctx)

Initialize a mbedtls_pk_context (as NONE).

Parameters: ctx – The context to initialize. This must not be NULL.

void mbedtls_pk_free(mbedtls_pk_context *ctx)

Free the components of a mbedtls_pk_context.

Note

For contexts that have been set up with mbedtls_pk_setup_opaque(), this does not free the underlying PSA key and you still need to call psa_destroy_key() independently if you want to destroy that key.

Parameters: ctx – The context to clear. It must have been initialized. If this is NULL, this function does nothing.

void mbedtls_pk_restart_init(mbedtls_pk_restart_ctx *ctx)

Initialize a restart context.

Parameters: ctx – The context to initialize. This must not be NULL.

void mbedtls_pk_restart_free(mbedtls_pk_restart_ctx *ctx)

Free the components of a restart context.

Parameters: ctx – The context to clear. It must have been initialized. If this is NULL, this function does nothing.

int mbedtls_pk_setup(mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info)

Initialize a PK context with the information given and allocates the type-specific PK subcontext.

Note

For contexts holding an RSA-alt key, use mbedtls_pk_setup_rsa_alt() instead.

Parameters

ctx – Context to initialize. It must not have been set up yet (type MBEDTLS_PK_NONE).
info – Information to use

Returns

0 on success, MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input, MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.

int mbedtls_pk_setup_opaque(mbedtls_pk_context *ctx, const mbedtls_svc_key_id_t key)

Initialize a PK context to wrap a PSA key.

This function creates a PK context which wraps a PSA key. The PSA wrapped key must be an EC or RSA key pair (DH is not suported in the PK module).

Under the hood PSA functions will be used to perform the required operations and, based on the key type, used algorithms will be:

EC:
- verify, verify_ext, sign, sign_ext: ECDSA.
RSA:
- sign, decrypt: use the primary algorithm in the wrapped PSA key;
- sign_ext: RSA PSS if the pk_type is MBEDTLS_PK_RSASSA_PSS, otherwise it falls back to the sign() case;
- verify, verify_ext, encrypt: not supported.

In order for the above operations to succeed, the policy of the wrapped PSA key must allow the specified algorithm.

Opaque PK contexts wrapping an EC keys also support mbedtls_pk_check_pair(), whereas RSA ones do not.

Warning

The PSA wrapped key must remain valid as long as the wrapping PK context is in use, that is at least between the point this function is called and the point mbedtls_pk_free() is called on this context.

Parameters

ctx – The context to initialize. It must be empty (type NONE).
key – The PSA key to wrap, which must hold an ECC or RSA key pair.

Returns

0 on success.

Returns

MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input (context already used, invalid key identifier).

Returns

MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE if the key is not an ECC or RSA key pair.

Returns

MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.

int mbedtls_pk_setup_rsa_alt(mbedtls_pk_context *ctx, void *key, mbedtls_pk_rsa_alt_decrypt_func decrypt_func, mbedtls_pk_rsa_alt_sign_func sign_func, mbedtls_pk_rsa_alt_key_len_func key_len_func)

Initialize an RSA-alt context.

Note

This function replaces mbedtls_pk_setup() for RSA-alt.

Parameters

ctx – Context to initialize. It must not have been set up yet (type MBEDTLS_PK_NONE).
key – RSA key pointer
decrypt_func – Decryption function
sign_func – Signing function
key_len_func – Function returning key length in bytes

Returns

0 on success, or MBEDTLS_ERR_PK_BAD_INPUT_DATA if the context wasn’t already initialized as RSA_ALT.

size_t mbedtls_pk_get_bitlen(const mbedtls_pk_context *ctx)

Get the size in bits of the underlying key.

Parameters: ctx – The context to query. It must have been initialized.
Returns: Key size in bits, or 0 on error

static inline size_t mbedtls_pk_get_len(const mbedtls_pk_context *ctx)

Get the length in bytes of the underlying key.

Parameters: ctx – The context to query. It must have been initialized.
Returns: Key length in bytes, or 0 on error

int mbedtls_pk_can_do(const mbedtls_pk_context *ctx, mbedtls_pk_type_t type)

Tell if a context can do the operation given by type.

Parameters

ctx – The context to query. It must have been initialized.
type – The desired type.

Returns

1 if the context can do operations on the given type.

Returns

0 if the context cannot do the operations on the given type. This is always the case for a context that has been initialized but not set up, or that has been cleared with mbedtls_pk_free().

int mbedtls_pk_can_do_ext(const mbedtls_pk_context *ctx, psa_algorithm_t alg, psa_key_usage_t usage)

Tell if context can do the operation given by PSA algorithm.

Warning

Since the set of allowed algorithms and usage flags may be expanded in the future, the return value 0 should not be taken in account for non-allowed algorithms and usage flags.

Parameters

ctx – The context to query. It must have been initialized.
alg – PSA algorithm to check against, the following are allowed: PSA_ALG_RSA_PKCS1V15_SIGN(hash), PSA_ALG_RSA_PSS(hash), PSA_ALG_RSA_PKCS1V15_CRYPT, PSA_ALG_ECDSA(hash), PSA_ALG_ECDH, where hash is a specific hash.
usage – PSA usage flag to check against, must be composed of: PSA_KEY_USAGE_SIGN_HASH PSA_KEY_USAGE_DECRYPT PSA_KEY_USAGE_DERIVE. Context key must match all passed usage flags.

Returns

1 if the context can do operations on the given type.

Returns

0 if the context cannot do the operations on the given type, for non-allowed algorithms and usage flags, or for a context that has been initialized but not set up or that has been cleared with mbedtls_pk_free().

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.

The attributes determined by this function are suitable for calling mbedtls_pk_import_into_psa() to create a PSA key with the same key material.

The typical flow of operations involving this function is

psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
int ret = mbedtls_pk_get_psa_attributes(pk, &attributes);
if (ret != 0) ...; // error handling omitted
// Tweak attributes if desired
psa_key_id_t key_id = 0;
ret = mbedtls_pk_import_into_psa(pk, &attributes, &key_id);
if (ret != 0) ...; // error handling omitted

Note

This function does not support RSA-alt contexts (set up with mbedtls_pk_setup_rsa_alt()).

Parameters

pk – [in] The PK context to use. It must have been set up. It can either contain a key pair or just a public key.
usage – A single PSA_KEY_USAGE_xxx flag among the following:
- PSA_KEY_USAGE_DECRYPT: pk must contain a key pair. The output attributes will contain a key pair type, and the usage policy will allow PSA_KEY_USAGE_ENCRYPT as well as PSA_KEY_USAGE_DECRYPT.
- PSA_KEY_USAGE_DERIVE: pk must contain a key pair. The output attributes will contain a key pair type.
- PSA_KEY_USAGE_ENCRYPT: The output attributes will contain a public key type.
- PSA_KEY_USAGE_SIGN_HASH: pk must contain a key pair. The output attributes will contain a key pair type, and the usage policy will allow PSA_KEY_USAGE_VERIFY_HASH as well as PSA_KEY_USAGE_SIGN_HASH.
- PSA_KEY_USAGE_SIGN_MESSAGE: pk must contain a key pair. The output attributes will contain a key pair type, and the usage policy will allow PSA_KEY_USAGE_VERIFY_MESSAGE as well as PSA_KEY_USAGE_SIGN_MESSAGE.
- PSA_KEY_USAGE_VERIFY_HASH: The output attributes will contain a public key type.
- PSA_KEY_USAGE_VERIFY_MESSAGE: The output attributes will contain a public key type.
attributes – [out] On success, valid attributes to import the key into PSA.
- The lifetime and key identifier are unchanged. If the attribute structure was initialized or reset before calling this function, this will result in a volatile key. Call psa_set_key_identifier() before or after this function if you wish to create a persistent key. Call psa_set_key_lifetime() before or after this function if you wish to import the key in a secure element.
- The key type and bit-size are determined by the contents of the PK context. If the PK context contains a key pair, the key type can be either a key pair type or the corresponding public key type, depending on usage. If the PK context contains a public key, the key type is a public key type.
- The key’s policy is determined by the key type and the usage parameter. The usage always allows usage, exporting and copying the key, and possibly other permissions as documented for the usage parameter. The permitted algorithm policy is determined as follows based on the mbedtls_pk_type_t type of pk, the chosen usage and other factors:
  - MBEDTLS_PK_RSA whose underlying mbedtls_rsa_context has the padding mode MBEDTLS_RSA_PKCS_V15: PSA_ALG_RSA_PKCS1V15_SIGN(PSA_ALG_ANY_HASH) if usage is SIGN/VERIFY, and PSA_ALG_RSA_PKCS1V15_CRYPT if usage is ENCRYPT/DECRYPT.
  - MBEDTLS_PK_RSA whose underlying mbedtls_rsa_context has the padding mode MBEDTLS_RSA_PKCS_V21 and the digest type corresponding to the PSA algorithm hash: PSA_ALG_RSA_PSS_ANY_SALT(PSA_ALG_ANY_HASH) if usage is SIGN/VERIFY, and PSA_ALG_RSA_OAEP(hash) if usage is ENCRYPT/DECRYPT.
  - MBEDTLS_PK_RSA_ALT: not supported.
  - MBEDTLS_PK_ECDSA or MBEDTLS_PK_ECKEY if usage is SIGN/VERIFY: PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_ANY_HASH) if MBEDTLS_ECDSA_DETERMINISTIC is enabled, otherwise PSA_ALG_ECDSA(PSA_ALG_ANY_HASH).
  - MBEDTLS_PK_ECKEY_DH or MBEDTLS_PK_ECKEY if usage is DERIVE: PSA_ALG_ECDH.
  - MBEDTLS_PK_OPAQUE: same as the primary algorithm set for the underlying PSA key, except that sign/decrypt flags are removed if the type is set to a public key type. The underlying key must allow usage. Note that the enrollment algorithm set with psa_set_key_enrollment_algorithm() is not copied.

Returns

0 on success. MBEDTLS_ERR_PK_TYPE_MISMATCH if pk does not contain a key of the type identified in attributes. Another error code on other failures.

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.

This function is equivalent to calling psa_import_key() with the key material from pk.

The typical way to use this function is:

Call mbedtls_pk_get_psa_attributes() to obtain attributes for the given key.
If desired, modify the attributes, for example:
- To create a persistent key, call psa_set_key_identifier() and optionally psa_set_key_lifetime().
- To import only the public part of a key pair:
```
psa_set_key_type(&attributes,
                 PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(
                     psa_get_key_type(&attributes)));
```
- Restrict the key usage if desired.
Call mbedtls_pk_import_into_psa().

Note

This function does not support RSA-alt contexts (set up with mbedtls_pk_setup_rsa_alt()).

Parameters

pk – [in] The PK context to use. It must have been set up. It can either contain a key pair or just a public key.
attributes – [in] The attributes to use for the new key. They must be compatible with pk. In particular, the key type must match the content of pk. If pk contains a key pair, the key type in attributes can be either the key pair type or the corresponding public key type (to import only the public part).
key_id – [out] On success, the identifier of the newly created key. On error, this is MBEDTLS_SVC_KEY_ID_INIT.

Returns

0 on success. MBEDTLS_ERR_PK_TYPE_MISMATCH if pk does not contain a key of the type identified in attributes. Another error code on other failures.

int mbedtls_pk_copy_from_psa(mbedtls_svc_key_id_t key_id, mbedtls_pk_context *pk)

Create a PK context starting from a key stored in PSA. This key:

must be exportable and
must be an RSA or EC key pair or public key (FFDH is not supported in PK).

The resulting PK object will be a transparent type:

MBEDTLS_PK_RSA for RSA keys or
MBEDTLS_PK_ECKEY for EC keys.

Once this functions returns the PK object will be completely independent from the original PSA key that it was generated from. Calling mbedtls_pk_sign(), mbedtls_pk_verify(), mbedtls_pk_encrypt(), mbedtls_pk_decrypt() on the resulting PK context will perform the corresponding algorithm for that PK context type.

For ECDSA, the choice of deterministic vs randomized will be based on the compile-time setting MBEDTLS_ECDSA_DETERMINISTIC.
For an RSA key, the output PK context will allow both encrypt/decrypt and sign/verify regardless of the original key’s policy. The original key’s policy determines the output key’s padding mode: PCKS1 v2.1 is set if the PSA key policy is OAEP or PSS, otherwise PKCS1 v1.5 is set.

Parameters

key_id – The key identifier of the key stored in PSA.
pk – The PK context that will be filled. It must be initialized, but not set up.

Returns

0 on success.

Returns

MBEDTLS_ERR_PK_BAD_INPUT_DATA in case the provided input parameters are not correct.

int mbedtls_pk_copy_public_from_psa(mbedtls_svc_key_id_t key_id, mbedtls_pk_context *pk)

Create a PK context for the public key of a PSA key.

             The key must be an RSA or ECC key. It can be either a
             public key or a key pair, and only the public key is copied.
             The resulting PK object will be a transparent type:
             - #MBEDTLS_PK_RSA for RSA keys or
             - #MBEDTLS_PK_ECKEY for EC keys.

             Once this functions returns the PK object will be completely
             independent from the original PSA key that it was generated
             from.
             Calling mbedtls_pk_verify() or
             mbedtls_pk_encrypt() on the resulting
             PK context will perform the corresponding algorithm for that
             PK context type.

             For an RSA key, the output PK context will allow both
             encrypt and verify regardless of the original key's policy.
             The original key's policy determines the output key's padding
             mode: PCKS1 v2.1 is set if the PSA key policy is OAEP or PSS,
             otherwise PKCS1 v1.5 is set.

Parameters

key_id – The key identifier of the key stored in PSA.
pk – The PK context that will be filled. It must be initialized, but not set up.

Returns

0 on success.

Returns

MBEDTLS_ERR_PK_BAD_INPUT_DATA in case the provided input parameters are not correct.

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 (including padding if relevant).

Note

For keys of type MBEDTLS_PK_RSA, the signature algorithm is either PKCS#1 v1.5 or PSS (accepting any salt length), depending on the padding mode in the underlying RSA context. For a pk object constructed by parsing, this is PKCS#1 v1.5 by default. Use mbedtls_pk_verify_ext() to explicitly select a different algorithm.

Parameters

ctx – The PK context to use. It must have been set up.
md_alg – Hash algorithm used. This can be MBEDTLS_MD_NONE if the signature algorithm does not rely on a hash algorithm (non-deterministic ECDSA, RSA PKCS#1 v1.5). For PKCS#1 v1.5, if md_alg is MBEDTLS_MD_NONE, then hash is the DigestInfo structure used by RFC 8017 9.2 steps 3—6. If md_alg is a valid hash algorithm then hash is the digest itself, and this function calculates the DigestInfo encoding internally.
hash – Hash of the message to sign
hash_len – Hash length
sig – Signature to verify
sig_len – Signature length

Returns

0 on success (signature is valid), MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid signature in sig but its length is less than sig_len, or a specific error code.

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()

Note

Performs the same job as mbedtls_pk_verify(), but can return early and restart according to the limit set with mbedtls_ecp_set_max_ops() to reduce blocking for ECC operations. For RSA, same as mbedtls_pk_verify().

Parameters

ctx – The PK context to use. It must have been set up.
md_alg – Hash algorithm used (see notes)
hash – Hash of the message to sign
hash_len – Hash length or 0 (see notes)
sig – Signature to verify
sig_len – Signature length
rs_ctx – Restart context (NULL to disable restart)

Returns

See mbedtls_pk_verify(), or

Returns

MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of operations was reached: see mbedtls_ecp_set_max_ops().

int mbedtls_pk_verify_ext(mbedtls_pk_type_t type, const void *options, 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, with options. (Includes verification of the padding depending on type.)

Note

If hash_len is 0, then the length associated with md_alg is used instead, or an error returned if it is invalid.

Note

md_alg may be MBEDTLS_MD_NONE, only if hash_len != 0

Note

If type is MBEDTLS_PK_RSASSA_PSS, then options must point to a mbedtls_pk_rsassa_pss_options structure, otherwise it must be NULL. Note that if MBEDTLS_USE_PSA_CRYPTO is defined, the salt length is not verified as PSA_ALG_RSA_PSS_ANY_SALT is used.

Parameters

type – Signature type (inc. possible padding type) to verify
options – Pointer to type-specific options, or NULL
ctx – The PK context to use. It must have been set up.
md_alg – Hash algorithm used (see notes)
hash – Hash of the message to sign
hash_len – Hash length or 0 (see notes)
sig – Signature to verify
sig_len – Signature length

Returns

0 on success (signature is valid), MBEDTLS_ERR_PK_TYPE_MISMATCH if the PK context can’t be used for this type of signatures, MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid signature in sig but its length is less than sig_len, or a specific error code.

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, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng)

Make signature, including padding if relevant.

Note

For keys of type MBEDTLS_PK_RSA, the signature algorithm is either PKCS#1 v1.5 or PSS (using the largest possible salt length up to the hash length), depending on the padding mode in the underlying RSA context. For a pk object constructed by parsing, this is PKCS#1 v1.5 by default. Use mbedtls_pk_verify_ext() to explicitly select a different algorithm.

Note

For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0. For ECDSA, md_alg may never be MBEDTLS_MD_NONE.

Parameters

ctx – The PK context to use. It must have been set up with a private key.
md_alg – Hash algorithm used (see notes)
hash – Hash of the message to sign
hash_len – Hash length
sig – Place to write the signature. It must have enough room for the signature. MBEDTLS_PK_SIGNATURE_MAX_SIZE is always enough. You may use a smaller buffer if it is large enough given the key type.
sig_size – The size of the sig buffer in bytes.
sig_len – On successful return, the number of bytes written to sig.
f_rng – RNG function, must not be NULL.
p_rng – RNG parameter

Returns

0 on success, or a specific error code.

int mbedtls_pk_sign_ext(mbedtls_pk_type_t pk_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, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng)

Make signature given a signature type.

Note

When pk_type is MBEDTLS_PK_RSASSA_PSS, see PSA_ALG_RSA_PSS for a description of PSS options used.

Note

For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0. For ECDSA, md_alg may never be MBEDTLS_MD_NONE.

Parameters

pk_type – Signature type.
ctx – The PK context to use. It must have been set up with a private key.
md_alg – Hash algorithm used (see notes)
hash – Hash of the message to sign
hash_len – Hash length
sig – Place to write the signature. It must have enough room for the signature. MBEDTLS_PK_SIGNATURE_MAX_SIZE is always enough. You may use a smaller buffer if it is large enough given the key type.
sig_size – The size of the sig buffer in bytes.
sig_len – On successful return, the number of bytes written to sig.
f_rng – RNG function, must not be NULL.
p_rng – RNG parameter

Returns

0 on success, or a specific error code.

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, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, mbedtls_pk_restart_ctx *rs_ctx)

Restartable version of mbedtls_pk_sign()

Note

Performs the same job as mbedtls_pk_sign(), but can return early and restart according to the limit set with mbedtls_ecp_set_max_ops() to reduce blocking for ECC operations. For RSA, same as mbedtls_pk_sign().

Parameters

ctx – The PK context to use. It must have been set up with a private key.
md_alg – Hash algorithm used (see notes for mbedtls_pk_sign())
hash – Hash of the message to sign
hash_len – Hash length
sig – Place to write the signature. It must have enough room for the signature. MBEDTLS_PK_SIGNATURE_MAX_SIZE is always enough. You may use a smaller buffer if it is large enough given the key type.
sig_size – The size of the sig buffer in bytes.
sig_len – On successful return, the number of bytes written to sig.
f_rng – RNG function, must not be NULL.
p_rng – RNG parameter
rs_ctx – Restart context (NULL to disable restart)

Returns

See mbedtls_pk_sign().

Returns

MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of operations was reached: see mbedtls_ecp_set_max_ops().

int mbedtls_pk_decrypt(mbedtls_pk_context *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen, size_t osize, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng)

Decrypt message (including padding if relevant).

Note

For keys of type MBEDTLS_PK_RSA, the signature algorithm is either PKCS#1 v1.5 or OAEP, depending on the padding mode in the underlying RSA context. For a pk object constructed by parsing, this is PKCS#1 v1.5 by default.

Parameters

ctx – The PK context to use. It must have been set up with a private key.
input – Input to decrypt
ilen – Input size
output – Decrypted output
olen – Decrypted message length
osize – Size of the output buffer
f_rng – RNG function, must not be NULL.
p_rng – RNG parameter

Returns

0 on success, or a specific error code.

int mbedtls_pk_encrypt(mbedtls_pk_context *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen, size_t osize, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng)

Encrypt message (including padding if relevant).

Note

For keys of type MBEDTLS_PK_RSA, the signature algorithm is either PKCS#1 v1.5 or OAEP, depending on the padding mode in the underlying RSA context. For a pk object constructed by parsing, this is PKCS#1 v1.5 by default.

Note

f_rng is used for padding generation.

Parameters

ctx – The PK context to use. It must have been set up.
input – Message to encrypt
ilen – Message size
output – Encrypted output
olen – Encrypted output length
osize – Size of the output buffer
f_rng – RNG function, must not be NULL.
p_rng – RNG parameter

Returns

0 on success, or a specific error code.

int mbedtls_pk_check_pair(const mbedtls_pk_context *pub, const mbedtls_pk_context *prv, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng)

Check if a public-private pair of keys matches.

Parameters

pub – Context holding a public key.
prv – Context holding a private (and public) key.
f_rng – RNG function, must not be NULL.
p_rng – RNG parameter

Returns

0 on success (keys were checked and match each other).

Returns

MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE if the keys could not be checked - in that case they may or may not match.

Returns

MBEDTLS_ERR_PK_BAD_INPUT_DATA if a context is invalid.

Returns

Another non-zero value if the keys do not match.

int mbedtls_pk_debug(const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *items)

Export debug information.

Parameters

ctx – The PK context to use. It must have been initialized.
items – Place to write debug items

Returns

0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA

const char *mbedtls_pk_get_name(const mbedtls_pk_context *ctx)

Access the type name.

Parameters: ctx – The PK context to use. It must have been initialized.
Returns: Type name on success, or “invalid PK”

mbedtls_pk_type_t mbedtls_pk_get_type(const mbedtls_pk_context *ctx)

Get the key type.

Parameters: ctx – The PK context to use. It must have been initialized.
Returns: Type on success.
Returns: MBEDTLS_PK_NONE for a context that has not been set up.

static inline mbedtls_rsa_context *mbedtls_pk_rsa(const mbedtls_pk_context pk)

Quick access to an RSA context inside a PK context.

Warning

This function can only be used when the type of the context, as returned by mbedtls_pk_get_type(), is MBEDTLS_PK_RSA. Ensuring that is the caller’s responsibility. Alternatively, you can check whether this function returns NULL.

Returns: The internal RSA context held by the PK context, or NULL.

static inline mbedtls_ecp_keypair *mbedtls_pk_ec(const mbedtls_pk_context pk)

Quick access to an EC context inside a PK context.

Warning

This function can only be used when the type of the context, as returned by mbedtls_pk_get_type(), is MBEDTLS_PK_ECKEY, MBEDTLS_PK_ECKEY_DH, or MBEDTLS_PK_ECDSA. Ensuring that is the caller’s responsibility. Alternatively, you can check whether this function returns NULL.

Returns: The internal EC context held by the PK context, or NULL.

int mbedtls_pk_parse_key(mbedtls_pk_context *ctx, const unsigned char *key, size_t keylen, const unsigned char *pwd, size_t pwdlen, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng)

Parse a private key in PEM or DER format.

Note

If MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto subsystem must have been initialized by calling psa_crypto_init() before calling this function.

Note

On entry, ctx must be empty, either freshly initialised with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a specific key type, check the result with mbedtls_pk_can_do().

Note

The key is also checked for correctness.

Parameters

ctx – The PK context to fill. It must have been initialized but not set up.
key – Input buffer to parse. The buffer must contain the input exactly, with no extra trailing material. For PEM, the buffer must contain a null-terminated string.
keylen – Size of key in bytes. For PEM data, this includes the terminating null byte, so keylen must be equal to strlen(key) + 1.
pwd – Optional password for decryption. Pass NULL if expecting a non-encrypted key. Pass a string of pwdlen bytes if expecting an encrypted key; a non-encrypted key will also be accepted. The empty password is not supported.
pwdlen – Size of the password in bytes. Ignored if pwd is NULL.
f_rng – RNG function, must not be NULL. Used for blinding.
p_rng – RNG parameter

Returns

0 if successful, or a specific PK or PEM error code

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.

Note

If MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto subsystem must have been initialized by calling psa_crypto_init() before calling this function.

Note

On entry, ctx must be empty, either freshly initialised with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a specific key type, check the result with mbedtls_pk_can_do().

Note

For compressed points, see MBEDTLS_ECP_PF_COMPRESSED for limitations.

Note

The key is also checked for correctness.

Parameters

ctx – The PK context to fill. It must have been initialized but not set up.
key – Input buffer to parse. The buffer must contain the input exactly, with no extra trailing material. For PEM, the buffer must contain a null-terminated string.
keylen – Size of key in bytes. For PEM data, this includes the terminating null byte, so keylen must be equal to strlen(key) + 1.

Returns

0 if successful, or a specific PK or PEM error code

int mbedtls_pk_parse_keyfile(mbedtls_pk_context *ctx, const char *path, const char *password, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng)

Load and parse a private key.

Note

If MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto subsystem must have been initialized by calling psa_crypto_init() before calling this function.

Note

On entry, ctx must be empty, either freshly initialised with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a specific key type, check the result with mbedtls_pk_can_do().

Note

The key is also checked for correctness.

Parameters

ctx – The PK context to fill. It must have been initialized but not set up.
path – filename to read the private key from
password – Optional password to decrypt the file. Pass NULL if expecting a non-encrypted key. Pass a null-terminated string if expecting an encrypted key; a non-encrypted key will also be accepted. The empty password is not supported.
f_rng – RNG function, must not be NULL. Used for blinding.
p_rng – RNG parameter

Returns

0 if successful, or a specific PK or PEM error code

int mbedtls_pk_parse_public_keyfile(mbedtls_pk_context *ctx, const char *path)

Load and parse a public key.

Note

On entry, ctx must be empty, either freshly initialised with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a specific key type, check the result with mbedtls_pk_can_do().

Note

The key is also checked for correctness.

Parameters

ctx – The PK context to fill. It must have been initialized but not set up.
path – filename to read the public key from

Returns

0 if successful, or a specific PK or PEM error code

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! Use the return value to determine where you should start using the buffer.

Parameters

ctx – PK context which must contain a valid private key.
buf – buffer to write to
size – size of the buffer

Returns

length of data written if successful, or a specific error code

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 buffer! Use the return value to determine where you should start using the buffer.

Parameters

ctx – PK context which must contain a valid public or private key.
buf – buffer to write to
size – size of the buffer

Returns

length of data written if successful, or a specific error code

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.

Parameters

ctx – PK context which must contain a valid public or private key.
buf – Buffer to write to. The output includes a terminating null byte.
size – Size of the buffer in bytes.

Returns

0 if successful, or a specific error code

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.

Parameters

ctx – PK context which must contain a valid private key.
buf – Buffer to write to. The output includes a terminating null byte.
size – Size of the buffer in bytes.

Returns

0 if successful, or a specific error code

int mbedtls_pk_parse_subpubkey(unsigned char **p, const unsigned char *end, mbedtls_pk_context *pk)

Parse a SubjectPublicKeyInfo DER structure.

Parameters

p – the position in the ASN.1 data
end – end of the buffer
pk – The PK context to fill. It must have been initialized but not set up.

Returns

0 if successful, or a specific PK error code

int mbedtls_pk_write_pubkey(unsigned char **p, unsigned char *start, const mbedtls_pk_context *key)

Write a subjectPublicKey to ASN.1 data Note: function works backwards in data buffer.

Parameters

p – reference to current position pointer
start – start of the buffer (for bounds-checking)
key – PK context which must contain a valid public or private key.

Returns

the length written or a negative error code

struct mbedtls_pk_rsassa_pss_options

#include <pk.h>

Options for RSASSA-PSS signature verification. See mbedtls_rsa_rsassa_pss_verify_ext()

Public Members

mbedtls_md_type_t mgf1_hash_id: The digest to use for MGF1 in PSS.

Note

When MBEDTLS_USE_PSA_CRYPTO is enabled and MBEDTLS_RSA_C is disabled, this must be equal to the md_alg argument passed to mbedtls_pk_verify_ext(). In a future version of the library, this constraint may apply whenever MBEDTLS_USE_PSA_CRYPTO is enabled regardless of the status of MBEDTLS_RSA_C.

int expected_salt_len: The expected length of the salt, in bytes. This may be MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.

Note

When MBEDTLS_USE_PSA_CRYPTO is enabled, only MBEDTLS_RSA_SALT_LEN_ANY is valid. Any other value may be ignored (allowing any salt length).

struct mbedtls_pk_debug_item

#include <pk.h>

Item to send to the debug module.

Public Members

mbedtls_pk_debug_type private_type

const char *private_name

void *private_value

struct mbedtls_pk_context

#include <pk.h>

Public key container.

Public Members

const mbedtls_pk_info_t *private_pk_info: Public key information

void *private_pk_ctx: Underlying public key context

mbedtls_svc_key_id_t private_priv_id: Key ID for opaque keys

struct mbedtls_pk_restart_ctx

#include <pk.h>

Context for resuming operations.

Public Members

const mbedtls_pk_info_t *private_pk_info: Public key information

void *private_rs_ctx: Underlying restart context