Mbed TLS v3.6.1
Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Enumerations | Functions
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...
 

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().
 
#define MBEDTLS_PK_DEBUG_MAX_ITEMS   3
 
#define MBEDTLS_PK_MAX_EC_PUBKEY_RAW_LEN    PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)
 

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.
 
typedef struct mbedtls_pk_context mbedtls_pk_context
 Public key container.
 
typedef void mbedtls_pk_restart_ctx
 
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)
 

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 , MBEDTLS_PK_DEBUG_PSA_EC }
 Types for interfacing with the debug module. More...
 

Functions

const mbedtls_pk_info_tmbedtls_pk_info_from_type (mbedtls_pk_type_t pk_type)
 Return information associated with the given PK type.
 
void mbedtls_pk_init (mbedtls_pk_context *ctx)
 Initialize a mbedtls_pk_context (as NONE).
 
void mbedtls_pk_free (mbedtls_pk_context *ctx)
 Free the components of a mbedtls_pk_context.
 
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.
 
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.
 
size_t mbedtls_pk_get_bitlen (const mbedtls_pk_context *ctx)
 Get the size in bits of the underlying key.
 
static size_t mbedtls_pk_get_len (const mbedtls_pk_context *ctx)
 Get the length in bytes of the underlying key.
 
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.
 
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_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.
 
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:
 
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.
 
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).
 
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()
 
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.)
 
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.
 
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.
 
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()
 
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).
 
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).
 
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.
 
int mbedtls_pk_debug (const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *items)
 Export debug information.
 
const char * mbedtls_pk_get_name (const mbedtls_pk_context *ctx)
 Access the type name.
 
mbedtls_pk_type_t mbedtls_pk_get_type (const mbedtls_pk_context *ctx)
 Get the key type.
 
static mbedtls_rsa_contextmbedtls_pk_rsa (const mbedtls_pk_context pk)
 
static mbedtls_ecp_keypairmbedtls_pk_ec (const mbedtls_pk_context pk)
 
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.
 
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_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.
 
int mbedtls_pk_parse_public_keyfile (mbedtls_pk_context *ctx, const char *path)
 Load and parse a public 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! Use the return value to determine where you should start using the buffer.
 
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.
 
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_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.
 
int mbedtls_pk_parse_subpubkey (unsigned char **p, const unsigned char *end, mbedtls_pk_context *pk)
 Parse a SubjectPublicKeyInfo DER structure.
 
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.
 

Detailed Description

Public Key abstraction layer.

Definition in file pk.h.

Macro Definition Documentation

◆ MBEDTLS_ERR_PK_ALLOC_FAILED

#define MBEDTLS_ERR_PK_ALLOC_FAILED   -0x3F80

Memory allocation failed.

Definition at line 36 of file pk.h.

◆ MBEDTLS_ERR_PK_BAD_INPUT_DATA

#define MBEDTLS_ERR_PK_BAD_INPUT_DATA   -0x3E80

Bad input parameters to function.

Definition at line 40 of file pk.h.

◆ MBEDTLS_ERR_PK_BUFFER_TOO_SMALL

#define MBEDTLS_ERR_PK_BUFFER_TOO_SMALL   -0x3880

The output buffer is too small.

Definition at line 64 of file pk.h.

◆ MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE

#define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE   -0x3980

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

Definition at line 60 of file pk.h.

◆ MBEDTLS_ERR_PK_FILE_IO_ERROR

#define MBEDTLS_ERR_PK_FILE_IO_ERROR   -0x3E00

Read/write of file failed.

Definition at line 42 of file pk.h.

◆ MBEDTLS_ERR_PK_INVALID_ALG

#define MBEDTLS_ERR_PK_INVALID_ALG   -0x3A80

The algorithm tag or value is invalid.

Definition at line 56 of file pk.h.

◆ MBEDTLS_ERR_PK_INVALID_PUBKEY

#define MBEDTLS_ERR_PK_INVALID_PUBKEY   -0x3B00

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

Definition at line 54 of file pk.h.

◆ MBEDTLS_ERR_PK_KEY_INVALID_FORMAT

#define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT   -0x3D00

Invalid key tag or value.

Definition at line 46 of file pk.h.

◆ MBEDTLS_ERR_PK_KEY_INVALID_VERSION

#define MBEDTLS_ERR_PK_KEY_INVALID_VERSION   -0x3D80

Unsupported key version

Definition at line 44 of file pk.h.

◆ MBEDTLS_ERR_PK_PASSWORD_MISMATCH

#define MBEDTLS_ERR_PK_PASSWORD_MISMATCH   -0x3B80

Given private key password does not allow for correct decryption.

Definition at line 52 of file pk.h.

