Mbed TLS v4.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Macros | Typedefs | Enumerations | Functions
pk.h File Reference

Public Key abstraction layer. More...

#include "mbedtls/private_access.h"
#include "tf-psa-crypto/build_info.h"
#include "mbedtls/compat-3-crypto.h"
#include "mbedtls/md.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_context
 Public key container. More...
 
struct  mbedtls_pk_restart_ctx
 Context for resuming operations. More...
 

Macros

#define MBEDTLS_PK_HAVE_PRIVATE_HEADER
 
#define MBEDTLS_ERR_PK_TYPE_MISMATCH   -0x3F00
 
#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_PK_SIGNATURE_MAX_SIZE   0
 Maximum size of a signature made by mbedtls_pk_sign() and other signature functions. More...
 
#define MBEDTLS_PK_SIGNATURE_MAX_SIZE   MBEDTLS_MPI_MAX_SIZE
 Maximum size of a signature made by mbedtls_pk_sign() and other signature functions. More...
 
#define MBEDTLS_PK_USE_PSA_EC_DATA
 
#define MBEDTLS_PK_USE_PSA_RSA_DATA
 
#define MBEDTLS_PK_MAX_EC_PUBKEY_RAW_LEN   PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)
 
#define MBEDTLS_PK_MAX_RSA_PUBKEY_RAW_LEN   PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_RSA_MAX_KEY_BITS)
 
#define MBEDTLS_PK_MAX_PUBKEY_RAW_LEN
 
#define MBEDTLS_PK_ALG_ECDSA(hash_alg)   PSA_ALG_DETERMINISTIC_ECDSA(hash_alg)
 

Typedefs

typedef struct mbedtls_pk_info_t mbedtls_pk_info_t
 
typedef struct mbedtls_pk_context mbedtls_pk_context
 Public key container. More...
 

Enumerations

enum  mbedtls_pk_sigalg_t { MBEDTLS_PK_SIGALG_NONE = 0, MBEDTLS_PK_SIGALG_RSA_PKCS1V15, MBEDTLS_PK_SIGALG_RSA_PSS, MBEDTLS_PK_SIGALG_ECDSA }
 
enum  mbedtls_pk_rsa_padding_t { MBEDTLS_PK_RSA_PKCS_V15 = 0, MBEDTLS_PK_RSA_PKCS_V21 }
 

Functions

void mbedtls_pk_init (mbedtls_pk_context *ctx)
 Initialize a mbedtls_pk_context (as empty). More...
 
void mbedtls_pk_free (mbedtls_pk_context *ctx)
 Empty a mbedtls_pk_context. After this, the context can be re-used as if it had been freshly initialized. More...
 
void mbedtls_pk_restart_init (mbedtls_pk_restart_ctx *ctx)
 Initialize a restart context. More...
 
void mbedtls_pk_restart_free (mbedtls_pk_restart_ctx *ctx)
 Free the components of a restart context. More...
 
int mbedtls_pk_wrap_psa (mbedtls_pk_context *ctx, const mbedtls_svc_key_id_t key)
 Populate a PK context by wrapping a PSA key pair. More...
 
size_t mbedtls_pk_get_bitlen (const mbedtls_pk_context *ctx)
 Get the size in bits of the underlying key. More...
 
int mbedtls_pk_can_do_psa (const mbedtls_pk_context *pk, psa_algorithm_t alg, psa_key_usage_t usage)
 Tell if the key wrapped in the PK context is able to perform the usage operation using the alg algorithm. More...
 
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. More...
 
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. More...
 
int mbedtls_pk_copy_from_psa (mbedtls_svc_key_id_t key_id, mbedtls_pk_context *pk)
 Populate a PK context with the key material from a PSA key. More...
 
int mbedtls_pk_copy_public_from_psa (mbedtls_svc_key_id_t key_id, mbedtls_pk_context *pk)
 Populate a PK context with the public key material of a PSA key. 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. 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_sigalg_t type, 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, selecting a specific algorithm. More...
 
int mbedtls_pk_sign (mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, unsigned char *sig, size_t sig_size, size_t *sig_len)
 Make signature. More...
 
int mbedtls_pk_sign_restartable (mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, unsigned char *sig, size_t sig_size, size_t *sig_len, mbedtls_pk_restart_ctx *rs_ctx)
 Restartable version of mbedtls_pk_sign() More...
 
