Macros
#define	PSA_KEY_ATTRIBUTES_INIT
	This macro returns a suitable initializer for a key attribute structure of type psa_key_attributes_t. More...

#define	PSA_DH_FAMILY_CUSTOM ((psa_dh_family_t) MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(0x7e))
	Custom Diffie-Hellman group. More...

#define	PSA_KEY_DOMAIN_PARAMETERS_SIZE(key_type, key_bits) MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(1u)
	Safe output buffer size for psa_get_key_domain_parameters(). More...

#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

Typedefs
typedef struct psa_key_attributes_s	psa_key_attributes_t
	The type of a structure containing key attributes. More...

Functions
static psa_key_attributes_t	psa_key_attributes_init (void)
	Return an initial value for a key attributes structure. More...

static void	psa_set_key_id (psa_key_attributes_t *attributes, mbedtls_svc_key_id_t key)
	Declare a key as persistent and set its key identifier. More...

static void	psa_set_key_lifetime (psa_key_attributes_t *attributes, psa_key_lifetime_t lifetime)
	Set the location of a persistent key. More...

static mbedtls_svc_key_id_t	psa_get_key_id (const psa_key_attributes_t *attributes)
	Retrieve the key identifier from key attributes. More...

static psa_key_lifetime_t	psa_get_key_lifetime (const psa_key_attributes_t *attributes)
	Retrieve the lifetime from key attributes. More...

static void	psa_set_key_usage_flags (psa_key_attributes_t *attributes, psa_key_usage_t usage_flags)
	Declare usage flags for a key. More...

static psa_key_usage_t	psa_get_key_usage_flags (const psa_key_attributes_t *attributes)
	Retrieve the usage flags from key attributes. More...

static void	psa_set_key_algorithm (psa_key_attributes_t *attributes, psa_algorithm_t alg)
	Declare the permitted algorithm policy for a key. More...

static psa_algorithm_t	psa_get_key_algorithm (const psa_key_attributes_t *attributes)
	Retrieve the algorithm policy from key attributes. More...

static void	psa_set_key_type (psa_key_attributes_t *attributes, psa_key_type_t type)
	Declare the type of a key. More...

static void	psa_set_key_bits (psa_key_attributes_t *attributes, size_t bits)
	Declare the size of a key. More...

static psa_key_type_t	psa_get_key_type (const psa_key_attributes_t *attributes)
	Retrieve the key type from key attributes. More...

static size_t	psa_get_key_bits (const psa_key_attributes_t *attributes)
	Retrieve the key size from key attributes. More...

psa_status_t	psa_get_key_attributes (mbedtls_svc_key_id_t key, psa_key_attributes_t *attributes)
	Retrieve the attributes of a key. More...

void	psa_reset_key_attributes (psa_key_attributes_t *attributes)
	Reset a key attribute structure to a freshly initialized state. More...

static psa_status_t MBEDTLS_DEPRECATED	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...

static psa_status_t MBEDTLS_DEPRECATED	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 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...

Detailed Description

Macro Definition Documentation

◆ PSA_DH_FAMILY_CUSTOM

#define PSA_DH_FAMILY_CUSTOM ((psa_dh_family_t) MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(0x7e))

Custom Diffie-Hellman group.

Mbed TLS does not support custom DH groups.

Deprecated:: This value is not useful, so this macro will be removed in a future version of the library.

Definition at line 161 of file crypto_compat.h.

◆ PSA_KEY_ATTRIBUTES_INIT

#define PSA_KEY_ATTRIBUTES_INIT

Value:

                                      { PSA_KEY_ATTRIBUTES_MAYBE_SLOT_NUMBER \
                                      PSA_KEY_TYPE_NONE, 0,            \
                                      PSA_KEY_LIFETIME_VOLATILE,       \
                                      PSA_KEY_POLICY_INIT,             \
                                      MBEDTLS_SVC_KEY_ID_INIT }

This macro returns a suitable initializer for a key attribute structure of type psa_key_attributes_t.

Definition at line 323 of file crypto_struct.h.

◆ PSA_KEY_DOMAIN_PARAMETERS_SIZE

#define PSA_KEY_DOMAIN_PARAMETERS_SIZE	(	key_type,
		key_bits
	)	MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(1u)

Safe output buffer size for psa_get_key_domain_parameters().

Definition at line 220 of file crypto_compat.h.

◆ PSA_PAKE_OPERATION_STAGE_COLLECT_INPUTS

#define PSA_PAKE_OPERATION_STAGE_COLLECT_INPUTS 1

Definition at line 421 of file crypto_extra.h.

◆ PSA_PAKE_OPERATION_STAGE_COMPUTATION

#define PSA_PAKE_OPERATION_STAGE_COMPUTATION 2

Definition at line 422 of file crypto_extra.h.

◆ PSA_PAKE_OPERATION_STAGE_SETUP

#define PSA_PAKE_OPERATION_STAGE_SETUP 0

PAKE operation stages.

Definition at line 420 of file crypto_extra.h.

Typedef Documentation

◆ psa_key_attributes_t

typedef struct psa_key_attributes_s psa_key_attributes_t

The type of a structure containing key attributes.

This is an opaque structure that can represent the metadata of a key object. Metadata that can be stored in attributes includes:

The location of the key in storage, indicated by its key identifier and its lifetime.
The key's policy, comprising usage flags and a specification of the permitted algorithm(s).
Information about the key itself: the key type and its size.
Additional implementation-defined attributes.

The actual key material is not considered an attribute of a key. Key attributes do not contain information that is generally considered highly confidential.

An attribute structure works like a simple data structure where each function `psa_set_key_xxx` sets a field and the corresponding function `psa_get_key_xxx` retrieves the value of the corresponding field. However, a future version of the library may report values that are equivalent to the original one, but have a different encoding. Invalid values may be mapped to different, also invalid values.

An attribute structure may contain references to auxiliary resources, for example pointers to allocated memory or indirect references to pre-calculated values. In order to free such resources, the application must call psa_reset_key_attributes(). As an exception, calling psa_reset_key_attributes() on an attribute structure is optional if the structure has only been modified by the following functions since it was initialized or last reset with psa_reset_key_attributes():

Before calling any function on a key attribute structure, the application must initialize it by any of the following means:

Set the structure to all-bits-zero, for example:
psa_key_attributes_t attributes;

memset(&attributes, 0, sizeof(attributes));

attributes
static const struct attribute attributes[]
Definition: attributes.c:165

psa_key_attributes_s
Definition: crypto_struct.h:295
Initialize the structure to logical zero values, for example:
psa_key_attributes_t attributes = {0};
Initialize the structure to the initializer PSA_KEY_ATTRIBUTES_INIT, for example:
psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;

PSA_KEY_ATTRIBUTES_INIT
#define PSA_KEY_ATTRIBUTES_INIT
This macro returns a suitable initializer for a key attribute structure of type psa_key_attributes_t.
Definition: crypto_struct.h:323
Assign the result of the function psa_key_attributes_init() to the structure, for example:
psa_key_attributes_t attributes;

attributes = psa_key_attributes_init();

psa_key_attributes_init
static psa_key_attributes_t psa_key_attributes_init(void)
Return an initial value for a key attributes structure.

A freshly initialized attribute structure contains the following values:

lifetime: PSA_KEY_LIFETIME_VOLATILE.
key identifier: 0 (which is not a valid key identifier).
type: 0 (meaning that the type is unspecified).
key size: 0 (meaning that the size is unspecified).
usage flags: 0 (which allows no usage except exporting a public key).
algorithm: 0 (which allows no cryptographic usage, but allows exporting).

A typical sequence to create a key is as follows:

Create and initialize an attribute structure.
If the key is persistent, call psa_set_key_id(). Also call psa_set_key_lifetime() to place the key in a non-default location.
Set the key policy with psa_set_key_usage_flags() and psa_set_key_algorithm().
Set the key type with psa_set_key_type(). Skip this step if copying an existing key with psa_copy_key().
When generating a random key with psa_generate_key() or deriving a key with psa_key_derivation_output_key(), set the desired key size with psa_set_key_bits().
Call a key creation function: psa_import_key(), psa_generate_key(), psa_key_derivation_output_key() or psa_copy_key(). This function reads the attribute structure, creates a key with these attributes, and outputs a key identifier to the newly created key.
The attribute structure is now no longer necessary. You may call psa_reset_key_attributes(), although this is optional with the workflow presented here because the attributes currently defined in this specification do not require any additional resources beyond the structure itself.

