Merge pull request #227 from adrianlshaw/fix_section
Move psa_destroy_key and psa_copy_key to Key Management section
This commit is contained in:
Jaeden Amero
GitHub
commit
d93c965d6e
1 changed files with 136 additions and 131 deletions
|
|
@ -443,6 +443,140 @@ psa_status_t psa_open_key(psa_key_id_t id,
|
||||||
*/
|
*/
|
||||||
psa_status_t psa_close_key(psa_key_handle_t handle);
|
psa_status_t psa_close_key(psa_key_handle_t 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 \p 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 \p 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.
|
||||||
|
*
|
||||||
|
* \param source_handle The key to copy. It must be a valid key handle.
|
||||||
|
* \param[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 \p attributes so that
|
||||||
|
* both sets of restrictions apply, as
|
||||||
|
* described in the documentation of this function.
|
||||||
|
* \param[out] target_handle On success, a handle to the newly created key.
|
||||||
|
* \c 0 on failure.
|
||||||
|
*
|
||||||
|
* \retval #PSA_SUCCESS
|
||||||
|
* \retval #PSA_ERROR_INVALID_HANDLE
|
||||||
|
* \p source_handle is invalid.
|
||||||
|
* \retval #PSA_ERROR_ALREADY_EXISTS
|
||||||
|
* This is an attempt to create a persistent key, and there is
|
||||||
|
* already a persistent key with the given identifier.
|
||||||
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||||||
|
* The lifetime or identifier in \p attributes are invalid.
|
||||||
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||||||
|
* The policy constraints on the source and specified in
|
||||||
|
* \p attributes are incompatible.
|
||||||
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||||||
|
* \p attributes specifies a key type or key size
|
||||||
|
* which does not match the attributes of the source key.
|
||||||
|
* \retval #PSA_ERROR_NOT_PERMITTED
|
||||||
|
* The source key does not have the #PSA_KEY_USAGE_COPY usage flag.
|
||||||
|
* \retval #PSA_ERROR_NOT_PERMITTED
|
||||||
|
* The source key is not exportable and its lifetime does not
|
||||||
|
* allow copying it to the target's lifetime.
|
||||||
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
||||||
|
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
|
||||||
|
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
||||||
|
* \retval #PSA_ERROR_HARDWARE_FAILURE
|
||||||
|
* \retval #PSA_ERROR_STORAGE_FAILURE
|
||||||
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
||||||
|
* \retval #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);
|
||||||
|
|
||||||
|
|
||||||
|
/**
|
||||||
|
* \brief 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.
|
||||||
|
*
|
||||||
|
* \param handle Handle to the key to erase.
|
||||||
|
*
|
||||||
|
* \retval #PSA_SUCCESS
|
||||||
|
* The key material has been erased.
|
||||||
|
* \retval #PSA_ERROR_NOT_PERMITTED
|
||||||
|
* The key cannot be erased because it is
|
||||||
|
* read-only, either due to a policy or due to physical restrictions.
|
||||||
|
* \retval #PSA_ERROR_INVALID_HANDLE
|
||||||
|
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
||||||
|
* There was an failure in communication with the cryptoprocessor.
|
||||||
|
* The key material may still be present in the cryptoprocessor.
|
||||||
|
* \retval #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.
|
||||||
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
||||||
|
* An unexpected condition which is not a storage corruption or
|
||||||
|
* a communication failure occurred. The cryptoprocessor may have
|
||||||
|
* been compromised.
|
||||||
|
* \retval #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);
|
||||||
|
|
||||||
/**@}*/
|
/**@}*/
|
||||||
|
|
||||||
/** \defgroup import_export Key import and export
|
/** \defgroup import_export Key import and export
|
||||||
|
|
@ -519,50 +653,7 @@ psa_status_t psa_import_key(const psa_key_attributes_t *attributes,
|
||||||
size_t data_length,
|
size_t data_length,
|
||||||
psa_key_handle_t *handle);
|
psa_key_handle_t *handle);
|
||||||
|
|
||||||
/**
|
|
||||||
* \brief 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.
|
|
||||||
*
|
|
||||||
* \param handle Handle to the key to erase.
|
|
||||||
*
|
|
||||||
* \retval #PSA_SUCCESS
|
|
||||||
* The key material has been erased.
|
|
||||||
* \retval #PSA_ERROR_NOT_PERMITTED
|
|
||||||
* The key cannot be erased because it is
|
|
||||||
* read-only, either due to a policy or due to physical restrictions.
|
|
||||||
* \retval #PSA_ERROR_INVALID_HANDLE
|
|
||||||
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
|
||||||
* There was an failure in communication with the cryptoprocessor.
|
|
||||||
* The key material may still be present in the cryptoprocessor.
|
|
||||||
* \retval #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.
|
|
||||||
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
|
||||||
* An unexpected condition which is not a storage corruption or
|
|
||||||
* a communication failure occurred. The cryptoprocessor may have
|
|
||||||
* been compromised.
|
|
||||||
* \retval #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);
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* \brief Export a key in binary format.
|
* \brief Export a key in binary format.
|
||||||
|
|
@ -722,93 +813,7 @@ psa_status_t psa_export_public_key(psa_key_handle_t handle,
|
||||||
size_t data_size,
|
size_t data_size,
|
||||||
size_t *data_length);
|
size_t *data_length);
|
||||||
|
|
||||||
/** 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 \p 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 \p 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.
|
|
||||||
*
|
|
||||||
* \param source_handle The key to copy. It must be a valid key handle.
|
|
||||||
* \param[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 \p attributes so that
|
|
||||||
* both sets of restrictions apply, as
|
|
||||||
* described in the documentation of this function.
|
|
||||||
* \param[out] target_handle On success, a handle to the newly created key.
|
|
||||||
* \c 0 on failure.
|
|
||||||
*
|
|
||||||
* \retval #PSA_SUCCESS
|
|
||||||
* \retval #PSA_ERROR_INVALID_HANDLE
|
|
||||||
* \p source_handle is invalid.
|
|
||||||
* \retval #PSA_ERROR_ALREADY_EXISTS
|
|
||||||
* This is an attempt to create a persistent key, and there is
|
|
||||||
* already a persistent key with the given identifier.
|
|
||||||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
||||||
* The lifetime or identifier in \p attributes are invalid.
|
|
||||||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
||||||
* The policy constraints on the source and specified in
|
|
||||||
* \p attributes are incompatible.
|
|
||||||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
||||||
* \p attributes specifies a key type or key size
|
|
||||||
* which does not match the attributes of the source key.
|
|
||||||
* \retval #PSA_ERROR_NOT_PERMITTED
|
|
||||||
* The source key does not have the #PSA_KEY_USAGE_COPY usage flag.
|
|
||||||
* \retval #PSA_ERROR_NOT_PERMITTED
|
|
||||||
* The source key is not exportable and its lifetime does not
|
|
||||||
* allow copying it to the target's lifetime.
|
|
||||||
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
|
||||||
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
|
|
||||||
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
|
||||||
* \retval #PSA_ERROR_HARDWARE_FAILURE
|
|
||||||
* \retval #PSA_ERROR_STORAGE_FAILURE
|
|
||||||
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
|
||||||
* \retval #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);
|
|
||||||
|
|
||||||
/**@}*/
|
/**@}*/
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue