pk.h File Reference

Public Key abstraction layer. More...

#include "mbedtls/private_access.h"
#include "mbedtls/build_info.h"
#include "mbedtls/md.h"
#include "mbedtls/rsa.h"
#include "mbedtls/ecp.h"
#include "mbedtls/ecdsa.h"
#include "psa/crypto.h"

Include dependency graph for pk.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	mbedtls_pk_rsassa_pss_options
	Options for RSASSA-PSS signature verification. See mbedtls_rsa_rsassa_pss_verify_ext() More...
struct	mbedtls_pk_debug_item
	Item to send to the debug module. More...
struct	mbedtls_pk_context
	Public key container. More...
struct	mbedtls_pk_restart_ctx
	Context for resuming operations. More...

Macros
#define	MBEDTLS_ERR_PK_ALLOC_FAILED   -0x3F80
#define	MBEDTLS_ERR_PK_TYPE_MISMATCH   -0x3F00
#define	MBEDTLS_ERR_PK_BAD_INPUT_DATA   -0x3E80
#define	MBEDTLS_ERR_PK_FILE_IO_ERROR   -0x3E00
#define	MBEDTLS_ERR_PK_KEY_INVALID_VERSION   -0x3D80
#define	MBEDTLS_ERR_PK_KEY_INVALID_FORMAT   -0x3D00
#define	MBEDTLS_ERR_PK_UNKNOWN_PK_ALG   -0x3C80
#define	MBEDTLS_ERR_PK_PASSWORD_REQUIRED   -0x3C00
#define	MBEDTLS_ERR_PK_PASSWORD_MISMATCH   -0x3B80
#define	MBEDTLS_ERR_PK_INVALID_PUBKEY   -0x3B00
#define	MBEDTLS_ERR_PK_INVALID_ALG   -0x3A80
#define	MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE   -0x3A00
#define	MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE   -0x3980
#define	MBEDTLS_ERR_PK_SIG_LEN_MISMATCH   -0x3900
#define	MBEDTLS_ERR_PK_BUFFER_TOO_SMALL   -0x3880
#define	MBEDTLS_PK_SIGNATURE_MAX_SIZE   0
	Maximum size of a signature made by mbedtls_pk_sign(). More...
#define	MBEDTLS_PK_SIGNATURE_MAX_SIZE   MBEDTLS_MPI_MAX_SIZE
	Maximum size of a signature made by mbedtls_pk_sign(). More...
#define	MBEDTLS_PK_DEBUG_MAX_ITEMS   3

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() More...
typedef struct mbedtls_pk_debug_item	mbedtls_pk_debug_item
	Item to send to the debug module. More...
typedef struct mbedtls_pk_info_t	mbedtls_pk_info_t
	Public key information and operations. More...
typedef struct mbedtls_pk_context	mbedtls_pk_context
	Public key container. More...
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. More...
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)

Enumerations
enum	mbedtls_pk_type_t {   MBEDTLS_PK_NONE =0, MBEDTLS_PK_RSA, MBEDTLS_PK_ECKEY, MBEDTLS_PK_ECKEY_DH,   MBEDTLS_PK_ECDSA, MBEDTLS_PK_RSA_ALT, MBEDTLS_PK_RSASSA_PSS, MBEDTLS_PK_OPAQUE }
	Public key types. More...
enum	mbedtls_pk_debug_type { MBEDTLS_PK_DEBUG_NONE = 0, MBEDTLS_PK_DEBUG_MPI, MBEDTLS_PK_DEBUG_ECP }
	Types for interfacing with the debug module. More...

Functions
static mbedtls_rsa_context *	mbedtls_pk_rsa (const mbedtls_pk_context pk)
static mbedtls_ecp_keypair *	mbedtls_pk_ec (const mbedtls_pk_context pk)
const mbedtls_pk_info_t *	mbedtls_pk_info_from_type (mbedtls_pk_type_t pk_type)
	Return information associated with the given PK type. More...
void	mbedtls_pk_init (mbedtls_pk_context *ctx)
	Initialize a mbedtls_pk_context (as NONE). More...
void	mbedtls_pk_free (mbedtls_pk_context *ctx)
	Free the components of a mbedtls_pk_context. More...
void	mbedtls_pk_restart_init (mbedtls_pk_restart_ctx *ctx)
	Initialize a restart context. More...
void	mbedtls_pk_restart_free (mbedtls_pk_restart_ctx *ctx)
	Free the components of a restart context. More...
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. More...
int	mbedtls_pk_setup_opaque (mbedtls_pk_context *ctx, const psa_key_id_t key)
	Initialize a PK context to wrap a PSA key. More...
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. More...
size_t	mbedtls_pk_get_bitlen (const mbedtls_pk_context *ctx)
	Get the size in bits of the underlying key. More...
static size_t	mbedtls_pk_get_len (const mbedtls_pk_context *ctx)
	Get the length in bytes of the underlying key. More...
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. More...
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). More...
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() More...
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.) More...
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. More...
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() More...
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). More...
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). More...
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. More...
int	mbedtls_pk_debug (const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *items)
	Export debug information. More...