A typical sequence to query a key's attributes is as follows:

Call psa_get_key_attributes().
Call `psa_get_key_xxx` functions to retrieve the attribute(s) that you are interested in.
Call psa_reset_key_attributes() to free any resources that may be used by the attribute structure.

Once a key has been created, it is impossible to change its attributes.

Definition at line 323 of file crypto_types.h.

Function Documentation

◆ psa_get_key_algorithm()

static psa_algorithm_t psa_get_key_algorithm ( const psa_key_attributes_t * attributes )

static

Retrieve the algorithm policy from key attributes.

This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Parameters

[in] attributes The key attribute structure to query.

Returns: The algorithm stored in the attribute structure.

◆ psa_get_key_attributes()

psa_status_t psa_get_key_attributes	(	mbedtls_svc_key_id_t	key,
		psa_key_attributes_t *	attributes
	)

Retrieve the attributes of a key.

This function first resets the attribute structure as with psa_reset_key_attributes(). It then copies the attributes of the given key into the given attribute structure.

Note: This function may allocate memory or other resources. Once you have called this function on an attribute structure, you must call psa_reset_key_attributes() to free these resources.

Parameters

[in]	key	Identifier of the key to query.
[in,out]	attributes	On success, the attributes of the key. On failure, equivalent to a freshly-initialized structure.

Return values

PSA_SUCCESS	\emptydescription
PSA_ERROR_INVALID_HANDLE	\emptydescription
PSA_ERROR_INSUFFICIENT_MEMORY	\emptydescription
PSA_ERROR_COMMUNICATION_FAILURE	\emptydescription
PSA_ERROR_CORRUPTION_DETECTED	\emptydescription
PSA_ERROR_STORAGE_FAILURE	\emptydescription
PSA_ERROR_DATA_CORRUPT	\emptydescription
PSA_ERROR_DATA_INVALID	\emptydescription
PSA_ERROR_BAD_STATE	The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_get_key_bits()

static size_t psa_get_key_bits ( const psa_key_attributes_t * attributes )

static

Retrieve the key size from key attributes.

This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Parameters

[in] attributes The key attribute structure to query.

Returns: The key size stored in the attribute structure, in bits.

◆ psa_get_key_domain_parameters()

static psa_status_t MBEDTLS_DEPRECATED psa_get_key_domain_parameters	(	const psa_key_attributes_t *	attributes,
		uint8_t *	data,
		size_t	data_size,
		size_t *	data_length
	)

inlinestatic

Get domain parameters for a key.

Deprecated:: Mbed TLS no longer supports any domain parameters. This function alwaya has an empty output and will be removed in a future version of the library.

Parameters

[in]	attributes	Ignored.
[out]	data	Ignored.
	data_size	Ignored.
[out]	data_length	Set to 0.

Return values

PSA_SUCCESS \emptydescription

Definition at line 206 of file crypto_compat.h.

References attributes, data, and PSA_SUCCESS.

◆ psa_get_key_enrollment_algorithm()

static psa_algorithm_t psa_get_key_enrollment_algorithm ( const psa_key_attributes_t * attributes )

inlinestatic

Retrieve the enrollment algorithm policy from key attributes.

Parameters

[in] attributes The key attribute structure to query.

Returns: The enrollment algorithm stored in the attribute structure.

Definition at line 71 of file crypto_extra.h.

References attributes.

◆ psa_get_key_id()

static mbedtls_svc_key_id_t psa_get_key_id ( const psa_key_attributes_t * attributes )

static

Retrieve the key identifier from key attributes.

This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Parameters

[in] attributes The key attribute structure to query.

Returns: The persistent identifier stored in the attribute structure. This value is unspecified if the attribute structure declares the key as volatile.

◆ psa_get_key_lifetime()

static psa_key_lifetime_t psa_get_key_lifetime ( const psa_key_attributes_t * attributes )

static

Retrieve the lifetime from key attributes.

This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Parameters

[in] attributes The key attribute structure to query.

Returns: The lifetime value stored in the attribute structure.

◆ psa_get_key_type()

static psa_key_type_t psa_get_key_type ( const psa_key_attributes_t * attributes )

static

Retrieve the key type from key attributes.

