Move the definition of psa_key_attributes_t to crypto_types.h
psa_key_attributes_t is used in the SE driver HAL, so it must be defined in a common header, not in the API-only header crypto.h.
This commit is contained in:
Gilles Peskine
parent
9dd125d8bb
commit
105f67f0fa
3 changed files with 114 additions and 112 deletions
|
|
@ -93,117 +93,10 @@ psa_status_t psa_crypto_init(void);
|
|||
|
||||
/**@}*/
|
||||
|
||||
/** \defgroup attributes Key attributes
|
||||
/** \addtogroup attributes
|
||||
* @{
|
||||
*/
|
||||
|
||||
/** The type of a structure containing key attributes.
|
||||
*
|
||||
* This is an opaque structure that can represent the metadata of a key
|
||||
* object. Metadata that can be stored in attributes includes:
|
||||
* - The location of the key in storage, indicated by its key identifier
|
||||
* and its lifetime.
|
||||
* - The key's policy, comprising usage flags and a specification of
|
||||
* the permitted algorithm(s).
|
||||
* - Information about the key itself: the key type and its size.
|
||||
* - Implementations may define additional attributes.
|
||||
*
|
||||
* The actual key material is not considered an attribute of a key.
|
||||
* Key attributes do not contain information that is generally considered
|
||||
* highly confidential.
|
||||
*
|
||||
* An attribute structure can be a simple data structure where each function
|
||||
* `psa_set_key_xxx` sets a field and the corresponding function
|
||||
* `psa_get_key_xxx` retrieves the value of the corresponding field.
|
||||
* However, implementations may report values that are equivalent to the
|
||||
* original one, but have a different encoding. For example, an
|
||||
* implementation may use a more compact representation for types where
|
||||
* many bit-patterns are invalid or not supported, and store all values
|
||||
* that it does not support as a special marker value. In such an
|
||||
* implementation, after setting an invalid value, the corresponding
|
||||
* get function returns an invalid value which may not be the one that
|
||||
* was originally stored.
|
||||
*
|
||||
* An attribute structure may contain references to auxiliary resources,
|
||||
* for example pointers to allocated memory or indirect references to
|
||||
* pre-calculated values. In order to free such resources, the application
|
||||
* must call psa_reset_key_attributes(). As an exception, calling
|
||||
* psa_reset_key_attributes() on an attribute structure is optional if
|
||||
* the structure has only been modified by the following functions
|
||||
* since it was initialized or last reset with psa_reset_key_attributes():
|
||||
* - psa_set_key_id()
|
||||
* - psa_set_key_lifetime()
|
||||
* - psa_set_key_type()
|
||||
* - psa_set_key_bits()
|
||||
* - psa_set_key_usage_flags()
|
||||
* - psa_set_key_algorithm()
|
||||
*
|
||||
* Before calling any function on a key attribute structure, the application
|
||||
* must initialize it by any of the following means:
|
||||
* - Set the structure to all-bits-zero, for example:
|
||||
* \code
|
||||
* psa_key_attributes_t attributes;
|
||||
* memset(&attributes, 0, sizeof(attributes));
|
||||
* \endcode
|
||||
* - Initialize the structure to logical zero values, for example:
|
||||
* \code
|
||||
* psa_key_attributes_t attributes = {0};
|
||||
* \endcode
|
||||
* - Initialize the structure to the initializer #PSA_KEY_ATTRIBUTES_INIT,
|
||||
* for example:
|
||||
* \code
|
||||
* psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
|
||||
* \endcode
|
||||
* - Assign the result of the function psa_key_attributes_init()
|
||||
* to the structure, for example:
|
||||
* \code
|
||||
* psa_key_attributes_t attributes;
|
||||
* attributes = psa_key_attributes_init();
|
||||
* \endcode
|
||||
*
|
||||
* A freshly initialized attribute structure contains the following
|
||||
* values:
|
||||
*
|
||||
* - lifetime: #PSA_KEY_LIFETIME_VOLATILE.
|
||||
* - key identifier: unspecified.
|
||||
* - type: \c 0.
|
||||
* - key size: \c 0.
|
||||
* - usage flags: \c 0.
|
||||
* - algorithm: \c 0.
|
||||
*
|
||||
* A typical sequence to create a key is as follows:
|
||||
* -# Create and initialize an attribute structure.
|
||||
* -# If the key is persistent, call psa_set_key_id().
|
||||
* Also call psa_set_key_lifetime() to place the key in a non-default
|
||||
* location.
|
||||
* -# Set the key policy with psa_set_key_usage_flags() and
|
||||
* psa_set_key_algorithm().
|
||||
* -# Set the key type with psa_set_key_type().
|
||||
* Skip this step if copying an existing key with psa_copy_key().
|
||||
* -# When generating a random key with psa_generate_key() or deriving a key
|
||||
* with psa_key_derivation_output_key(), set the desired key size with
|
||||
* psa_set_key_bits().
|
||||
* -# Call a key creation function: psa_import_key(), psa_generate_key(),
|
||||
* psa_key_derivation_output_key() or psa_copy_key(). This function reads
|
||||
* the attribute structure, creates a key with these attributes, and
|
||||
* outputs a handle to the newly created key.
|
||||
* -# The attribute structure is now no longer necessary.
|
||||
* You may call psa_reset_key_attributes(), although this is optional
|
||||
* with the workflow presented here because the attributes currently
|
||||
* defined in this specification do not require any additional resources
|
||||
* beyond the structure itself.
|
||||
*
|
||||
* A typical sequence to query a key's attributes is as follows:
|
||||
* -# Call psa_get_key_attributes().
|
||||
* -# Call `psa_get_key_xxx` functions to retrieve the attribute(s) that
|
||||
* you are interested in.
|
||||
* -# Call psa_reset_key_attributes() to free any resources that may be
|
||||
* used by the attribute structure.
|
||||
*
|
||||
* Once a key has been created, it is impossible to change its attributes.
|
||||
*/
|
||||
typedef struct psa_key_attributes_s psa_key_attributes_t;
|
||||
|
||||
/** \def PSA_KEY_ATTRIBUTES_INIT
|
||||
*
|
||||
* This macro returns a suitable initializer for a key attribute structure
|
||||
|
|
|
|||
|
|
@ -782,10 +782,6 @@ typedef struct {
|
|||
*/
|
||||
/**@{*/
|
||||
|
||||
/* This type is documented in crypto.h. As far as drivers are concerned,
|
||||
* this is an opaque type. */
|
||||
typedef struct psa_key_attributes_s psa_key_attributes_t;
|
||||
|
||||
/** \brief A function that allocates a slot for a key.
|
||||
*
|
||||
* \param[in,out] drv_context The driver context structure.
|
||||
|
|
|
|||
|
|
@ -133,6 +133,119 @@ typedef uint32_t psa_key_usage_t;
|
|||
|
||||
/**@}*/
|
||||
|
||||
/** \defgroup attributes Key attributes
|
||||
* @{
|
||||
*/
|
||||
|
||||
/** The type of a structure containing key attributes.
|
||||
*
|
||||
* This is an opaque structure that can represent the metadata of a key
|
||||
* object. Metadata that can be stored in attributes includes:
|
||||
* - The location of the key in storage, indicated by its key identifier
|
||||
* and its lifetime.
|
||||
* - The key's policy, comprising usage flags and a specification of
|
||||
* the permitted algorithm(s).
|
||||
* - Information about the key itself: the key type and its size.
|
||||
* - Implementations may define additional attributes.
|
||||
*
|
||||
* The actual key material is not considered an attribute of a key.
|
||||
* Key attributes do not contain information that is generally considered
|
||||
* highly confidential.
|
||||
*
|
||||
* An attribute structure can be a simple data structure where each function
|
||||
* `psa_set_key_xxx` sets a field and the corresponding function
|
||||
* `psa_get_key_xxx` retrieves the value of the corresponding field.
|
||||
* However, implementations may report values that are equivalent to the
|
||||
* original one, but have a different encoding. For example, an
|
||||
* implementation may use a more compact representation for types where
|
||||
* many bit-patterns are invalid or not supported, and store all values
|
||||
* that it does not support as a special marker value. In such an
|
||||
* implementation, after setting an invalid value, the corresponding
|
||||
* get function returns an invalid value which may not be the one that
|
||||
* was originally stored.
|
||||
*
|
||||
* An attribute structure may contain references to auxiliary resources,
|
||||
* for example pointers to allocated memory or indirect references to
|
||||
* pre-calculated values. In order to free such resources, the application
|
||||
* must call psa_reset_key_attributes(). As an exception, calling
|
||||
* psa_reset_key_attributes() on an attribute structure is optional if
|
||||
* the structure has only been modified by the following functions
|
||||
* since it was initialized or last reset with psa_reset_key_attributes():
|
||||
* - psa_set_key_id()
|
||||
* - psa_set_key_lifetime()
|
||||
* - psa_set_key_type()
|
||||
* - psa_set_key_bits()
|
||||
* - psa_set_key_usage_flags()
|
||||
* - psa_set_key_algorithm()
|
||||
*
|
||||
* Before calling any function on a key attribute structure, the application
|
||||
* must initialize it by any of the following means:
|
||||
* - Set the structure to all-bits-zero, for example:
|
||||
* \code
|
||||
* psa_key_attributes_t attributes;
|
||||
* memset(&attributes, 0, sizeof(attributes));
|
||||
* \endcode
|
||||
* - Initialize the structure to logical zero values, for example:
|
||||
* \code
|
||||
* psa_key_attributes_t attributes = {0};
|
||||
* \endcode
|
||||
* - Initialize the structure to the initializer #PSA_KEY_ATTRIBUTES_INIT,
|
||||
* for example:
|
||||
* \code
|
||||
* psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
|
||||
* \endcode
|
||||
* - Assign the result of the function psa_key_attributes_init()
|
||||
* to the structure, for example:
|
||||
* \code
|
||||
* psa_key_attributes_t attributes;
|
||||
* attributes = psa_key_attributes_init();
|
||||
* \endcode
|
||||
*
|
||||
* A freshly initialized attribute structure contains the following
|
||||
* values:
|
||||
*
|
||||
* - lifetime: #PSA_KEY_LIFETIME_VOLATILE.
|
||||
* - key identifier: unspecified.
|
||||
* - type: \c 0.
|
||||
* - key size: \c 0.
|
||||
* - usage flags: \c 0.
|
||||
* - algorithm: \c 0.
|
||||
*
|
||||
* A typical sequence to create a key is as follows:
|
||||
* -# Create and initialize an attribute structure.
|
||||
* -# If the key is persistent, call psa_set_key_id().
|
||||
* Also call psa_set_key_lifetime() to place the key in a non-default
|
||||
* location.
|
||||
* -# Set the key policy with psa_set_key_usage_flags() and
|
||||
* psa_set_key_algorithm().
|
||||
* -# Set the key type with psa_set_key_type().
|
||||
* Skip this step if copying an existing key with psa_copy_key().
|
||||
* -# When generating a random key with psa_generate_key() or deriving a key
|
||||
* with psa_key_derivation_output_key(), set the desired key size with
|
||||
* psa_set_key_bits().
|
||||
* -# Call a key creation function: psa_import_key(), psa_generate_key(),
|
||||
* psa_key_derivation_output_key() or psa_copy_key(). This function reads
|
||||
* the attribute structure, creates a key with these attributes, and
|
||||
* outputs a handle to the newly created key.
|
||||
* -# The attribute structure is now no longer necessary.
|
||||
* You may call psa_reset_key_attributes(), although this is optional
|
||||
* with the workflow presented here because the attributes currently
|
||||
* defined in this specification do not require any additional resources
|
||||
* beyond the structure itself.
|
||||
*
|
||||
* A typical sequence to query a key's attributes is as follows:
|
||||
* -# Call psa_get_key_attributes().
|
||||
* -# Call `psa_get_key_xxx` functions to retrieve the attribute(s) that
|
||||
* you are interested in.
|
||||
* -# Call psa_reset_key_attributes() to free any resources that may be
|
||||
* used by the attribute structure.
|
||||
*
|
||||
* Once a key has been created, it is impossible to change its attributes.
|
||||
*/
|
||||
typedef struct psa_key_attributes_s psa_key_attributes_t;
|
||||
|
||||
/**@}*/
|
||||
|
||||
/** \defgroup derivation Key derivation
|
||||
* @{
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in a new issue