Key management
Functions | |
psa_status_t | psa_open_key (psa_key_id_t id, psa_key_handle_t *handle) |
psa_status_t | psa_close_key (psa_key_handle_t handle) |
psa_status_t | psa_copy_key (psa_key_handle_t source_handle, const psa_key_attributes_t *attributes, psa_key_handle_t *target_handle) |
psa_status_t | psa_destroy_key (psa_key_handle_t handle) |
Destroy a key. | |
Function Documentation
psa_status_t psa_close_key | ( | psa_key_handle_t |
handle | ) |
Close a key handle.
If the handle designates a volatile key, this will destroy the key material and free all associated resources, just like psa_destroy_key().
If this is the last open handle to a persistent key, then closing the handle will free all resources associated with the key in volatile memory. The key data in persistent storage is not affected and can be opened again later with a call to psa_open_key().
Closing the key handle makes the handle invalid, and the key handle must not be used again by the application.
- Note
- If the key handle was used to set up an active :ref:`multipart operation <multipart-operations>`, then closing the key handle can cause the multipart operation to fail. Applications should maintain the key handle until after the multipart operation has finished.
- Parameters
-
handle
The key handle to close. If this is 0
, do nothing and returnPSA_SUCCESS
.
- Return values
-
PSA_SUCCESS
handle
was a valid handle or0
. It is now closed.PSA_ERROR_INVALID_HANDLE
handle
is not a valid handle nor0
.PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
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_status_t psa_copy_key | ( | psa_key_handle_t |
source_handle, |
const psa_key_attributes_t * | attributes, |
||
psa_key_handle_t * |
target_handle |
||
) |
Make a copy of a key.
Copy key material from one location to another.
This function is primarily useful to copy a key from one location to another, since it populates a key using the material from another key which may have a different lifetime.
This function may be used to share a key with a different party, subject to implementation-defined restrictions on key sharing.
The policy on the source key must have the usage flag PSA_KEY_USAGE_COPY set. This flag is sufficient to permit the copy if the key has the lifetime PSA_KEY_LIFETIME_VOLATILE or PSA_KEY_LIFETIME_PERSISTENT. Some secure elements do not provide a way to copy a key without making it extractable from the secure element. If a key is located in such a secure element, then the key must have both usage flags PSA_KEY_USAGE_COPY and PSA_KEY_USAGE_EXPORT in order to make a copy of the key outside the secure element.
The resulting key may only be used in a way that conforms to both the policy of the original key and the policy specified in the attributes
parameter:
- The usage flags on the resulting key are the bitwise-and of the usage flags on the source policy and the usage flags in
attributes
. - If both allow the same algorithm or wildcard-based algorithm policy, the resulting key has the same algorithm policy.
- If either of the policies allows an algorithm and the other policy allows a wildcard-based algorithm policy that includes this algorithm, the resulting key allows the same algorithm.
- If the policies do not allow any algorithm in common, this function fails with the status
PSA_ERROR_INVALID_ARGUMENT
.
The effect of this function on implementation-defined attributes is implementation-defined.
- Parameters
-
source_handle
The key to copy. It must be a valid key handle. [in] attributes
The attributes for the new key. They are used as follows: - The key type and size may be 0. If either is nonzero, it must match the corresponding attribute of the source key.
- The key location (the lifetime and, for persistent keys, the key identifier) is used directly.
- The policy constraints (usage flags and algorithm policy) are combined from the source key and
attributes
so that both sets of restrictions apply, as described in the documentation of this function.
[out] target_handle
On success, a handle to the newly created key. 0
on failure.
- Return values
-
PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
source_handle
is invalid.PSA_ERROR_ALREADY_EXISTS
This is an attempt to create a persistent key, and there is already a persistent key with the given identifier. PSA_ERROR_INVALID_ARGUMENT
The lifetime or identifier in attributes
are invalid.PSA_ERROR_INVALID_ARGUMENT
The policy constraints on the source and specified in attributes
are incompatible.PSA_ERROR_INVALID_ARGUMENT
attributes
specifies a key type or key size which does not match the attributes of the source key.PSA_ERROR_NOT_PERMITTED
The source key does not have the PSA_KEY_USAGE_COPY usage flag. PSA_ERROR_NOT_PERMITTED
The source key is not exportable and its lifetime does not allow copying it to the target's lifetime. PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
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_status_t psa_destroy_key | ( | psa_key_handle_t |
handle | ) |
Destroy a key.
This function destroys a key from both volatile memory and, if applicable, non-volatile storage. Implementations shall make a best effort to ensure that that the key material cannot be recovered.
This function also erases any metadata such as policies and frees resources associated with the key. To free all resources associated with the key, all handles to the key must be closed or destroyed.
Destroying the key makes the handle invalid, and the key handle must not be used again by the application. Using other open handles to the destroyed key in a cryptographic operation will result in an error.
If a key is currently in use in a multipart operation, then destroying the key will cause the multipart operation to fail.
- Parameters
-
handle
Handle to the key to erase. If this is 0
, do nothing and returnPSA_SUCCESS
.
- Return values
-
PSA_SUCCESS
handle
was a valid handle and the key material that it referred to has been erased. Alternatively,handle
is0
.PSA_ERROR_NOT_PERMITTED
The key cannot be erased because it is read-only, either due to a policy or due to physical restrictions. PSA_ERROR_INVALID_HANDLE
handle
is not a valid handle nor0
.PSA_ERROR_COMMUNICATION_FAILURE
There was an failure in communication with the cryptoprocessor. The key material may still be present in the cryptoprocessor. PSA_ERROR_STORAGE_FAILURE
The storage is corrupted. Implementations shall make a best effort to erase key material even in this stage, however applications should be aware that it may be impossible to guarantee that the key material is not recoverable in such cases. PSA_ERROR_CORRUPTION_DETECTED
An unexpected condition which is not a storage corruption or a communication failure occurred. The cryptoprocessor may have been compromised. 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_status_t psa_open_key | ( | psa_key_id_t | id, |
psa_key_handle_t * |
handle |
||
) |
Open a handle to an existing persistent key.
Open a handle to a persistent key. A key is persistent if it was created with a lifetime other than PSA_KEY_LIFETIME_VOLATILE. A persistent key always has a nonzero key identifier, set with psa_set_key_id() when creating the key. Implementations may provide additional pre-provisioned keys that can be opened with psa_open_key(). Such keys have a key identifier in the vendor range, as documented in the description of psa_key_id_t.
The application must eventually close the handle with psa_close_key() or psa_destroy_key() to release associated resources. If the application dies without calling one of these functions, the implementation should perform the equivalent of a call to psa_close_key().
Some implementations permit an application to open the same key multiple times. If this is successful, each call to psa_open_key() will return a different key handle.
- Note
- Applications that rely on opening a key multiple times will not be portable to implementations that only permit a single key handle to be opened. See also :ref:`key-handles`.
- Parameters
-
id
The persistent identifier of the key. [out] handle
On success, a handle to the key.
- Return values
-
PSA_SUCCESS
Success. The application can now use the value of *handle
to access the key.PSA_ERROR_INSUFFICIENT_MEMORY
The implementation does not have sufficient resources to open the key. This can be due to reaching an implementation limit on the number of open keys, the number of open key handles, or available memory. PSA_ERROR_DOES_NOT_EXIST
There is no persistent key with key identifier id
.PSA_ERROR_INVALID_ARGUMENT
id
is not a valid persistent key identifier.PSA_ERROR_NOT_PERMITTED
The 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. PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
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.