int mbedtls_pk_sign_ext (mbedtls_pk_sigalg_t sig_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)
 Generate a signature, selecting a specific algorithm. 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_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 (const mbedtls_pk_context *ctx, unsigned char *buf, size_t size)
 Write a private key to a PKCS#1 or SEC1 DER structure Note: data is written at the end of the buffer! Use the return value to determine where you should start using the buffer. More...
 
int mbedtls_pk_write_pubkey_der (const mbedtls_pk_context *ctx, unsigned char *buf, size_t size)
 Write a public key to a SubjectPublicKeyInfo DER structure Note: data is written at the end of the buffer! Use the return value to determine where you should start using the buffer. More...
 
int mbedtls_pk_write_pubkey_pem (const mbedtls_pk_context *ctx, unsigned char *buf, size_t size)
 Write a public key to a PEM string. More...
 
int mbedtls_pk_write_key_pem (const mbedtls_pk_context *ctx, unsigned char *buf, size_t size)
 Write a private key to a PKCS#1 or SEC1 PEM string. More...
 

Detailed Description

Public Key abstraction layer.

Definition in file pk.h.

Macro Definition Documentation

#define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE   -0x3980

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

Definition at line 47 of file pk.h.

#define MBEDTLS_ERR_PK_FILE_IO_ERROR   -0x3E00

Read/write of file failed.

Definition at line 29 of file pk.h.

#define MBEDTLS_ERR_PK_INVALID_ALG   -0x3A80

The algorithm tag or value is invalid.

Definition at line 43 of file pk.h.

#define MBEDTLS_ERR_PK_INVALID_PUBKEY   -0x3B00

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

Definition at line 41 of file pk.h.

#define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT   -0x3D00

Invalid key tag or value.

Definition at line 33 of file pk.h.

#define MBEDTLS_ERR_PK_KEY_INVALID_VERSION   -0x3D80

Unsupported key version

Definition at line 31 of file pk.h.

#define MBEDTLS_ERR_PK_PASSWORD_MISMATCH   -0x3B80

Given private key password does not allow for correct decryption.

Definition at line 39 of file pk.h.

#define MBEDTLS_ERR_PK_PASSWORD_REQUIRED   -0x3C00

Private key password can't be empty.

Definition at line 37 of file pk.h.

#define MBEDTLS_ERR_PK_TYPE_MISMATCH   -0x3F00

Type mismatch, eg attempt to do ECDSA with an RSA key

Definition at line 27 of file pk.h.

#define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE   -0x3A00

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

Definition at line 45 of file pk.h.

#define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG   -0x3C80

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

Definition at line 35 of file pk.h.

#define MBEDTLS_PK_ALG_ECDSA (   hash_alg)    PSA_ALG_DETERMINISTIC_ECDSA(hash_alg)

This helper exposes which ECDSA variant the PK module uses by default: this is deterministic ECDSA if available, or randomized otherwise.

Warning
This default algorithm selection might change in the future.

Definition at line 208 of file pk.h.

#define MBEDTLS_PK_HAVE_PRIVATE_HEADER

Definition at line 13 of file pk.h.

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

#define MBEDTLS_PK_MAX_PUBKEY_RAW_LEN
Value:

Definition at line 130 of file pk.h.

#define MBEDTLS_PK_MAX_RSA_PUBKEY_RAW_LEN   PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_RSA_MAX_KEY_BITS)

Definition at line 127 of file pk.h.

#define MBEDTLS_PK_SIGNATURE_MAX_SIZE   0

Maximum size of a signature made by mbedtls_pk_sign() and other signature functions.

Definition at line 79 of file pk.h.

#define MBEDTLS_PK_SIGNATURE_MAX_SIZE   MBEDTLS_MPI_MAX_SIZE

Maximum size of a signature made by mbedtls_pk_sign() and other signature functions.

Definition at line 79 of file pk.h.

#define MBEDTLS_PK_USE_PSA_EC_DATA

Definition at line 111 of file pk.h.

#define MBEDTLS_PK_USE_PSA_RSA_DATA

Definition at line 119 of file pk.h.

Typedef Documentation

Public key container.

Definition at line 122 of file pk.h.

Enumeration Type Documentation

Enumerator
MBEDTLS_PK_RSA_PKCS_V15 
MBEDTLS_PK_RSA_PKCS_V21 

Definition at line 134 of file pk.h.

Enumerator
MBEDTLS_PK_SIGALG_NONE 
MBEDTLS_PK_SIGALG_RSA_PKCS1V15 
MBEDTLS_PK_SIGALG_RSA_PSS 
MBEDTLS_PK_SIGALG_ECDSA 

