mirror of
https://github.com/yuzu-emu/mbedtls.git
synced 2024-12-25 13:45:36 +00:00
Move legacy definitions to crypto_extra.h
Types and functions that are not used in the attribute-based key creation API are now implementation-specific extensions, kept around until we finish transitioning to the new API.
This commit is contained in:
Gilles Peskine
parent
2062859496
commit
a3dd737be4
|
|
@ -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
|
/** \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 an existing persistent key.
|
||||||
*
|
*
|
||||||
* Open a handle to a key which was previously created with psa_create_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);
|
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.
|
* \brief Set domain parameters for a key.
|
||||||
*
|
*
|
||||||
|
|
|
||||||
|
|
@ -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. */
|
/* FIXME Deprecated. Remove this as soon as all the tests are updated. */
|
||||||
#define PSA_ALG_SELECT_RAW ((psa_algorithm_t)0x31000001)
|
#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
|
/** \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_id_t id,
|
||||||
psa_key_handle_t *handle);
|
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.
|
/** \brief Retrieve the lifetime of an open key.
|
||||||
*
|
*
|
||||||
* \param handle Handle to query.
|
* \param handle Handle to query.
|
||||||
|
|
|
||||||
|
|
@ -252,6 +252,7 @@ struct psa_key_policy_s
|
||||||
psa_key_usage_t usage;
|
psa_key_usage_t usage;
|
||||||
psa_algorithm_t alg;
|
psa_algorithm_t alg;
|
||||||
};
|
};
|
||||||
|
typedef struct psa_key_policy_s psa_key_policy_t;
|
||||||
|
|
||||||
#define PSA_KEY_POLICY_INIT {0, 0}
|
#define PSA_KEY_POLICY_INIT {0, 0}
|
||||||
static inline struct psa_key_policy_s psa_key_policy_init( void )
|
static inline struct psa_key_policy_s psa_key_policy_init( void )
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue