mirror of
https://github.com/yuzu-emu/mbedtls.git
synced 2024-12-25 01:05:41 +00:00
Merge pull request #269 from ARMmbed/psa-slots_to_handles
Update API documentation to refer to handles and key ids, not slots
This commit is contained in:
commit
fba7539ad7
|
@ -332,6 +332,7 @@ static psa_key_usage_t psa_get_key_usage_flags(
|
|||
static void psa_set_key_algorithm(psa_key_attributes_t *attributes,
|
||||
psa_algorithm_t alg);
|
||||
|
||||
|
||||
/** Retrieve the algorithm policy from key attributes.
|
||||
*
|
||||
* This function may be declared as `static` (i.e. without external
|
||||
|
@ -360,6 +361,7 @@ static psa_algorithm_t psa_get_key_algorithm(
|
|||
static void psa_set_key_type(psa_key_attributes_t *attributes,
|
||||
psa_key_type_t type);
|
||||
|
||||
|
||||
/** Declare the size of a key.
|
||||
*
|
||||
* This function overwrites any key size previously set in \p attributes.
|
||||
|
@ -443,20 +445,21 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes);
|
|||
|
||||
/** Open a handle to an existing persistent key.
|
||||
*
|
||||
* Open a handle to a key which was previously created with psa_create_key().
|
||||
* Open a handle to a key which was previously created with
|
||||
* psa_make_key_persistent() when setting its attributes.
|
||||
* The handle should eventually be closed with psa_close_key()
|
||||
* to release associated resources.
|
||||
*
|
||||
* Implementations may provide additional 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.
|
||||
*
|
||||
* \param id The persistent identifier of the key.
|
||||
* \param[out] handle On success, a handle to a key slot which contains
|
||||
* the data and metadata loaded from the specified
|
||||
* persistent location.
|
||||
* \param[out] handle On success, a handle to the key.
|
||||
*
|
||||
* \retval #PSA_SUCCESS
|
||||
* Success. The application can now use the value of `*handle`
|
||||
* to access the newly allocated key slot.
|
||||
* to access the key.
|
||||
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
||||
* \retval #PSA_ERROR_DOES_NOT_EXIST
|
||||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||||
|
@ -472,13 +475,14 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes);
|
|||
psa_status_t psa_open_key(psa_key_id_t id,
|
||||
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
|
||||
* with the key in volatile memory. The key 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,
|
||||
|
@ -513,6 +517,7 @@ psa_status_t psa_close_key(psa_key_handle_t handle);
|
|||
* minimize the risk that an invalid input is accidentally interpreted
|
||||
* according to a different format.
|
||||
*
|
||||
|
||||
* \param[in] attributes The attributes for the new key.
|
||||
* The key size is always determined from the
|
||||
* \p data buffer.
|
||||
|
@ -568,23 +573,19 @@ psa_status_t psa_import_key(const psa_key_attributes_t *attributes,
|
|||
/**
|
||||
* \brief Destroy a key.
|
||||
*
|
||||
* This function destroys the content of the key slot from both volatile
|
||||
* This function destroys a key from both volatile
|
||||
* memory and, if applicable, non-volatile storage. Implementations shall
|
||||
* make a best effort to ensure that any previous content of the slot is
|
||||
* unrecoverable.
|
||||
* 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 all
|
||||
* resources associated with the key.
|
||||
*
|
||||
* If the key is currently in use in a multipart operation,
|
||||
* the multipart operation is aborted.
|
||||
*
|
||||
* \param handle Handle to the key slot to erase.
|
||||
* \param handle Handle to the key to erase.
|
||||
*
|
||||
* \retval #PSA_SUCCESS
|
||||
* The slot's content, if any, has been erased.
|
||||
* The key material has been erased.
|
||||
* \retval #PSA_ERROR_NOT_PERMITTED
|
||||
* The slot holds content and cannot be erased because it is
|
||||
* 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
|
||||
|
@ -770,8 +771,7 @@ psa_status_t psa_export_public_key(psa_key_handle_t handle,
|
|||
* to another, since it populates a key using the material from
|
||||
* another key which may have a different lifetime.
|
||||
*
|
||||
* In an implementation where slots have different ownerships,
|
||||
* this function may be used to share a key with a different party,
|
||||
* 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
|
||||
|
@ -800,8 +800,7 @@ psa_status_t psa_export_public_key(psa_key_handle_t handle,
|
|||
* The effect of this function on implementation-defined attributes is
|
||||
* implementation-defined.
|
||||
*
|
||||
* \param source_handle The key to copy. It must be a handle to an
|
||||
* occupied slot.
|
||||
* \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
|
||||
|
@ -3291,7 +3290,7 @@ psa_status_t psa_key_derivation_output_bytes(
|
|||
* this function will not succeed, even with a smaller output buffer.
|
||||
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||||
* The key type or key size is not supported, either by the
|
||||
* implementation in general or in this particular slot.
|
||||
* implementation in general or in this particular location.
|
||||
* \retval #PSA_ERROR_BAD_STATE
|
||||
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
||||
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
|
||||
|
|
|
@ -232,7 +232,7 @@ static psa_key_policy_t psa_key_policy_init(void);
|
|||
*
|
||||
* Note that this function does not make any consistency check of the
|
||||
* parameters. The values are only checked when applying the policy to
|
||||
* a key slot with psa_set_key_policy().
|
||||
* a key with psa_set_key_policy().
|
||||
*
|
||||
* \param[in,out] policy The key policy to modify. It must have been
|
||||
* initialized as per the documentation for
|
||||
|
@ -260,14 +260,14 @@ psa_key_usage_t psa_key_policy_get_usage(const psa_key_policy_t *policy);
|
|||
*/
|
||||
psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy);
|
||||
|
||||
/** \brief Set the usage policy on a key slot.
|
||||
/** \brief Set the usage policy for a key.
|
||||
*
|
||||
* This function must be called on an empty key slot, before importing,
|
||||
* generating or creating a key in the slot. Changing the policy of an
|
||||
* This function must be called on a key handle before importing,
|
||||
* generating or creating a key. Changing the policy of an
|
||||
* existing key is not permitted.
|
||||
*
|
||||
* Implementations may set restrictions on supported key policies
|
||||
* depending on the key type and the key slot.
|
||||
* depending on the key type.
|
||||
*
|
||||
* \param handle Handle to the key whose policy is to be changed.
|
||||
* \param[in] policy The policy object to query.
|
||||
|
@ -292,9 +292,9 @@ psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy);
|
|||
psa_status_t psa_set_key_policy(psa_key_handle_t handle,
|
||||
const psa_key_policy_t *policy);
|
||||
|
||||
/** \brief Get the usage policy for a key slot.
|
||||
/** \brief Get the usage policy for a key.
|
||||
*
|
||||
* \param handle Handle to the key slot whose policy is being queried.
|
||||
* \param handle Handle to the key whose policy is being queried.
|
||||
* \param[out] policy On success, the key's policy.
|
||||
*
|
||||
* \retval #PSA_SUCCESS
|
||||
|
@ -321,9 +321,9 @@ psa_status_t psa_get_key_policy(psa_key_handle_t handle,
|
|||
* a structure that represents the properties.
|
||||
*/
|
||||
|
||||
/** Create a new persistent key slot.
|
||||
/** Create a new persistent key.
|
||||
*
|
||||
* Create a new persistent key slot and return a handle to it. The handle
|
||||
* Create a new persistent key 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().
|
||||
|
@ -332,13 +332,13 @@ psa_status_t psa_get_key_policy(psa_key_handle_t handle,
|
|||
* area where the key material is stored. This must not
|
||||
* be #PSA_KEY_LIFETIME_VOLATILE.
|
||||
* \param id The persistent identifier of the key.
|
||||
* \param[out] handle On success, a handle to the newly created key slot.
|
||||
* When key material is later created in this key slot,
|
||||
* \param[out] handle On success, a handle to the newly created key.
|
||||
* When key material is later created in this key,
|
||||
* it will be saved to the specified persistent location.
|
||||
*
|
||||
* \retval #PSA_SUCCESS
|
||||
* Success. The application can now use the value of `*handle`
|
||||
* to access the newly allocated key slot.
|
||||
* for key operations.
|
||||
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
||||
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
|
||||
* \retval #PSA_ERROR_ALREADY_EXISTS
|
||||
|
@ -358,20 +358,20 @@ psa_status_t psa_create_key(psa_key_lifetime_t lifetime,
|
|||
psa_key_id_t id,
|
||||
psa_key_handle_t *handle);
|
||||
|
||||
/** Allocate a key slot for a transient key, i.e. a key which is only stored
|
||||
/** Allocate space 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
|
||||
* The allocated key and its handle remain valid until the
|
||||
* application calls psa_close_key() or psa_destroy_key() or until the
|
||||
* application terminates.
|
||||
*
|
||||
* \param[out] handle On success, a handle to a volatile key slot.
|
||||
* \param[out] handle On success, a handle to a volatile key.
|
||||
*
|
||||
* \retval #PSA_SUCCESS
|
||||
* Success. The application can now use the value of `*handle`
|
||||
* to access the newly allocated key slot.
|
||||
* to refer to the key.
|
||||
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
||||
* There was not enough memory, or the maximum number of key slots
|
||||
* There was not enough memory, or the maximum number of transient keys
|
||||
* has been reached.
|
||||
*/
|
||||
psa_status_t psa_allocate_key(psa_key_handle_t *handle);
|
||||
|
@ -379,7 +379,7 @@ psa_status_t psa_allocate_key(psa_key_handle_t *handle);
|
|||
/**
|
||||
* \brief Get basic metadata about a key.
|
||||
*
|
||||
* \param handle Handle to the key slot to query.
|
||||
* \param handle Handle to the key to query.
|
||||
* \param[out] type On success, the key type (a \c PSA_KEY_TYPE_XXX value).
|
||||
* This may be a null pointer, in which case the key type
|
||||
* is not written.
|
||||
|
@ -390,7 +390,7 @@ psa_status_t psa_allocate_key(psa_key_handle_t *handle);
|
|||
* \retval #PSA_SUCCESS
|
||||
* \retval #PSA_ERROR_INVALID_HANDLE
|
||||
* \retval #PSA_ERROR_DOES_NOT_EXIST
|
||||
* The handle is to a key slot which does not contain key material yet.
|
||||
* The handle does not contain a key.
|
||||
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
||||
* \retval #PSA_ERROR_HARDWARE_FAILURE
|
||||
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
||||
|
|
|
@ -105,9 +105,13 @@
|
|||
* descriptions for permitted sequencing of functions.
|
||||
*
|
||||
* Implementations shall not return this error code to indicate
|
||||
* that a key slot is occupied when it needs to be free or vice versa,
|
||||
* but shall return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST
|
||||
* as applicable. */
|
||||
* that a key either exists or not,
|
||||
* but shall instead return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST
|
||||
* as applicable.
|
||||
*
|
||||
* Implementations shall not return this error code to indicate that a
|
||||
* key handle is invalid, but shall return #PSA_ERROR_INVALID_HANDLE
|
||||
* instead. */
|
||||
#define PSA_ERROR_BAD_STATE ((psa_status_t)-137)
|
||||
|
||||
/** The parameters passed to the function are invalid.
|
||||
|
@ -115,12 +119,7 @@
|
|||
* Implementations may return this error any time a parameter or
|
||||
* combination of parameters are recognized as invalid.
|
||||
*
|
||||
* Implementations shall not return this error code to indicate
|
||||
* that a key slot is occupied when it needs to be free or vice versa,
|
||||
* but shall return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST
|
||||
* as applicable.
|
||||
*
|
||||
* Implementation shall not return this error code to indicate that a
|
||||
* Implementations shall not return this error code to indicate that a
|
||||
* key handle is invalid, but shall return #PSA_ERROR_INVALID_HANDLE
|
||||
* instead.
|
||||
*/
|
||||
|
|
Loading…
Reference in a new issue