mbed TLS v2.16.3: pk.h File Reference

mbed TLS v2.16.3

Data Structures | Macros | Typedefs | Enumerations | Functions
pk.h File Reference

Public Key abstraction layer. More...

`#include "config.h"`
`#include "md.h"`
`#include "rsa.h"`
`#include "ecp.h"`
`#include "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_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 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. More...
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 }
| 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...
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_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_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_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)
| 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)
| 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)
| 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 (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 (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 (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 (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)

## 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 53 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 55 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 65 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 56 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 69 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 63 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 58 of file pk.h.

## ◆ MBEDTLS_ERR_PK_KEY_INVALID_VERSION

#define MBEDTLS_ERR_PK_KEY_INVALID_VERSION -0x3D80

Unsupported key version

Definition at line 57 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 61 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 60 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 66 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 54 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 64 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 59 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 120 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 125 of file pk.h.

## ◆ mbedtls_pk_restart_ctx

typedef void mbedtls_pk_restart_ctx

Definition at line 147 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 180 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 187 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 183 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 102 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 |

Definition at line 78 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 or MBEDTLS_ERR_PK_BAD_INPUT_DATA

## ◆ 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 | ) |
| 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 170 of file pk.h.

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

## ◆ 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 | ) |
| 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 288 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.

## ◆ 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 | ) |
| 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 157 of file pk.h.

## ◆ 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
  sig_len | Number of bytes written
  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.
  In order to ensure enough space for the signature, the `sig` buffer size must be of at least `max(MBEDTLS_ECDSA_MAX_LEN, MBEDTLS_MPI_MAX_SIZE)` bytes.

## ◆ 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()`.
  In order to ensure enough space for the signature, the `sig` buffer size must be of at least `max(MBEDTLS_ECDSA_MAX_LEN, MBEDTLS_MPI_MAX_SIZE)` bytes.

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
  sig_len | Number of bytes written
  f_rng | RNG function
  p_rng | RNG parameter
  rs_ctx | Restart context (NULL to disable restart)

Returns
  See `mbedtls_pk_sign()`, or
  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 `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.
  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 `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.

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