This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Parameters

[in] attributes The key attribute structure to query.

Returns: The key type stored in the attribute structure.

◆ psa_get_key_usage_flags()

static psa_key_usage_t psa_get_key_usage_flags ( const psa_key_attributes_t * attributes )

static

Retrieve the usage flags from key attributes.

This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Parameters

[in] attributes The key attribute structure to query.

Returns: The usage flags stored in the attribute structure.

◆ psa_key_attributes_init()

static psa_key_attributes_t psa_key_attributes_init ( void )

static

Return an initial value for a key attributes structure.

◆ psa_reset_key_attributes()

void psa_reset_key_attributes ( psa_key_attributes_t * attributes )

Reset a key attribute structure to a freshly initialized state.

You must initialize the attribute structure as described in the documentation of the type psa_key_attributes_t before calling this function. Once the structure has been initialized, you may call this function at any time.

This function frees any auxiliary resources that the structure may contain.

Parameters

[in,out] attributes The attribute structure to reset.

◆ psa_set_key_algorithm()

static void psa_set_key_algorithm	(	psa_key_attributes_t *	attributes,
		psa_algorithm_t	alg
	)

static

Declare the permitted algorithm policy for a key.

The permitted algorithm policy of a key encodes which algorithm or algorithms are permitted to be used with this key. The following algorithm policies are supported:

0 does not allow any cryptographic operation with the key. The key may be used for non-cryptographic actions such as exporting (if permitted by the usage flags).
An algorithm value permits this particular algorithm.
An algorithm wildcard built from PSA_ALG_ANY_HASH allows the specified signature scheme with any hash algorithm.
An algorithm built from PSA_ALG_AT_LEAST_THIS_LENGTH_MAC allows any MAC algorithm from the same base class (e.g. CMAC) which generates/verifies a MAC length greater than or equal to the length encoded in the wildcard algorithm.
An algorithm built from PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG allows any AEAD algorithm from the same base class (e.g. CCM) which generates/verifies a tag length greater than or equal to the length encoded in the wildcard algorithm.

This function overwrites any algorithm policy previously set in attributes.

This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Parameters

[out]	attributes	The attribute structure to write to.
	alg	The permitted algorithm policy to write.

◆ psa_set_key_bits()

static void psa_set_key_bits	(	psa_key_attributes_t *	attributes,
		size_t	bits
	)

static

Declare the size of a key.

This function overwrites any key size previously set in attributes.

This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Parameters

[out]	attributes	The attribute structure to write to.
	bits	The key size in bits. If this is 0, the key size in `attributes` becomes unspecified. Keys of size 0 are not supported.

◆ psa_set_key_domain_parameters()

static psa_status_t MBEDTLS_DEPRECATED psa_set_key_domain_parameters	(	psa_key_attributes_t *	attributes,
		psa_key_type_t	type,
		const uint8_t *	data,
		size_t	data_length
	)

inlinestatic

Set domain parameters for a key.

Deprecated:: Mbed TLS no longer supports any domain parameters. This function only does the equivalent of psa_set_key_type() and will be removed in a future version of the library.

Parameters

[in,out]	attributes	Attribute structure where `type` will be set.
	type	Key type (a `PSA_KEY_TYPE_XXX` value).
[in]	data	Ignored.
	data_length	Must be 0.

Return values

PSA_SUCCESS	\emptydescription
PSA_ERROR_NOT_SUPPORTED	\emptydescription

Definition at line 180 of file crypto_compat.h.

References attributes, data, PSA_ERROR_NOT_SUPPORTED, psa_set_key_type(), and PSA_SUCCESS.

◆ psa_set_key_enrollment_algorithm()

static void psa_set_key_enrollment_algorithm	(	psa_key_attributes_t *	attributes,
		psa_algorithm_t	alg2
	)

inlinestatic

Declare the enrollment algorithm for a key.

An operation on a key may indifferently use the algorithm set with psa_set_key_algorithm() or with this function.

Parameters

[out]	attributes	The attribute structure to write to.
	alg2	A second algorithm that the key may be used for, in addition to the algorithm set with psa_set_key_algorithm().

Warning: Setting an enrollment algorithm is not recommended, because using the same key with different algorithms can allow some attacks based on arithmetic relations between different computations made with the same key, or can escalate harmless side channels into exploitable ones. Use this function only if it is necessary to support a protocol for which it has been verified that the usage of the key with multiple algorithms is safe.

