Key attributes

Macros
#define	PSA_KEY_ATTRIBUTES_INIT
#define	PSA_DH_FAMILY_CUSTOM    ((psa_dh_family_t) MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(0x7e))
#define	PSA_KEY_DOMAIN_PARAMETERS_SIZE(key_type, key_bits)    MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(1u)
#define	PSA_PAKE_OPERATION_STAGE_SETUP   0
#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

Functions
psa_status_t	psa_get_key_attributes (mbedtls_svc_key_id_t key, psa_key_attributes_t *attributes)
void	psa_reset_key_attributes (psa_key_attributes_t *attributes)

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.

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.

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

PSA_PAKE_OPERATION_STAGE_COLLECT_INPUTS

#define PSA_PAKE_OPERATION_STAGE_COLLECT_INPUTS   1

PSA_PAKE_OPERATION_STAGE_COMPUTATION

#define PSA_PAKE_OPERATION_STAGE_COMPUTATION   2

PSA_PAKE_OPERATION_STAGE_SETUP

#define PSA_PAKE_OPERATION_STAGE_SETUP   0

PAKE operation stages.

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():

• psa_set_key_id()
• psa_set_key_lifetime()
• psa_set_key_type()
• psa_set_key_bits()
• psa_set_key_usage_flags()
• psa_set_key_algorithm()

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));

• 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;

• 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();

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:

1. Create and initialize an attribute structure.
2. 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.
3. Set the key policy with psa_set_key_usage_flags() and psa_set_key_algorithm().
4. Set the key type with psa_set_key_type(). Skip this step if copying an existing key with psa_copy_key().
5. 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().
6. 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.
7. 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:

1. Call psa_get_key_attributes().
2. Call psa_get_key_xxx functions to retrieve the attribute(s) that you are interested in.
3. 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.

Function Documentation

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