attributes.h File Reference

Key attributes definitions for the PSA Crypto API. More...

Detailed Description

Key attributes definitions for the PSA Crypto API.

Author

Armin Wolf wolf..nosp@m.armi.nosp@m.n@mai.nosp@m.lbox.nosp@m..tu-d.nosp@m.resd.nosp@m.en.de

Lena Boeckmann lena..nosp@m.boec.nosp@m.kmann.nosp@m.@haw.nosp@m.-hamb.nosp@m.urg..nosp@m.de

Definition in file attributes.h.

#include "psa/algorithm.h"
#include "bits.h"
#include "id.h"
#include "lifetime.h"
#include "type.h"
#include "usage.h"

Include dependency graph for attributes.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	psa_key_policy_s
	Structure storing the key usage policies. More...
struct	psa_key_attributes_s
	Structure storing key attributes. More...
#define	PSA_KEY_ATTRIBUTES_INIT   { 0 }
	This macro returns a suitable initializer for a key attribute object of type psa_key_attributes_t.
typedef struct psa_key_policy_s	psa_key_policy_t
	Type for key usage policies.
typedef struct psa_key_attributes_s	psa_key_attributes_t
	The type of an object containing key attributes.
static psa_key_attributes_t	psa_key_attributes_init (void)
	Return an initial value for a key attribute object.

Macro Definition Documentation

PSA_KEY_ATTRIBUTES_INIT

#define PSA_KEY_ATTRIBUTES_INIT   { 0 }

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

Definition at line 167 of file attributes.h.

Typedef Documentation

psa_key_attributes_t

typedef struct psa_key_attributes_s psa_key_attributes_t

The type of an object containing key attributes.

This is the object that represents 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 can 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.

Note

Implementations are recommended to define the attribute object as a simple data structure, with fields corresponding to the individual key attributes. In such an implementation, each function psa_set_key_xxx() sets a field and the corresponding function psa_get_key_xxx() retrieves the value of the field. An implementation can report attribute values that are equivalent to the original one, but have a different encoding. For example, an implementation can 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 might not be the one that was originally stored.

This is an implementation-defined type. Applications that make assumptions about the content of this object will result in in implementation-specific behavior, and are non-portable.

An attribute object can 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 object is optional if the object 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 object, the application must initialize it by any of the following means:
• Set the object to all-bits-zero, for example:

  @ref psa_key_attributes_t attributes;
  memset(&attributes, 0, sizeof(attributes));

• Initialize the object to logical zero values by declaring the object as static or global without an explicit initializer, for example:

  static @ref psa_key_attributes_t attributes;

• Initialize the object to the initializer PSA_KEY_ATTRIBUTES_INIT, for example:

  @ref psa_key_attributes_t attributes = @ref PSA_KEY_ATTRIBUTES_INIT;

• Assign the result of the function psa_key_attributes_init() to the object, for example:

  @ref psa_key_attributes_t attributes;
  attributes = @ref psa_key_attributes_init();

A freshly initialized attribute object contains the following values:

• lifetime: PSA_KEY_LIFETIME_VOLATILE.
• key identifier: PSA_KEY_ID_NULL — which is not a valid key identifier.
• type: PSA_KEY_TYPE_NONE — 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: PSA_ALG_NONE — which does not allow cryptographic usage, but allows exporting.

Usage

A typical sequence to create a key is as follows:

1. Create and initialize an attribute object.
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 object, creates a key with these attributes, and outputs an identifier for the newly created key.
7. Optionally call psa_reset_key_attributes(), now that the attribute object is no longer needed. Currently this call is not required as the attributes defined in this specification do not require additional resources beyond the object 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 required attribute(s).
3. Call psa_reset_key_attributes() to free any resources that can be used by the attribute object.

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

Definition at line 161 of file attributes.h.

psa_key_policy_t

typedef struct psa_key_policy_s psa_key_policy_t

Type for key usage policies.

Definition at line 47 of file attributes.h.

Function Documentation

psa_key_attributes_init()

static psa_key_attributes_t psa_key_attributes_init ( void  )

inlinestatic

Return an initial value for a key attribute object.

Returns

psa_key_attributes_t

Definition at line 174 of file attributes.h.