Mbed OS Reference
Loading...
Searching...
No Matches
crypto_extra.h File Reference

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

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

Macros

#define PSA_CRYPTO_ITS_RANDOM_SEED_UID   0xFFFFFF52
 UID for secure storage seed. More...
 
#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 an DSA key (pair or public-only). More...
 
#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(hash_alg)    (PSA_ALG_DETERMINISTIC_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
 Deterministic DSA signature with hashing. More...
 
#define PSA_DH_FAMILY_CUSTOM   ((psa_dh_family_t) 0x7e)
 Custom Diffie-Hellman group. More...
 
#define PSA_KEY_DOMAIN_PARAMETERS_SIZE(key_type, key_bits)
 Safe output buffer size for psa_get_key_domain_parameters(). More...
 

Typedefs

typedef struct mbedtls_psa_stats_s mbedtls_psa_stats_t
 Statistics about resource consumption related to the PSA keystore. More...
 

Functions

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

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

◆ PSA_CRYPTO_ITS_RANDOM_SEED_UID

#define PSA_CRYPTO_ITS_RANDOM_SEED_UID   0xFFFFFF52

UID for secure storage seed.

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

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

◆ 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_MIN_PLATFORM and MBEDTLS_ENTROPY_BLOCK_SIZE. 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.