Kenji Arai / mbed-os_TYBLE16

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

Embed: (wiki syntax)

« Back to documentation index

Key attributes

Key attributes

Typedefs

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

Functions

static psa_key_attributes_t psa_key_attributes_init (void)
 Return an initial value for a key attributes structure.
static void psa_set_key_id (psa_key_attributes_t *attributes, psa_key_id_t id)
 Declare a key as persistent and set its key identifier.
static void psa_set_key_lifetime (psa_key_attributes_t *attributes, psa_key_lifetime_t lifetime)
 Set the location of a persistent key.
static psa_key_id_t psa_get_key_id (const psa_key_attributes_t *attributes)
 Retrieve the key identifier from key attributes.
static psa_key_lifetime_t psa_get_key_lifetime (const psa_key_attributes_t *attributes)
 Retrieve the lifetime from key attributes.
static void psa_set_key_usage_flags (psa_key_attributes_t *attributes, psa_key_usage_t usage_flags)
 Declare usage flags for a key.
static psa_key_usage_t psa_get_key_usage_flags (const psa_key_attributes_t *attributes)
 Retrieve the usage flags from key attributes.
static void psa_set_key_algorithm (psa_key_attributes_t *attributes, psa_algorithm_t alg)
 Declare the permitted algorithm policy for a key.
static psa_algorithm_t psa_get_key_algorithm (const psa_key_attributes_t *attributes)
 Retrieve the algorithm policy from key attributes.
static void psa_set_key_type (psa_key_attributes_t *attributes, psa_key_type_t type)
 Declare the type of a key.
static void psa_set_key_bits (psa_key_attributes_t *attributes, size_t bits)
 Declare the size of a key.
static psa_key_type_t psa_get_key_type (const psa_key_attributes_t *attributes)
 Retrieve the key type from key attributes.
static size_t psa_get_key_bits (const psa_key_attributes_t *attributes)
 Retrieve the key size from key attributes.
psa_status_t psa_get_key_attributes (psa_key_handle_t handle, psa_key_attributes_t *attributes)
 Retrieve the attributes of a key.
void psa_reset_key_attributes (psa_key_attributes_t *attributes)
 Reset a key attribute structure to a freshly initialized state.
static void psa_set_key_enrollment_algorithm (psa_key_attributes_t *attributes, psa_algorithm_t alg2)
 Declare the enrollment algorithm for a key.
static psa_algorithm_t psa_get_key_enrollment_algorithm (const psa_key_attributes_t *attributes)
 Retrieve the enrollment algorithm policy from key attributes.
psa_status_t psa_get_key_slot_number (const psa_key_attributes_t *attributes, psa_key_slot_number_t *slot_number)
 Retrieve the slot number where a key is stored.
static void psa_set_key_slot_number (psa_key_attributes_t *attributes, psa_key_slot_number_t slot_number)
 Choose the slot number where a key is stored.
static void psa_clear_key_slot_number (psa_key_attributes_t *attributes)
 Remove the slot number attribute from a key attribute structure.
psa_status_t mbedtls_psa_register_se_key (const psa_key_attributes_t *attributes)
 Register a key that is already present in a secure element.
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.
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.

Typedef Documentation

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.
  • Implementations may define additional 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 can be 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, implementations may report values that are equivalent to the original one, but have a different encoding. For example, an implementation may use a more compact representation for types where many bit-patterns are invalid or not supported, and store all values that it does not support as a special marker value. In such an implementation, after setting an invalid value, the corresponding get function returns an invalid value which may not be the one that was originally stored.

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:

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

Definition at line 319 of file crypto_types.h.


Function Documentation

psa_status_t mbedtls_psa_register_se_key ( const psa_key_attributes_t attributes )

Register a key that is already present in a secure element.

The key must be located in a secure element designated by the lifetime field in attributes, in the slot set with psa_set_key_slot_number() in the attribute structure. This function makes the key available through the key identifier specified in attributes.