Definition at line 53 of file pk.h.

Function Documentation

int mbedtls_pk_can_do_psa ( const mbedtls_pk_context pk,
psa_algorithm_t  alg,
psa_key_usage_t  usage 
)

Tell if the key wrapped in the PK context is able to perform the usage operation using the alg algorithm.

The operation may be a PK function, a PSA operation on the underlying PSA key if the PK object wraps a PSA key, or a PSA operation on a key obtained with mbedtls_pk_import_into_psa().

Note
As of TF-PSA-Crypto 1.0.0, this function returns 0 if the key type and policy are suitable for the requested algorithm and usage, even if the key would not work for some other reason, for example an RSA key that is too small for OAEP with the specified hash. This behavior may change without notice in future versions of the library.
Parameters
pkThe context to query. It must have been populated.
algPSA algorithm to check against. Allowed values are:
usagePSA usage flag that the key must be verified against. A single flag from the following list must be specified:
Returns
1 if the key can do operation on the given type.
0 if the key cannot do the operations, or the context has not been populated.
int mbedtls_pk_check_pair ( const mbedtls_pk_context pub,
const mbedtls_pk_context prv 
)

Check if a public-private pair of keys matches.

Note
This function currently does not work on keys created with mbedtls_pk_wrap_psa().
Parameters
pubContext holding a public key.
prvContext 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.
PSA_ERROR_INVALID_ARGUMENT if a context is invalid.
Another non-zero value if the keys do not match.
int mbedtls_pk_copy_from_psa ( mbedtls_svc_key_id_t  key_id,
mbedtls_pk_context pk 
)

Populate a PK context with the key material from a PSA key.

This key:

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

Once this function returns the PK object will be completely independent from the original PSA key that it was generated from.

Note
This function only copies the key material but discards policy information entirely. See mbedtls_pk_get_psa_attributes() for details on which algorithm is going to be used by PK for contexts populated with this function.

If you want to retain the PSA policy, see mbedtls_pk_wrap_psa() - but then the PSA key needs to live at least as long as the PK context.

Parameters
key_idThe key identifier of the key stored in PSA.
pkThe PK context to populate. It must be empty.
Returns
0 on success.
PSA_ERROR_INVALID_ARGUMENT in case the provided input parameters are not correct.
int mbedtls_pk_copy_public_from_psa ( mbedtls_svc_key_id_t  key_id,
mbedtls_pk_context pk 
)

Populate a PK context with the public key material 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.

Once this function returns the PK object will be completely independent from the original PSA key that it was generated from.

Note
This function only copies the key material but discards policy information entirely. See mbedtls_pk_get_psa_attributes() for details on which algorithm is going to be used by PK for contexts populated with this function.

If you want to retain the PSA policy, see mbedtls_pk_wrap_psa() - but then the PSA key needs to live at least as long as the PK context.

Parameters
key_idThe key identifier of the key stored in PSA.
pkThe PK context to populate. It must be empty.
Returns
0 on success.
PSA_ERROR_INVALID_ARGUMENT in case the provided input parameters are not correct.
void mbedtls_pk_free ( mbedtls_pk_context ctx)

Empty a mbedtls_pk_context. After this, the context can be re-used as if it had been freshly initialized.

Parameters
ctxThe context to clear. It must have been initialized. If this is NULL, this function does nothing.
Note
For contexts that have been populated with mbedtls_pk_wrap_psa(), this does not free the underlying PSA key and you still need to call psa_destroy_key() independently if you want to destroy that key.
size_t mbedtls_pk_get_bitlen ( const mbedtls_pk_context ctx)

Get the size in bits of the underlying key.

Parameters
ctxThe context to query. It must have been populated.
Returns
Key size in bits, or 0 on error
int mbedtls_pk_get_psa_attributes ( const mbedtls_pk_context pk,
psa_key_usage_t  usage,
psa_key_attributes_t attributes 
)

Determine valid PSA attributes that can be used to import a key into PSA.

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

The typical flow of operations involving this function is ``` psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT; int ret = mbedtls_pk_get_psa_attributes(pk, &attributes); if (ret != 0) ...; // error handling omitted // Tweak attributes if desired psa_key_id_t key_id = 0; ret = mbedtls_pk_import_into_psa(pk, &attributes, &key_id); if (ret != 0) ...; // error handling omitted ```

