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)   (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY)
#define	PSA_ALG_DSA_BASE   ((psa_algorithm_t) 0x06000400)
#define	PSA_ALG_DSA(hash_alg)   (PSA_ALG_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
#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)   (PSA_ALG_DETERMINISTIC_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
#define	PSA_ALG_IS_DSA(alg)
#define	PSA_ALG_DSA_IS_DETERMINISTIC(alg)   (((alg) & PSA_ALG_DSA_DETERMINISTIC_FLAG) != 0)
#define	PSA_ALG_IS_DETERMINISTIC_DSA(alg)   (PSA_ALG_IS_DSA(alg) && PSA_ALG_DSA_IS_DETERMINISTIC(alg))
#define	PSA_ALG_IS_RANDOMIZED_DSA(alg)   (PSA_ALG_IS_DSA(alg) && !PSA_ALG_DSA_IS_DETERMINISTIC(alg))
#define	PSA_ALG_IS_VENDOR_HASH_AND_SIGN(alg)   PSA_ALG_IS_DSA(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)   (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_PAKE)
#define	PSA_ALG_JPAKE_BASE   ((psa_algorithm_t) 0x0a000100)
#define	PSA_ALG_JPAKE(hash_alg)   (PSA_ALG_JPAKE_BASE | ((hash_alg) & (PSA_ALG_HASH_MASK)))
#define	PSA_ALG_IS_JPAKE(alg)   (((alg) & (~(PSA_ALG_HASH_MASK))) == PSA_ALG_JPAKE_BASE)
#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)   (PSA_KEY_TYPE_SPAKE2P_KEY_PAIR_BASE | (curve))
#define	PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(curve)   (PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY_BASE | (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)   (PSA_ALG_SPAKE2P_HMAC_BASE | ((hash_alg) & (PSA_ALG_HASH_MASK)))
#define	PSA_ALG_IS_SPAKE2P_HMAC(alg)   (((alg) & (~(PSA_ALG_HASH_MASK))) == PSA_ALG_SPAKE2P_HMAC_BASE)
#define	PSA_ALG_SPAKE2P_CMAC_BASE   ((psa_algorithm_t) 0x0a000500)
#define	PSA_ALG_SPAKE2P_CMAC(hash_alg)   (PSA_ALG_SPAKE2P_CMAC_BASE | ((hash_alg) & (PSA_ALG_HASH_MASK)))
#define	PSA_ALG_IS_SPAKE2P_CMAC(alg)   (((alg) & (~(PSA_ALG_HASH_MASK))) == PSA_ALG_SPAKE2P_CMAC_BASE)
#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)

Typedefs
typedef struct mbedtls_psa_stats_s	mbedtls_psa_stats_t
	Statistics about resource consumption related to the PSA keystore. More...
typedef uint64_t	psa_drv_slot_number_t
typedef uint8_t	psa_pake_role_t
	Encoding of the application role of PAKE. More...
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. More...
typedef uint32_t	psa_pake_primitive_t
	Encoding of the primitive associated with the PAKE. More...
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. More...
static psa_algorithm_t	psa_get_key_enrollment_algorithm (const psa_key_attributes_t *attributes)
void	mbedtls_psa_crypto_free (void)
	Library deinitialization. More...
void	mbedtls_psa_get_stats (mbedtls_psa_stats_t *stats)
	Get statistics about resource consumption related to the PSA keystore. More...
psa_status_t	mbedtls_psa_external_get_random (mbedtls_psa_external_random_context_t *context, uint8_t *output, size_t output_size, size_t *output_length)
static int	psa_key_id_is_builtin (psa_key_id_t key_id)
psa_status_t	mbedtls_psa_platform_get_builtin_key (mbedtls_svc_key_id_t key_id, psa_key_lifetime_t *lifetime, psa_drv_slot_number_t *slot_number)
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

#define PSA_CRYPTO_ITS_RANDOM_SEED_UID   0xFFFFFF52

Definition at line 29 of file crypto_extra.h.

#define PSA_JPAKE_EXPECTED_INPUTS

(

round

)

Value:

((round) == PSA_JPAKE_FINISHED ? 0 : \
                                          ((round) == PSA_JPAKE_FIRST ? 2 : 1))

Definition at line 1040 of file crypto_extra.h.

#define PSA_JPAKE_EXPECTED_OUTPUTS

(

round

)

Value:

((round) == PSA_JPAKE_FINISHED ? 0 : \
                                           ((round) == PSA_JPAKE_FIRST ? 2 : 1))

Definition at line 1042 of file crypto_extra.h.

#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 944 of file crypto_extra.h.

Referenced by psa_pake_cipher_suite_init().

#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 965 of file crypto_extra.h.

#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 939 of file crypto_extra.h.

#define PSA_PAKE_INPUT_SIZE	(		alg,
			primitive,
			input_step
	)

Value:

(PSA_ALG_IS_JPAKE(alg) &&                                           \
     primitive == PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC,      \
                                     PSA_ECC_FAMILY_SECP_R1, 256) ?    \
     (                                                                 \
         input_step == PSA_PAKE_STEP_KEY_SHARE ? 65 :                    \
         input_step == PSA_PAKE_STEP_ZK_PUBLIC ? 65 :                    \
         32                                                              \
     ) :                                                               \
     0)

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

alg	A PAKE algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_PAKE(alg) is true).
primitive	A primitive of type psa_pake_primitive_t that is compatible with algorithm alg.
input_step	A 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 906 of file crypto_extra.h.

#define PSA_PAKE_OPERATION_INIT

Value:

{ 0, PSA_ALG_NONE, 0, PSA_PAKE_OPERATION_STAGE_SETUP, \
                                  { 0 }, { { 0 } } }

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

Definition at line 952 of file crypto_extra.h.

Referenced by psa_pake_operation_init().

#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 927 of file crypto_extra.h.

#define PSA_PAKE_OUTPUT_SIZE	(		alg,
			primitive,
			output_step
	)

Value:

(PSA_ALG_IS_JPAKE(alg) &&                                           \
     primitive == PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC,      \
                                     PSA_ECC_FAMILY_SECP_R1, 256) ?    \
     (                                                                 \
         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

alg	A PAKE algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_PAKE(alg) is true).
primitive	A primitive of type psa_pake_primitive_t that is compatible with algorithm alg.
output_step	A 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 876 of file crypto_extra.h.

#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 979 of file crypto_extra.h.

Typedef Documentation

typedef struct mbedtls_psa_stats_s 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.

typedef enum psa_crypto_driver_pake_step psa_crypto_driver_pake_step_t

typedef enum psa_jpake_io_mode psa_jpake_io_mode_t

typedef enum psa_jpake_round psa_jpake_round_t

Enumeration Type Documentation

enum 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 1000 of file crypto_extra.h.

enum psa_jpake_io_mode

Enumerator
PSA_JPAKE_INPUT
PSA_JPAKE_OUTPUT

Definition at line 1022 of file crypto_extra.h.

enum psa_jpake_round

Enumerator
PSA_JPAKE_FIRST
PSA_JPAKE_SECOND
PSA_JPAKE_FINISHED

Definition at line 1016 of file crypto_extra.h.

Function Documentation

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.

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.