Parameters:
[in]attributesThe attributes of the existing key.
Return values:
PSA_SUCCESSThe key was successfully registered. Note that depending on the design of the driver, this may or may not guarantee that a key actually exists in the designated slot and is compatible with the specified attributes.
PSA_ERROR_ALREADY_EXISTSThere is already a key with the identifier specified in attributes.
PSA_ERROR_NOT_SUPPORTEDThe secure element driver for the specified lifetime does not support registering a key.
PSA_ERROR_INVALID_ARGUMENTattributes specifies a lifetime which is not located in a secure element.
PSA_ERROR_INVALID_ARGUMENTNo slot number is specified in attributes, or the specified slot number is not valid.
PSA_ERROR_NOT_PERMITTEDThe caller is not authorized to register the specified key slot.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

Definition at line 1889 of file psa_crypto.c.

static void psa_clear_key_slot_number ( psa_key_attributes_t attributes ) [static]

Remove the slot number attribute from a key attribute structure.

This function undoes the action of psa_set_key_slot_number().

Parameters:
[out]attributesThe attribute structure to write to.

Definition at line 165 of file crypto_extra.h.

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]attributesThe key attribute structure to query.
Returns:
The algorithm stored in the attribute structure.
psa_status_t psa_get_key_attributes ( psa_key_handle_t  handle,
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]handleHandle to the key to query.
[in,out]attributesOn success, the attributes of the key. On failure, equivalent to a freshly-initialized structure.
Return values:
PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

Definition at line 1186 of file psa_crypto.c.

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]attributesThe key attribute structure to query.
Returns:
The key size stored in the attribute structure, in bits.
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.

Get the domain parameters for a key with this function, if any. The format of the domain parameters written to data is specified in the documentation for psa_set_key_domain_parameters().

Note:
This is an experimental extension to the interface. It may change in future versions of the library.
Parameters:
[in]attributesThe key attribute structure to query.
[out]dataOn success, the key domain parameters.
data_sizeSize of the data buffer in bytes. The buffer is guaranteed to be large enough if its size in bytes is at least the value given by PSA_KEY_DOMAIN_PARAMETERS_SIZE().
[out]data_lengthOn success, the number of bytes that make up the key domain parameters data.
Return values:
PSA_SUCCESS
PSA_ERROR_BUFFER_TOO_SMALL

Definition at line 1129 of file psa_crypto.c.

static psa_algorithm_t psa_get_key_enrollment_algorithm ( const psa_key_attributes_t attributes ) [static]

Retrieve the enrollment algorithm policy from key attributes.

Parameters:
[in]attributesThe key attribute structure to query.
Returns:
The enrollment algorithm stored in the attribute structure.

Definition at line 94 of file crypto_extra.h.

static psa_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]attributesThe 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.
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]attributesThe key attribute structure to query.
Returns:
The lifetime value stored in the attribute structure.
psa_status_t psa_get_key_slot_number ( const psa_key_attributes_t attributes,
psa_key_slot_number_t slot_number 
)

Retrieve the slot number where a key is stored.

A slot number is only defined for keys that are stored in a secure element.

This information is only useful if the secure element is not entirely managed through the PSA Cryptography API. It is up to the secure element driver to decide how PSA slot numbers map to any other interface that the secure element may have.

Parameters:
[in]attributesThe key attribute structure to query.
[out]slot_numberOn success, the slot number containing the key.
Return values:
PSA_SUCCESSThe key is located in a secure element, and *slot_number indicates the slot number that contains it.
PSA_ERROR_NOT_PERMITTEDThe caller is not permitted to query the slot number. Mbed Crypto currently does not return this error.
PSA_ERROR_INVALID_ARGUMENTThe key is not located in a secure element.

Definition at line 1234 of file psa_crypto.c.

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]attributesThe key attribute structure to query.
Returns:
The key type stored in the attribute structure.
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]attributesThe key attribute structure to query.
Returns:
The usage flags stored in the attribute structure.
static psa_key_attributes_t psa_key_attributes_init ( void   ) [static]

Return an initial value for a key attributes structure.

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]attributesThe attribute structure to reset.

Definition at line 1093 of file psa_crypto.c.

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.

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]attributesThe attribute structure to write to.
algThe permitted algorithm policy to write.
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]attributesThe attribute structure to write to.
bitsThe key size in bits. If this is 0, the key size in attributes becomes unspecified. Keys of size 0 are not supported.
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.

