Key attributes

Macros
#define	KEYSTORE_PSA_KEY_ATTRIBUTES_INIT   PSA_KEY_ATTRIBUTES_INIT
#define	GET_KEY_ID(keyID, ID)   keyID = ID
#define	SET_KEY_ID(ID, keyID)   ID = keyID

Typedefs
typedef psa_key_attributes_t	KeyStore_PSA_KeyAttributes

Detailed Description

Macro Definition Documentation

KEYSTORE_PSA_KEY_ATTRIBUTES_INIT

#define KEYSTORE_PSA_KEY_ATTRIBUTES_INIT   PSA_KEY_ATTRIBUTES_INIT

GET_KEY_ID

#define GET_KEY_ID	(		keyID,
			ID
	)		keyID = ID

Macro to assign and get keyID

It depends on MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER to assign keyID and owner if multiple partition supported by mbedtls

SET_KEY_ID

#define SET_KEY_ID	(		ID,
			keyID
	)		ID = keyID

Typedef Documentation

KeyStore_PSA_KeyAttributes

typedef psa_key_attributes_t KeyStore_PSA_KeyAttributes

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.

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 KeyStore_PSA_setKeyXXX sets a field and the corresponding function KeyStore_PSA_getKeyXXX 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 KeyStore_PSA_resetKeyAttributes(). As an exception, calling KeyStore_PSA_resetKeyAttributes() 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 KeyStore_PSA_resetKeyAttributes():

• KeyStore_PSA_setKeyId()
• KeyStore_PSA_setKeyLifetime()
• KeyStore_PSA_setKeyType()
• KeyStore_PSA_setKeyBits()
• KeyStore_PSA_setKeyUsageFlags()
• KeyStore_PSA_setKeyAlgorithm()

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:

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

• Initialize the structure to logical zero values, for example:

  KeyStore_PSA_KeyAttributes attributes = {0};

• Initialize the structure to the initializer KEYSTORE_PSA_KEY_ATTRIBUTES_INIT, for example:

  KeyStore_PSA_KeyAttributes attributes = KEYSTORE_PSA_KEY_ATTRIBUTES_INIT;

A freshly initialized attribute structure contains the following values:

• lifetime: KEYSTORE_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 KeyStore_PSA_setKeyId(). Also call KeyStore_PSA_setKeyLifetime() to place the key in a non-default location.
3. Set the key policy with KeyStore_PSA_setKeyUsageFlags() and KeyStore_PSA_setKeyAlgorithm().
4. Set the key type with KeyStore_PSA_setKeyType().
5. When generating a random key with KeyStore_PSA_generateKey() or deriving a key with KeyStore_PSA_key_derivation_output_key(), set the desired key size with KeyStore_PSA_setKeyBits().
6. Call a key creation function: KeyStore_PSA_importKey(), KeyStore_PSA_generateKey(), KeyStore_PSA_key_derivation_output_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 KeyStore_PSA_resetKeyAttributes(), 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 KeyStore_PSA_getKeyAttributes().
2. Call KeyStore_PSA_get_key_xxx functions to retrieve the attribute(s) that you are interested in.
3. Call KeyStore_PSA_resetKeyAttributes() 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.