mirror of
https://github.com/Mbed-TLS/mbedtls.git
synced 2025-08-08 17:42:09 +03: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
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user