Rename functions that inject key material to an allocated handle
This commit starts a migration to a new interface for key creation.
Today, the application allocates a handle, then fills its metadata,
and finally injects key material. The new interface fills metadata
into a temporary structure, and a handle is allocated at the same time
it gets filled with both metadata and key material.
This commit was obtained by moving the declaration of the old-style
functions to crypto_extra.h and renaming them with the to_handle
suffix, adding declarations for the new-style functions in crypto.h
under their new name, and running
perl -i -pe 's/\bpsa_(import|copy|generator_import|generate)_key\b/$&_to_handle/g' library/*.c tests/suites/*.function programs/psa/*.c
perl -i -pe 's/\bpsa_get_key_lifetime\b/$&_from_handle/g' library/*.c tests/suites/*.function programs/psa/*.c
Many functions that are specific to the old interface, and which will
not remain under the same name with the new interface, are still in
crypto.h for now.
All functional tests should still pass. The documentation may have
some broken links.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 6a7bce8..564dd87 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -93,6 +93,24 @@
/**@}*/
+/** \defgroup attributes Key attributes
+ * @{
+ */
+
+/** The type of a structure containing key attributes.
+ *
+ * This is an opaque structure that can represent the metadata of a key
+ * object, including the key type and size, domain parameters, usage policies,
+ * location in storage, and any other similar information.
+ *
+ * The actual key material is not considered an attribute of a key.
+ * Key attributes do not contain information that is generally considered
+ * highly confidential.
+ */
+typedef struct psa_key_attributes_s psa_key_attributes_t;
+
+/**@}*/
+
/** \defgroup policy Key policies
* @{
*/
@@ -231,26 +249,6 @@
* @{
*/
-/** \brief Retrieve the lifetime of an open key.
- *
- * \param handle Handle to query.
- * \param[out] lifetime On success, the lifetime value.
- *
- * \retval #PSA_SUCCESS
- * Success.
- * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_TAMPERING_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_get_key_lifetime(psa_key_handle_t handle,
- psa_key_lifetime_t *lifetime);
-
-
/** Allocate a key slot for a transient key, i.e. a key which is only stored
* in volatile memory.
*
@@ -302,43 +300,6 @@
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().
- *
- * \param lifetime The lifetime of the key. This designates a storage
- * 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,
- * 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.
- * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
- * \retval #PSA_ERROR_ALREADY_EXISTS
- * There is already a key with the identifier \p id in the storage
- * area designated by \p lifetime.
- * \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p lifetime is invalid, for example #PSA_KEY_LIFETIME_VOLATILE.
- * \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p id is invalid for the specified lifetime.
- * \retval #PSA_ERROR_NOT_SUPPORTED
- * \p lifetime is not supported.
- * \retval #PSA_ERROR_NOT_PERMITTED
- * \p lifetime is valid, but the application does not have the
- * permission to create a key there.
- */
-psa_status_t psa_create_key(psa_key_lifetime_t lifetime,
- 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
@@ -417,7 +378,8 @@
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
-psa_status_t psa_import_key(psa_key_handle_t handle,
+psa_status_t psa_import_key(const psa_key_attributes_t *attributes,
+ psa_key_handle_t *handle,
psa_key_type_t type,
const uint8_t *data,
size_t data_length);
@@ -809,8 +771,8 @@
* \retval #PSA_ERROR_TAMPERING_DETECTED
*/
psa_status_t psa_copy_key(psa_key_handle_t source_handle,
- psa_key_handle_t target_handle,
- const psa_key_policy_t *constraint);
+ const psa_key_attributes_t *attributes,
+ psa_key_handle_t *target_handle);
/**@}*/
@@ -3006,7 +2968,8 @@
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
-psa_status_t psa_generator_import_key(psa_key_handle_t handle,
+psa_status_t psa_generator_import_key(const psa_key_attributes_t *attributes,
+ psa_key_handle_t *handle,
psa_key_type_t type,
size_t bits,
psa_crypto_generator_t *generator);
@@ -3398,7 +3361,8 @@
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
-psa_status_t psa_generate_key(psa_key_handle_t handle,
+psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
+ psa_key_handle_t *handle,
psa_key_type_t type,
size_t bits,
const void *extra,