diff --git a/include/psa/crypto.h b/include/psa/crypto.h index e0ac89cade..2046947ddc 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -365,162 +365,10 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes); /**@}*/ -/** \defgroup policy Key policies - * @{ - */ - -/** The type of the key policy data structure. - * - * Before calling any function on a key policy, the application must initialize - * it by any of the following means: - * - Set the structure to all-bits-zero, for example: - * \code - * psa_key_policy_t policy; - * memset(&policy, 0, sizeof(policy)); - * \endcode - * - Initialize the structure to logical zero values, for example: - * \code - * psa_key_policy_t policy = {0}; - * \endcode - * - Initialize the structure to the initializer #PSA_KEY_POLICY_INIT, - * for example: - * \code - * psa_key_policy_t policy = PSA_KEY_POLICY_INIT; - * \endcode - * - Assign the result of the function psa_key_policy_init() - * to the structure, for example: - * \code - * psa_key_policy_t policy; - * policy = psa_key_policy_init(); - * \endcode - * - * This is an implementation-defined \c struct. Applications should not - * make any assumptions about the content of this structure except - * as directed by the documentation of a specific implementation. */ -typedef struct psa_key_policy_s psa_key_policy_t; - -/** \def PSA_KEY_POLICY_INIT - * - * This macro returns a suitable initializer for a key policy object of type - * #psa_key_policy_t. - */ -#ifdef __DOXYGEN_ONLY__ -/* This is an example definition for documentation purposes. - * Implementations should define a suitable value in `crypto_struct.h`. - */ -#define PSA_KEY_POLICY_INIT {0} -#endif - -/** Return an initial value for a key policy that forbids all usage of the key. - */ -static psa_key_policy_t psa_key_policy_init(void); - -/** \brief Set the standard fields of a policy structure. - * - * Note that this function does not make any consistency check of the - * parameters. The values are only checked when applying the policy to - * a key slot with psa_set_key_policy(). - * - * \param[in,out] policy The key policy to modify. It must have been - * initialized as per the documentation for - * #psa_key_policy_t. - * \param usage The permitted uses for the key. - * \param alg The algorithm that the key may be used for. - */ -void psa_key_policy_set_usage(psa_key_policy_t *policy, - psa_key_usage_t usage, - psa_algorithm_t alg); - -/** \brief Retrieve the usage field of a policy structure. - * - * \param[in] policy The policy object to query. - * - * \return The permitted uses for a key with this policy. - */ -psa_key_usage_t psa_key_policy_get_usage(const psa_key_policy_t *policy); - -/** \brief Retrieve the algorithm field of a policy structure. - * - * \param[in] policy The policy object to query. - * - * \return The permitted algorithm for a key with this policy. - */ -psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy); - -/** \brief Set the usage policy on a key slot. - * - * This function must be called on an empty key slot, before importing, - * generating or creating a key in the slot. Changing the policy of an - * existing key is not permitted. - * - * Implementations may set restrictions on supported key policies - * depending on the key type and the key slot. - * - * \param handle Handle to the key whose policy is to be changed. - * \param[in] policy The policy object to query. - * - * \retval #PSA_SUCCESS - * Success. - * If the key is persistent, it is implementation-defined whether - * the policy has been saved to persistent storage. Implementations - * may defer saving the policy until the key material is created. - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_ALREADY_EXISTS - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \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_set_key_policy(psa_key_handle_t handle, - const psa_key_policy_t *policy); - -/** \brief Get the usage policy for a key slot. - * - * \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 - * \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_policy(psa_key_handle_t handle, - psa_key_policy_t *policy); - -/**@}*/ - /** \defgroup key_management Key management * @{ */ -/** Allocate a key slot for a transient key, i.e. a key which is only stored - * in volatile memory. - * - * The allocated key slot and its handle remain valid until the - * application calls psa_close_key() or psa_destroy_key() or until the - * application terminates. - * - * \param[out] handle On success, a handle to a volatile key slot. - * - * \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 - * There was not enough memory, or the maximum number of key slots - * has been reached. - */ -psa_status_t psa_allocate_key(psa_key_handle_t *handle); - /** Open a handle to an existing persistent key. * * Open a handle to a key which was previously created with psa_create_key(). @@ -684,33 +532,6 @@ psa_status_t psa_import_key(const psa_key_attributes_t *attributes, */ psa_status_t psa_destroy_key(psa_key_handle_t handle); -/** - * \brief Get basic metadata about a key. - * - * \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. - * \param[out] bits On success, the key size in bits. - * This may be a null pointer, in which case the key size - * is not written. - * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_DOES_NOT_EXIST - * The handle is to a key slot which does not contain key material yet. - * \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_information(psa_key_handle_t handle, - psa_key_type_t *type, - size_t *bits); - /** * \brief Set domain parameters for a key. * diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h index efd1b76dab..f2cf05150c 100644 --- a/include/psa/crypto_extra.h +++ b/include/psa/crypto_extra.h @@ -202,6 +202,115 @@ psa_status_t psa_key_derivation(psa_crypto_generator_t *generator, /* FIXME Deprecated. Remove this as soon as all the tests are updated. */ #define PSA_ALG_SELECT_RAW ((psa_algorithm_t)0x31000001) +/** \defgroup policy Key policies + * @{ + * + * The functions in this section are legacy interfaces where the properties + * of a key object are set after allocating a handle, in constrast with the + * preferred interface where key objects are created atomically from + * a structure that represents the properties. + */ + +/** \def PSA_KEY_POLICY_INIT + * + * This macro returns a suitable initializer for a key policy object of type + * #psa_key_policy_t. + */ +#ifdef __DOXYGEN_ONLY__ +/* This is an example definition for documentation purposes. + * Implementations should define a suitable value in `crypto_struct.h`. + */ +#define PSA_KEY_POLICY_INIT {0} +#endif + +/** Return an initial value for a key policy that forbids all usage of the key. + */ +static psa_key_policy_t psa_key_policy_init(void); + +/** \brief Set the standard fields of a policy structure. + * + * Note that this function does not make any consistency check of the + * parameters. The values are only checked when applying the policy to + * a key slot with psa_set_key_policy(). + * + * \param[in,out] policy The key policy to modify. It must have been + * initialized as per the documentation for + * #psa_key_policy_t. + * \param usage The permitted uses for the key. + * \param alg The algorithm that the key may be used for. + */ +void psa_key_policy_set_usage(psa_key_policy_t *policy, + psa_key_usage_t usage, + psa_algorithm_t alg); + +/** \brief Retrieve the usage field of a policy structure. + * + * \param[in] policy The policy object to query. + * + * \return The permitted uses for a key with this policy. + */ +psa_key_usage_t psa_key_policy_get_usage(const psa_key_policy_t *policy); + +/** \brief Retrieve the algorithm field of a policy structure. + * + * \param[in] policy The policy object to query. + * + * \return The permitted algorithm for a key with this policy. + */ +psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy); + +/** \brief Set the usage policy on a key slot. + * + * This function must be called on an empty key slot, before importing, + * generating or creating a key in the slot. Changing the policy of an + * existing key is not permitted. + * + * Implementations may set restrictions on supported key policies + * depending on the key type and the key slot. + * + * \param handle Handle to the key whose policy is to be changed. + * \param[in] policy The policy object to query. + * + * \retval #PSA_SUCCESS + * Success. + * If the key is persistent, it is implementation-defined whether + * the policy has been saved to persistent storage. Implementations + * may defer saving the policy until the key material is created. + * \retval #PSA_ERROR_INVALID_HANDLE + * \retval #PSA_ERROR_ALREADY_EXISTS + * \retval #PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_INVALID_ARGUMENT + * \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_set_key_policy(psa_key_handle_t handle, + const psa_key_policy_t *policy); + +/** \brief Get the usage policy for a key slot. + * + * \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 + * \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_policy(psa_key_handle_t handle, + psa_key_policy_t *policy); + +/**@}*/ + /** \defgroup to_handle Key creation to allocated handle * @{ * @@ -248,6 +357,51 @@ psa_status_t psa_create_key(psa_key_lifetime_t lifetime, psa_key_id_t id, psa_key_handle_t *handle); +/** Allocate a key slot for a transient key, i.e. a key which is only stored + * in volatile memory. + * + * The allocated key slot and its handle remain valid until the + * application calls psa_close_key() or psa_destroy_key() or until the + * application terminates. + * + * \param[out] handle On success, a handle to a volatile key slot. + * + * \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 + * There was not enough memory, or the maximum number of key slots + * has been reached. + */ +psa_status_t psa_allocate_key(psa_key_handle_t *handle); + +/** + * \brief Get basic metadata about a key. + * + * \param handle Handle to the key slot to query. + * \param[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. + * \param[out] bits On success, the key size in bits. + * This may be a null pointer, in which case the key size + * is not written. + * + * \retval #PSA_SUCCESS + * \retval #PSA_ERROR_INVALID_HANDLE + * \retval #PSA_ERROR_DOES_NOT_EXIST + * The handle is to a key slot which does not contain key material yet. + * \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_information(psa_key_handle_t handle, + psa_key_type_t *type, + size_t *bits); + /** \brief Retrieve the lifetime of an open key. * * \param handle Handle to query. diff --git a/include/psa/crypto_struct.h b/include/psa/crypto_struct.h index 51c9402481..273f6b6ecb 100644 --- a/include/psa/crypto_struct.h +++ b/include/psa/crypto_struct.h @@ -252,6 +252,7 @@ struct psa_key_policy_s psa_key_usage_t usage; psa_algorithm_t alg; }; +typedef struct psa_key_policy_s psa_key_policy_t; #define PSA_KEY_POLICY_INIT {0, 0} static inline struct psa_key_policy_s psa_key_policy_init( void )