NCBI C++ ToolKit
Classes | Macros | Typedefs | Enumerations | Functions
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 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.

Go to the SVN repository for this file.

Classes

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
 The type of input values for PAKE operations. More...
 
struct  psa_jpake_computation_stage_s
 The type of computation stage for J-PAKE operations. More...
 
struct  psa_pake_operation_s
 The type of the state data structure for PAKE operations. More...
 

Macros

#define PSA_CRYPTO_ITS_RANDOM_SEED_UID   0xFFFFFF52
 
#define PSA_KEY_TYPE_DSA_PUBLIC_KEY   ((psa_key_type_t) 0x4002)
 DSA public key. More...
 
#define PSA_KEY_TYPE_DSA_KEY_PAIR   ((psa_key_type_t) 0x7002)
 DSA key pair (private and public key). More...
 
#define PSA_KEY_TYPE_IS_DSA(type)    (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY)
 Whether a key type is a DSA key (pair or public-only). More...
 
#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))
 DSA signature with hashing. More...
 
#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))
 Deterministic DSA signature with hashing. More...
 
#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
 PAKE operation stages. More...
 
#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)
 The minimum value for a key identifier that is built into the implementation. More...
 
#define MBEDTLS_PSA_KEY_ID_BUILTIN_MAX   ((psa_key_id_t) 0x7fffefff)
 The maximum value for a key identifier that is built into the implementation. More...
 
#define PSA_ALG_CATEGORY_PAKE   ((psa_algorithm_t) 0x0a000000)
 
#define PSA_ALG_IS_PAKE(alg)    (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_PAKE)
 Whether the specified algorithm is a password-authenticated key exchange. More...
 
#define PSA_ALG_JPAKE   ((psa_algorithm_t) 0x0a000100)
 The Password-authenticated key exchange by juggling (J-PAKE) algorithm. More...
 
#define PSA_PAKE_ROLE_NONE   ((psa_pake_role_t) 0x00)
 A value to indicate no role in a PAKE algorithm. More...
 
#define PSA_PAKE_ROLE_FIRST   ((psa_pake_role_t) 0x01)
 The first peer in a balanced PAKE. More...
 
#define PSA_PAKE_ROLE_SECOND   ((psa_pake_role_t) 0x02)
 The second peer in a balanced PAKE. More...
 
#define PSA_PAKE_ROLE_CLIENT   ((psa_pake_role_t) 0x11)
 The client in an augmented PAKE. More...
 
#define PSA_PAKE_ROLE_SERVER   ((psa_pake_role_t) 0x12)
 The server in an augmented PAKE. More...
 
#define PSA_PAKE_PRIMITIVE_TYPE_ECC   ((psa_pake_primitive_type_t) 0x01)
 The PAKE primitive type indicating the use of elliptic curves. More...
 
#define PSA_PAKE_PRIMITIVE_TYPE_DH   ((psa_pake_primitive_type_t) 0x02)
 The PAKE primitive type indicating the use of Diffie-Hellman groups. More...
 
#define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits)
 Construct a PAKE primitive from type, family and bit-size. More...
 
#define PSA_PAKE_STEP_KEY_SHARE   ((psa_pake_step_t) 0x01)
 The key share being sent to or received from the peer. More...
 
#define PSA_PAKE_STEP_ZK_PUBLIC   ((psa_pake_step_t) 0x02)
 A Schnorr NIZKP public key. More...
 
#define PSA_PAKE_STEP_ZK_PROOF   ((psa_pake_step_t) 0x03)
 A Schnorr NIZKP proof. More...
 
#define PSA_PAKE_OUTPUT_SIZE(alg, primitive, output_step)
 A sufficient output buffer size for psa_pake_output(). More...
 
#define PSA_PAKE_INPUT_SIZE(alg, primitive, input_step)
 A sufficient input buffer size for psa_pake_input(). More...
 
#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. More...
 
#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. More...
 
#define PSA_PAKE_CIPHER_SUITE_INIT   { PSA_ALG_NONE, 0, 0, 0, PSA_ALG_NONE }
 Returns a suitable initializer for a PAKE cipher suite object of type psa_pake_cipher_suite_t. More...
 
#define PSA_PAKE_OPERATION_INIT
 Returns a suitable initializer for a PAKE operation object of type psa_pake_operation_t. More...
 
#define PSA_JPAKE_EXPECTED_INPUTS(round)
 
#define PSA_JPAKE_EXPECTED_OUTPUTS(round)
 
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.