Some key types require additional domain parameters in addition to the key type identifier and the key size. Use this function instead of psa_set_key_type() when you need to specify domain parameters.

The format for the required domain parameters varies based on the key type.

  • For RSA keys (PSA_KEY_TYPE_RSA_PUBLIC_KEY or PSA_KEY_TYPE_RSA_KEY_PAIR), the domain parameter data consists of the public exponent, represented as a big-endian integer with no leading zeros. This information is used when generating an RSA key pair. When importing a key, the public exponent is read from the imported key data and the exponent recorded in the attribute structure is ignored. As an exception, the public exponent 65537 is represented by an empty byte string.
  • For DSA keys (PSA_KEY_TYPE_DSA_PUBLIC_KEY or PSA_KEY_TYPE_DSA_KEY_PAIR), the `Dss-Parms` format as defined by RFC 3279 2.3.2. ``` Dss-Parms ::= SEQUENCE { p INTEGER, q INTEGER, g INTEGER } ```
  • For Diffie-Hellman key exchange keys (PSA_KEY_TYPE_DH_PUBLIC_KEY(PSA_DH_GROUP_CUSTOM) or PSA_KEY_TYPE_DH_KEY_PAIR(PSA_DH_GROUP_CUSTOM)), the `DomainParameters` format as defined by RFC 3279 2.3.3. ``` DomainParameters ::= SEQUENCE { p INTEGER, -- odd prime, p=jq +1 g INTEGER, -- generator, g q INTEGER, -- factor of p-1 j INTEGER OPTIONAL, -- subgroup factor validationParms ValidationParms OPTIONAL } ValidationParms ::= SEQUENCE { seed BIT STRING, pgenCounter INTEGER } ```
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.
This is an experimental extension to the interface. It may change in future versions of the library.
Parameters:
[in,out]attributesAttribute structure where the specified domain parameters will be stored. If this function fails, the content of attributes is not modified.
typeKey type (a PSA_KEY_TYPE_XXX value).
[in]dataBuffer containing the key domain parameters. The content of this buffer is interpreted according to type as described above.
data_lengthSize of the data buffer in bytes.
Return values:
PSA_SUCCESS
PSA_ERROR_INVALID_ARGUMENT
PSA_ERROR_NOT_SUPPORTED
PSA_ERROR_INSUFFICIENT_MEMORY

Definition at line 1099 of file psa_crypto.c.

static void psa_set_key_enrollment_algorithm ( psa_key_attributes_t attributes,
psa_algorithm_t  alg2 
) [static]

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]attributesThe attribute structure to write to.
alg2A 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 81 of file crypto_extra.h.

static void psa_set_key_id ( psa_key_attributes_t attributes,
psa_key_id_t  id 
) [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_key_derivation_output_key() 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]attributesThe attribute structure to write to.
idThe persistent identifier for the key.
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_key_derivation_output_key() 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]attributesThe attribute structure to write to.
lifetimeThe 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.
static void psa_set_key_slot_number ( psa_key_attributes_t attributes,
psa_key_slot_number_t  slot_number 
) [static]

Choose the slot number where a key is stored.

This function declares a slot number in the specified attribute structure.

A slot number is only meaningful for keys that are stored in a secure element. It is up to the secure element driver to decide how PSA slot numbers map to any other interface that the secure element may have.

Note:
Setting a slot number in key attributes for a key creation can cause the following errors when creating the key:
  • PSA_ERROR_NOT_SUPPORTED if the selected secure element does not support choosing a specific slot number.
  • PSA_ERROR_NOT_PERMITTED if the caller is not permitted to choose slot numbers in general or to choose this specific slot.
  • PSA_ERROR_INVALID_ARGUMENT if the chosen slot number is not valid in general or not valid for this specific key.
  • PSA_ERROR_ALREADY_EXISTS if there is already a key in the selected slot.
Parameters:
[out]attributesThe attribute structure to write to.
slot_numberThe slot number to set.

Definition at line 151 of file crypto_extra.h.

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]attributesThe attribute structure to write to.
typeThe key type to write. If this is 0, the key type in attributes becomes unspecified.
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]attributesThe attribute structure to write to.
usage_flagsThe usage flags to write.