psa: Move from key handle to key identifier
Move all the PSA crypto APIs using key handles
to use key identifiers but psa_key_open() and
psa_key_close(). This is done without modifying
any test as key handles and key identifiers are
now the same.
Update the library modules using PSA crypto APIs
to get rid of key handles.
Programs and unit tests are updated to not use
key handles in subsequent commits, not in this
one.
Signed-off-by: Ronald Cron <ronald.cron@arm.com>
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 5ba16b9..2620af5 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -348,7 +348,7 @@
* Once you have called this function on an attribute structure,
* you must call psa_reset_key_attributes() to free these resources.
*
- * \param[in] handle Handle to the key to query.
+ * \param[in] key Identifier of the key to query.
* \param[in,out] attributes On success, the attributes of the key.
* On failure, equivalent to a
* freshly-initialized structure.
@@ -364,7 +364,7 @@
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
-psa_status_t psa_get_key_attributes(psa_key_handle_t handle,
+psa_status_t psa_get_key_attributes(mbedtls_svc_key_id_t key,
psa_key_attributes_t *attributes);
/** Reset a key attribute structure to a freshly initialized state.
@@ -387,94 +387,6 @@
* @{
*/
-/** 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 an application
- * 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\`.
- *
- * \param key The persistent identifier of the key.
- * \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 key.
- * \retval #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.
- * \retval #PSA_ERROR_DOES_NOT_EXIST
- * There is no persistent key with key identifier \p id.
- * \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p id is not a valid persistent key identifier.
- * \retval #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.
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_STORAGE_FAILURE
- * \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_open_key( mbedtls_svc_key_id_t 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.
- *
- * \param handle The key handle to close.
- * If this is \c 0, do nothing and return \c PSA_SUCCESS.
- *
- * \retval #PSA_SUCCESS
- * \p handle was a valid handle or \c 0. It is now closed.
- * \retval #PSA_ERROR_INVALID_HANDLE
- * \p handle is not a valid handle nor \c 0.
- * \retval #PSA_ERROR_COMMUNICATION_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_close_key(psa_key_handle_t handle);
-
/** Make a copy of a key.
*
* Copy key material from one location to another.
@@ -512,7 +424,10 @@
* 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 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.
* \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
@@ -526,12 +441,12 @@
* 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.
+ * \param[out] target_key On success, an identifier for the newly created
+ * key. \c 0 on failure.
*
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_INVALID_HANDLE
- * \p source_handle is invalid.
+ * \p source_key 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.
@@ -559,9 +474,9 @@
* 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,
+psa_status_t psa_copy_key(mbedtls_svc_key_id_t source_key,
const psa_key_attributes_t *attributes,
- psa_key_handle_t *target_handle);
+ mbedtls_svc_key_id_t *target_key);
/**
@@ -572,28 +487,22 @@
* 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.
+ * 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.
*
- * \param handle Handle to the key to erase.
- * If this is \c 0, do nothing and return \c PSA_SUCCESS.
+ * \param key Identifier of the key to erase. If this is \c 0, do nothing and
+ * return PSA_SUCCESS.
*
* \retval #PSA_SUCCESS
- * \p handle was a valid handle and the key material that it
- * referred to has been erased.
- * Alternatively, \p handle is \c 0.
+ * \p key was a valid identifier and the key material that it
+ * referred to has been erased. Alternatively, \p key is \c 0.
* \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
- * \p handle is not a valid handle nor \c 0.
+ * \p key is not a valid identifier nor \c 0.
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* There was an failure in communication with the cryptoprocessor.
* The key material may still be present in the cryptoprocessor.
@@ -611,7 +520,7 @@
* 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);
+psa_status_t psa_destroy_key(mbedtls_svc_key_id_t key);
/**@}*/
@@ -646,7 +555,7 @@
* \p data buffer.
* If the key size in \p attributes is nonzero,
* it must be equal to the size from \p data.
- * \param[out] handle On success, a handle to the newly created key.
+ * \param[out] key On success, an identifier to the newly created key.
* \c 0 on failure.
* \param[in] data Buffer containing the key data. The content of this
* buffer is interpreted according to the type declared
@@ -691,7 +600,7 @@
psa_status_t psa_import_key(const psa_key_attributes_t *attributes,
const uint8_t *data,
size_t data_length,
- psa_key_handle_t *handle);
+ mbedtls_svc_key_id_t *key);
@@ -752,7 +661,9 @@
*
* The policy on the key must have the usage flag #PSA_KEY_USAGE_EXPORT set.
*
- * \param handle Handle to the key to export.
+ * \param key Identifier of the key to export. It must allow the
+ * usage PSA_KEY_USAGE_EXPORT, unless it is a public
+ * key.
* \param[out] data Buffer where the key data is to be written.
* \param data_size Size of the \p data buffer in bytes.
* \param[out] data_length On success, the number of bytes
@@ -779,7 +690,7 @@
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
-psa_status_t psa_export_key(psa_key_handle_t handle,
+psa_status_t psa_export_key(mbedtls_svc_key_id_t key,
uint8_t *data,
size_t data_size,
size_t *data_length);
@@ -822,7 +733,7 @@
* Exporting a public key object or the public part of a key pair is
* always permitted, regardless of the key's usage flags.
*
- * \param handle Handle to the key to export.
+ * \param key Identifier of the key to export.
* \param[out] data Buffer where the key data is to be written.
* \param data_size Size of the \p data buffer in bytes.
* \param[out] data_length On success, the number of bytes
@@ -849,7 +760,7 @@
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
-psa_status_t psa_export_public_key(psa_key_handle_t handle,
+psa_status_t psa_export_public_key(mbedtls_svc_key_id_t key,
uint8_t *data,
size_t data_size,
size_t *data_length);
@@ -1226,7 +1137,8 @@
* about the MAC value which could allow an attacker to guess
* a valid MAC and thereby bypass security controls.
*
- * \param handle Handle to the key to use for the operation.
+ * \param key Identifier of the key to use for the operation. It
+ * must allow the usage PSA_KEY_USAGE_SIGN_MESSAGE.
* \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
* such that #PSA_ALG_IS_MAC(\p alg) is true).
* \param[in] input Buffer containing the input message.
@@ -1241,7 +1153,7 @@
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p handle is not compatible with \p alg.
+ * \p key is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a MAC algorithm.
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
@@ -1257,7 +1169,7 @@
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
-psa_status_t psa_mac_compute(psa_key_handle_t handle,
+psa_status_t psa_mac_compute(mbedtls_svc_key_id_t key,
psa_algorithm_t alg,
const uint8_t *input,
size_t input_length,
@@ -1267,7 +1179,8 @@
/** Calculate the MAC of a message and compare it with a reference value.
*
- * \param handle Handle to the key to use for the operation.
+ * \param key Identifier of the key to use for the operation. It
+ * must allow the usage PSA_KEY_USAGE_VERIFY_MESSAGE.
* \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
* such that #PSA_ALG_IS_MAC(\p alg) is true).
* \param[in] input Buffer containing the input message.
@@ -1283,7 +1196,7 @@
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p handle is not compatible with \p alg.
+ * \p key is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a MAC algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -1297,7 +1210,7 @@
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
-psa_status_t psa_mac_verify(psa_key_handle_t handle,
+psa_status_t psa_mac_verify(mbedtls_svc_key_id_t key,
psa_algorithm_t alg,
const uint8_t *input,
size_t input_length,
@@ -1382,9 +1295,9 @@
* \param[in,out] operation The operation object to set up. It must have
* been initialized as per the documentation for
* #psa_mac_operation_t and not yet in use.
- * \param handle Handle to the key to use for the operation.
- * It must remain valid until the operation
- * terminates.
+ * \param key Identifier of the key to use for the operation. It
+ * must remain valid until the operation terminates.
+ * It must allow the usage PSA_KEY_USAGE_SIGN_MESSAGE.
* \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
* such that #PSA_ALG_IS_MAC(\p alg) is true).
*
@@ -1393,7 +1306,7 @@
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p handle is not compatible with \p alg.
+ * \p key is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a MAC algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -1410,7 +1323,7 @@
* results in this error code.
*/
psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
- psa_key_handle_t handle,
+ mbedtls_svc_key_id_t key,
psa_algorithm_t alg);
/** Set up a multipart MAC verification operation.
@@ -1444,9 +1357,10 @@
* \param[in,out] operation The operation object to set up. It must have
* been initialized as per the documentation for
* #psa_mac_operation_t and not yet in use.
- * \param handle Handle to the key to use for the operation.
- * It must remain valid until the operation
- * terminates.
+ * \param key Identifier of the key to use for the operation. It
+ * must remain valid until the operation terminates.
+ * It must allow the usage
+ * PSA_KEY_USAGE_VERIFY_MESSAGE.
* \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
* such that #PSA_ALG_IS_MAC(\p alg) is true).
*
@@ -1472,7 +1386,7 @@
* results in this error code.
*/
psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
- psa_key_handle_t handle,
+ mbedtls_svc_key_id_t key,
psa_algorithm_t alg);
/** Add a message fragment to a multipart MAC operation.
@@ -1639,9 +1553,8 @@
* vector). Use the multipart operation interface with a
* #psa_cipher_operation_t object to provide other forms of IV.
*
- * \param handle Handle to the key to use for the operation.
- * It must remain valid until the operation
- * terminates.
+ * \param key Identifier of the key to use for the operation.
+ * It must allow the usage PSA_KEY_USAGE_ENCRYPT.
* \param alg The cipher algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_CIPHER(\p alg) is true).
@@ -1659,7 +1572,7 @@
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p handle is not compatible with \p alg.
+ * \p key is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a cipher algorithm.
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
@@ -1673,7 +1586,7 @@
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
-psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
+psa_status_t psa_cipher_encrypt(mbedtls_svc_key_id_t key,
psa_algorithm_t alg,
const uint8_t *input,
size_t input_length,
@@ -1685,9 +1598,10 @@
*
* This function decrypts a message encrypted with a symmetric cipher.
*
- * \param handle Handle to the key to use for the operation.
+ * \param key Identifier of the key to use for the operation.
* It must remain valid until the operation
- * terminates.
+ * terminates. It must allow the usage
+ * PSA_KEY_USAGE_DECRYPT.
* \param alg The cipher algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_CIPHER(\p alg) is true).
@@ -1705,7 +1619,7 @@
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p handle is not compatible with \p alg.
+ * \p key is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a cipher algorithm.
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
@@ -1719,7 +1633,7 @@
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
-psa_status_t psa_cipher_decrypt(psa_key_handle_t handle,
+psa_status_t psa_cipher_decrypt(mbedtls_svc_key_id_t key,
psa_algorithm_t alg,
const uint8_t *input,
size_t input_length,
@@ -1805,9 +1719,10 @@
* \param[in,out] operation The operation object to set up. It must have
* been initialized as per the documentation for
* #psa_cipher_operation_t and not yet in use.
- * \param handle Handle to the key to use for the operation.
+ * \param key Identifier of the key to use for the operation.
* It must remain valid until the operation
- * terminates.
+ * terminates. It must allow the usage
+ * PSA_KEY_USAGE_ENCRYPT.
* \param alg The cipher algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_CIPHER(\p alg) is true).
@@ -1817,7 +1732,7 @@
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p handle is not compatible with \p alg.
+ * \p key is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a cipher algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -1833,7 +1748,7 @@
* results in this error code.
*/
psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
- psa_key_handle_t handle,
+ mbedtls_svc_key_id_t key,
psa_algorithm_t alg);
/** Set the key for a multipart symmetric decryption operation.
@@ -1868,9 +1783,10 @@
* \param[in,out] operation The operation object to set up. It must have
* been initialized as per the documentation for
* #psa_cipher_operation_t and not yet in use.
- * \param handle Handle to the key to use for the operation.
+ * \param key Identifier of the key to use for the operation.
* It must remain valid until the operation
- * terminates.
+ * terminates. It must allow the usage
+ * PSA_KEY_USAGE_DECRYPT.
* \param alg The cipher algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_CIPHER(\p alg) is true).
@@ -1880,7 +1796,7 @@
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p handle is not compatible with \p alg.
+ * \p key is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a cipher algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -1896,7 +1812,7 @@
* results in this error code.
*/
psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
- psa_key_handle_t handle,
+ mbedtls_svc_key_id_t key,
psa_algorithm_t alg);
/** Generate an IV for a symmetric encryption operation.
@@ -2110,7 +2026,9 @@
/** Process an authenticated encryption operation.
*
- * \param handle Handle to the key to use for the operation.
+ * \param key Identifier of the key to use for the
+ * operation. It must allow the usage
+ * PSA_KEY_USAGE_ENCRYPT.
* \param alg The AEAD algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(\p alg) is true).
@@ -2141,7 +2059,7 @@
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p handle is not compatible with \p alg.
+ * \p key is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not an AEAD algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2156,7 +2074,7 @@
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
-psa_status_t psa_aead_encrypt(psa_key_handle_t handle,
+psa_status_t psa_aead_encrypt(mbedtls_svc_key_id_t key,
psa_algorithm_t alg,
const uint8_t *nonce,
size_t nonce_length,
@@ -2170,7 +2088,9 @@
/** Process an authenticated decryption operation.
*
- * \param handle Handle to the key to use for the operation.
+ * \param key Identifier of the key to use for the
+ * operation. It must allow the usage
+ * PSA_KEY_USAGE_DECRYPT.
* \param alg The AEAD algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(\p alg) is true).
@@ -2201,7 +2121,7 @@
* The ciphertext is not authentic.
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p handle is not compatible with \p alg.
+ * \p key is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not an AEAD algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2216,7 +2136,7 @@
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
-psa_status_t psa_aead_decrypt(psa_key_handle_t handle,
+psa_status_t psa_aead_decrypt(mbedtls_svc_key_id_t key,
psa_algorithm_t alg,
const uint8_t *nonce,
size_t nonce_length,
@@ -2312,9 +2232,10 @@
* \param[in,out] operation The operation object to set up. It must have
* been initialized as per the documentation for
* #psa_aead_operation_t and not yet in use.
- * \param handle Handle to the key to use for the operation.
+ * \param key Identifier of the key to use for the operation.
* It must remain valid until the operation
- * terminates.
+ * terminates. It must allow the usage
+ * PSA_KEY_USAGE_ENCRYPT.
* \param alg The AEAD algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(\p alg) is true).
@@ -2326,7 +2247,7 @@
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p handle is not compatible with \p alg.
+ * \p key is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not an AEAD algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2340,7 +2261,7 @@
* results in this error code.
*/
psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
- psa_key_handle_t handle,
+ mbedtls_svc_key_id_t key,
psa_algorithm_t alg);
/** Set the key for a multipart authenticated decryption operation.
@@ -2378,9 +2299,10 @@
* \param[in,out] operation The operation object to set up. It must have
* been initialized as per the documentation for
* #psa_aead_operation_t and not yet in use.
- * \param handle Handle to the key to use for the operation.
+ * \param key Identifier of the key to use for the operation.
* It must remain valid until the operation
- * terminates.
+ * terminates. It must allow the usage
+ * PSA_KEY_USAGE_DECRYPT.
* \param alg The AEAD algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(\p alg) is true).
@@ -2392,7 +2314,7 @@
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p handle is not compatible with \p alg.
+ * \p key is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not an AEAD algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2406,7 +2328,7 @@
* results in this error code.
*/
psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
- psa_key_handle_t handle,
+ mbedtls_svc_key_id_t key,
psa_algorithm_t alg);
/** Generate a random nonce for an authenticated encryption operation.
@@ -2864,10 +2786,11 @@
* parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
* to determine the hash algorithm to use.
*
- * \param handle Handle to the key to use for the operation.
- * It must be an asymmetric key pair.
+ * \param key Identifier of the key to use for the operation.
+ * It must be an asymmetric key pair. The key must
+ * allow the usage PSA_KEY_USAGE_SIGN_HASH.
* \param alg A signature algorithm that is compatible with
- * the type of \p handle.
+ * the type of \p key.
* \param[in] hash The hash or message to sign.
* \param hash_length Size of the \p hash buffer in bytes.
* \param[out] signature Buffer where the signature is to be written.
@@ -2883,7 +2806,7 @@
* determine a sufficient buffer size by calling
* #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
* where \c key_type and \c key_bits are the type and bit-size
- * respectively of \p handle.
+ * respectively of \p key.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2897,7 +2820,7 @@
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
-psa_status_t psa_sign_hash(psa_key_handle_t handle,
+psa_status_t psa_sign_hash(mbedtls_svc_key_id_t key,
psa_algorithm_t alg,
const uint8_t *hash,
size_t hash_length,
@@ -2914,10 +2837,11 @@
* parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
* to determine the hash algorithm to use.
*
- * \param handle Handle to the key to use for the operation.
- * It must be a public key or an asymmetric key pair.
+ * \param key Identifier of the key to use for the operation. It
+ * must be a public key or an asymmetric key pair. The
+ * key must allow the usage PSA_KEY_USAGE_VERIFY_HASH.
* \param alg A signature algorithm that is compatible with
- * the type of \p handle.
+ * the type of \p key.
* \param[in] hash The hash or message whose signature is to be
* verified.
* \param hash_length Size of the \p hash buffer in bytes.
@@ -2943,7 +2867,7 @@
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
-psa_status_t psa_verify_hash(psa_key_handle_t handle,
+psa_status_t psa_verify_hash(mbedtls_svc_key_id_t key,
psa_algorithm_t alg,
const uint8_t *hash,
size_t hash_length,
@@ -2953,11 +2877,12 @@
/**
* \brief Encrypt a short message with a public key.
*
- * \param handle Handle to the key to use for the operation.
- * It must be a public key or an asymmetric
- * key pair.
+ * \param key Identifer of the key to use for the operation.
+ * It must be a public key or an asymmetric key
+ * pair. It must allow the usage
+ * PSA_KEY_USAGE_ENCRYPT.
* \param alg An asymmetric encryption algorithm that is
- * compatible with the type of \p handle.
+ * compatible with the type of \p key.
* \param[in] input The message to encrypt.
* \param input_length Size of the \p input buffer in bytes.
* \param[in] salt A salt or label, if supported by the
@@ -2986,7 +2911,7 @@
* determine a sufficient buffer size by calling
* #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
* where \c key_type and \c key_bits are the type and bit-size
- * respectively of \p handle.
+ * respectively of \p key.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -3000,7 +2925,7 @@
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
-psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle,
+psa_status_t psa_asymmetric_encrypt(mbedtls_svc_key_id_t key,
psa_algorithm_t alg,
const uint8_t *input,
size_t input_length,
@@ -3013,10 +2938,11 @@
/**
* \brief Decrypt a short message with a private key.
*
- * \param handle Handle to the key to use for the operation.
- * It must be an asymmetric key pair.
+ * \param key Identifier of the key to use for the operation.
+ * It must be an asymmetric key pair. It must
+ * allow the usage PSA_KEY_USAGE_DECRYPT.
* \param alg An asymmetric encryption algorithm that is
- * compatible with the type of \p handle.
+ * compatible with the type of \p key.
* \param[in] input The message to decrypt.
* \param input_length Size of the \p input buffer in bytes.
* \param[in] salt A salt or label, if supported by the
@@ -3045,7 +2971,7 @@
* determine a sufficient buffer size by calling
* #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
* where \c key_type and \c key_bits are the type and bit-size
- * respectively of \p handle.
+ * respectively of \p key.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -3060,7 +2986,7 @@
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
-psa_status_t psa_asymmetric_decrypt(psa_key_handle_t handle,
+psa_status_t psa_asymmetric_decrypt(mbedtls_svc_key_id_t key,
psa_algorithm_t alg,
const uint8_t *input,
size_t input_length,
@@ -3318,9 +3244,9 @@
* psa_key_derivation_setup() and must not
* have produced any output yet.
* \param step Which step the input data is for.
- * \param handle Handle to the key. It must have an
- * appropriate type for \p step and must
- * allow the usage #PSA_KEY_USAGE_DERIVE.
+ * \param key Identifier of the key. It must have an
+ * appropriate type for step and must allow the
+ * usage PSA_KEY_USAGE_DERIVE.
*
* \retval #PSA_SUCCESS
* Success.
@@ -3346,7 +3272,7 @@
psa_status_t psa_key_derivation_input_key(
psa_key_derivation_operation_t *operation,
psa_key_derivation_step_t step,
- psa_key_handle_t handle);
+ mbedtls_svc_key_id_t key);
/** Perform a key agreement and use the shared secret as input to a key
* derivation.
@@ -3371,7 +3297,8 @@
* The operation must be ready for an
* input of the type given by \p step.
* \param step Which step the input data is for.
- * \param private_key Handle to the private key to use.
+ * \param private_key Identifier of the private key to use. It must
+ * allow the usage PSA_KEY_USAGE_DERIVE.
* \param[in] peer_key Public key of the peer. The peer key must be in the
* same format that psa_import_key() accepts for the
* public key type corresponding to the type of
@@ -3415,7 +3342,7 @@
psa_status_t psa_key_derivation_key_agreement(
psa_key_derivation_operation_t *operation,
psa_key_derivation_step_t step,
- psa_key_handle_t private_key,
+ mbedtls_svc_key_id_t private_key,
const uint8_t *peer_key,
size_t peer_key_length);
@@ -3559,8 +3486,8 @@
*
* \param[in] attributes The attributes for the new key.
* \param[in,out] operation The key derivation operation object to read from.
- * \param[out] handle On success, a handle to the newly created key.
- * \c 0 on failure.
+ * \param[out] key On success, an identifier for the newly created
+ * key. \c 0 on failure.
*
* \retval #PSA_SUCCESS
* Success.
@@ -3599,7 +3526,7 @@
psa_status_t psa_key_derivation_output_key(
const psa_key_attributes_t *attributes,
psa_key_derivation_operation_t *operation,
- psa_key_handle_t *handle);
+ mbedtls_svc_key_id_t *key);
/** Abort a key derivation operation.
*
@@ -3640,7 +3567,8 @@
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_RAW_KEY_AGREEMENT(\p alg)
* is true).
- * \param private_key Handle to the private key to use.
+ * \param private_key Identifier of the private key to use. It must
+ * allow the usage PSA_KEY_USAGE_DERIVE.
* \param[in] peer_key Public key of the peer. It must be
* in the same format that psa_import_key()
* accepts. The standard formats for public
@@ -3678,7 +3606,7 @@
* results in this error code.
*/
psa_status_t psa_raw_key_agreement(psa_algorithm_t alg,
- psa_key_handle_t private_key,
+ mbedtls_svc_key_id_t private_key,
const uint8_t *peer_key,
size_t peer_key_length,
uint8_t *output,
@@ -3734,8 +3662,8 @@
* attributes.
*
* \param[in] attributes The attributes for the new key.
- * \param[out] handle On success, a handle to the newly created key.
- * \c 0 on failure.
+ * \param[out] key On success, an identifier for the newly created
+ * key. \c 0 on failure.
*
* \retval #PSA_SUCCESS
* Success.
@@ -3759,7 +3687,7 @@
* results in this error code.
*/
psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
- psa_key_handle_t *handle);
+ mbedtls_svc_key_id_t *key);
/**@}*/