Loading...
Searching...
No Matches
pk.h File Reference

Public Key abstraction layer. More...

`#include "mbedtls/config.h"`
`#include "mbedtls/md.h"`
`#include "mbedtls/rsa.h"`
`#include "mbedtls/ecp.h"`
`#include "mbedtls/ecdsa.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_HW_ACCEL_FAILED -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

## 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, int mode, 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, int mode, 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

const mbedtls_pk_info_t * | mbedtls_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_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_len, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
| Make signature, including padding if relevant.
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_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)
| 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_context * | mbedtls_pk_rsa (const mbedtls_pk_context pk)
static mbedtls_ecp_keypair * | mbedtls_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)
| 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)
| 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 (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 (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 (mbedtls_pk_context *ctx, unsigned char *buf, size_t size)
| Write a public key to a PEM string.
int | mbedtls_pk_write_key_pem (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.
int | mbedtls_pk_load_file (const char *path, unsigned char **buf, size_t *n)

## 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 44 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 48 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 68 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 50 of file pk.h.

## MBEDTLS_ERR_PK_HW_ACCEL_FAILED

#define MBEDTLS_ERR_PK_HW_ACCEL_FAILED -0x3880

PK hardware accelerator failed.

Definition at line 74 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 64 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 62 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 54 of file pk.h.

## MBEDTLS_ERR_PK_KEY_INVALID_VERSION

#define MBEDTLS_ERR_PK_KEY_INVALID_VERSION -0x3D80

Unsupported key version

Definition at line 52 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 60 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 58 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 70 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 46 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 66 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 56 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 175 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 116 of file pk.h.

## Typedef Documentation

## mbedtls_pk_context

typedef struct mbedtls_pk_context mbedtls_pk_context

Public key container.

## mbedtls_pk_debug_item

typedef struct mbedtls_pk_debug_item mbedtls_pk_debug_item

Item to send to the debug module.

## mbedtls_pk_info_t

typedef struct mbedtls_pk_info_t mbedtls_pk_info_t

Public key information and operations.

Definition at line 180 of file pk.h.

## mbedtls_pk_restart_ctx

typedef void mbedtls_pk_restart_ctx

Definition at line 200 of file pk.h.

## mbedtls_pk_rsa_alt_decrypt_func

typedef int(* mbedtls_pk_rsa_alt_decrypt_func) (void *ctx, int mode, size_t *olen, const unsigned char *input, unsigned char *output, size_t output_max_len)

Types for RSA-alt abstraction.

Definition at line 207 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 216 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, int mode, mbedtls_md_type_t md_alg, unsigned int hashlen, const unsigned char *hash, unsigned char *sig)

Definition at line 210 of file pk.h.

## mbedtls_pk_rsassa_pss_options

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

## mbedtls_pk_debug_type

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

## mbedtls_pk_type_t

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

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

## mbedtls_pk_check_pair()

int mbedtls_pk_check_pair | ( | const mbedtls_pk_context * | pub,
|  | const mbedtls_pk_context * | prv
| ) |  |

Check if a public-private pair of keys matches.

Parameters

  pub | Context holding a public key.
  prv | Context holding a private (and public) key.

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

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

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

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

## mbedtls_pk_ec()

static mbedtls_ecp_keypair * mbedtls_pk_ec | ( | const mbedtls_pk_context | pk | ) |

inline static

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

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

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

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

## mbedtls_pk_free()

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.

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

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

## mbedtls_pk_get_len()

static size_t mbedtls_pk_get_len | ( | const mbedtls_pk_context * | ctx | ) |

inline static

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

  ctx | The PK context to use. It must have been initialized.

Returns
  Type name on success, or "invalid PK"

## mbedtls_pk_get_type()

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.

Referenced by mbedtls_pk_ec(), and mbedtls_pk_rsa().

## 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_type | PK 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

  ctx | The context to initialize. This must not be `NULL`.

## mbedtls_pk_load_file()

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

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

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

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

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.

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.

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

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

  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

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

  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

## mbedtls_pk_rsa()

static mbedtls_rsa_context * mbedtls_pk_rsa | ( | const mbedtls_pk_context | pk | ) |

inline static

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

References mbedtls_pk_get_type(), and MBEDTLS_PK_RSA.

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

  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.

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

  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.

## 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_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 or 0 (see notes)
  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_len | On successful return, the number of bytes written to `sig`.
  f_rng | RNG function
  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.
  If hash_len is 0, then the length associated with md_alg is used instead, or an error returned if it is invalid.
  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_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 or 0 (see notes for mbedtls_pk_sign())
  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_len | On successful return, the number of bytes written to `sig`.
  f_rng | RNG function
  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()`.

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

  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_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
  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.
  If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto subsystem must have been initialized by calling psa_crypto_init() before calling this function, if the key might be an ECC (ECDSA) key.
  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

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

  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.

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.

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

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

## mbedtls_pk_write_key_der()

int mbedtls_pk_write_key_der | ( | 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

## mbedtls_pk_write_key_pem()

int mbedtls_pk_write_key_pem | ( | 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

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

  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

## mbedtls_pk_write_pubkey_der()

int mbedtls_pk_write_pubkey_der | ( | 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

## mbedtls_pk_write_pubkey_pem()

int mbedtls_pk_write_pubkey_pem | ( | 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