diff --git a/sys/include/psa_crypto/psa/crypto_struct.h b/sys/include/psa_crypto/psa/crypto_struct.h index 342877eb4e02..3551aa9196af 100644 --- a/sys/include/psa_crypto/psa/crypto_struct.h +++ b/sys/include/psa_crypto/psa/crypto_struct.h @@ -28,50 +28,6 @@ extern "C" { #include "crypto_sizes.h" #include "crypto_contexts.h" -#if IS_USED(MODULE_PSA_KEY_MANAGEMENT) || defined(DOXYGEN) -/** - * @brief Structure storing the key usage policies - */ -struct psa_key_policy_s { - psa_key_usage_t usage; /**< Key usage policy */ - psa_algorithm_t alg; /**< Algorithm for key usage */ -}; - -/** - * @brief Type for key usage policies. - */ -typedef struct psa_key_policy_s psa_key_policy_t; - -/** - * @brief Structure storing key attributes - */ -struct psa_key_attributes_s { - psa_key_type_t type; /**< Type of key */ - psa_key_bits_t bits; /**< Size of key in bits */ - psa_key_lifetime_t lifetime; /**< Lifetime of key */ - psa_key_id_t id; /**< Key identifier */ - psa_key_policy_t policy; /**< Key usage policy */ -}; - -/** - * @brief This macro returns a suitable initializer for a key attribute object of - * type @ref psa_key_attributes_t. - */ -#define PSA_KEY_ATTRIBUTES_INIT { 0 } - -/** - * @brief Return an initial value for a key attribute object. - * - * @return struct psa_key_attributes_s - */ -static inline struct psa_key_attributes_s psa_key_attributes_init(void) -{ - const struct psa_key_attributes_s v = PSA_KEY_ATTRIBUTES_INIT; - - return v; -} -#endif /*(MODULE_PSA_KEY_MANAGEMENT */ - #if IS_USED(MODULE_PSA_AEAD) || defined(DOXYGEN) /** * @brief Structure storing an AEAD operation context diff --git a/sys/include/psa_crypto/psa/crypto_types.h b/sys/include/psa_crypto/psa/crypto_types.h index 597bae9cbac6..0d4e50296f14 100644 --- a/sys/include/psa_crypto/psa/crypto_types.h +++ b/sys/include/psa_crypto/psa/crypto_types.h @@ -28,11 +28,7 @@ extern "C" { #include "psa/algorithm.h" #include "psa/error.h" -#include "psa/key/bits.h" -#include "psa/key/id.h" -#include "psa/key/lifetime.h" -#include "psa/key/usage.h" -#include "psa/key/type.h" +#include "psa/key/attributes.h" /** * @brief For encrypt-decrypt functions, whether the operation is an encryption @@ -177,109 +173,6 @@ typedef struct psa_mac_operation_s psa_mac_operation_t; */ typedef struct psa_hash_operation_s psa_hash_operation_t; -/** - * @brief The type of an object containing key attributes. - * - * @details This is the object that represents 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 can 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. - * - * @note Implementations are recommended to define the attribute object as a simple data - * structure, with fields corresponding to the individual key attributes. In such an - * implementation, each function @c psa_set_key_xxx() sets a field and the corresponding - * function @c psa_get_key_xxx() retrieves the value of the field. - * An implementation can report attribute values that are equivalent to the original one, - * but have a different encoding. For example, an implementation can 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 might not be the one that was originally stored. - * - * This is an implementation-defined type. Applications that make assumptions about the - * content of this object will result in in implementation-specific behavior, and are - * non-portable. - * - * An attribute object can 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 @ref psa_reset_key_attributes(). As an - * exception, calling @ref psa_reset_key_attributes() on an attribute object is optional - * if the object has only been modified by the following functions since it was - * initialized or last reset with @ref psa_reset_key_attributes(): - * - @ref psa_set_key_id() - * - @ref psa_set_key_lifetime() - * - @ref psa_set_key_type() - * - @ref psa_set_key_bits() - * - @ref psa_set_key_usage_flags() - * - @ref psa_set_key_algorithm() - * Before calling any function on a key attribute object, the application must initialize - * it by any of the following means: - * - Set the object to all-bits-zero, for example: - * @code - * @ref psa_key_attributes_t attributes; - * memset(&attributes, 0, sizeof(attributes)); - * @endcode - * - Initialize the object to logical zero values by declaring the object as static or - * global without an explicit initializer, for example: - * @code - * static @ref psa_key_attributes_t attributes; - * @endcode - * - Initialize the object to the initializer @ref PSA_KEY_ATTRIBUTES_INIT, for example: - * @code - * @ref psa_key_attributes_t attributes = @ref PSA_KEY_ATTRIBUTES_INIT; - * @endcode - * - Assign the result of the function @ref psa_key_attributes_init() to the object, - * for example: - * @code - * @ref psa_key_attributes_t attributes; - * attributes = @ref psa_key_attributes_init(); - * @endcode - * - * A freshly initialized attribute object contains the following values: - * - lifetime: @ref PSA_KEY_LIFETIME_VOLATILE. - * - key identifier: @ref PSA_KEY_ID_NULL — which is not a valid key identifier. - * - type: @ref PSA_KEY_TYPE_NONE — meaning that the type is unspecified. - * - key size: @c 0 — meaning that the size is unspecified. - * - usage flags: @c 0 — which allows no usage except exporting a public key. - * - algorithm: @ref PSA_ALG_NONE — which does not allow cryptographic usage, - * but allows exporting. - * - * ## Usage - * A typical sequence to create a key is as follows: - * -# Create and initialize an attribute object. - * -# If the key is persistent, call @ref psa_set_key_id(). Also call @ref - * psa_set_key_lifetime() to place the key in a non-default location. - * -# Set the key policy with @ref psa_set_key_usage_flags() and @ref - * psa_set_key_algorithm(). - * -# Set the key type with @ref psa_set_key_type(). Skip this step if copying an existing - * key with @ref psa_copy_key(). - * -# When generating a random key with @ref psa_generate_key() or deriving a key with - * @ref psa_key_derivation_output_key(), set the desired key size with @ref - * psa_set_key_bits(). - * -# Call a key creation function: @ref psa_import_key(), @ref psa_generate_key(), - * @ref psa_key_derivation_output_key() or @ref psa_copy_key(). This function reads the - * attribute object, creates a key with these attributes, and outputs an identifier for - * the newly created key. - * -# Optionally call @ref psa_reset_key_attributes(), now that the attribute object is no - * longer needed. Currently this call is not required as the attributes defined in this - * specification do not require additional resources beyond the object itself. - * - * A typical sequence to query a key’s attributes is as follows: - * -# Call @ref psa_get_key_attributes(). - * -# Call @c psa_get_key_xxx() functions to retrieve the required attribute(s). - * -# Call @ref psa_reset_key_attributes() to free any resources that can be used by the - * attribute object. - * - * Once a key has been created, it is impossible to change its attributes. - */ -typedef struct psa_key_attributes_s psa_key_attributes_t; - /** * @brief The type of the state object for multi-part cipher operations. * diff --git a/sys/include/psa_crypto/psa/key/attributes.h b/sys/include/psa_crypto/psa/key/attributes.h new file mode 100644 index 000000000000..a084f833e57f --- /dev/null +++ b/sys/include/psa_crypto/psa/key/attributes.h @@ -0,0 +1,188 @@ +/* + * Copyright (C) 2024 TU Dresden + * Copyright (C) 2021 HAW Hamburg + * + * This file is subject to the terms and conditions of the GNU Lesser + * General Public License v2.1. See the file LICENSE in the top level + * directory for more details. + */ + +/** + * @ingroup sys_psa_crypto + * @{ + * + * @file key/attributes.h + * @brief Key attributes definitions for the PSA Crypto API + * + * @author Armin Wolf + * @author Lena Boeckmann + * + */ + +#ifndef PSA_CRYPTO_PSA_KEY_ATTRIBUTES_H +#define PSA_CRYPTO_PSA_KEY_ATTRIBUTES_H + +#ifdef __cplusplus +extern "C" { +#endif + +#include "psa/algorithm.h" +#include "bits.h" +#include "id.h" +#include "lifetime.h" +#include "type.h" +#include "usage.h" + +#if IS_USED(MODULE_PSA_KEY_MANAGEMENT) || defined(DOXYGEN) +/** + * @brief Structure storing the key usage policies + */ +struct psa_key_policy_s { + psa_key_usage_t usage; /**< Key usage policy */ + psa_algorithm_t alg; /**< Algorithm for key usage */ +}; + +/** + * @brief Type for key usage policies. + */ +typedef struct psa_key_policy_s psa_key_policy_t; + +/** + * @brief Structure storing key attributes + */ +struct psa_key_attributes_s { + psa_key_type_t type; /**< Type of key */ + psa_key_bits_t bits; /**< Size of key in bits */ + psa_key_lifetime_t lifetime; /**< Lifetime of key */ + psa_key_id_t id; /**< Key identifier */ + psa_key_policy_t policy; /**< Key usage policy */ +}; + +/** + * @brief The type of an object containing key attributes. + * + * @details This is the object that represents 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 can 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. + * + * @note Implementations are recommended to define the attribute object as a simple data + * structure, with fields corresponding to the individual key attributes. In such an + * implementation, each function @c psa_set_key_xxx() sets a field and the corresponding + * function @c psa_get_key_xxx() retrieves the value of the field. + * An implementation can report attribute values that are equivalent to the original one, + * but have a different encoding. For example, an implementation can 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 might not be the one that was originally stored. + * + * This is an implementation-defined type. Applications that make assumptions about the + * content of this object will result in in implementation-specific behavior, and are + * non-portable. + * + * An attribute object can 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 @ref psa_reset_key_attributes(). As an + * exception, calling @ref psa_reset_key_attributes() on an attribute object is optional + * if the object has only been modified by the following functions since it was + * initialized or last reset with @ref psa_reset_key_attributes(): + * - @ref psa_set_key_id() + * - @ref psa_set_key_lifetime() + * - @ref psa_set_key_type() + * - @ref psa_set_key_bits() + * - @ref psa_set_key_usage_flags() + * - @ref psa_set_key_algorithm() + * Before calling any function on a key attribute object, the application must initialize + * it by any of the following means: + * - Set the object to all-bits-zero, for example: + * @code + * @ref psa_key_attributes_t attributes; + * memset(&attributes, 0, sizeof(attributes)); + * @endcode + * - Initialize the object to logical zero values by declaring the object as static or + * global without an explicit initializer, for example: + * @code + * static @ref psa_key_attributes_t attributes; + * @endcode + * - Initialize the object to the initializer @ref PSA_KEY_ATTRIBUTES_INIT, for example: + * @code + * @ref psa_key_attributes_t attributes = @ref PSA_KEY_ATTRIBUTES_INIT; + * @endcode + * - Assign the result of the function @ref psa_key_attributes_init() to the object, + * for example: + * @code + * @ref psa_key_attributes_t attributes; + * attributes = @ref psa_key_attributes_init(); + * @endcode + * + * A freshly initialized attribute object contains the following values: + * - lifetime: @ref PSA_KEY_LIFETIME_VOLATILE. + * - key identifier: @ref PSA_KEY_ID_NULL — which is not a valid key identifier. + * - type: @ref PSA_KEY_TYPE_NONE — meaning that the type is unspecified. + * - key size: @c 0 — meaning that the size is unspecified. + * - usage flags: @c 0 — which allows no usage except exporting a public key. + * - algorithm: @ref PSA_ALG_NONE — which does not allow cryptographic usage, + * but allows exporting. + * + * ## Usage + * A typical sequence to create a key is as follows: + * -# Create and initialize an attribute object. + * -# If the key is persistent, call @ref psa_set_key_id(). Also call @ref + * psa_set_key_lifetime() to place the key in a non-default location. + * -# Set the key policy with @ref psa_set_key_usage_flags() and @ref + * psa_set_key_algorithm(). + * -# Set the key type with @ref psa_set_key_type(). Skip this step if copying an existing + * key with @ref psa_copy_key(). + * -# When generating a random key with @ref psa_generate_key() or deriving a key with + * @ref psa_key_derivation_output_key(), set the desired key size with @ref + * psa_set_key_bits(). + * -# Call a key creation function: @ref psa_import_key(), @ref psa_generate_key(), + * @ref psa_key_derivation_output_key() or @ref psa_copy_key(). This function reads the + * attribute object, creates a key with these attributes, and outputs an identifier for + * the newly created key. + * -# Optionally call @ref psa_reset_key_attributes(), now that the attribute object is no + * longer needed. Currently this call is not required as the attributes defined in this + * specification do not require additional resources beyond the object itself. + * + * A typical sequence to query a key’s attributes is as follows: + * -# Call @ref psa_get_key_attributes(). + * -# Call @c psa_get_key_xxx() functions to retrieve the required attribute(s). + * -# Call @ref psa_reset_key_attributes() to free any resources that can be used by the + * attribute object. + * + * Once a key has been created, it is impossible to change its attributes. + */ +typedef struct psa_key_attributes_s psa_key_attributes_t; + +/** + * @brief This macro returns a suitable initializer for a key attribute object of + * type @ref psa_key_attributes_t. + */ +#define PSA_KEY_ATTRIBUTES_INIT { 0 } + +/** + * @brief Return an initial value for a key attribute object. + * + * @return psa_key_attributes_t + */ +static inline psa_key_attributes_t psa_key_attributes_init(void) +{ + const psa_key_attributes_t v = PSA_KEY_ATTRIBUTES_INIT; + + return v; +} +#endif /* MODULE_PSA_KEY_MANAGEMENT */ + +#ifdef __cplusplus +} +#endif + +#endif /* PSA_CRYPTO_PSA_KEY_ATTRIBUTES_H */ +/** @} */