◆ MBEDTLS_ERR_PK_PASSWORD_REQUIRED

#define MBEDTLS_ERR_PK_PASSWORD_REQUIRED   -0x3C00

Private key password can't be empty.

Definition at line 50 of file pk.h.

◆ MBEDTLS_ERR_PK_SIG_LEN_MISMATCH

#define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH   -0x3900

The buffer contains a valid signature followed by more data.

Definition at line 62 of file pk.h.

◆ MBEDTLS_ERR_PK_TYPE_MISMATCH

#define MBEDTLS_ERR_PK_TYPE_MISMATCH   -0x3F00

Type mismatch, eg attempt to encrypt with an ECDSA key

Definition at line 38 of file pk.h.

◆ MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE

#define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE   -0x3A00

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

Definition at line 58 of file pk.h.

◆ MBEDTLS_ERR_PK_UNKNOWN_PK_ALG

#define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG   -0x3C80

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

Definition at line 48 of file pk.h.

◆ MBEDTLS_PK_DEBUG_MAX_ITEMS

#define MBEDTLS_PK_DEBUG_MAX_ITEMS   3

Maximum number of item send for debugging, plus 1

Definition at line 204 of file pk.h.

◆ MBEDTLS_PK_MAX_EC_PUBKEY_RAW_LEN

#define MBEDTLS_PK_MAX_EC_PUBKEY_RAW_LEN    PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)

Definition at line 215 of file pk.h.

◆ MBEDTLS_PK_SIGNATURE_MAX_SIZE

#define MBEDTLS_PK_SIGNATURE_MAX_SIZE   0

Maximum size of a signature made by mbedtls_pk_sign().

Definition at line 122 of file pk.h.

Typedef Documentation

◆ mbedtls_pk_context

Public key container.

◆ mbedtls_pk_debug_item

Item to send to the debug module.

◆ 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 213 of file pk.h.

◆ mbedtls_pk_restart_ctx

typedef void mbedtls_pk_restart_ctx

Definition at line 277 of file pk.h.

◆ mbedtls_pk_rsa_alt_decrypt_func

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 284 of file pk.h.

◆ mbedtls_pk_rsa_alt_key_len_func

typedef size_t(* mbedtls_pk_rsa_alt_key_len_func) (void *ctx)

Definition at line 292 of file pk.h.

◆ mbedtls_pk_rsa_alt_sign_func

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 287 of file pk.h.

◆ mbedtls_pk_rsassa_pss_options

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

Enumeration Type Documentation

◆ mbedtls_pk_debug_type

Types for interfacing with the debug module.

Enumerator
MBEDTLS_PK_DEBUG_NONE 
MBEDTLS_PK_DEBUG_MPI 
MBEDTLS_PK_DEBUG_ECP 
MBEDTLS_PK_DEBUG_PSA_EC 

Definition at line 187 of file pk.h.

◆ 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 73 of file pk.h.

Function Documentation

◆ mbedtls_pk_can_do()

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
ctxThe context to query. It must have been initialized.
typeThe 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().

◆ mbedtls_pk_check_pair()

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
pubContext holding a public key.
prvContext holding a private (and public) key.
f_rngRNG function, must not be NULL.
p_rngRNG 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.

◆ mbedtls_pk_copy_from_psa()

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:

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_idThe key identifier of the key stored in PSA.
pkThe PK context that will be filled. It must be initialized, but not set up.
Returns
0 on success.
MBEDTLS_ERR_PK_BAD_INPUT_DATA in case the provided input parameters are not correct.

◆ mbedtls_pk_copy_public_from_psa()

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_idThe key identifier of the key stored in PSA.
pkThe PK context that will be filled. It must be initialized, but not set up.
Returns
0 on success.
MBEDTLS_ERR_PK_BAD_INPUT_DATA in case the provided input parameters are not correct.

◆ mbedtls_pk_debug()

int mbedtls_pk_debug ( const mbedtls_pk_context ctx,
mbedtls_pk_debug_item items 
)

Export debug information.

Parameters
ctxThe PK context to use. It must have been initialized.
itemsPlace to write debug items
Returns
0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA

◆ mbedtls_pk_decrypt()

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
ctxThe PK context to use. It must have been set up with a private key.
inputInput to decrypt
ilenInput size
outputDecrypted output
olenDecrypted message length
osizeSize of the output buffer
f_rngRNG function, must not be NULL.
p_rngRNG parameter
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.
Returns
0 on success, or a specific error code.

◆ mbedtls_pk_ec()

static mbedtls_ecp_keypair * mbedtls_pk_ec ( const mbedtls_pk_context  pk)
inlinestatic

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.

Definition at line 1060 of file pk.h.

References MBEDTLS_PK_ECDSA, MBEDTLS_PK_ECKEY, MBEDTLS_PK_ECKEY_DH, mbedtls_pk_get_type(), and MBEDTLS_PRIVATE.

◆ mbedtls_pk_encrypt()

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
ctxThe PK context to use. It must have been set up.
inputMessage to encrypt
ilenMessage size
outputEncrypted output
olenEncrypted output length
osizeSize of the output buffer
f_rngRNG function, must not be NULL.
p_rngRNG parameter
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.
f_rng is used for padding generation.
Returns
0 on success, or a specific error code.

◆ mbedtls_pk_free()

void mbedtls_pk_free ( mbedtls_pk_context ctx)

Free the components of a mbedtls_pk_context.

Parameters
ctxThe 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.

◆ mbedtls_pk_get_bitlen()

size_t mbedtls_pk_get_bitlen ( const mbedtls_pk_context ctx)

Get the size in bits of the underlying key.

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

Referenced by mbedtls_pk_get_len().

◆ 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
ctxThe context to query. It must have been initialized.
Returns
Key length in bytes, or 0 on error

Definition at line 439 of file pk.h.

References mbedtls_pk_get_bitlen().

◆ mbedtls_pk_get_name()

const char * mbedtls_pk_get_name ( const mbedtls_pk_context ctx)

Access the type name.

Parameters
ctxThe PK context to use. It must have been initialized.
Returns
Type name on success, or "invalid PK"

◆ mbedtls_pk_get_psa_attributes()

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

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
#define PSA_KEY_ATTRIBUTES_INIT
uint32_t psa_key_id_t
Definition: crypto_types.h:275
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_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.
Note
This function does not support RSA-alt contexts (set up with mbedtls_pk_setup_rsa_alt()).
Parameters
[in]pkThe PK context to use. It must have been set up. It can either contain a key pair or just a public key.
usageA single PSA_KEY_USAGE_xxx flag among the following:
[out]attributesOn success, valid attributes to import the key into PSA.
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.

◆ mbedtls_pk_get_type()

mbedtls_pk_type_t mbedtls_pk_get_type ( const mbedtls_pk_context ctx)

Get the key type.

Parameters
ctxThe 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.

Referenced by mbedtls_pk_ec(), and mbedtls_pk_rsa().

◆ mbedtls_pk_import_into_psa()

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:

  1. Call mbedtls_pk_get_psa_attributes() to obtain attributes for the given key.
  2. 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.
  3. Call mbedtls_pk_import_into_psa().
Note
This function does not support RSA-alt contexts (set up with mbedtls_pk_setup_rsa_alt()).
Parameters
[in]pkThe PK context to use. It must have been set up. It can either contain a key pair or just a public key.
[in]attributesThe 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).
[out]key_idOn 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.

◆ mbedtls_pk_info_from_type()

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_typePK type to search for.
Returns
The PK info associated with the type or NULL if not found.

◆ mbedtls_pk_init()

void mbedtls_pk_init ( mbedtls_pk_context ctx)

Initialize a mbedtls_pk_context (as NONE).

Parameters
ctxThe context to initialize. This must not be NULL.

◆ mbedtls_pk_parse_key()

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.

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.
Parameters
ctxThe PK context to fill. It must have been initialized but not set up.
keyInput 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.
keylenSize of key in bytes. For PEM data, this includes the terminating null byte, so keylen must be equal to strlen(key) + 1.
pwdOptional 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.
pwdlenSize of the password in bytes. Ignored if pwd is NULL.
f_rngRNG function, must not be NULL. Used for blinding.
p_rngRNG 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

◆ mbedtls_pk_parse_keyfile()

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.

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.
Parameters
ctxThe PK context to fill. It must have been initialized but not set up.
pathfilename to read the private key from
passwordOptional 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_rngRNG function, must not be NULL. Used for blinding.
p_rngRNG 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

◆ mbedtls_pk_parse_public_key()

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.
Parameters
ctxThe PK context to fill. It must have been initialized but not set up.
keyInput 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.
keylenSize 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().
For compressed points, see MBEDTLS_ECP_PF_COMPRESSED for limitations.
The key is also checked for correctness.
Returns
0 if successful, or a specific PK or PEM error code

◆ mbedtls_pk_parse_public_keyfile()

int mbedtls_pk_parse_public_keyfile ( mbedtls_pk_context ctx,
const char *  path 
)

Load and parse a public key.

Parameters
ctxThe PK context to fill. It must have been initialized but not set up.
pathfilename 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

◆ mbedtls_pk_parse_subpubkey()

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

Parse a SubjectPublicKeyInfo DER structure.

Parameters
pthe position in the ASN.1 data
endend of the buffer
pkThe PK context to fill. It must have been initialized but not set up.
Returns
0 if successful, or a specific PK error code

◆ mbedtls_pk_rsa()

static mbedtls_rsa_context * mbedtls_pk_rsa ( const mbedtls_pk_context  pk)
inlinestatic

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.

Definition at line 1037 of file pk.h.

References mbedtls_pk_get_type(), MBEDTLS_PK_RSA, and MBEDTLS_PRIVATE.

◆ mbedtls_pk_setup()

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
ctxContext to initialize. It must not have been set up yet (type MBEDTLS_PK_NONE).
infoInformation 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.

◆ mbedtls_pk_setup_rsa_alt()

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
ctxContext to initialize. It must not have been set up yet (type MBEDTLS_PK_NONE).
keyRSA key pointer
decrypt_funcDecryption function
sign_funcSigning function
key_len_funcFunction 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.

◆ mbedtls_pk_sign()

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
ctxThe PK context to use. It must have been set up with a private key.
md_algHash algorithm used (see notes)
hashHash of the message to sign
hash_lenHash length
sigPlace 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_sizeThe size of the sig buffer in bytes.
sig_lenOn successful return, the number of bytes written to sig.
f_rngRNG function, must not be NULL.
p_rngRNG parameter
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.
Returns
0 on success, or a specific error code.
Note
For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0. For ECDSA, md_alg may never be MBEDTLS_MD_NONE.

◆ mbedtls_pk_sign_ext()

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

Make signature given a signature type.

Parameters
pk_typeSignature type.
ctxThe PK context to use. It must have been set up with a private key.
md_algHash algorithm used (see notes)
hashHash of the message to sign
hash_lenHash length
sigPlace 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_sizeThe size of the sig buffer in bytes.
sig_lenOn successful return, the number of bytes written to sig.
f_rngRNG function, must not be NULL.
p_rngRNG parameter
Returns
0 on success, or a specific error code.
Note
When pk_type is MBEDTLS_PK_RSASSA_PSS, see PSA_ALG_RSA_PSS for a description of PSS options used.
For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0. For ECDSA, md_alg may never be MBEDTLS_MD_NONE.

◆ mbedtls_pk_sign_restartable()

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
ctxThe PK context to use. It must have been set up with a private key.
md_algHash algorithm used (see notes for mbedtls_pk_sign())
hashHash of the message to sign
hash_lenHash length
sigPlace 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_sizeThe size of the sig buffer in bytes.
sig_lenOn successful return, the number of bytes written to sig.
f_rngRNG function, must not be NULL.
p_rngRNG parameter
rs_ctxRestart 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().

◆ mbedtls_pk_verify()

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
ctxThe PK context to use. It must have been set up.
md_algHash 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.
hashHash of the message to sign
hash_lenHash length
sigSignature to verify
sig_lenSignature length
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.
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.

◆ mbedtls_pk_verify_ext()

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
typeSignature type (inc. possible padding type) to verify
optionsPointer to type-specific options, or NULL
ctxThe PK context to use. It must have been set up.
md_algHash algorithm used (see notes)
hashHash of the message to sign
hash_lenHash length or 0 (see notes)
sigSignature to verify
sig_lenSignature 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.
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. Note that if #MBEDTLS_USE_PSA_CRYPTO is defined, the salt length is not verified as PSA_ALG_RSA_PSS_ANY_SALT is used.

◆ mbedtls_pk_verify_restartable()

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
ctxThe PK context to use. It must have been set up.
md_algHash algorithm used (see notes)
hashHash of the message to sign
hash_lenHash length or 0 (see notes)
sigSignature to verify
sig_lenSignature length
rs_ctxRestart 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().

◆ mbedtls_pk_write_key_der()

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
ctxPK context which must contain a valid private key.
bufbuffer to write to
sizesize of the buffer
Returns
length of data written if successful, or a specific error code

◆ mbedtls_pk_write_key_pem()

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
ctxPK context which must contain a valid private key.
bufBuffer to write to. The output includes a terminating null byte.
sizeSize of the buffer in bytes.
Returns
0 if successful, or a specific error code

◆ mbedtls_pk_write_pubkey()

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
preference to current position pointer
startstart of the buffer (for bounds-checking)
keyPK context which must contain a valid public or private key.
Returns
the length written or a negative error code

◆ mbedtls_pk_write_pubkey_der()

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
ctxPK context which must contain a valid public or private key.
bufbuffer to write to
sizesize of the buffer
Returns
length of data written if successful, or a specific error code

◆ mbedtls_pk_write_pubkey_pem()

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
ctxPK context which must contain a valid public or private key.
bufBuffer to write to. The output includes a terminating null byte.
sizeSize of the buffer in bytes.
Returns
0 if successful, or a specific error code