cuberite/polarssl
1
0
Fork 0
mirror of https://github.com/cuberite/polarssl.git synced 2025-11-04 04:32:24 -05:00
Code Issues Packages Projects Releases Wiki Activity

Move legacy definitions to crypto_extra.h

Browse Source 
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 2019-04-19 19:42:26 +02:00
parent 2062859496
commit a3dd737be4
3 changed files with 155 additions and 179 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

179
include/psa/crypto.h
View File

@ -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.
*

154
include/psa/crypto_extra.h
View File

@ -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.

1
include/psa/crypto_struct.h
View File

@ -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 )