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

#include "mbedtls/private_access.h"
#include "mbedtls/platform_util.h"
#include "crypto_types.h"
#include "crypto_compat.h"
#include "mbedtls/ecp.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_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_DH_FAMILY_CUSTOM ((psa_dh_family_t) 0x7e)

#define	PSA_KEY_DOMAIN_PARAMETERS_SIZE(key_type, key_bits)

#define	PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) (4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 3 /without optional parts/)

#define	PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) (4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 2 /p, g/ + 34 /q/)

#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 ((psa_algorithm_t)0x0a000100)

#define	PSA_PAKE_SIDE_FIRST ((psa_pake_side_t)0x01)

#define	PSA_PAKE_SIDE_SECOND ((psa_pake_side_t)0x02)

#define	PSA_PAKE_SIDE_CLIENT ((psa_pake_side_t)0x11)

#define	PSA_PAKE_SIDE_SERVER ((psa_pake_side_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_OUTPUT_SIZE(alg, primitive, output_step) 0

#define	PSA_PAKE_INPUT_SIZE(alg, primitive, input_step) 0

#define	PSA_PAKE_OUTPUT_MAX_SIZE 0

#define	PSA_PAKE_INPUT_MAX_SIZE 0

#define	PSA_PAKE_OPERATION_INIT {0, {0}}

SECTION: Module configuration options
This section allows for the setting of module specific sizes and configuration options. The default values are already present in the relevant header files and should suffice for the regular use cases. Our advice is to enable options and change their values here only if you have a good reason and know the consequences. Please check the respective header file for documentation on these parameters (to prevent duplicate documentation).
#define	MBEDTLS_PSA_KEY_SLOT_COUNT 32

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_side_t
	Encoding of the side 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 struct psa_pake_cipher_suite_s	psa_pake_cipher_suite_t

typedef struct psa_pake_operation_s	psa_pake_operation_t

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)

psa_status_t	psa_get_key_slot_number (const psa_key_attributes_t attributes, psa_key_slot_number_t slot_number)

static void	psa_set_key_slot_number (psa_key_attributes_t *attributes, psa_key_slot_number_t slot_number)

static void	psa_clear_key_slot_number (psa_key_attributes_t *attributes)

psa_status_t	mbedtls_psa_register_se_key (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_inject_entropy (const uint8_t *seed, size_t seed_size)
	Inject an initial entropy seed for the random generator into secure storage. More...

psa_status_t	psa_set_key_domain_parameters (psa_key_attributes_t attributes, psa_key_type_t type, const uint8_t data, size_t data_length)
	Set domain parameters for a key. More...

psa_status_t	psa_get_key_domain_parameters (const psa_key_attributes_t attributes, uint8_t data, size_t data_size, size_t *data_length)
	Get domain parameters for a key. More...

static psa_ecc_family_t	mbedtls_ecc_group_to_psa (mbedtls_ecp_group_id grpid, size_t *bits)

mbedtls_ecp_group_id	mbedtls_ecc_group_of_psa (psa_ecc_family_t curve, size_t bits, int bits_is_sloppy)

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_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_algorithm_t	psa_pake_cs_get_hash (const psa_pake_cipher_suite_t *cipher_suite)

static void	psa_pake_cs_set_hash (psa_pake_cipher_suite_t *cipher_suite, psa_algorithm_t hash)

static psa_pake_operation_t	psa_pake_operation_init (void)

psa_status_t	psa_pake_setup (psa_pake_operation_t *operation, psa_pake_cipher_suite_t cipher_suite)

psa_status_t	psa_pake_set_password_key (psa_pake_operation_t *operation, mbedtls_svc_key_id_t password)

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_side (psa_pake_operation_t *operation, psa_pake_side_t side)

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, uint8_t input, size_t input_length)

psa_status_t	psa_pake_get_implicit_key (psa_pake_operation_t operation, psa_key_derivation_operation_t output)

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 MBEDTLS_PSA_KEY_SLOT_COUNT 32

Use HMAC_DRBG with the specified hash algorithm for HMAC_DRBG for the PSA crypto subsystem.

If this option is unset:

If CTR_DRBG is available, the PSA subsystem uses it rather than HMAC_DRBG.
Otherwise, the PSA subsystem uses HMAC_DRBG with either MBEDTLS_MD_SHA512 or MBEDTLS_MD_SHA256 based on availability and on unspecified heuristics. Restrict the PSA library to supporting a maximum amount of simultaneously loaded keys. A loaded key is a key stored by the PSA Crypto core as a volatile key, or a persistent key which is loaded temporarily by the library as part of a crypto operation in flight.

If this option is unset, the library will fall back to a default value of 32 keys.

#define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52

Definition at line 42 of file crypto_extra.h.

#define PSA_PAKE_INPUT_MAX_SIZE 0

Input buffer size for psa_pake_input() for any of the supported cipher suites and PAKE algorithms.

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

See also PSA_PAKE_INPUT_SIZE(alg, cipher_suite, input).

Definition at line 1744 of file crypto_extra.h.

#define PSA_PAKE_INPUT_SIZE	(	alg,
		primitive,
		input_step
	)	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.

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 Crypto and may change arbitrarily from version to version.

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 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 Crypto is built as part of a service, with isolation between the application and the keystore, the service may or may not expose this function.

psa_status_t mbedtls_psa_inject_entropy	(	const uint8_t *	seed,
		size_t	seed_size
	)

Inject an initial entropy seed for the random generator into secure storage.

This function injects data to be used as a seed for the random generator used by the PSA Crypto implementation. On devices that lack a trusted entropy source (preferably a hardware random number generator), the Mbed PSA Crypto implementation uses this value to seed its random generator.

On devices without a trusted entropy source, this function must be called exactly once in the lifetime of the device. On devices with a trusted entropy source, calling this function is optional. In all cases, this function may only be called before calling any other function in the PSA Crypto API, including psa_crypto_init().

When this function returns successfully, it populates a file in persistent storage. Once the file has been created, this function can no longer succeed.

If any error occurs, this function does not change the system state. You can call this function again after correcting the reason for the error if possible.

Warning: This function can fail! Callers MUST check the return status.; If you use this function, you should use it as part of a factory provisioning process. The value of the injected seed is critical to the security of the device. It must be secret, unpredictable and (statistically) unique per device. You should be generate it randomly using a cryptographically secure random generator seeded from trusted entropy sources. You should transmit it securely to the device and ensure that its value is not leaked or stored anywhere beyond the needs of transmitting it from the point of generation to the call of this function, and erase all copies of the value once this function returns.

This is an Mbed TLS extension.

Note

This function is only available on the following platforms:

If the compile-time option MBEDTLS_PSA_INJECT_ENTROPY is enabled. Note that you must provide compatible implementations of mbedtls_nv_seed_read and mbedtls_nv_seed_write.
In a client-server integration of PSA Cryptography, on the client side, if the server supports this feature.

Parameters

[in]	seed	Buffer containing the seed value to inject.
[in]	seed_size	Size of the `seed` buffer. The size of the seed in bytes must be greater or equal to both MBEDTLS_ENTROPY_BLOCK_SIZE and the value of `MBEDTLS_ENTROPY_MIN_PLATFORM` in `library/entropy_poll.h` in the Mbed TLS source code. It must be less or equal to MBEDTLS_ENTROPY_MAX_SEED_SIZE.

Return values

PSA_SUCCESS	The seed value was injected successfully. The random generator of the PSA Crypto implementation is now ready for use. You may now call psa_crypto_init() and use the PSA Crypto implementation.
PSA_ERROR_INVALID_ARGUMENT	`seed_size` is out of range.
PSA_ERROR_STORAGE_FAILURE	There was a failure reading or writing from storage.
PSA_ERROR_NOT_PERMITTED	The library has already been initialized. It is no longer possible to call this function.

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

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation