Platform Security Architecture — cryptography and keystore interface  beta 2 — 2019-02-22
Functions
Key management

Functions

psa_status_t psa_get_key_lifetime (psa_key_handle_t handle, psa_key_lifetime_t *lifetime)
 Retrieve the lifetime of an open key. More...
 
psa_status_t psa_allocate_key (psa_key_handle_t *handle)
 
psa_status_t psa_open_key (psa_key_lifetime_t lifetime, psa_key_id_t id, psa_key_handle_t *handle)
 
psa_status_t psa_create_key (psa_key_lifetime_t lifetime, psa_key_id_t id, psa_key_handle_t *handle)
 
psa_status_t psa_close_key (psa_key_handle_t handle)
 

Detailed Description

Function Documentation

psa_status_t psa_allocate_key ( psa_key_handle_t handle)

Allocate a key slot for a transient key, i.e. a key which is only stored in volatile memory.

The allocated key slot and its handle remain valid until the application calls psa_close_key() or psa_destroy_key() or until the application terminates.

Parameters
[out]handleOn success, a handle to a volatile key slot.
Return values
PSA_SUCCESSSuccess. The application can now use the value of *handle to access the newly allocated key slot.
PSA_ERROR_INSUFFICIENT_MEMORYThere was not enough memory, or the maximum number of key slots has been reached.
psa_status_t psa_close_key ( psa_key_handle_t  handle)

Close a key handle.

If the handle designates a volatile key, destroy the key material and free all associated resources, just like psa_destroy_key().

If the handle designates a persistent key, free all resources associated with the key in volatile memory. The key slot in persistent storage is not affected and can be opened again later with psa_open_key().

If the key is currently in use in a multipart operation, the multipart operation is aborted.

Parameters
handleThe key handle to close.
Return values
PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_COMMUNICATION_FAILURE
psa_status_t psa_create_key ( psa_key_lifetime_t  lifetime,
psa_key_id_t  id,
psa_key_handle_t handle 
)

Create a new persistent key slot.

Create a new persistent key slot and return a handle to it. The handle remains valid until the application calls psa_close_key() or terminates. The application can open the key again with psa_open_key() until it removes the key by calling psa_destroy_key().

Parameters
lifetimeThe lifetime of the key. This designates a storage area where the key material is stored. This must not be PSA_KEY_LIFETIME_VOLATILE.
idThe persistent identifier of the key.
[out]handleOn success, a handle to the newly created key slot. When key material is later created in this key slot, it will be saved to the specified persistent location.
Return values
PSA_SUCCESSSuccess. The application can now use the value of *handle to access the newly allocated key slot.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_OCCUPIED_SLOTThere is already a key with the identifier id in the storage area designated by lifetime.
PSA_ERROR_INVALID_ARGUMENTlifetime is invalid, for example PSA_KEY_LIFETIME_VOLATILE.
PSA_ERROR_INVALID_ARGUMENTid is invalid for the specified lifetime.
PSA_ERROR_NOT_SUPPORTEDlifetime is not supported.
PSA_ERROR_NOT_PERMITTEDlifetime is valid, but the application does not have the permission to create a key there.
psa_status_t psa_get_key_lifetime ( psa_key_handle_t  handle,
psa_key_lifetime_t lifetime 
)

Retrieve the lifetime of an open key.

Parameters
handleHandle to query.
[out]lifetimeOn success, the lifetime value.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_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.
psa_status_t psa_open_key ( psa_key_lifetime_t  lifetime,
psa_key_id_t  id,
psa_key_handle_t handle 
)

Open a handle to an existing persistent key.

Open a handle to a key which was previously created with psa_create_key().

Parameters
lifetimeThe lifetime of the key. This designates a storage area where the key material is stored. This must not be PSA_KEY_LIFETIME_VOLATILE.
idThe persistent identifier of the key.
[out]handleOn success, a handle to a key slot which contains the data and metadata loaded from the specified persistent location.
Return values
PSA_SUCCESSSuccess. The application can now use the value of *handle to access the newly allocated key slot.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_EMPTY_SLOT
PSA_ERROR_INVALID_ARGUMENTlifetime is invalid, for example PSA_KEY_LIFETIME_VOLATILE.
PSA_ERROR_INVALID_ARGUMENTid is invalid for the specified lifetime.
PSA_ERROR_NOT_SUPPORTEDlifetime is not supported.
PSA_ERROR_NOT_PERMITTEDThe specified key exists, but the application does not have the permission to access it. Note that this specification does not define any way to create such a key, but it may be possible through implementation-specific means.