diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 0e57972cc..6807c73f3 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -36,19 +36,15 @@ * @{ */ -/** \brief Key slot number. +/** \brief Key handle. * - * This type represents key slots. It must be an unsigned integral + * 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 slot number. The meaning of other values is * implementation dependent. - * - * At any given point in time, each key slot either contains a - * cryptographic object, or is empty. Key slots are persistent: - * once set, the cryptographic object remains in the key slot until - * explicitly destroyed. */ -typedef _unsigned_integral_type_ psa_key_slot_t; +typedef _unsigned_integral_type_ psa_key_handle_t; /**@}*/ #endif /* __DOXYGEN_ONLY__ */ @@ -1428,17 +1424,14 @@ typedef uint32_t psa_key_id_t; */ #define PSA_KEY_LIFETIME_WRITE_ONCE ((psa_key_lifetime_t)0x7fffffff) -/** \brief Retrieve the lifetime of a key slot. +/** \brief Retrieve the lifetime of an open key. * - * The assignment of lifetimes to slots is implementation-dependent. - * - * \param key Slot to query. + * \param handle Handle to query. * \param[out] lifetime On success, the lifetime value. * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INVALID_ARGUMENT - * The key slot is invalid. + * \retval #PSA_ERROR_INVALID_HANDLE * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED @@ -1447,7 +1440,7 @@ typedef uint32_t psa_key_id_t; * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_get_key_lifetime(psa_key_slot_t key, +psa_status_t psa_get_key_lifetime(psa_key_handle_t handle, psa_key_lifetime_t *lifetime); /** \brief Change the lifetime of a key slot. @@ -1488,7 +1481,7 @@ psa_status_t psa_get_key_lifetime(psa_key_slot_t key, * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_set_key_lifetime(psa_key_slot_t key, +psa_status_t psa_set_key_lifetime(psa_key_handle_t key, psa_key_lifetime_t lifetime); /** Allocate a key slot for a transient key, i.e. a key which is only stored @@ -1609,6 +1602,7 @@ psa_status_t psa_create_key(psa_key_lifetime_t lifetime, * * \retval #PSA_SUCCESS * \retval #PSA_ERROR_INVALID_HANDLE + * \retval #PSA_ERROR_COMMUNICATION_FAILURE */ psa_status_t psa_close_key(psa_key_handle_t handle); @@ -1633,9 +1627,12 @@ 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 key Slot where the key will be stored. This must be a - * valid slot for a key of the chosen type. It must - * be unoccupied. + * \param handle Handle to the slot where the key will be stored. + * This must be a valid slot for a key of the chosen + * type: it must have been obtained by calling + * psa_allocate_key() or psa_create_key() with the + * correct \p type and with a maximum size that is + * compatible with \p data. * \param type Key type (a \c PSA_KEY_TYPE_XXX value). On a successful * import, the key slot will contain a key of this type. * \param[in] data Buffer containing the key data. The content of this @@ -1647,6 +1644,7 @@ psa_status_t psa_close_key(psa_key_handle_t handle); * * \retval #PSA_SUCCESS * Success. + * \retval #PSA_ERROR_INVALID_HANDLE * \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. @@ -1666,31 +1664,30 @@ psa_status_t psa_close_key(psa_key_handle_t handle); * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_import_key(psa_key_slot_t key, +psa_status_t psa_import_key(psa_key_handle_t handle, psa_key_type_t type, const uint8_t *data, size_t data_length); /** - * \brief Destroy a key and restore the slot to its default state. + * \brief Destroy a key. * * This function destroys the content of the key slot 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. * - * This function also erases any metadata such as policies. It returns the - * specified slot to its default state. + * This function also erases any metadata such as policies and frees all + * resources associated with the key. * - * \param key The key slot to erase. + * \param handle Handle to the key slot to erase. * * \retval #PSA_SUCCESS * The slot's content, if any, has been erased. * \retval #PSA_ERROR_NOT_PERMITTED * The slot holds content and cannot be erased because it is * read-only, either due to a policy or due to physical restrictions. - * \retval #PSA_ERROR_INVALID_ARGUMENT - * The specified slot number does not designate a valid slot. + * \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. @@ -1708,13 +1705,12 @@ psa_status_t psa_import_key(psa_key_slot_t key, * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_destroy_key(psa_key_slot_t key); +psa_status_t psa_destroy_key(psa_key_handle_t handle); /** * \brief Get basic metadata about a key. * - * \param key Slot whose content is queried. This must - * be an occupied key slot. + * \param handle Handle to the key slot 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. @@ -1723,7 +1719,9 @@ psa_status_t psa_destroy_key(psa_key_slot_t key); * is not written. * * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_INVALID_HANDLE * \retval #PSA_ERROR_EMPTY_SLOT + * The handle is to a key slot which does not contain key material yet. * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED @@ -1732,7 +1730,7 @@ psa_status_t psa_destroy_key(psa_key_slot_t key); * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_get_key_information(psa_key_slot_t key, +psa_status_t psa_get_key_information(psa_key_handle_t handle, psa_key_type_t *type, size_t *bits); @@ -1798,14 +1796,14 @@ psa_status_t psa_get_key_information(psa_key_slot_t key, * - For public keys (key types for which #PSA_KEY_TYPE_IS_PUBLIC_KEY is * true), the format is the same as for psa_export_public_key(). * - * \param key Slot whose content is to be exported. This must - * be an occupied key slot. + * \param handle Handle to 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 * that make up the key data. * * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_INVALID_HANDLE * \retval #PSA_ERROR_EMPTY_SLOT * \retval #PSA_ERROR_NOT_PERMITTED * \retval #PSA_ERROR_NOT_SUPPORTED @@ -1823,7 +1821,7 @@ psa_status_t psa_get_key_information(psa_key_slot_t key, * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_export_key(psa_key_slot_t key, +psa_status_t psa_export_key(psa_key_handle_t handle, uint8_t *data, size_t data_size, size_t *data_length); @@ -1900,14 +1898,14 @@ psa_status_t psa_export_key(psa_key_slot_t key, * namedCurve OBJECT IDENTIFIER } * ``` * - * \param key Slot whose content is to be exported. This must - * be an occupied key slot. + * \param handle Handle to 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 * that make up the key data. * * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_INVALID_HANDLE * \retval #PSA_ERROR_EMPTY_SLOT * \retval #PSA_ERROR_INVALID_ARGUMENT * The key is neither a public key nor a key pair. @@ -1926,7 +1924,7 @@ psa_status_t psa_export_key(psa_key_slot_t key, * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_export_public_key(psa_key_slot_t key, +psa_status_t psa_export_public_key(psa_key_handle_t handle, uint8_t *data, size_t data_size, size_t *data_length); @@ -2052,10 +2050,11 @@ psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy); * Implementations may set restrictions on supported key policies * depending on the key type and the key slot. * - * \param key The key slot whose policy is to be changed. + * \param handle Handle to the key whose policy is to be changed. * \param[in] policy The policy object to query. * * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_INVALID_HANDLE * \retval #PSA_ERROR_OCCUPIED_SLOT * \retval #PSA_ERROR_NOT_SUPPORTED * \retval #PSA_ERROR_INVALID_ARGUMENT @@ -2067,15 +2066,16 @@ psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy); * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_set_key_policy(psa_key_slot_t key, +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. * - * \param key The key slot whose policy is being queried. + * \param handle Handle to the key slot whose policy is being queried. * \param[out] policy On success, the key's policy. * * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_INVALID_HANDLE * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED @@ -2084,7 +2084,7 @@ psa_status_t psa_set_key_policy(psa_key_slot_t key, * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_get_key_policy(psa_key_slot_t key, +psa_status_t psa_get_key_policy(psa_key_handle_t handle, psa_key_policy_t *policy); /**@}*/ @@ -2341,12 +2341,13 @@ typedef struct psa_mac_operation_s psa_mac_operation_t; * - A call to psa_mac_sign_finish() or psa_mac_abort(). * * \param[out] operation The operation object to use. - * \param key Slot containing the key to use for the operation. + * \param handle Handle to the key to use for the operation. * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value * such that #PSA_ALG_IS_MAC(alg) is true). * * \retval #PSA_SUCCESS * Success. + * \retval #PSA_ERROR_INVALID_HANDLE * \retval #PSA_ERROR_EMPTY_SLOT * \retval #PSA_ERROR_NOT_PERMITTED * \retval #PSA_ERROR_INVALID_ARGUMENT @@ -2363,7 +2364,7 @@ typedef struct psa_mac_operation_s psa_mac_operation_t; * results in this error code. */ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation, - psa_key_slot_t key, + psa_key_handle_t handle, psa_algorithm_t alg); /** Start a multipart MAC verification operation. @@ -2393,12 +2394,13 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation, * - A call to psa_mac_verify_finish() or psa_mac_abort(). * * \param[out] operation The operation object to use. - * \param key Slot containing the key to use for the operation. + * \param handle Handle to the key to use for the operation. * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value * such that #PSA_ALG_IS_MAC(\p alg) is true). * * \retval #PSA_SUCCESS * Success. + * \retval #PSA_ERROR_INVALID_HANDLE * \retval #PSA_ERROR_EMPTY_SLOT * \retval #PSA_ERROR_NOT_PERMITTED * \retval #PSA_ERROR_INVALID_ARGUMENT @@ -2415,7 +2417,7 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation, * results in this error code. */ psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation, - psa_key_slot_t key, + psa_key_handle_t handle, psa_algorithm_t alg); /** Add a message fragment to a multipart MAC operation. @@ -2592,13 +2594,14 @@ typedef struct psa_cipher_operation_s psa_cipher_operation_t; * - A call to psa_cipher_finish() or psa_cipher_abort(). * * \param[out] operation The operation object to use. - * \param key Slot containing the key to use for the operation. + * \param handle Handle to the key to use for the operation. * \param alg The cipher algorithm to compute * (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_CIPHER(\p alg) is true). * * \retval #PSA_SUCCESS * Success. + * \retval #PSA_ERROR_INVALID_HANDLE * \retval #PSA_ERROR_EMPTY_SLOT * \retval #PSA_ERROR_NOT_PERMITTED * \retval #PSA_ERROR_INVALID_ARGUMENT @@ -2615,7 +2618,7 @@ typedef struct psa_cipher_operation_s psa_cipher_operation_t; * results in this error code. */ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, - psa_key_slot_t key, + psa_key_handle_t handle, psa_algorithm_t alg); /** Set the key for a multipart symmetric decryption operation. @@ -2645,13 +2648,14 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, * - A call to psa_cipher_finish() or psa_cipher_abort(). * * \param[out] operation The operation object to use. - * \param key Slot containing the key to use for the operation. + * \param handle Handle to the key to use for the operation. * \param alg The cipher algorithm to compute * (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_CIPHER(\p alg) is true). * * \retval #PSA_SUCCESS * Success. + * \retval #PSA_ERROR_INVALID_HANDLE * \retval #PSA_ERROR_EMPTY_SLOT * \retval #PSA_ERROR_NOT_PERMITTED * \retval #PSA_ERROR_INVALID_ARGUMENT @@ -2668,7 +2672,7 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, * results in this error code. */ psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation, - psa_key_slot_t key, + psa_key_handle_t handle, psa_algorithm_t alg); /** Generate an IV for a symmetric encryption operation. @@ -2871,7 +2875,7 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation); /** Process an authenticated encryption operation. * - * \param key Slot containing the key to use. + * \param handle Handle to the key to use for the operation. * \param alg The AEAD algorithm to compute * (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_AEAD(\p alg) is true). @@ -2899,6 +2903,7 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation); * * \retval #PSA_SUCCESS * Success. + * \retval #PSA_ERROR_INVALID_HANDLE * \retval #PSA_ERROR_EMPTY_SLOT * \retval #PSA_ERROR_NOT_PERMITTED * \retval #PSA_ERROR_INVALID_ARGUMENT @@ -2914,7 +2919,7 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation); * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_aead_encrypt(psa_key_slot_t key, +psa_status_t psa_aead_encrypt(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *nonce, size_t nonce_length, @@ -2928,7 +2933,7 @@ psa_status_t psa_aead_encrypt(psa_key_slot_t key, /** Process an authenticated decryption operation. * - * \param key Slot containing the key to use. + * \param handle Handle to the key to use for the operation. * \param alg The AEAD algorithm to compute * (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_AEAD(\p alg) is true). @@ -2954,6 +2959,7 @@ psa_status_t psa_aead_encrypt(psa_key_slot_t key, * * \retval #PSA_SUCCESS * Success. + * \retval #PSA_ERROR_INVALID_HANDLE * \retval #PSA_ERROR_EMPTY_SLOT * \retval #PSA_ERROR_INVALID_SIGNATURE * The ciphertext is not authentic. @@ -2971,7 +2977,7 @@ psa_status_t psa_aead_encrypt(psa_key_slot_t key, * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_aead_decrypt(psa_key_slot_t key, +psa_status_t psa_aead_decrypt(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *nonce, size_t nonce_length, @@ -3009,7 +3015,8 @@ psa_status_t psa_aead_decrypt(psa_key_slot_t key, * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg) * to determine the hash algorithm to use. * - * \param key Key slot containing an asymmetric key pair. + * \param handle Handle to the key to use for the operation. + * It must be an asymmetric key pair. * \param alg A signature algorithm that is compatible with * the type of \p key. * \param[in] hash The hash or message to sign. @@ -3038,7 +3045,7 @@ psa_status_t psa_aead_decrypt(psa_key_slot_t key, * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_asymmetric_sign(psa_key_slot_t key, +psa_status_t psa_asymmetric_sign(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, @@ -3055,8 +3062,8 @@ psa_status_t psa_asymmetric_sign(psa_key_slot_t key, * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg) * to determine the hash algorithm to use. * - * \param key Key slot containing a public key or an - * asymmetric key pair. + * \param handle Handle to the key to use for the operation. + * It must be a public key or an asymmetric key pair. * \param alg A signature algorithm that is compatible with * the type of \p key. * \param[in] hash The hash or message whose signature is to be @@ -3081,7 +3088,7 @@ psa_status_t psa_asymmetric_sign(psa_key_slot_t key, * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_asymmetric_verify(psa_key_slot_t key, +psa_status_t psa_asymmetric_verify(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, @@ -3096,8 +3103,9 @@ psa_status_t psa_asymmetric_verify(psa_key_slot_t key, /** * \brief Encrypt a short message with a public key. * - * \param key Key slot containing a public key or an - * asymmetric key pair. + * \param handle Handle to the key to use for the operation. + * It must be a public key or an asymmetric + * key pair. * \param alg An asymmetric encryption algorithm that is * compatible with the type of \p key. * \param[in] input The message to encrypt. @@ -3139,7 +3147,7 @@ psa_status_t psa_asymmetric_verify(psa_key_slot_t key, * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_asymmetric_encrypt(psa_key_slot_t key, +psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, @@ -3152,7 +3160,8 @@ psa_status_t psa_asymmetric_encrypt(psa_key_slot_t key, /** * \brief Decrypt a short message with a private key. * - * \param key Key slot containing an asymmetric key pair. + * \param handle Handle to the key to use for the operation. + * It must be an asymmetric key pair. * \param alg An asymmetric encryption algorithm that is * compatible with the type of \p key. * \param[in] input The message to decrypt. @@ -3195,7 +3204,7 @@ psa_status_t psa_asymmetric_encrypt(psa_key_slot_t key, * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_asymmetric_decrypt(psa_key_slot_t key, +psa_status_t psa_asymmetric_decrypt(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, @@ -3314,9 +3323,13 @@ psa_status_t psa_generator_read(psa_crypto_generator_t *generator, * if the implementation provides an isolation boundary then * the key material is not exposed outside the isolation boundary. * - * \param key Slot where the key will be stored. This must be a - * valid slot for a key of the chosen type. It must - * be unoccupied. + * \param handle Handle to the slot where the key will be stored. + * This must be a valid slot for a key of the chosen + * type: it must have been obtained by calling + * psa_allocate_key() or psa_create_key() with the + * correct \p type and with a maximum size that is + * compatible with \p bits. + * It must not contain any key material yet. * \param type Key type (a \c PSA_KEY_TYPE_XXX value). * This must be a symmetric key type. * \param bits Key size in bits. @@ -3335,8 +3348,7 @@ psa_status_t psa_generator_read(psa_crypto_generator_t *generator, * The key type or key size is not supported, either by the * implementation in general or in this particular slot. * \retval #PSA_ERROR_BAD_STATE - * \retval #PSA_ERROR_INVALID_ARGUMENT - * The key slot is invalid. + * \retval #PSA_ERROR_INVALID_HANDLE * \retval #PSA_ERROR_OCCUPIED_SLOT * There is already a key in the specified slot. * \retval #PSA_ERROR_INSUFFICIENT_MEMORY @@ -3349,7 +3361,7 @@ psa_status_t psa_generator_read(psa_crypto_generator_t *generator, * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_generator_import_key(psa_key_slot_t key, +psa_status_t psa_generator_import_key(psa_key_handle_t handle, psa_key_type_t type, size_t bits, psa_crypto_generator_t *generator); @@ -3409,7 +3421,7 @@ psa_status_t psa_generator_abort(psa_crypto_generator_t *generator); * a logical zero (`{0}`), * \c PSA_CRYPTO_GENERATOR_INIT or * psa_crypto_generator_init(). - * \param key Slot containing the secret key to use. + * \param handle Handle to the secret key. * \param alg The key derivation algorithm to compute * (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_KEY_DERIVATION(\p alg) is true). @@ -3422,6 +3434,7 @@ psa_status_t psa_generator_abort(psa_crypto_generator_t *generator); * * \retval #PSA_SUCCESS * Success. + * \retval #PSA_ERROR_INVALID_HANDLE * \retval #PSA_ERROR_EMPTY_SLOT * \retval #PSA_ERROR_NOT_PERMITTED * \retval #PSA_ERROR_INVALID_ARGUMENT @@ -3439,7 +3452,7 @@ psa_status_t psa_generator_abort(psa_crypto_generator_t *generator); * results in this error code. */ psa_status_t psa_key_derivation(psa_crypto_generator_t *generator, - psa_key_slot_t key, + psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *salt, size_t salt_length, @@ -3462,7 +3475,7 @@ psa_status_t psa_key_derivation(psa_crypto_generator_t *generator, * a logical zero (`{0}`), * \c PSA_CRYPTO_GENERATOR_INIT or * psa_crypto_generator_init(). - * \param private_key Slot containing the private key to use. + * \param private_key Handle to the private key to use. * \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 @@ -3475,6 +3488,7 @@ psa_status_t psa_key_derivation(psa_crypto_generator_t *generator, * * \retval #PSA_SUCCESS * Success. + * \retval #PSA_ERROR_INVALID_HANDLE * \retval #PSA_ERROR_EMPTY_SLOT * \retval #PSA_ERROR_NOT_PERMITTED * \retval #PSA_ERROR_INVALID_ARGUMENT @@ -3489,7 +3503,7 @@ psa_status_t psa_key_derivation(psa_crypto_generator_t *generator, * \retval #PSA_ERROR_TAMPERING_DETECTED */ psa_status_t psa_key_agreement(psa_crypto_generator_t *generator, - psa_key_slot_t private_key, + psa_key_handle_t private_key, const uint8_t *peer_key, size_t peer_key_length, psa_algorithm_t alg); @@ -3538,9 +3552,13 @@ typedef struct { /** * \brief Generate a key or key pair. * - * \param key Slot where the key will be stored. This must be a - * valid slot for a key of the chosen type. It must - * be unoccupied. + * \param handle Handle to the slot where the key will be stored. + * This must be a valid slot for a key of the chosen + * type: it must have been obtained by calling + * psa_allocate_key() or psa_create_key() with the + * correct \p type and with a maximum size that is + * compatible with \p bits. + * It must not contain any key material yet. * \param type Key type (a \c PSA_KEY_TYPE_XXX value). * \param bits Key size in bits. * \param[in] extra Extra parameters for key generation. The @@ -3569,6 +3587,9 @@ typedef struct { * \c NULL then \p extra_size must be zero. * * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_INVALID_HANDLE + * \retval #PSA_ERROR_OCCUPIED_SLOT + * There is already a key in the specified slot. * \retval #PSA_ERROR_NOT_SUPPORTED * \retval #PSA_ERROR_INVALID_ARGUMENT * \retval #PSA_ERROR_INSUFFICIENT_MEMORY @@ -3581,7 +3602,7 @@ typedef struct { * It is implementation-dependent whether a failure to initialize * results in this error code. */ -psa_status_t psa_generate_key(psa_key_slot_t key, +psa_status_t psa_generate_key(psa_key_handle_t handle, psa_key_type_t type, size_t bits, const void *extra,