Definition at line 58 of file crypto_extra.h.

References attributes.

◆ psa_set_key_id()

static void psa_set_key_id	(	psa_key_attributes_t *	attributes,
		mbedtls_svc_key_id_t	key
	)

static

Declare a key as persistent and set its key identifier.

If the attribute structure currently declares the key as volatile (which is the default content of an attribute structure), this function sets the lifetime attribute to PSA_KEY_LIFETIME_PERSISTENT.

This function does not access storage, it merely stores the given value in the structure. The persistent key will be written to storage when the attribute structure is passed to a key creation function such as psa_import_key(), psa_generate_key(), psa_generate_key_custom(), psa_key_derivation_output_key(), psa_key_derivation_output_key_custom() or psa_copy_key().

This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Parameters

[out]	attributes	The attribute structure to write to.
	key	The persistent identifier for the key. This can be any value in the range from PSA_KEY_ID_USER_MIN to PSA_KEY_ID_USER_MAX inclusive.

◆ psa_set_key_lifetime()

static void psa_set_key_lifetime	(	psa_key_attributes_t *	attributes,
		psa_key_lifetime_t	lifetime
	)

static

Set the location of a persistent key.

To make a key persistent, you must give it a persistent key identifier with psa_set_key_id(). By default, a key that has a persistent identifier is stored in the default storage area identifier by PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage area, or to explicitly declare the key as volatile.

This function does not access storage, it merely stores the given value in the structure. The persistent key will be written to storage when the attribute structure is passed to a key creation function such as psa_import_key(), psa_generate_key(), psa_generate_key_custom(), psa_key_derivation_output_key(), psa_key_derivation_output_key_custom() or psa_copy_key().

This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Parameters

[out]	attributes	The attribute structure to write to.
	lifetime	The lifetime for the key. If this is PSA_KEY_LIFETIME_VOLATILE, the key will be volatile, and the key identifier attribute is reset to 0.

◆ psa_set_key_type()

static void psa_set_key_type	(	psa_key_attributes_t *	attributes,
		psa_key_type_t	type
	)

static

Declare the type of a key.

This function overwrites any key type previously set in attributes.

This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Parameters

[out]	attributes	The attribute structure to write to.
	type	The key type to write. If this is 0, the key type in `attributes` becomes unspecified.

Referenced by psa_set_key_domain_parameters().

◆ psa_set_key_usage_flags()

static void psa_set_key_usage_flags	(	psa_key_attributes_t *	attributes,
		psa_key_usage_t	usage_flags
	)

static

Declare usage flags for a key.

Usage flags are part of a key's usage policy. They encode what kind of operations are permitted on the key. For more details, refer to the documentation of the type psa_key_usage_t.

This function overwrites any usage flags previously set in attributes.

This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Parameters

[out]	attributes	The attribute structure to write to.
	usage_flags	The usage flags to write.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ PSA_DH_FAMILY_CUSTOM

◆ PSA_KEY_ATTRIBUTES_INIT

◆ PSA_KEY_DOMAIN_PARAMETERS_SIZE

◆ PSA_PAKE_OPERATION_STAGE_COLLECT_INPUTS

◆ PSA_PAKE_OPERATION_STAGE_COMPUTATION

◆ PSA_PAKE_OPERATION_STAGE_SETUP

Typedef Documentation

◆ psa_key_attributes_t

Function Documentation

◆ psa_get_key_algorithm()

◆ psa_get_key_attributes()

◆ psa_get_key_bits()

◆ psa_get_key_domain_parameters()

◆ psa_get_key_enrollment_algorithm()

◆ psa_get_key_id()

◆ psa_get_key_lifetime()

◆ psa_get_key_type()

◆ psa_get_key_usage_flags()

◆ psa_key_attributes_init()

◆ psa_reset_key_attributes()

◆ psa_set_key_algorithm()

◆ psa_set_key_bits()

◆ psa_set_key_domain_parameters()

◆ psa_set_key_enrollment_algorithm()

◆ psa_set_key_id()

◆ psa_set_key_lifetime()

◆ psa_set_key_type()

◆ psa_set_key_usage_flags()