const char *	mbedtls_pk_get_name (const mbedtls_pk_context *ctx)
	Access the type name. More...
mbedtls_pk_type_t	mbedtls_pk_get_type (const mbedtls_pk_context *ctx)
	Get the key type. More...
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. More...
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. More...
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. More...
int	mbedtls_pk_parse_public_keyfile (mbedtls_pk_context *ctx, const char *path)
	Load and parse a public key. More...
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. More...
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. More...
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. More...
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. More...
int	mbedtls_pk_parse_subpubkey (unsigned char **p, const unsigned char *end, mbedtls_pk_context *pk)
	Parse a SubjectPublicKeyInfo DER structure. More...
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. More...
int	mbedtls_pk_load_file (const char *path, unsigned char **buf, size_t *n)
int	mbedtls_pk_wrap_as_opaque (mbedtls_pk_context *pk, psa_key_id_t *key, psa_algorithm_t hash_alg)
	Turn an EC key into an opaque one. More...

Detailed Description

Public Key abstraction layer.

Definition in file pk.h.

Macro Definition Documentation

#define MBEDTLS_ERR_PK_ALLOC_FAILED   -0x3F80

Memory allocation failed.

Definition at line 53 of file pk.h.

Referenced by mbedtls_psa_err_translate_pk().

#define MBEDTLS_ERR_PK_BAD_INPUT_DATA   -0x3E80

Bad input parameters to function.

Definition at line 57 of file pk.h.

Referenced by mbedtls_psa_err_translate_pk().

#define MBEDTLS_ERR_PK_BUFFER_TOO_SMALL   -0x3880

The output buffer is too small.

Definition at line 81 of file pk.h.

#define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE   -0x3980

Unavailable feature, e.g. RSA disabled for RSA key.

Definition at line 77 of file pk.h.

Referenced by mbedtls_psa_err_translate_pk().

#define MBEDTLS_ERR_PK_FILE_IO_ERROR   -0x3E00

Read/write of file failed.

Definition at line 59 of file pk.h.

#define MBEDTLS_ERR_PK_INVALID_ALG   -0x3A80

The algorithm tag or value is invalid.

Definition at line 73 of file pk.h.

#define MBEDTLS_ERR_PK_INVALID_PUBKEY   -0x3B00

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

Definition at line 71 of file pk.h.

#define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT   -0x3D00

Invalid key tag or value.

Definition at line 63 of file pk.h.

#define MBEDTLS_ERR_PK_KEY_INVALID_VERSION   -0x3D80

Unsupported key version

Definition at line 61 of file pk.h.

#define MBEDTLS_ERR_PK_PASSWORD_MISMATCH   -0x3B80

Given private key password does not allow for correct decryption.

Definition at line 69 of file pk.h.

#define MBEDTLS_ERR_PK_PASSWORD_REQUIRED   -0x3C00

Private key password can't be empty.

Definition at line 67 of file pk.h.

#define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH   -0x3900

The buffer contains a valid signature followed by more data.

Definition at line 79 of file pk.h.

#define MBEDTLS_ERR_PK_TYPE_MISMATCH   -0x3F00

Type mismatch, eg attempt to encrypt with an ECDSA key

Definition at line 55 of file pk.h.

#define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE   -0x3A00

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

Definition at line 75 of file pk.h.

#define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG   -0x3C80

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

Definition at line 65 of file pk.h.

#define MBEDTLS_PK_DEBUG_MAX_ITEMS   3

Maximum number of item send for debugging, plus 1

Definition at line 185 of file pk.h.

#define MBEDTLS_PK_SIGNATURE_MAX_SIZE   0

Maximum size of a signature made by mbedtls_pk_sign().

Definition at line 133 of file pk.h.

#define MBEDTLS_PK_SIGNATURE_MAX_SIZE   MBEDTLS_MPI_MAX_SIZE

Maximum size of a signature made by mbedtls_pk_sign().

Definition at line 133 of file pk.h.

Typedef Documentation

typedef struct mbedtls_pk_context mbedtls_pk_context

Public key container.

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

Definition at line 194 of file pk.h.

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.

Definition at line 249 of file pk.h.

typedef size_t(* mbedtls_pk_rsa_alt_key_len_func)(void *ctx)

Definition at line 256 of file pk.h.

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)

Definition at line 252 of file pk.h.

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

Enumeration Type Documentation

enum mbedtls_pk_debug_type

Types for interfacing with the debug module.

Enumerator
MBEDTLS_PK_DEBUG_NONE
MBEDTLS_PK_DEBUG_MPI
MBEDTLS_PK_DEBUG_ECP

Definition at line 167 of file pk.h.

enum mbedtls_pk_type_t

Public key types.