Parameters
[in]pkThe PK context to use. It must have been populated. 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.
  • The lifetime and key identifier are unchanged. If the attribute structure was initialized or reset before calling this function, this will result in a volatile key. Call psa_set_key_identifier() before or after this function if you wish to create a persistent key. Call psa_set_key_lifetime() before or after this function if you wish to import the key in a secure element.
  • The key type and bit-size are determined by the contents of the PK context. If the PK context contains a key pair, the key type can be either a key pair type or the corresponding public key type, depending on usage. If the PK context contains a public key, the key type is a public key type.
  • The key's policy is determined by the key type and the usage parameter. The usage always allows usage, exporting and copying the key, and possibly other permissions as documented for the usage parameter. The enrolment algorithm (if available in this build) is left unchanged. For keys created with mbedtls_pk_wrap_psa(), the primary algorithm is the same as the original PSA key. Otherwise, it is determined as follows:
Returns
0 on success. MBEDTLS_ERR_PK_TYPE_MISMATCH if pk does not contain a key compatible with the desired usage. Another error code on other failures.
int mbedtls_pk_import_into_psa ( const mbedtls_pk_context pk,
const psa_key_attributes_t attributes,
mbedtls_svc_key_id_t key_id 
)

Import a key into the PSA key store.

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

The typical way to use this function is:

  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().
Parameters
[in]pkThe PK context to use. It must have been populated. 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.
void mbedtls_pk_init ( mbedtls_pk_context ctx)

Initialize a mbedtls_pk_context (as empty).

After this, you want to populate the context using one of the following functions:

Parameters
ctxThe context to initialize. This must not be NULL.
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
ctxThe PK context to populate. It must be empty.
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.
Note
If you need a specific key type, check the result with mbedtls_pk_can_do_psa().
The key is also checked for correctness.
Returns
0 if successful, or a specific PK or PEM error code
int mbedtls_pk_parse_keyfile ( mbedtls_pk_context ctx,
const char *  path,
const char *  password 
)

Load and parse a private key.

Parameters
ctxThe PK context to populate. It must be empty.
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.
Note
If you need a specific key type, check the result with mbedtls_pk_can_do_psa().
The key is also checked for correctness.
Returns
0 if successful, or a specific PK or PEM error code
int mbedtls_pk_parse_public_key ( mbedtls_pk_context ctx,
const unsigned char *  key,
size_t  keylen 
)

Parse a public key in PEM or DER format.

Parameters
ctxThe PK context to populate. It must be empty.
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
If you need a specific key type, check the result with mbedtls_pk_can_do_psa().
The key is also checked for correctness.
Returns
0 if successful, or a specific PK or PEM error code
int mbedtls_pk_parse_public_keyfile ( mbedtls_pk_context ctx,
const char *  path 
)

Load and parse a public key.

Parameters
ctxThe PK context to populate. It must be empty.
pathfilename to read the public key from
Note
If you need a specific key type, check the result with mbedtls_pk_can_do_psa().
The key is also checked for correctness.
Returns
0 if successful, or a specific PK or PEM error code
void mbedtls_pk_restart_free ( mbedtls_pk_restart_ctx ctx)

Free the components of a restart context.

Parameters
ctxThe context to clear. It must have been initialized. If this is NULL, this function does nothing.
void mbedtls_pk_restart_init ( mbedtls_pk_restart_ctx ctx)

Initialize a restart context.

Parameters
ctxThe context to initialize. This must not be NULL.
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 
)

Make signature.

Note
The signature algorithm used will be the one that would be selected by mbedtls_pk_get_psa_attributes() called with a usage of PSA_KEY_USAGE_SIGN_HASH - see that function's documentation for details. If you want to select a specific signature algorithm, see mbedtls_pk_sign_ext().
Parameters
ctxThe PK context to use. It must have been populated with a private key.
md_algHash algorithm used
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.
Returns
0 on success, or a specific error code.
int mbedtls_pk_sign_ext ( mbedtls_pk_sigalg_t  sig_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 
)

Generate a signature, selecting a specific algorithm.

