Mbed TLS v4.1.1
Loading...
Searching...
No Matches
crypto_extra.h File Reference

PSA cryptography module: Mbed TLS vendor extensions. More...

#include "mbedtls/private_access.h"
#include "crypto_types.h"
#include "crypto_compat.h"
#include "crypto_values.h"
Include dependency graph for crypto_extra.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  mbedtls_psa_stats_s
 Statistics about resource consumption related to the PSA keystore. More...
struct  psa_pake_cipher_suite_s
struct  psa_crypto_driver_pake_inputs_s
struct  psa_jpake_computation_stage_s
struct  psa_pake_operation_s

Macros

#define PSA_CRYPTO_ITS_RANDOM_SEED_UID   0xFFFFFF52
#define PSA_KEY_TYPE_DSA_PUBLIC_KEY   ((psa_key_type_t) 0x4002)
#define PSA_KEY_TYPE_DSA_KEY_PAIR   ((psa_key_type_t) 0x7002)
#define PSA_KEY_TYPE_IS_DSA(type)
#define PSA_ALG_DSA_BASE   ((psa_algorithm_t) 0x06000400)
#define PSA_ALG_DSA(hash_alg)
#define PSA_ALG_DETERMINISTIC_DSA_BASE   ((psa_algorithm_t) 0x06000500)
#define PSA_ALG_DSA_DETERMINISTIC_FLAG   PSA_ALG_ECDSA_DETERMINISTIC_FLAG
#define PSA_ALG_DETERMINISTIC_DSA(hash_alg)
#define PSA_ALG_IS_DSA(alg)
#define PSA_ALG_DSA_IS_DETERMINISTIC(alg)
#define PSA_ALG_IS_DETERMINISTIC_DSA(alg)
#define PSA_ALG_IS_RANDOMIZED_DSA(alg)
#define PSA_ALG_IS_VENDOR_HASH_AND_SIGN(alg)
#define PSA_PAKE_OPERATION_STAGE_SETUP   0
#define PSA_PAKE_OPERATION_STAGE_COLLECT_INPUTS   1
#define PSA_PAKE_OPERATION_STAGE_COMPUTATION   2
#define MBEDTLS_PSA_KEY_ID_BUILTIN_MIN   ((psa_key_id_t) 0x7fff0000)
#define MBEDTLS_PSA_KEY_ID_BUILTIN_MAX   ((psa_key_id_t) 0x7fffefff)
#define PSA_ALG_CATEGORY_PAKE   ((psa_algorithm_t) 0x0a000000)
#define PSA_ALG_IS_PAKE(alg)
#define PSA_ALG_JPAKE_BASE   ((psa_algorithm_t) 0x0a000100)
#define PSA_ALG_JPAKE(hash_alg)
#define PSA_ALG_IS_JPAKE(alg)
#define PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY_BASE   ((psa_key_type_t) 0x4400)
#define PSA_KEY_TYPE_SPAKE2P_KEY_PAIR_BASE   ((psa_key_type_t) 0x7400)
#define PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(curve)
#define PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(curve)
#define PSA_KEY_TYPE_IS_SPAKE2P_KEY_PAIR(type)
#define PSA_KEY_TYPE_IS_SPAKE2P_PUBLIC_KEY(type)
#define PSA_KEY_TYPE_IS_SPAKE2P(type)
#define PSA_ALG_SPAKE2P_HMAC_BASE   ((psa_algorithm_t) 0x0a000400)
#define PSA_ALG_SPAKE2P_HMAC(hash_alg)
#define PSA_ALG_IS_SPAKE2P_HMAC(alg)
#define PSA_ALG_SPAKE2P_CMAC_BASE   ((psa_algorithm_t) 0x0a000500)
#define PSA_ALG_SPAKE2P_CMAC(hash_alg)
#define PSA_ALG_IS_SPAKE2P_CMAC(alg)
#define PSA_ALG_SPAKE2P_MATTER   ((psa_algorithm_t) 0x0a000609)
#define PSA_ALG_IS_SPAKE2P(alg)
#define PSA_PAKE_ROLE_NONE   ((psa_pake_role_t) 0x00)
#define PSA_PAKE_ROLE_FIRST   ((psa_pake_role_t) 0x01)
#define PSA_PAKE_ROLE_SECOND   ((psa_pake_role_t) 0x02)
#define PSA_PAKE_ROLE_CLIENT   ((psa_pake_role_t) 0x11)
#define PSA_PAKE_ROLE_SERVER   ((psa_pake_role_t) 0x12)
#define PSA_PAKE_PRIMITIVE_TYPE_ECC   ((psa_pake_primitive_type_t) 0x01)
#define PSA_PAKE_PRIMITIVE_TYPE_DH   ((psa_pake_primitive_type_t) 0x02)
#define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits)
#define PSA_PAKE_STEP_KEY_SHARE   ((psa_pake_step_t) 0x01)
#define PSA_PAKE_STEP_ZK_PUBLIC   ((psa_pake_step_t) 0x02)
#define PSA_PAKE_STEP_ZK_PROOF   ((psa_pake_step_t) 0x03)
#define PSA_PAKE_STEP_CONFIRM   ((psa_pake_step_t) 0x04)
#define PSA_PAKE_OUTPUT_SIZE(alg, primitive, output_step)
#define PSA_PAKE_INPUT_SIZE(alg, primitive, input_step)
#define PSA_PAKE_OUTPUT_MAX_SIZE   65
#define PSA_PAKE_INPUT_MAX_SIZE   65
#define PSA_PAKE_CIPHER_SUITE_INIT   { PSA_ALG_NONE, 0, 0, 0, 0 }
#define PSA_PAKE_OPERATION_INIT
#define PSA_PAKE_CONFIRMED_KEY   0
#define PSA_PAKE_UNCONFIRMED_KEY   1
#define PSA_JPAKE_EXPECTED_INPUTS(round)
#define PSA_JPAKE_EXPECTED_OUTPUTS(round)
SECTION: PSA core