Enumerator
MBEDTLS_PK_NONE
MBEDTLS_PK_RSA
MBEDTLS_PK_ECKEY
MBEDTLS_PK_ECKEY_DH
MBEDTLS_PK_ECDSA
MBEDTLS_PK_RSA_ALT
MBEDTLS_PK_RSASSA_PSS
MBEDTLS_PK_OPAQUE

Definition at line 90 of file pk.h.

Function Documentation

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.

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_check_pair	(	const mbedtls_pk_context *	pub,
		const mbedtls_pk_context *	prv,
		int(*)(void *, unsigned char *, size_t)	f_rng,
		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).

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

MBEDTLS_ERR_PK_BAD_INPUT_DATA if a context is invalid.

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

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

Decrypt message (including padding if relevant).

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

Note

For RSA keys, the default padding type is PKCS#1 v1.5.

Returns

0 on success, or a specific error code.

static mbedtls_ecp_keypair* mbedtls_pk_ec ( const mbedtls_pk_context  pk )

inlinestatic

Quick access to an EC context inside a PK context.

Warning

You must make sure the PK context actually holds an EC context before using this function!

Definition at line 239 of file pk.h.

References MBEDTLS_PRIVATE.

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

Encrypt message (including padding if relevant).

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

Note

f_rng is used for padding generation.

For RSA keys, the default padding type is PKCS#1 v1.5.

Returns

0 on success, or a specific error code.

void mbedtls_pk_free

(

mbedtls_pk_context *

ctx

)

Free the components of a mbedtls_pk_context.

Parameters

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

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.

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

Referenced by mbedtls_pk_get_len().

static size_t mbedtls_pk_get_len ( const mbedtls_pk_context *  ctx )

inlinestatic

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

Definition at line 395 of file pk.h.

References mbedtls_pk_get_bitlen().

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.

MBEDTLS_PK_NONE for a context that has not been set up.

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.

int mbedtls_pk_load_file	(	const char *	path,
		unsigned char **	buf,
		size_t *	n
	)

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

Parse a private key in PEM or DER format.

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

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

The key is also checked for correctness.

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

Load and parse a private key.

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

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

The key is also checked for correctness.

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.

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.

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

The key is also checked for correctness.

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.

Parameters

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

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

The key is also checked for correctness.

Returns

0 if successful, or a specific PK or PEM 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

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.

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.

static mbedtls_rsa_context* mbedtls_pk_rsa ( const mbedtls_pk_context  pk )

inlinestatic

Quick access to an RSA context inside a PK context.

Warning

You must make sure the PK context actually holds an RSA context before using this function!

Definition at line 226 of file pk.h.

References MBEDTLS_PRIVATE.

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.

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.

Note

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

int mbedtls_pk_setup_opaque	(	mbedtls_pk_context *	ctx,
		const psa_key_id_t	key
	)

Initialize a PK context to wrap a PSA key.

Note

This function replaces mbedtls_pk_setup() for contexts that wrap a (possibly opaque) PSA key instead of storing and manipulating the key material directly.

Parameters

ctx	The context to initialize. It must be empty (type NONE).
key	The PSA key to wrap, which must hold an ECC key pair (see notes below).

Note

The 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. The wrapped key might then be independently used or destroyed.

This function is currently only available for ECC key pairs (that is, ECC keys containing private key material). Support for other key types may be added later.

Returns

0 on success.

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

MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE if the key is not an ECC key pair.

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.

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.

Note

This function replaces mbedtls_pk_setup() for RSA-alt.

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

Make signature, including padding if relevant.

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.

Note

For RSA keys, the default padding type is PKCS#1 v1.5. There is no interface in the PK module to make RSASSA-PSS signatures yet.

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

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

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

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

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 siglen, or a specific error code.

Note

For RSA keys, the default padding type is PKCS#1 v1.5. Use mbedtls_pk_verify_ext( MBEDTLS_PK_RSASSA_PSS, ... ) to verify RSASSA_PSS signatures.

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

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 siglen, or a specific error code.

Note

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

md_alg may be MBEDTLS_MD_NONE, only if hash_len != 0

If type is MBEDTLS_PK_RSASSA_PSS, then options must point to a mbedtls_pk_rsassa_pss_options structure, otherwise it must be NULL.

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

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

int mbedtls_pk_wrap_as_opaque	(	mbedtls_pk_context *	pk,
		psa_key_id_t *	key,
		psa_algorithm_t	hash_alg
	)

Turn an EC key into an opaque one.

Warning

This is a temporary utility function for tests. It might change or be removed at any time without notice.

Note

Only ECDSA keys are supported so far. Signing with the specified hash is the only allowed use of that key.

Parameters

pk	Input: the EC key to import to a PSA key. Output: a PK context wrapping that PSA key.
key	Output: a PSA key identifier. It's the caller's responsibility to call psa_destroy_key() on that key identifier after calling mbedtls_pk_free() on the PK context.
hash_alg	The hash algorithm to allow for use with that key.

Returns

0 if successful.

An Mbed TLS error code otherwise.

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_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_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

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