key_management

# Key management

psa_status_t psa_status_t psa_purge_key (mbedtls_svc_key_id_t key) psa_purge_key mbedtls_svc_key_id_t key

Remove non-essential copies of key material from memory.

If the key identifier designates a volatile key, this functions does not do anything and returns successfully.

If the key identifier designates a persistent key, then this function will free all resources associated with the key in volatile memory. The key data in persistent storage is not affected and the key can still be used.

key

Identifier of the key to purge.

PSA_SUCCESS

The key material will have been removed from memory if it is not currently required.

PSA_ERROR_INVALID_ARGUMENT

`key` is not a valid key identifier.

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_status_t psa_copy_key (mbedtls_svc_key_id_t source_key, const psa_key_attributes_t *attributes, mbedtls_svc_key_id_t *target_key) psa_copy_key mbedtls_svc_key_id_t source_key const psa_key_attributes_t * attributes mbedtls_svc_key_id_t * target_key

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.

source_key

The key to copy. It must allow the usage PSA_KEY_USAGE_COPY. If a private or secret key is being copied outside of a secure element it must also allow PSA_KEY_USAGE_EXPORT.

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.

target_key

On success, an identifier for the newly created key. For persistent keys, this is the key identifier defined in `attributes`. `0` on failure.

PSA_SUCCESS

PSA_ERROR_INVALID_HANDLE

`source_key` 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, or the policy constraints on the source and specified in `attributes` are incompatible, or `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, or 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_DATA_INVALID

PSA_ERROR_DATA_CORRUPT

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_status_t psa_destroy_key (mbedtls_svc_key_id_t key) psa_destroy_key mbedtls_svc_key_id_t key

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.

If a key is currently in use in a multipart operation, then destroying the key will cause the multipart operation to fail.

key

Identifier of the key to erase. If this is `0`, do nothing and return PSA_SUCCESS.

PSA_SUCCESS

`key` was a valid identifier and the key material that it referred to has been erased. Alternatively, `key` is `0`.

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

`key` is not a valid identifier nor `0`.

PSA_ERROR_COMMUNICATION_FAILURE

There was a failure in communication with the cryptoprocessor. The key material may still be present in the cryptoprocessor.

PSA_ERROR_DATA_INVALID

This error is typically a result of either storage corruption on a cleartext storage backend, or an attempt to read data that was written by an incompatible version of the library.

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.