This section sets PSA specific settings.

#define MBEDTLS_PSA_KEY_SLOT_COUNT   32
#define MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE   1

Typedefs

typedef struct mbedtls_psa_stats_s mbedtls_psa_stats_t
 Statistics about resource consumption related to the PSA keystore.
typedef uint64_t psa_drv_slot_number_t
typedef uint8_t psa_pake_role_t
 Encoding of the application role of PAKE.
typedef uint8_t psa_pake_step_t
typedef uint8_t psa_pake_primitive_type_t
typedef uint8_t psa_pake_family_t
 Encoding of the family of the primitive associated with the PAKE.
typedef uint32_t psa_pake_primitive_t
 Encoding of the primitive associated with the PAKE.
typedef enum psa_crypto_driver_pake_step psa_crypto_driver_pake_step_t
typedef enum psa_jpake_round psa_jpake_round_t
typedef enum psa_jpake_io_mode psa_jpake_io_mode_t
typedef struct psa_pake_cipher_suite_s psa_pake_cipher_suite_t
typedef struct psa_pake_operation_s psa_pake_operation_t
typedef struct psa_crypto_driver_pake_inputs_s psa_crypto_driver_pake_inputs_t
typedef struct psa_jpake_computation_stage_s psa_jpake_computation_stage_t

Enumerations

