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.

include/psa/crypto.h

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

include/psa/crypto_se_driver.h

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

include/psa/crypto_types.h

@@ -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
  * @{
  */