Parameters
sig_typeSignature type to generate.
ctxThe PK context to use. It must have been populated with a private key.
md_algHash algorithm used
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.
Returns
0 on success, MBEDTLS_ERR_PK_TYPE_MISMATCH if the PK context can't be used for this type of signature, or a specific error code.
int mbedtls_pk_sign_restartable ( mbedtls_pk_context ctx,
mbedtls_md_type_t  md_alg,
const unsigned char *  hash,
size_t  hash_len,
unsigned char *  sig,
size_t  sig_size,
size_t *  sig_len,
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 psa_interruptible_set_max_ops() to reduce blocking for ECC operations. For RSA, same as mbedtls_pk_sign().
For ECC keys, always uses MBEDTLS_PK_ALG_ECDSA(hash), where hash is the PSA alg identifier corresponding to hash.
This function currently does not work on ECC keys created with mbedtls_pk_wrap_psa().
Parameters
ctxThe PK context to use. It must have been populated with a private key.
md_algHash algorithm used.
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.
rs_ctxRestart context (NULL to disable restart)
Returns
See mbedtls_pk_sign().
PSA_OPERATION_INCOMPLETE if the maximum number of operations was reached: see psa_interruptible_set_max_ops().
int mbedtls_pk_verify ( mbedtls_pk_context ctx,
mbedtls_md_type_t  md_alg,
const unsigned char *  hash,
size_t  hash_len,
const unsigned char *  sig,
size_t  sig_len 
)

Verify signature.

Note
The signature algorithm used will be the one that would be selected by mbedtls_pk_get_psa_attributes() called with a usage of PSA_KEY_USAGE_VERIFY_HASH - see that function's documentation for details. If you want to select a specific signature algorithm, see mbedtls_pk_verify_ext().
This function currently does not work on RSA keys created with mbedtls_pk_wrap_psa().
Parameters
ctxThe PK context to use. It must have been populated.
md_algHash algorithm used.
hashHash of the message to sign
hash_lenHash length
sigSignature to verify
sig_lenSignature length
Returns
0 on success (signature is valid), PSA_ERROR_INVALID_SIGNATURE if the signature is invalid, or another specific error code.
int mbedtls_pk_verify_ext ( mbedtls_pk_sigalg_t  type,
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, selecting a specific algorithm.

Parameters
typeSignature type to verify
ctxThe PK context to use. It must have been populated.
md_algHash algorithm used.
hashHash of the message to sign
hash_lenHash length
sigSignature to verify
sig_lenSignature length
Note
If type is MBEDTLS_PK_SIGALG_RSA_PSS, then any salt length is accepted: PSA_ALG_RSA_PSS_ANY_SALT is used.
Returns
0 on success (signature is valid), MBEDTLS_ERR_PK_TYPE_MISMATCH if the PK context can't be used for this type of signature, PSA_ERROR_INVALID_SIGNATURE if the signature is invalid, or a specific error code.
int mbedtls_pk_verify_restartable ( mbedtls_pk_context ctx,
mbedtls_md_type_t  md_alg,
const unsigned char *  hash,
size_t  hash_len,
const unsigned char *  sig,
size_t  sig_len,
mbedtls_pk_restart_ctx rs_ctx 
)

Restartable version of mbedtls_pk_verify()

Note
Performs the same job as mbedtls_pk_verify(), but can return early and restart according to the limit set with psa_interruptible_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 populated.
md_algHash algorithm used
hashHash of the message to sign
hash_lenHash length
sigSignature to verify
sig_lenSignature length
rs_ctxRestart context (NULL to disable restart)
Returns
See mbedtls_pk_verify(), or
PSA_OPERATION_INCOMPLETE if maximum number of operations was reached: see psa_interruptible_set_max_ops().
int mbedtls_pk_wrap_psa ( mbedtls_pk_context ctx,
const mbedtls_svc_key_id_t  key 
)

Populate a PK context by wrapping a PSA key pair.

The PSA key must be an EC or RSA key pair (FFDH is not suported in PK).

The resulting context can only perform operations that are allowed by the key's policy. Additionally, it currently has the following limitations:

  • restartable operations can't be used;
  • for RSA keys, signature verification is not supported, and neither is use of mbedtls_pk_check_pair().
Warning
The PSA wrapped key must remain valid as long as the wrapping PK context is in use, that is at least between the point this function is called and the point mbedtls_pk_free() is called on this context.
Parameters
ctxThe context to populate. It must be empty.
keyThe PSA key to wrap, which must hold an ECC or RSA key pair.
Returns
0 on success.
PSA_ERROR_INVALID_ARGUMENT on invalid input (context already used, invalid key identifier).
MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE if the key is not an ECC or RSA key pair.
PSA_ERROR_INSUFFICIENT_MEMORY on allocation failure.
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
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
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
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