#define MBEDTLS_PSA_KEY_SLOT_COUNT   32
 Use HMAC_DRBG with the specified hash algorithm for HMAC_DRBG for the PSA crypto subsystem. More...
 

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
 A slot number identifying a key in a driver. More...
 
typedef uint8_t psa_pake_role_t
 Encoding of the application role of PAKE. More...
 
typedef uint8_t psa_pake_step_t
 Encoding of input and output indicators for PAKE. More...
 
typedef uint8_t psa_pake_primitive_type_t
 Encoding of the type of the PAKE's primitive. More...
 
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
 The type of the data structure for PAKE cipher suites. More...
 
typedef struct psa_crypto_driver_pake_inputs_s psa_crypto_driver_pake_inputs_t
 The type of input values for PAKE operations. 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_jpake_computation_stage_s psa_jpake_computation_stage_t
 The type of computation stage for J-PAKE operations. More...
 
typedef struct psa_pake_operation_s psa_pake_operation_t
 The type of the state data structure for PAKE operations. More...
 

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)
 Retrieve the enrollment algorithm policy from key attributes. More...
 
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...
 
static psa_pake_cipher_suite_t psa_pake_cipher_suite_init (void)
 Return an initial value for a PAKE cipher suite object. More...
 
static psa_algorithm_t psa_pake_cs_get_algorithm (const psa_pake_cipher_suite_t *cipher_suite)
 Retrieve the PAKE algorithm from a PAKE cipher suite. More...
 
static void psa_pake_cs_set_algorithm (psa_pake_cipher_suite_t *cipher_suite, psa_algorithm_t algorithm)
 Declare the PAKE algorithm for the cipher suite. More...
 
static psa_pake_primitive_t psa_pake_cs_get_primitive (const psa_pake_cipher_suite_t *cipher_suite)
 Retrieve the primitive from a PAKE cipher suite. More...
 
static void psa_pake_cs_set_primitive (psa_pake_cipher_suite_t *cipher_suite, psa_pake_primitive_t primitive)
 Declare the primitive for a PAKE cipher suite. More...
 
static psa_pake_family_t psa_pake_cs_get_family (const psa_pake_cipher_suite_t *cipher_suite)
 Retrieve the PAKE family from a PAKE cipher suite. More...
 
static uint16_t psa_pake_cs_get_bits (const psa_pake_cipher_suite_t *cipher_suite)
 Retrieve the PAKE primitive bit-size from a PAKE cipher suite. More...
 
static psa_algorithm_t psa_pake_cs_get_hash (const psa_pake_cipher_suite_t *cipher_suite)
 Retrieve the hash algorithm from a PAKE cipher suite. More...
 
static void psa_pake_cs_set_hash (psa_pake_cipher_suite_t *cipher_suite, psa_algorithm_t hash)
 Declare the hash algorithm for a PAKE cipher suite. More...
 
uint8_t MBEDTLS_PRIVATE (dummy)
 
psa_driver_pake_context_t MBEDTLS_PRIVATE (ctx)
 
psa_crypto_driver_pake_inputs_t MBEDTLS_PRIVATE (inputs)
 
static psa_pake_operation_t psa_pake_operation_init (void)
 Return an initial value for a PAKE operation object. More...
 
psa_status_t psa_crypto_driver_pake_get_password_len (const psa_crypto_driver_pake_inputs_t *inputs, size_t *password_len)
 Get the length of the password in bytes from given inputs. More...
 
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)
 Get the password from given inputs. More...
 
psa_status_t psa_crypto_driver_pake_get_user_len (const psa_crypto_driver_pake_inputs_t *inputs, size_t *user_len)
 Get the length of the user id in bytes from given inputs. More...
 
psa_status_t psa_crypto_driver_pake_get_peer_len (const psa_crypto_driver_pake_inputs_t *inputs, size_t *peer_len)
 Get the length of the peer id in bytes from given inputs. More...
 
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)
 Get the user id from given inputs. More...
 
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)
 Get the peer id from given inputs. More...
 
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)
 Get the cipher suite from given inputs. More...
 
psa_status_t psa_pake_setup (psa_pake_operation_t *operation, const psa_pake_cipher_suite_t *cipher_suite)
 Set the session information for a password-authenticated key exchange. More...
 
psa_status_t psa_pake_set_password_key (psa_pake_operation_t *operation, mbedtls_svc_key_id_t password)
 Set the password for a password-authenticated key exchange from key ID. More...
 
psa_status_t psa_pake_set_user (psa_pake_operation_t *operation, const uint8_t *user_id, size_t user_id_len)
 Set the user ID for a password-authenticated key exchange. More...
 
psa_status_t psa_pake_set_peer (psa_pake_operation_t *operation, const uint8_t *peer_id, size_t peer_id_len)
 Set the peer ID for a password-authenticated key exchange. More...
 
psa_status_t psa_pake_set_role (psa_pake_operation_t *operation, psa_pake_role_t role)
 Set the application role for a password-authenticated key exchange. More...
 
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)
 Get output for a step of a password-authenticated key exchange. More...
 
psa_status_t psa_pake_input (psa_pake_operation_t *operation, psa_pake_step_t step, const uint8_t *input, size_t input_length)
 Provide input for a step of a password-authenticated key exchange. More...
 
psa_status_t psa_pake_get_implicit_key (psa_pake_operation_t *operation, psa_key_derivation_operation_t *output)
 Get implicitly confirmed shared secret from a PAKE. More...
 
psa_status_t psa_pake_abort (psa_pake_operation_t *operation)
 Abort a PAKE operation. More...
 

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

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.

Definition at line 32 of file crypto_extra.h.

◆ PSA_CRYPTO_ITS_RANDOM_SEED_UID

#define PSA_CRYPTO_ITS_RANDOM_SEED_UID   0xFFFFFF52

Definition at line 28 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))
T round(const T &v)
@ PSA_JPAKE_FINISHED
@ PSA_JPAKE_FIRST

Definition at line 1857 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 1859 of file crypto_extra.h.

◆ PSA_PAKE_CIPHER_SUITE_INIT

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

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

Definition at line 1784 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 1779 of file crypto_extra.h.

◆ PSA_PAKE_INPUT_SIZE

#define PSA_PAKE_INPUT_SIZE (   alg,
  primitive,
  input_step 
)
Value:
(alg == PSA_ALG_JPAKE && \
( \
input_step == PSA_PAKE_STEP_KEY_SHARE ? 65 : \
input_step == PSA_PAKE_STEP_ZK_PUBLIC ? 65 : \
32 \
) : \
0)
#define PSA_ECC_FAMILY_SECP_R1
SEC random curves over prime fields.
#define PSA_ALG_JPAKE
The Password-authenticated key exchange by juggling (J-PAKE) algorithm.
Definition: crypto_extra.h:701
#define PSA_PAKE_STEP_KEY_SHARE
The key share being sent to or received from the peer.
Definition: crypto_extra.h:868
#define PSA_PAKE_PRIMITIVE_TYPE_ECC
The PAKE primitive type indicating the use of elliptic curves.
Definition: crypto_extra.h:810
#define PSA_PAKE_STEP_ZK_PUBLIC
A Schnorr NIZKP public key.
Definition: crypto_extra.h:885
#define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits)
Construct a PAKE primitive from type, family and bit-size.
Definition: crypto_extra.h:851

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

◆ PSA_PAKE_OPERATION_INIT

#define PSA_PAKE_OPERATION_INIT
Value:
{ 0 }, { { 0 } } }
#define PSA_PAKE_OPERATION_STAGE_SETUP
PAKE operation stages.
Definition: crypto_extra.h:412
#define PSA_ALG_NONE
An invalid algorithm identifier value.

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

Definition at line 1792 of file crypto_extra.h.

◆ 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 1767 of file crypto_extra.h.

◆ PSA_PAKE_OUTPUT_SIZE

#define PSA_PAKE_OUTPUT_SIZE (   alg,
  primitive,
  output_step 
)
Value:
(alg == PSA_ALG_JPAKE && \
( \
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 1716 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.

Function Documentation

◆ MBEDTLS_PRIVATE() [1/3]

psa_driver_pake_context_t MBEDTLS_PRIVATE::MBEDTLS_PRIVATE ( ctx  )

◆ MBEDTLS_PRIVATE() [2/3]

uint8_t MBEDTLS_PRIVATE::MBEDTLS_PRIVATE ( dummy  )

◆ MBEDTLS_PRIVATE() [3/3]

psa_crypto_driver_pake_inputs_t MBEDTLS_PRIVATE::MBEDTLS_PRIVATE ( inputs  )

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

◆ mbedtls_psa_inject_entropy()

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]seedBuffer containing the seed value to inject.
[in]seed_sizeSize 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_SUCCESSThe 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_ARGUMENTseed_size is out of range.
PSA_ERROR_STORAGE_FAILUREThere was a failure reading or writing from storage.
PSA_ERROR_NOT_PERMITTEDThe library has already been initialized. It is no longer possible to call this function.
Modified on Mon Jun 17 05:08:33 2024 by modify_doxy.py rev. 669887