enum  psa_crypto_driver_pake_step {
  PSA_JPAKE_STEP_INVALID = 0 , PSA_JPAKE_X1_STEP_KEY_SHARE = 1 , PSA_JPAKE_X1_STEP_ZK_PUBLIC = 2 , PSA_JPAKE_X1_STEP_ZK_PROOF = 3 ,
  PSA_JPAKE_X2_STEP_KEY_SHARE = 4 , PSA_JPAKE_X2_STEP_ZK_PUBLIC = 5 , PSA_JPAKE_X2_STEP_ZK_PROOF = 6 , PSA_JPAKE_X2S_STEP_KEY_SHARE = 7 ,
  PSA_JPAKE_X2S_STEP_ZK_PUBLIC = 8 , PSA_JPAKE_X2S_STEP_ZK_PROOF = 9 , PSA_JPAKE_X4S_STEP_KEY_SHARE = 10 , PSA_JPAKE_X4S_STEP_ZK_PUBLIC = 11 ,
  PSA_JPAKE_X4S_STEP_ZK_PROOF = 12
}
enum  psa_jpake_round { PSA_JPAKE_FIRST = 0 , PSA_JPAKE_SECOND = 1 , PSA_JPAKE_FINISHED = 2 }
enum  psa_jpake_io_mode { PSA_JPAKE_INPUT = 0 , PSA_JPAKE_OUTPUT = 1 }

Functions

static void psa_set_key_enrollment_algorithm (psa_key_attributes_t *attributes, psa_algorithm_t alg2)
 Declare the enrollment algorithm for a key.
static psa_algorithm_t psa_get_key_enrollment_algorithm (const psa_key_attributes_t *attributes)
void mbedtls_psa_crypto_free (void)
 Library deinitialization.
void mbedtls_psa_get_stats (mbedtls_psa_stats_t *stats)
 Get statistics about resource consumption related to the PSA keystore.
psa_status_t psa_random_reseed (const uint8_t *perso, size_t perso_size)
psa_status_t psa_random_deplete (void)
psa_status_t psa_random_set_prediction_resistance (unsigned enabled)
static int psa_key_id_is_builtin (psa_key_id_t key_id)
static psa_pake_cipher_suite_t psa_pake_cipher_suite_init (void)
static psa_algorithm_t psa_pake_cs_get_algorithm (const psa_pake_cipher_suite_t *cipher_suite)
static void psa_pake_cs_set_algorithm (psa_pake_cipher_suite_t *cipher_suite, psa_algorithm_t algorithm)
static psa_pake_primitive_t psa_pake_cs_get_primitive (const psa_pake_cipher_suite_t *cipher_suite)
static void psa_pake_cs_set_primitive (psa_pake_cipher_suite_t *cipher_suite, psa_pake_primitive_t primitive)
static psa_pake_family_t psa_pake_cs_get_family (const psa_pake_cipher_suite_t *cipher_suite)
static uint16_t psa_pake_cs_get_bits (const psa_pake_cipher_suite_t *cipher_suite)
static uint32_t psa_pake_cs_get_key_confirmation (const psa_pake_cipher_suite_t *cipher_suite)
static void psa_pake_cs_set_key_confirmation (psa_pake_cipher_suite_t *cipher_suite, uint32_t key_confirmation)
static psa_pake_operation_t psa_pake_operation_init (void)
psa_status_t psa_crypto_driver_pake_get_password_len (const psa_crypto_driver_pake_inputs_t *inputs, size_t *password_len)
psa_status_t psa_crypto_driver_pake_get_password (const psa_crypto_driver_pake_inputs_t *inputs, uint8_t *buffer, size_t buffer_size, size_t *buffer_length)
psa_status_t psa_crypto_driver_pake_get_user_len (const psa_crypto_driver_pake_inputs_t *inputs, size_t *user_len)
psa_status_t psa_crypto_driver_pake_get_peer_len (const psa_crypto_driver_pake_inputs_t *inputs, size_t *peer_len)
psa_status_t psa_crypto_driver_pake_get_user (const psa_crypto_driver_pake_inputs_t *inputs, uint8_t *user_id, size_t user_id_size, size_t *user_id_len)
psa_status_t psa_crypto_driver_pake_get_peer (const psa_crypto_driver_pake_inputs_t *inputs, uint8_t *peer_id, size_t peer_id_size, size_t *peer_id_length)
psa_status_t psa_crypto_driver_pake_get_cipher_suite (const psa_crypto_driver_pake_inputs_t *inputs, psa_pake_cipher_suite_t *cipher_suite)
psa_status_t psa_pake_setup (psa_pake_operation_t *operation, mbedtls_svc_key_id_t password_key, const psa_pake_cipher_suite_t *cipher_suite)
psa_status_t psa_pake_set_user (psa_pake_operation_t *operation, const uint8_t *user_id, size_t user_id_len)
psa_status_t psa_pake_set_peer (psa_pake_operation_t *operation, const uint8_t *peer_id, size_t peer_id_len)
psa_status_t psa_pake_set_role (psa_pake_operation_t *operation, psa_pake_role_t role)
psa_status_t psa_pake_set_context (psa_pake_operation_t *operation, const uint8_t *context, size_t context_len)
psa_status_t psa_pake_output (psa_pake_operation_t *operation, psa_pake_step_t step, uint8_t *output, size_t output_size, size_t *output_length)
psa_status_t psa_pake_input (psa_pake_operation_t *operation, psa_pake_step_t step, const uint8_t *input, size_t input_length)
psa_status_t psa_pake_get_shared_key (psa_pake_operation_t *operation, const psa_key_attributes_t *attributes, mbedtls_svc_key_id_t *key)
psa_status_t psa_pake_abort (psa_pake_operation_t *operation)

Detailed Description

PSA cryptography module: Mbed TLS vendor extensions.

Note
This file may not be included directly. Applications must include psa/crypto.h.

This file is reserved for vendor-specific definitions.

Definition in file crypto_extra.h.

Macro Definition Documentation

◆ MBEDTLS_PSA_KEY_SLOT_COUNT

#define MBEDTLS_PSA_KEY_SLOT_COUNT   32

When MBEDTLS_PSA_KEY_STORE_DYNAMIC is disabled, the maximum amount of PSA keys simultaneously in memory. This counts all volatile keys, plus loaded persistent keys.

When MBEDTLS_PSA_KEY_STORE_DYNAMIC is enabled, the maximum number of loaded persistent keys.

Currently, persistent keys do not need to be loaded all the time while a multipart operation is in progress, only while the operation is being set up. This may change in future versions of the library.

Currently, the library traverses of the whole table on each access to a persistent key. Therefore large values may cause poor performance.

This option has no effect when MBEDTLS_PSA_CRYPTO_C is disabled.

Definition at line 33 of file crypto_extra.h.

◆ MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE

#define MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE   1

Define the size (in bytes) of each static key buffer when #MBEDTLS_PSA_STATIC_KEY_SLOTS is set. If not explicitly defined then it's automatically guessed from available PSA keys enabled in the build through PSA_WANT_xxx symbols. If required by the application this parameter can be set to higher values in order to store larger objects (ex: raw keys), but please note that this will increase RAM usage.

Definition at line 41 of file crypto_extra.h.

◆ PSA_CRYPTO_ITS_RANDOM_SEED_UID

#define PSA_CRYPTO_ITS_RANDOM_SEED_UID   0xFFFFFF52

Definition at line 29 of file crypto_extra.h.

◆ PSA_JPAKE_EXPECTED_INPUTS

#define PSA_JPAKE_EXPECTED_INPUTS ( round)
Value:
((round) == PSA_JPAKE_FINISHED ? 0 : \
((round) == PSA_JPAKE_FIRST ? 2 : 1))
@ PSA_JPAKE_FINISHED
@ PSA_JPAKE_FIRST

Definition at line 1208 of file crypto_extra.h.

◆ PSA_JPAKE_EXPECTED_OUTPUTS

#define PSA_JPAKE_EXPECTED_OUTPUTS ( round)
Value:
((round) == PSA_JPAKE_FINISHED ? 0 : \
((round) == PSA_JPAKE_FIRST ? 2 : 1))

Definition at line 1210 of file crypto_extra.h.

◆ PSA_PAKE_CIPHER_SUITE_INIT

#define PSA_PAKE_CIPHER_SUITE_INIT   { PSA_ALG_NONE, 0, 0, 0, 0 }

