Crypto: Upgrade Mbed TLS to 2.25
Set the MBEDCRYPTO_VERSION to 2.25.0.
First three patches in existing v2.24 already applied in v2.25
and hence removed.
Replaced MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER with
MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER in all configuration and
source as updated in v2.25 library.
Update all headers of psa/include as per mbedtls-v2.25 excluding
changes required to hide some implementation.
Update id field in the client_key_attributes structure to
psa_key_id_t.
Update Copyright year to 2021!
Removed patch 006 as not required in MbedTLS v2.25.0.
Update references of handle to key as per MbedTLS api changes.
Increase NUM_HANDLES to 32 to accommodate crypto api tests.
Added corresponding tfm implementation of psa_purge_key().
Signed-off-by: Maulik Patel <maulik.patel@arm.com>
Change-Id: I6a532da96735cf32996250c4a8733a8654c1f44e
diff --git a/interface/include/psa/crypto.h b/interface/include/psa/crypto.h
index c58abda..e9d3c66 100644
--- a/interface/include/psa/crypto.h
+++ b/interface/include/psa/crypto.h
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2018-2020, Arm Limited. All rights reserved.
+ * Copyright (c) 2018-2021, Arm Limited. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*
@@ -24,16 +24,6 @@
* @{
*/
-/** \brief Key handle.
- *
- * This type represents open handles to keys. It must be an unsigned integral
- * type. The choice of type is implementation-dependent.
- *
- * 0 is not a valid key handle. How other handle values are assigned is
- * implementation-dependent.
- */
-typedef _unsigned_integral_type_ psa_key_handle_t;
-
/**@}*/
#endif /* __DOXYGEN_ONLY__ */
@@ -134,11 +124,11 @@
* linkage). This function may be provided as a function-like macro,
* but in this case it must evaluate each of its arguments exactly once.
*
- * \param[out] attributes The attribute structure to write to.
- * \param id The persistent identifier for the key.
+ * \param[out] attributes The attribute structure to write to.
+ * \param key The persistent identifier for the key.
*/
static void psa_set_key_id(psa_key_attributes_t *attributes,
- psa_key_id_t id);
+ psa_key_id_t key);
/** Set the location of a persistent key.
*
@@ -335,7 +325,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.
@@ -351,7 +341,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(psa_key_id_t key,
psa_key_attributes_t *attributes);
/** Reset a key attribute structure to a freshly initialized state.
@@ -374,93 +364,28 @@
* @{
*/
-/** Open a handle to an existing persistent key.
+/** Remove non-essential copies of key material from memory.
*
- * 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 a key identifier
- * in the vendor range, as documented in the description of #psa_key_id_t.
+ * If the key identifier designates a volatile key, this functions does not do
+ * anything and returns successfully.
*
- * 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().
+ * 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.
*
- * 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 id The persistent identifier of the key.
- * \param[out] handle On success, a handle to the key.
+ * \param key Identifier of the key to purge.
*
* \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.
+ * The key material will have been removed from memory if it is not
+ * currently required.
* \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
+ * \p key is not a valid key identifier.
* \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(psa_key_id_t id,
- 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);
+psa_status_t psa_purge_key(psa_key_id_t key);
/** Make a copy of a key.
*
@@ -499,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
@@ -513,12 +441,14 @@
* 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.
+ * \param[out] target_key On success, an identifier for the newly created
+ * key. For persistent keys, this is the key
+ * identifier defined in \p attributes.
* \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.
@@ -546,9 +476,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(psa_key_id_t source_key,
const psa_key_attributes_t *attributes,
- psa_key_handle_t *target_handle);
+ psa_key_id_t *target_key);
/**
@@ -559,28 +489,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.
@@ -598,7 +522,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(psa_key_id_t key);
/**@}*/
@@ -633,7 +557,9 @@
* \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.
+ * For persistent keys, this is the key identifier
+ * defined in \p attributes.
* \c 0 on failure.
* \param[in] data Buffer containing the key data. The content of this
* buffer is interpreted according to the type declared
@@ -678,7 +604,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);
+ psa_key_id_t *key);
@@ -739,7 +665,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
@@ -766,7 +694,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(psa_key_id_t key,
uint8_t *data,
size_t data_size,
size_t *data_length);
@@ -809,7 +737,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
@@ -836,7 +764,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(psa_key_id_t key,
uint8_t *data,
size_t data_size,
size_t *data_length);
@@ -1213,7 +1141,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.
@@ -1228,7 +1157,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
@@ -1244,7 +1173,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(psa_key_id_t key,
psa_algorithm_t alg,
const uint8_t *input,
size_t input_length,
@@ -1254,7 +1183,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.
@@ -1270,7 +1200,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
@@ -1284,7 +1214,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(psa_key_id_t key,
psa_algorithm_t alg,
const uint8_t *input,
size_t input_length,
@@ -1369,9 +1299,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).
*
@@ -1380,7 +1310,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
@@ -1397,7 +1327,7 @@
* results in this error code.
*/
psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
- psa_key_handle_t handle,
+ psa_key_id_t key,
psa_algorithm_t alg);
/** Set up a multipart MAC verification operation.
@@ -1431,9 +1361,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).
*
@@ -1459,7 +1390,7 @@
* results in this error code.
*/
psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
- psa_key_handle_t handle,
+ psa_key_id_t key,
psa_algorithm_t alg);
/** Add a message fragment to a multipart MAC operation.
@@ -1626,9 +1557,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).
@@ -1646,7 +1576,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
@@ -1660,7 +1590,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(psa_key_id_t key,
psa_algorithm_t alg,
const uint8_t *input,
size_t input_length,
@@ -1672,9 +1602,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).
@@ -1692,7 +1623,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
@@ -1706,7 +1637,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(psa_key_id_t key,
psa_algorithm_t alg,
const uint8_t *input,
size_t input_length,
@@ -1792,9 +1723,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).
@@ -1804,7 +1736,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
@@ -1820,7 +1752,7 @@
* results in this error code.
*/
psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
- psa_key_handle_t handle,
+ psa_key_id_t key,
psa_algorithm_t alg);
/** Set the key for a multipart symmetric decryption operation.
@@ -1855,9 +1787,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).
@@ -1867,7 +1800,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
@@ -1883,7 +1816,7 @@
* results in this error code.
*/
psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
- psa_key_handle_t handle,
+ psa_key_id_t key,
psa_algorithm_t alg);
/** Generate an IV for a symmetric encryption operation.
@@ -2097,7 +2030,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).
@@ -2128,7 +2063,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
@@ -2143,7 +2078,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(psa_key_id_t key,
psa_algorithm_t alg,
const uint8_t *nonce,
size_t nonce_length,
@@ -2157,7 +2092,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).
@@ -2188,7 +2125,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
@@ -2203,7 +2140,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(psa_key_id_t key,
psa_algorithm_t alg,
const uint8_t *nonce,
size_t nonce_length,
@@ -2299,9 +2236,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).
@@ -2310,10 +2248,10 @@
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (it must be inactive).
- * \retval #PSA_ERROR_INVALID_HANDLE
+ * \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
@@ -2327,7 +2265,7 @@
* results in this error code.
*/
psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
- psa_key_handle_t handle,
+ psa_key_id_t key,
psa_algorithm_t alg);
/** Set the key for a multipart authenticated decryption operation.
@@ -2365,9 +2303,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).
@@ -2376,10 +2315,10 @@
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (it must be inactive).
- * \retval #PSA_ERROR_INVALID_HANDLE
+ * \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
@@ -2393,7 +2332,7 @@
* results in this error code.
*/
psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
- psa_key_handle_t handle,
+ psa_key_id_t key,
psa_algorithm_t alg);
/** Generate a random nonce for an authenticated encryption operation.
@@ -2419,7 +2358,7 @@
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (it must be an active aead encrypt
- operation, with no nonce set).
+ * operation, with no nonce set).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p nonce buffer is too small.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2851,10 +2790,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.
@@ -2870,7 +2810,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
@@ -2884,7 +2824,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(psa_key_id_t key,
psa_algorithm_t alg,
const uint8_t *hash,
size_t hash_length,
@@ -2901,10 +2841,12 @@
* 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.
@@ -2930,7 +2872,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(psa_key_id_t key,
psa_algorithm_t alg,
const uint8_t *hash,
size_t hash_length,
@@ -2940,11 +2882,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
@@ -2973,7 +2916,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
@@ -2987,7 +2930,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(psa_key_id_t key,
psa_algorithm_t alg,
const uint8_t *input,
size_t input_length,
@@ -3000,10 +2943,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
@@ -3032,7 +2976,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
@@ -3047,7 +2991,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(psa_key_id_t key,
psa_algorithm_t alg,
const uint8_t *input,
size_t input_length,
@@ -3305,9 +3249,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.
@@ -3333,7 +3277,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);
+ psa_key_id_t key);
/** Perform a key agreement and use the shared secret as input to a key
* derivation.
@@ -3358,7 +3302,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
@@ -3402,7 +3347,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,
+ psa_key_id_t private_key,
const uint8_t *peer_key,
size_t peer_key_length);
@@ -3546,7 +3491,9 @@
*
* \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.
+ * \param[out] key On success, an identifier for the newly created
+ * key. For persistent keys, this is the key
+ * identifier defined in \p attributes.
* \c 0 on failure.
*
* \retval #PSA_SUCCESS
@@ -3586,7 +3533,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);
+ psa_key_id_t *key);
/** Abort a key derivation operation.
*
@@ -3627,7 +3574,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
@@ -3665,7 +3613,7 @@
* results in this error code.
*/
psa_status_t psa_raw_key_agreement(psa_algorithm_t alg,
- psa_key_handle_t private_key,
+ psa_key_id_t private_key,
const uint8_t *peer_key,
size_t peer_key_length,
uint8_t *output,
@@ -3721,7 +3669,9 @@
* attributes.
*
* \param[in] attributes The attributes for the new key.
- * \param[out] handle On success, a handle to the newly created key.
+ * \param[out] key On success, an identifier for the newly created
+ * key. For persistent keys, this is the key
+ * identifier defined in \p attributes.
* \c 0 on failure.
*
* \retval #PSA_SUCCESS
@@ -3746,7 +3696,7 @@
* results in this error code.
*/
psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
- psa_key_handle_t *handle);
+ psa_key_id_t *key);
/**@}*/