Returns a suitable initializer for a PAKE cipher suite object of type psa_pake_cipher_suite_t.

Definition at line 1112 of file crypto_extra.h.

Referenced by psa_pake_cipher_suite_init().

◆ PSA_PAKE_CONFIRMED_KEY

#define PSA_PAKE_CONFIRMED_KEY   0

A key confirmation value that indicates an confirmed key in a PAKE cipher suite.

This key confirmation value will result in the PAKE algorithm exchanging data to verify that the shared key is identical for both parties. This is the default key confirmation value in an initialized PAKE cipher suite object.

Some algorithms do not include confirmation of the shared key.

Definition at line 1133 of file crypto_extra.h.

◆ PSA_PAKE_INPUT_MAX_SIZE

#define PSA_PAKE_INPUT_MAX_SIZE   65

Input buffer size for psa_pake_input() for any of the supported PAKE algorithm and primitive suites and input step.

This macro must expand to a compile-time constant integer.

The value of this macro must be at least as large as the largest value returned by PSA_PAKE_INPUT_SIZE()

See also PSA_PAKE_INPUT_SIZE(alg, primitive, output_step).

Definition at line 1107 of file crypto_extra.h.

◆ PSA_PAKE_INPUT_SIZE

#define PSA_PAKE_INPUT_SIZE ( alg,
primitive,
input_step )
Value:
(PSA_ALG_IS_JPAKE(alg) && \
( \
input_step == PSA_PAKE_STEP_KEY_SHARE ? 65 : \
input_step == PSA_PAKE_STEP_ZK_PUBLIC ? 65 : \
32 \
) : \
0)
#define PSA_ALG_IS_JPAKE(alg)
#define PSA_ECC_FAMILY_SECP_R1
#define PSA_PAKE_STEP_KEY_SHARE
#define PSA_PAKE_PRIMITIVE_TYPE_ECC
#define PSA_PAKE_STEP_ZK_PUBLIC
#define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits)

A sufficient input buffer size for psa_pake_input().

The value returned by this macro is guaranteed to be large enough for any valid input to psa_pake_input() in an operation with the specified parameters.

See also PSA_PAKE_INPUT_MAX_SIZE

Parameters
algA PAKE algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_PAKE(alg) is true).
primitiveA primitive of type psa_pake_primitive_t that is compatible with algorithm alg.
input_stepA value of type psa_pake_step_t that is valid for the algorithm alg.
Returns
A sufficient input buffer size for the specified input, cipher suite and algorithm. If the cipher suite, the input type or PAKE algorithm is not recognized, or the parameters are incompatible, return 0.

Definition at line 1074 of file crypto_extra.h.

◆ PSA_PAKE_OPERATION_INIT

#define PSA_PAKE_OPERATION_INIT
Value:
{ 0 }, { { 0 } } }
#define PSA_PAKE_OPERATION_STAGE_SETUP
#define PSA_ALG_NONE

Returns a suitable initializer for a PAKE operation object of type psa_pake_operation_t.

Definition at line 1120 of file crypto_extra.h.

Referenced by psa_pake_operation_init().

◆ PSA_PAKE_OUTPUT_MAX_SIZE

#define PSA_PAKE_OUTPUT_MAX_SIZE   65

Output buffer size for psa_pake_output() for any of the supported PAKE algorithm and primitive suites and output step.

This macro must expand to a compile-time constant integer.

The value of this macro must be at least as large as the largest value returned by PSA_PAKE_OUTPUT_SIZE()

See also PSA_PAKE_OUTPUT_SIZE(alg, primitive, output_step).

Definition at line 1095 of file crypto_extra.h.

◆ PSA_PAKE_OUTPUT_SIZE

#define PSA_PAKE_OUTPUT_SIZE ( alg,
primitive,
output_step )
Value:
(PSA_ALG_IS_JPAKE(alg) && \
( \
output_step == PSA_PAKE_STEP_KEY_SHARE ? 65 : \
output_step == PSA_PAKE_STEP_ZK_PUBLIC ? 65 : \
32 \
) : \
0)

A sufficient output buffer size for psa_pake_output().

If the size of the output buffer is at least this large, it is guaranteed that psa_pake_output() will not fail due to an insufficient output buffer size. The actual size of the output might be smaller in any given call.

See also PSA_PAKE_OUTPUT_MAX_SIZE

Parameters
algA PAKE algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_PAKE(alg) is true).
primitiveA primitive of type psa_pake_primitive_t that is compatible with algorithm alg.
output_stepA value of type psa_pake_step_t that is valid for the algorithm alg.
Returns
A sufficient output buffer size for the specified PAKE algorithm, primitive, and output step. If the PAKE algorithm, primitive, or output step is not recognized, or the parameters are incompatible, return 0.

Definition at line 1044 of file crypto_extra.h.

◆ PSA_PAKE_UNCONFIRMED_KEY

#define PSA_PAKE_UNCONFIRMED_KEY   1

A key confirmation value that indicates an unconfirmed key in a PAKE cipher suite.

This key confirmation value will result in the PAKE algorithm terminating prior to confirming that the resulting shared key is identical for both parties.

Some algorithms do not support returning an unconfirmed shared key.

Warning
When the shared key is not confirmed as part of the PAKE operation, the application is responsible for mitigating risks that arise from the possible mismatch in the output keys.

Definition at line 1147 of file crypto_extra.h.

Typedef Documentation

◆ mbedtls_psa_stats_t

Statistics about resource consumption related to the PSA keystore.

Note
The content of this structure is not part of the stable API and ABI of Mbed TLS and may change arbitrarily from version to version.

◆ psa_crypto_driver_pake_step_t

◆ psa_jpake_io_mode_t

◆ psa_jpake_round_t

Enumeration Type Documentation

◆ psa_crypto_driver_pake_step

Enumerator
PSA_JPAKE_STEP_INVALID 
PSA_JPAKE_X1_STEP_KEY_SHARE 
PSA_JPAKE_X1_STEP_ZK_PUBLIC 
PSA_JPAKE_X1_STEP_ZK_PROOF 
PSA_JPAKE_X2_STEP_KEY_SHARE 
PSA_JPAKE_X2_STEP_ZK_PUBLIC 
PSA_JPAKE_X2_STEP_ZK_PROOF 
PSA_JPAKE_X2S_STEP_KEY_SHARE 
PSA_JPAKE_X2S_STEP_ZK_PUBLIC 
PSA_JPAKE_X2S_STEP_ZK_PROOF 
PSA_JPAKE_X4S_STEP_KEY_SHARE 
PSA_JPAKE_X4S_STEP_ZK_PUBLIC 
PSA_JPAKE_X4S_STEP_ZK_PROOF 

Definition at line 1168 of file crypto_extra.h.

◆ psa_jpake_io_mode

Enumerator
PSA_JPAKE_INPUT 
PSA_JPAKE_OUTPUT 

Definition at line 1190 of file crypto_extra.h.

◆ psa_jpake_round

Enumerator
PSA_JPAKE_FIRST 
PSA_JPAKE_SECOND 
PSA_JPAKE_FINISHED 

Definition at line 1184 of file crypto_extra.h.

Function Documentation

◆ mbedtls_psa_crypto_free()

void mbedtls_psa_crypto_free ( void )

Library deinitialization.

This function clears all data associated with the PSA layer, including the whole key store. This function is not thread safe, it wipes every key slot regardless of state and reader count. It should only be called when no slot is in use.

This is an Mbed TLS extension.

◆ mbedtls_psa_get_stats()

void mbedtls_psa_get_stats ( mbedtls_psa_stats_t * stats)

Get statistics about resource consumption related to the PSA keystore.

Note
When Mbed TLS is built as part of a service, with isolation between the application and the keystore, the service may or may not expose this function.