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 edd695d2fc9a..0d4e50296f14 100644 --- a/sys/include/psa_crypto/psa/crypto_types.h +++ b/sys/include/psa_crypto/psa/crypto_types.h @@ -28,6 +28,7 @@ extern "C" { #include "psa/algorithm.h" #include "psa/error.h" +#include "psa/key/attributes.h" /** * @brief For encrypt-decrypt functions, whether the operation is an encryption @@ -38,30 +39,6 @@ typedef enum { PSA_CRYPTO_DRIVER_ENCRYPT } psa_encrypt_or_decrypt_t; -/** - * @brief The type of PSA finite-field Diffie-Hellman group family identifiers. - * - * @details The group family identifier is required to create a finite-field Diffie-Hellman - * key using the @ref PSA_KEY_TYPE_DH_KEY_PAIR() or @ref PSA_KEY_TYPE_DH_PUBLIC_KEY() - * macros. - * - * The specific Diffie-Hellman group within a family is identified by the @c key_bits - * attribute of the key. - */ -typedef uint8_t psa_dh_family_t; - -/** - * @brief The type of PSA elliptic curve family identifiers. - * - * @details The curve identifier is required to create an ECC key using the - * @ref PSA_KEY_TYPE_ECC_KEY_PAIR() or @ref PSA_KEY_TYPE_ECC_PUBLIC_KEY() - * macros. - * - * The specific ECC curve within a family is identified by the @c key_bits - * attribute of the key. - */ -typedef uint8_t psa_ecc_family_t; - /** * @brief The type of the state object for key derivation operations. * @@ -100,154 +77,6 @@ typedef struct psa_key_derivation_operation_s psa_key_derivation_operation_t; */ typedef uint16_t psa_key_derivation_step_t; -/** - * @brief Key identifier. - * - * @details A key identifier can be a permanent name for a persistent key, or a transient reference - * to volatile key. - */ -typedef uint32_t psa_key_id_t; - -/** - * @brief Encoding of key lifetimes. - * - * @details The lifetime of a key indicates where it is stored and which application and system - * actions will create and destroy it. - * - * Lifetime values have the following structure: - * - Bits[7:0]: Persistence level - * This value indicates what device management actions can cause it to be destroyed. - * In particular, it indicates whether the key is volatile or persistent. - * See @ref psa_key_persistence_t for more information. - * @ref PSA_KEY_LIFETIME_GET_PERSISTENCE(@p lifetime) returns the persistence level for - * a key lifetime value. - * - Bits[31:8]: Location indicator - * This value indicates where the key material is stored (or at least where it is - * accessible in cleartext) and where operations on the key are performed. See - * @ref psa_key_location_t for more information. - * @ref PSA_KEY_LIFETIME_GET_LOCATION(@p lifetime) returns the location indicator for a - * key lifetime value. - * - * Volatile keys are automatically destroyed when the application instance terminates or - * on a power reset of the device. Persistent keys are preserved until the application - * explicitly destroys them or until an implementation-specific device management event - * occurs, for example, a factor reset. - * - * Persistent keys have a key identifier of type @ref psa_key_id_t. This identifier - * remains valid throughout the lifetime of the key, even if the application instance - * that created the key terminates. - * - * This specification defines two basic lifetime values: - * - Keys with the lifetime @ref PSA_KEY_LIFETIME_VOLATILE are volatile. All - * implementations should support this lifetime. - * - Keys with the lifetime @ref PSA_KEY_LIFETIME_PERSISTENT are persistent. All - * implementations that have access to persistent storage with appropriate security - * guarantees should support this lifetime. - */ -typedef uint32_t psa_key_lifetime_t; - -/** - * @brief Encoding of key location indicators. - * - * @details If an implementation of this API can make calls to external cryptoprocessors such as - * secure elements, the location of a key indicates which secure element performs the - * operations on the key. If the key material is not stored persistently inside the secure - * element, it must be stored in a wrapped form such that only the secure element can - * access the key material in cleartext. - * - * @note Key location indicators are 24-bit values. Key management interfaces operate on - * lifetimes (type @ref psa_key_lifetime_t), and encode the location as the upper 24 bits - * of a 32-bit value. - * - * Values for location indicators defined by this specification are shown below: - * - @c 0: Primary local storage. - * All implementations should support this value. The primary local storage is - * typically the same storage area that contains the key metadata. - * - @c 1: Primary secure element. - * @note As of now, this value is not supported by this implementation. - * Use the vendor-defined location values. - * - * Implementations should support this value if there is a secure element - * attached to the operating environment. As a guideline, secure elements may - * provide higher resistance against side channel and physical attacks than the - * primary local storage, but may have restrictions on supported key types, - * sizes, policies and operations and may have different performance - * characteristics. - * - @c 2–0x7fffff: Other locations defined by a PSA specification. - * The PSA Cryptography API does not currently assign any meaning to - * these locations, but future versions of this specification or other - * PSA specifications may do so. - * - @c 0x800000–0xffffff: Vendor-defined locations. No PSA specification will assign a - * meaning to locations in this range. - */ -typedef uint32_t psa_key_location_t; - -/** - * @brief Encoding of key persistence levels. - * - * @details What distinguishes different persistence levels is which device management events can - * cause keys to be destroyed. For example, power reset, transfer of device ownership, - * or a factory reset are device management events that can affect keys at different - * persistence levels. The specific management events which affect persistent keys at - * different levels is outside the scope of the PSA Cryptography specification. - * - * @note Key persistence levels are 8-bit values. Key management interfaces operate on lifetimes - * (type @ref psa_key_lifetime_t), and encode the persistence value as the lower 8 bits of - * a 32-bit value. - * - * Values for persistence levels defined by this specification are shown below: - * - @c 0 = @ref PSA_KEY_PERSISTENCE_VOLATILE : Volatile key. - * A volatile key is automatically destroyed by the implementation when the - * application instance terminates. In particular, a volatile key is - * automatically destroyed on a power reset of the device. - * - @c 1 = @ref PSA_KEY_PERSISTENCE_DEFAULT : Persistent key with a default lifetime. - * Implementations should support this value if they support persistent keys - * at all. Applications should use this value if they have no specific needs - * that are only met by implementation-specific features. - * - @c 2–127: Persistent key with a PSA-specified lifetime. The PSA Cryptography - * specification does not define the meaning of these values, but other PSA - * specifications may do so. - * - @c 128–254: Persistent key with a vendor-specified lifetime. No PSA specification - * will define the meaning of these values, so implementations may choose - * the meaning freely. As a guideline, higher persistence levels should - * cause a key to survive more management events than lower levels. - * - @c 255 = @ref PSA_KEY_PERSISTENCE_READ_ONLY : Read-only or write-once key. - * A key with this persistence level cannot be destroyed. Implementations that - * support such keys may either allow their creation through the PSA - * Cryptography API, preferably only to applications with the appropriate - * privilege, or only expose keys created through implementation-specific - * means such as a factory ROM engraving process. - * @note Keys that are read-only due to policy restrictions rather than - * due to physical limitations should not have this persistence level. - */ -typedef uint8_t psa_key_persistence_t; - -/** - * @brief Encoding of a key type. - * - * @details This is a structured bitfield that identifies the category and type of key. The range - * of key type values is divided as follows: - * - @ref PSA_KEY_TYPE_NONE == @c 0: - * Reserved as an invalid key type. - * - @c 0x0001–0x7fff: - * Specification-defined key types. Key types defined by this standard always have bit - * 15 clear. Unallocated key type values in this range are reserved for future use. - * - @c 0x8000–0xffff: - * Implementation-defined key types. Implementations that define additional key types - * must use an encoding with bit 15 set. - */ -typedef uint16_t psa_key_type_t; - -/** - * @brief Encoding of permitted usage on a key. - */ -typedef uint32_t psa_key_usage_t; - -/** - * @brief Public interfaces use @c size_t, but internally we use a smaller type. - */ -typedef uint16_t psa_key_bits_t; - /* These are all temporarily defined as some numeric type to prevent errors at compile time.*/ /** * @brief The type of the state object for multi-part AEAD operations. @@ -344,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/crypto_values.h b/sys/include/psa_crypto/psa/crypto_values.h index c5e39cc88bd5..538a506d66ab 100644 --- a/sys/include/psa_crypto/psa/crypto_values.h +++ b/sys/include/psa_crypto/psa/crypto_values.h @@ -39,223 +39,6 @@ extern "C" { #include "psa/asymmetric_encryption/algorithm.h" #include "psa/asymmetric_signature/algorithm.h" -/** - * @brief Finite-field Diffie-Hellman groups defined for TLS in RFC 7919. - * - * @details This family includes groups with the following key sizes (in bits): 2048, 3072, 4096, - * 6144, 8192. An implementation can support all of these sizes or only a subset. - * - * Keys is this group can only be used with the @ref PSA_ALG_FFDH key agreement algorithm. - * - * These groups are defined by Negotiated Finite Field Diffie-Hellman Ephemeral Parameters - * for Transport Layer Security (TLS) [RFC7919](https://tools.ietf.org/html/rfc7919.html) - * Appendix A. - */ -#define PSA_DH_FAMILY_RFC7919 ((psa_dh_family_t)0x03) - -/** - * @brief Brainpool `P` random curves. - * - * @details This family comprises the following curves: - * - `brainpoolP160r1` : @c key_bits = 160 (Deprecated) - * - `brainpoolP192r1` : @c key_bits = 192 - * - `brainpoolP224r1` : @c key_bits = 224 - * - `brainpoolP256r1` : @c key_bits = 256 - * - `brainpoolP320r1` : @c key_bits = 320 - * - `brainpoolP384r1` : @c key_bits = 384 - * - `brainpoolP512r1` : @c key_bits = 512 - * - * They are defined in Elliptic Curve Cryptography (ECC) Brainpool Standard Curves and - * Curve Generation [RFC5639](https://tools.ietf.org/html/rfc5639.html). - * - * @warning The 160-bit curve `brainpoolP160r1` is weak and deprecated and is only recommended for - * use in legacy protocols. - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_DETERMINISTIC_ECDSA - * - @ref PSA_ALG_ECDSA - * - @ref PSA_ALG_ECDSA_ANY - * - @ref PSA_ALG_ECDH (key pair only) - */ -#define PSA_ECC_FAMILY_BRAINPOOL_P_R1 ((psa_ecc_family_t)0x30) - -/** - * @brief Curve used primarily in France and elsewhere in Europe. - * - * @details This family comprises one 256-bit curve: - * - `FRP256v1` : @c key_bits = 256 - * - * This is defined by Publication d'un paramétrage de courbe elliptique visant des - * applications de passeport électronique et de l'administration électronique française - * [FRP](https://www.ssi.gouv.fr/agence/rayonnement-scientifique/ - * publications-scientifiques/articles-ouvrages-actes). - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_DETERMINISTIC_ECDSA - * - @ref PSA_ALG_ECDSA - * - @ref PSA_ALG_ECDSA_ANY - * - @ref PSA_ALG_ECDH (key pair only) - */ -#define PSA_ECC_FAMILY_FRP ((psa_ecc_family_t)0x33) - -/** - * @brief Montgomery curves. - * - * @details This family comprises the following Montgomery curves: - * - `Curve25519` : @c key_bits = 255 - * - `Curve448` : @c key_bits = 448 - * - * `Curve25519` is defined in Curve25519: new Diffie-Hellman speed records - * [Curve25519](https://www.iacr.org/archive/pkc2006/39580209/39580209.pdf). - * `Curve448` is defined in Ed448-Goldilocks, a new elliptic curve - * [Curve448](https://eprint.iacr.org/2015/625.pdf). - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_ECDH (key pair only) - */ -#define PSA_ECC_FAMILY_MONTGOMERY ((psa_ecc_family_t)0x41) - -/** - * @brief SEC Koblitz curves over prime fields. - * - * @details This family comprises the following curves: - * - `secp192k1` : @c key_bits = 192 - * - `secp224k1` : @c key_bits = 225 - * - `secp256k1` : @c key_bits = 256 - * - * They are defined in SEC 2: Recommended Elliptic Curve Domain Parameters - * [SEC2](https://www.secg.org/sec2-v2.pdf). - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_DETERMINISTIC_ECDSA - * - @ref PSA_ALG_ECDSA - * - @ref PSA_ALG_ECDSA_ANY - * - @ref PSA_ALG_ECDH (key pair only) - */ -#define PSA_ECC_FAMILY_SECP_K1 ((psa_ecc_family_t)0x17) - -/** - * @brief SEC random curves over prime fields. - * - * @details This family comprises the following curves: - * - `secp192r1` : @c key_bits = 192 - * - `secp224r1` : @c key_bits = 224 - * - `secp256r1` : @c key_bits = 256 - * - `secp384r1` : @c key_bits = 384 - * - `secp521r1` : @c key_bits = 521 - * - * They are defined in [SEC2](https://www.secg.org/sec2-v2.pdf). - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_DETERMINISTIC_ECDSA - * - @ref PSA_ALG_ECDSA - * - @ref PSA_ALG_ECDSA_ANY - * - @ref PSA_ALG_ECDH (key pair only) - */ -#define PSA_ECC_FAMILY_SECP_R1 ((psa_ecc_family_t)0x12) - -/** - * @warning This family of curves is weak and deprecated. - * - * @details This family comprises the following curves: - * - `secp160r2` : @c key_bits = 160 (Deprecated) - * - * It is defined in the superseded SEC 2: Recommended Elliptic Curve Domain Parameters, - * Version 1.0 [SEC2v1](https://www.secg.org/SEC2-Ver-1.0.pdf). - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_DETERMINISTIC_ECDSA - * - @ref PSA_ALG_ECDSA - * - @ref PSA_ALG_ECDSA_ANY - * - @ref PSA_ALG_ECDH (key pair only) - */ -#define PSA_ECC_FAMILY_SECP_R2 ((psa_ecc_family_t)0x1b) - -/** - * @brief SEC Koblitz curves over binary fields. - * - * @details This family comprises the following curves: - * - `sect163k1` : @c key_bits = 163 (Deprecated) - * - `sect233k1` : @c key_bits = 233 - * - `sect239k1` : @c key_bits = 239 - * - `sect283k1` : @c key_bits = 283 - * - `sect409k1` : @c key_bits = 409 - * - `sect571k1` : @c key_bits = 571 - * - * They are defined in [SEC2](https://www.secg.org/sec2-v2.pdf). - * - * @warning The 163-bit curve `sect163k1` is weak and deprecated and is only recommended for use in - * legacy protocols. - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_DETERMINISTIC_ECDSA - * - @ref PSA_ALG_ECDSA - * - @ref PSA_ALG_ECDSA_ANY - * - @ref PSA_ALG_ECDH (key pair only) - */ -#define PSA_ECC_FAMILY_SECT_K1 ((psa_ecc_family_t)0x27) - -/** - * @brief SEC random curves over binary fields. - * - * @details This family comprises the following curves: - * - `sect163r1` : @c key_bits = 163 (Deprecated) - * - `sect233r1` : @c key_bits = 233 - * - `sect283r1` : @c key_bits = 283 - * - `sect409r1` : @c key_bits = 409 - * - `sect571r1` : @c key_bits = 571 - * - * They are defined in [SEC2](https://www.secg.org/sec2-v2.pdf). - * - * @warning The 163-bit curve `sect163r1` is weak and deprecated and is only recommended for use in - * legacy protocols. - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_DETERMINISTIC_ECDSA - * - @ref PSA_ALG_ECDSA - * - @ref PSA_ALG_ECDSA_ANY - * - @ref PSA_ALG_ECDH (key pair only) - */ -#define PSA_ECC_FAMILY_SECT_R1 ((psa_ecc_family_t)0x22) - -/** - * @brief SEC additional random curves over binary fields. - * - * @details This family comprises the following curves: - * - `sect163r2` : @c key_bits = 163 (Deprecated) - * - * It is defined in [SEC2](https://www.secg.org/sec2-v2.pdf). - * - * @warning The 163-bit curve `sect163r2` is weak and deprecated and is only recommended for use in - * legacy protocols. - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_DETERMINISTIC_ECDSA - * - @ref PSA_ALG_ECDSA - * - @ref PSA_ALG_ECDSA_ANY - * - @ref PSA_ALG_ECDH (key pair only) - */ -#define PSA_ECC_FAMILY_SECT_R2 ((psa_ecc_family_t)0x2b) - -/** - * @brief Twisted Edwards curves. - * - * @details This family comprises the following twisted Edwards curves: - * - `Edwards25519` : @c key_bits = 255. This curve is birationally equivalent to - * `Curve25519`. - * - `Edwards448` : @c key_bits = 448. This curve is birationally equivalent to `Curve448`. - * - * Edwards25519 is defined in Twisted Edwards curves - * [Ed25519](https://eprint.iacr.org/2008/013.pdf). Edwards448 is defined in - * Ed448-Goldilocks, a new elliptic curve [Curve448](https://eprint.iacr.org/2015/625.pdf). - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_PURE_EDDSA - * - @ref PSA_ALG_ED25519PH (Edwards25519 only) - * - @ref PSA_ALG_ED448PH (Edwards448 only) - */ -#define PSA_ECC_FAMILY_TWISTED_EDWARDS ((psa_ecc_family_t)0x42) - /** * @brief A context for key derivation. * @@ -340,944 +123,6 @@ extern "C" { #define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY \ /* implementation-defined value */ -/** - * @brief The null key identifier. - * - * @details The null key identifier is always invalid, except when used without in a call to - * @ref psa_destroy_key() which will return @ref PSA_SUCCESS. - */ -#define PSA_KEY_ID_NULL ((psa_key_id_t)0) - -/** - * @brief The maximum value for a key identifier chosen by the application. - */ -#define PSA_KEY_ID_USER_MAX ((psa_key_id_t)0x3fffffff) - -/** - * @brief The minimum value for a key identifier chosen by the application. - */ -#define PSA_KEY_ID_USER_MIN ((psa_key_id_t)0x00000001) - -/** - * @brief The maximum value for a key identifier chosen by the implementation. - */ -#define PSA_KEY_ID_VENDOR_MAX ((psa_key_id_t)0x7fffffff) - -/** - * @brief The minimum value for a key identifier chosen by the implementation. - */ -#define PSA_KEY_ID_VENDOR_MIN ((psa_key_id_t)0x40000000) - -/** - * @brief Construct a lifetime from a persistence level and a location. - * - * @param persistence The persistence level: a value of type @ref psa_key_persistence_t. - * @param location The location indicator: a value of type @ref psa_key_location_t. - * - * @return The constructed lifetime value. - */ -#define PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(persistence, location) \ - ((location) << 8 | (persistence)) - -/** - * @brief Extract the location indicator from a key lifetime. - * - * @param lifetime The lifetime value to query: a value of type @ref psa_key_lifetime_t. - */ -#define PSA_KEY_LIFETIME_GET_LOCATION(lifetime) \ - ((psa_key_location_t)((lifetime) >> 8)) - -/** - * @brief Extract the persistence level from a key lifetime. - * - * @param lifetime The lifetime value to query: a value of type @ref psa_key_lifetime_t. - */ -#define PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) \ - ((psa_key_persistence_t)((lifetime) & 0x000000ff)) - -/** - * @brief Whether a key lifetime indicates that the key is volatile. - * - * A volatile key is automatically destroyed by the implementation when the application - * instance terminates. In particular, a volatile key is automatically destroyed on a - * power reset of the device. - * - * A key that is not volatile is persistent. Persistent keys are preserved until the - * application explicitly destroys them or until an implementation-specific device - * management event occurs, for example, a factory reset. - * - * @param lifetime The lifetime value to query: a value of type @ref psa_key_lifetime_t. - * - * @return 1 if the key is volatile, otherwise 0. - */ -#define PSA_KEY_LIFETIME_IS_VOLATILE(lifetime) \ - (PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) == PSA_KEY_PERSISTENCE_VOLATILE) - -/** - * @brief The default lifetime for persistent keys. - * - * @details A persistent key remains in storage until it is explicitly destroyed or until the - * corresponding storage area is wiped. This specification does not define any mechanism - * to wipe a storage area. Implementations are permitted to provide their own mechanism, - * for example, to perform a factory reset, to prepare for device refurbishment, or to - * uninstall an application. - * - * This lifetime value is the default storage area for the calling application. - * Implementations can offer other storage areas designated by other lifetime values as - * implementation-specific extensions. - */ -#define PSA_KEY_LIFETIME_PERSISTENT ((psa_key_lifetime_t)0x00000001) - -/** - * @brief The default lifetime for volatile keys. - * - * @details A volatile key only exists as long as its identifier is not destroyed. The key material - * is guaranteed to be erased on a power reset. - * - * A key with this lifetime is typically stored in the RAM area of the PSA Crypto - * subsystem. However this is an implementation choice. If an implementation stores data - * about the key in a non-volatile memory, it must release all the resources associated - * with the key and erase the key material if the calling application terminates. - */ -#define PSA_KEY_LIFETIME_VOLATILE ((psa_key_lifetime_t)0x00000000) - -/** - * @brief The local storage area for persistent keys. - * - * @details This storage area is available on all systems that can store persistent keys without - * delegating the storage to a third-party cryptoprocessor. - * - * See @ref psa_key_location_t for more information. - */ -#define PSA_KEY_LOCATION_LOCAL_STORAGE ((psa_key_location_t)0x000000) - -/** - * @brief The default secure element storage area for persistent keys. - * - * @details This storage location is available on systems that have one or more secure elements - * that are able to store keys. - * - * Vendor-defined locations must be provided by the system for storing keys in additional - * secure elements. - * - * See @ref psa_key_location_t for more information. - */ -#define PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT ((psa_key_location_t)0x000001) - -/** - * @brief Mark vendor defined key locations - */ -#define PSA_KEY_LOCATION_VENDOR_FLAG ((psa_key_location_t)0x800000) - -/** - * @brief Minimum location value for secure elements - */ -#define PSA_KEY_LOCATION_SE_MIN (PSA_KEY_LOCATION_VENDOR_FLAG) - -/** - * @brief Maximum location value for secure elements - */ -#define PSA_KEY_LOCATION_SE_MAX ((psa_key_location_t)0x8000ff) - -/** - * @brief The default persistence level for persistent keys. - * - * @details See @ref psa_key_persistence_t for more information. - */ -#define PSA_KEY_PERSISTENCE_DEFAULT ((psa_key_persistence_t)0x01) - -/** - * @brief A persistence level indicating that a key is never destroyed. - * - * @details See @ref psa_key_persistence_t for more information. - */ -#define PSA_KEY_PERSISTENCE_READ_ONLY ((psa_key_persistence_t)0xff) - -/** - * @brief The persistence level of volatile keys. - * - * @details See @ref psa_key_persistence_t for more information. - */ -#define PSA_KEY_PERSISTENCE_VOLATILE ((psa_key_persistence_t)0x00) - -/** - * @brief Vendor-defined key type flag. - * - * @details Key types defined by this standard will never have the - * @ref PSA_KEY_TYPE_VENDOR_FLAG bit set. Vendors who define additional key types - * must use an encoding with the @ref PSA_KEY_TYPE_VENDOR_FLAG bit set and should - * respect the bitwise structure used by standard encodings whenever practical. - */ -#define PSA_KEY_TYPE_VENDOR_FLAG ((psa_key_type_t)0x8000) - -/** - * @brief Mask for key type categories - */ -#define PSA_KEY_TYPE_CATEGORY_MASK ((psa_key_type_t)0x7000) - -/** - * @brief Raw key data type - */ -#define PSA_KEY_TYPE_CATEGORY_RAW ((psa_key_type_t)0x1000) - -/** - * @brief Symmetric key type - */ -#define PSA_KEY_TYPE_CATEGORY_SYMMETRIC ((psa_key_type_t)0x2000) - -/** - * @brief Asymmetric public key type - */ -#define PSA_KEY_TYPE_CATEGORY_PUBLIC_KEY ((psa_key_type_t)0x4000) - -/** - * @brief Asymmetric key pair type - */ -#define PSA_KEY_TYPE_CATEGORY_KEY_PAIR ((psa_key_type_t)0x7000) - -/** - * @brief Asymmetric key pair flag - */ -#define PSA_KEY_TYPE_CATEGORY_FLAG_PAIR ((psa_key_type_t)0x3000) - -/** - * @brief Key for a cipher, AEAD or MAC algorithm based on the AES block cipher. - * - * @details The size of the key is related to the AES algorithm variant. For algorithms except the - * XTS block cipher mode, the following key sizes are used: - * - AES-128 uses a 16-byte key : @c key_bits = 128 - * - AES-192 uses a 24-byte key : @c key_bits = 192 - * - AES-256 uses a 32-byte key : @c key_bits = 256 - * - * For the XTS block cipher mode (@ref PSA_ALG_XTS), the following key sizes are used: - * - AES-128-XTS uses two 16-byte keys : @c key_bits = 256 - * - AES-192-XTS uses two 24-byte keys : @c key_bits = 384 - * - AES-256-XTS uses two 32-byte keys : @c key_bits = 512 - * - * The AES block cipher is defined in FIPS Publication 197: Advanced Encryption Standard - * (AES) [FIPS197](https://doi.org/10.6028/NIST.FIPS.197). - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_CBC_MAC - * - @ref PSA_ALG_CMAC - * - @ref PSA_ALG_CTR - * - @ref PSA_ALG_CFB - * - @ref PSA_ALG_OFB - * - @ref PSA_ALG_XTS - * - @ref PSA_ALG_CBC_NO_PADDING - * - @ref PSA_ALG_CBC_PKCS7 - * - @ref PSA_ALG_ECB_NO_PADDING - * - @ref PSA_ALG_CCM - * - @ref PSA_ALG_GCM - */ -#define PSA_KEY_TYPE_AES ((psa_key_type_t)0x2400) - -/** - * @brief Key for the ARC4 stream cipher. - * - * @warning The ARC4 cipher is weak and deprecated and is only recommended for use in legacy - * protocols. - * - * @details The ARC4 cipher supports key sizes between 40 and 2048 bits, that are multiples of 8. - * (5 to 256 bytes) - * - * Use algorithm @ref PSA_ALG_STREAM_CIPHER to use this key with the ARC4 cipher. - */ -#define PSA_KEY_TYPE_ARC4 ((psa_key_type_t)0x2002) - -/** - * @brief Key for a cipher, AEAD or MAC algorithm based on the ARIA block cipher. - * - * The size of the key is related to the ARIA algorithm variant. For algorithms except the - * XTS block cipher mode, the following key sizes are used: - * - ARIA-128 uses a 16-byte key : @c key_bits = 128 - * - ARIA-192 uses a 24-byte key : @c key_bits = 192 - * - ARIA-256 uses a 32-byte key : @c key_bits = 256 - * - * For the XTS block cipher mode (@ref PSA_ALG_XTS), the following key sizes are used: - * - ARIA-128-XTS uses two 16-byte keys : @c key_bits = 256 - * - ARIA-192-XTS uses two 24-byte keys : @c key_bits = 384 - * - ARIA-256-XTS uses two 32-byte keys : @c key_bits = 512 - * - * The ARIA block cipher is defined in A Description of the ARIA Encryption Algorithm - * [RFC5794](https://datatracker.ietf.org/doc/html/rfc5794). - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_CBC_MAC - * - @ref PSA_ALG_CMAC - * - @ref PSA_ALG_CTR - * - @ref PSA_ALG_CFB - * - @ref PSA_ALG_OFB - * - @ref PSA_ALG_XTS - * - @ref PSA_ALG_CBC_NO_PADDING - * - @ref PSA_ALG_CBC_PKCS7 - * - @ref PSA_ALG_ECB_NO_PADDING - * - @ref PSA_ALG_CCM - * - @ref PSA_ALG_GCM - */ -#define PSA_KEY_TYPE_ARIA ((psa_key_type_t)0x2406) - -/** - * @brief Key for a cipher, AEAD or MAC algorithm based on the Camellia block cipher. - * - * @details The size of the key is related to the Camellia algorithm variant. For algorithms except - * the XTS block cipher mode, the following key sizes are used: - * - Camellia-128 uses a 16-byte key : @c key_bits = 128 - * - Camellia-192 uses a 24-byte key : @c key_bits = 192 - * - Camellia-256 uses a 32-byte key : @c key_bits = 256 - * - * For the XTS block cipher mode (@ref PSA_ALG_XTS), the following key sizes are used: - * - Camellia-128-XTS uses two 16-byte keys : @c key_bits = 256 - * - Camellia-192-XTS uses two 24-byte keys : @c key_bits = 384 - * - Camellia-256-XTS uses two 32-byte keys : @c key_bits = 512 - * - * The Camellia block cipher is defined in Specification of Camellia — a 128-bit Block - * Cipher [NTT-CAM](https://info.isl.ntt.co.jp/crypt/eng/camellia/specifications) and - * also described in A Description of the Camellia Encryption - * Algorithm [RFC3713](https://tools.ietf.org/html/rfc3713). - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_CBC_MAC - * - @ref PSA_ALG_CMAC - * - @ref PSA_ALG_CTR - * - @ref PSA_ALG_CFB - * - @ref PSA_ALG_OFB - * - @ref PSA_ALG_XTS - * - @ref PSA_ALG_CBC_NO_PADDING - * - @ref PSA_ALG_CBC_PKCS7 - * - @ref PSA_ALG_ECB_NO_PADDING - * - @ref PSA_ALG_CCM - * - @ref PSA_ALG_GCM - */ -#define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x2403) - -/** - * @brief Key for the ChaCha20 stream cipher or the ChaCha20-Poly1305 AEAD algorithm. - * - * @details The ChaCha20 key size is 256 bits (32 bytes). - * - Use algorithm @ref PSA_ALG_STREAM_CIPHER to use this key with the ChaCha20 cipher for - * unauthenticated encryption. See @ref PSA_ALG_STREAM_CIPHER for details of this - * algorithm. - * - Use algorithm @ref PSA_ALG_CHACHA20_POLY1305 to use this key with the ChaCha20 cipher - * and Poly1305 authenticator for AEAD. See @ref PSA_ALG_CHACHA20_POLY1305 for details - * of this algorithm. - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_STREAM_CIPHER - * - @ref PSA_ALG_CHACHA20_POLY1305 - */ -#define PSA_KEY_TYPE_CHACHA20 ((psa_key_type_t)0x2004) - -/** - * @brief A secret for key derivation. - * - * @details This key type is for high-entropy secrets only. For low-entropy secrets, - * @ref PSA_KEY_TYPE_PASSWORD should be used instead. - * - * These keys can be used in the @ref PSA_KEY_DERIVATION_INPUT_SECRET or - * @ref PSA_KEY_DERIVATION_INPUT_PASSWORD input step of key derivation algorithms. - * - * The key policy determines which key derivation algorithm the key can be used for. - * - * The bit size of a secret for key derivation must be a non-zero multiple of 8. The - * maximum size of a secret for key derivation is implementation defined. - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_HKDF (secret input) - * - @ref PSA_ALG_TLS12_PRF (secret input) - * - @ref PSA_ALG_TLS12_PSK_TO_MS (secret input) - */ -#define PSA_KEY_TYPE_DERIVE ((psa_key_type_t)0x1200) - -/** - * @brief Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES). - * - * @details The size of the key determines which DES algorithm is used: - * - Single DES uses an 8-byte key : @c key_bits = 64 - * - 2-key 3DES uses a 16-byte key : @c key_bits = 128 - * - 3-key 3DES uses a 24-byte key : @c key_bits = 192 - * - * @warning Single DES and 2-key 3DES are weak and strongly deprecated and are only recommended for - * decrypting legacy data. - * 3-key 3DES is weak and deprecated and is only recommended for use in legacy protocols. - * - * The DES and 3DES block ciphers are defined in NIST Special Publication 800-67: - * Recommendation for the Triple Data Encryption Algorithm (TDEA) Block Cipher - * [SP800-67](https://doi.org/10.6028/NIST.SP.800-67r2). - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_CBC_MAC - * - @ref PSA_ALG_CMAC - * - @ref PSA_ALG_CTR - * - @ref PSA_ALG_CFB - * - @ref PSA_ALG_OFB - * - @ref PSA_ALG_XTS - * - @ref PSA_ALG_CBC_NO_PADDING - * - @ref PSA_ALG_CBC_PKCS7 - * - @ref PSA_ALG_ECB_NO_PADDING - */ -#define PSA_KEY_TYPE_DES ((psa_key_type_t)0x2301) - -/** - * @brief Extract the group family from a Diffie-Hellman key type. - * - * @param type A Diffie-Hellman key type: a value of type @ref psa_key_type_t such that - * @ref PSA_KEY_TYPE_IS_DH(@p type) is true. - * - * @return The Diffie-Hellman group family id, if type is a supported Diffie-Hellman key. - * Unspecified if type is not a supported Diffie-Hellman key. - */ -#define PSA_KEY_TYPE_DH_GET_FAMILY(type) \ - ((psa_dh_family_t)((type) & 0x00ff)) - -/** - * @brief Finite-field Diffie-Hellman key pair: both the private key and public key. - * - * @details @b Compatible @b algorithms - * - @ref PSA_ALG_FFDH - * - * @param group A value of type @ref psa_dh_family_t that identifies the Diffie-Hellman group - * family to be used. - */ -#define PSA_KEY_TYPE_DH_KEY_PAIR(group) \ - ((psa_key_type_t)(0x7200 | (group))) - -/** - * @brief Finite-field Diffie-Hellman public key. - * - * @details @b Compatible @b algorithms - * None. Finite-field Diffie-Hellman public keys are exported to use in a key agreement - * algorithm, and the peer key is provided to the @ref PSA_ALG_FFDH key agreement - * algorithm as a buffer of key data. - * - * @param group A value of type @ref psa_dh_family_t that identifies the Diffie-Hellman group - * family to be used. - */ -#define PSA_KEY_TYPE_DH_PUBLIC_KEY(group) \ - ((psa_key_type_t)(0x4200 | (group))) - -/** - * @brief Extract the curve family from an elliptic curve key type. - * - * @param type An elliptic curve key type: a value of type @ref psa_key_type_t such that - * @ref PSA_KEY_TYPE_IS_ECC(@p type) is true. - * - * @return The elliptic curve family id, if type is a supported elliptic curve key. - * Unspecified if type is not a supported elliptic curve key. - */ -#define PSA_KEY_TYPE_ECC_GET_FAMILY(type) \ - ((psa_ecc_family_t)((type) & 0x00ff)) - -/** - * @brief Base value for ECC public keys - */ -#define PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE ((psa_key_type_t)0x4100) - -/** - * @brief Base value for ECC key pairs - */ -#define PSA_KEY_TYPE_ECC_KEY_PAIR_BASE ((psa_key_type_t)0x7100) - -/** - * @brief Mask for ECC curves - */ -#define PSA_KEY_TYPE_ECC_CURVE_MASK ((psa_key_type_t)0x00ff) - -/** - * @brief Elliptic curve key pair: both the private and public key. - * - * @details The size of an elliptic curve key is the bit size associated with the curve, that is, - * the bit size of q for a curve over a field Fq. See the documentation of each Elliptic - * curve family for details. - * - * @b Compatible @b algorithms - * - Elliptic curve key pairs can be used in Asymmetric signature and Key agreement - * algorithms. - * - The set of compatible algorithms depends on the Elliptic curve key family. See the - * Elliptic curve family for details. - * - * @param curve A value of type @ref psa_ecc_family_t that identifies the ECC curve to be used. - */ -#define PSA_KEY_TYPE_ECC_KEY_PAIR(curve) \ - (PSA_KEY_TYPE_ECC_KEY_PAIR_BASE | (curve)) - -/** - * @brief Elliptic curve public key. - * - * @details The size of an elliptic curve public key is the same as the corresponding private key. - * See @ref PSA_KEY_TYPE_ECC_KEY_PAIR() and the documentation of each Elliptic curve - * family for details. - * - * @b Compatible @b algorithms - * Elliptic curve public keys can be used for verification in asymmetric signature - * algorithms. - * The set of compatible algorithms depends on the elliptic curve key family. See each - * elliptic curve family for details. - * - * @param curve A value of type @ref psa_ecc_family_t that identifies the ECC curve to be used. - */ -#define PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) \ - (PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE | (curve)) - -/** - * @brief Elliptic curve public key. - */ -#define PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) \ - (PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE | (curve)) - -/** - * @brief Whether a key type is an elliptic curve key, either a key pair or a public key. - * - * @param type A key type: a value of type @ref psa_key_type_t. - */ -#define PSA_KEY_TYPE_IS_ECC(type) \ - ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff00) == 0x4100) - -/** - * @brief Whether a key type is an elliptic curve key pair. - * - * @param type A key type: a value of type @ref psa_key_type_t. - */ -#define PSA_KEY_TYPE_IS_ECC_KEY_PAIR(type) \ - (((type) & 0xff00) == 0x7100) - -/** - * @brief Whether a key type is an elliptic curve public key. - * - * @param type A key type: a value of type @ref psa_key_type_t. - */ -#define PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(type) \ - (((type) & 0xff00) == 0x4100) - -/** - * @brief The public key type corresponding to a key pair type. - * You may also pass a key pair type as type, it will be left unchanged. - * - * @param type A public key type or key pair type. - * - * @return The corresponding public key type. - * If type is not a public key or a key pair, the return value is undefined. - */ -#define PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) \ - ((psa_key_type_t)((type) & ~0x3000)) - -/** - * @brief HMAC key. - * - * @details The key policy determines which underlying hash algorithm the key can be used for. - * - * The bit size of an HMAC key must be a non-zero multiple of 8. An HMAC key is typically - * the same size as the output of the underlying hash algorithm. An HMAC key that is - * longer than the block size of the underlying hash algorithm will be hashed before use. - * - * When an HMAC key is created that is longer than the block size, it is implementation - * defined whether the implementation stores the original HMAC key, or the hash of the - * HMAC key. If the hash of the key is stored, the key size reported by - * @ref psa_get_key_attributes() will be the size of the hashed key. - * - * @note @ref PSA_HASH_LENGTH(@p alg) provides the output size of hash algorithm @c alg, - * in bytes. - * @ref PSA_HASH_BLOCK_LENGTH(@p alg) provides the block size of hash algorithm - * @c alg, in bytes. - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_HMAC - */ -#define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x1100) - -/** - * @brief Whether a key type is asymmetric: either a key pair or a public key. - * - * @param type A key type: a value of type @ref psa_key_type_t. - */ -#define PSA_KEY_TYPE_IS_ASYMMETRIC(type) \ - (((type) & 0x4000) == 0x4000) - -/** - * @brief Whether a key type is a Diffie-Hellman key, either a key pair or a public key. - * - * @param type A key type: a value of type @ref psa_key_type_t. - */ -#define PSA_KEY_TYPE_IS_DH(type) \ - ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff00) == 0x4200) - -/** - * @brief Whether a key type is a Diffie-Hellman key pair. - * - * @param type A key type: a value of type @ref psa_key_type_t. - */ -#define PSA_KEY_TYPE_IS_DH_KEY_PAIR(type) \ - (((type) & 0xff00) == 0x7200) - -/** - * @brief Whether a key type is a Diffie-Hellman public key. - * - * @param type A key type: a value of type @ref psa_key_type_t. - */ -#define PSA_KEY_TYPE_IS_DH_PUBLIC_KEY(type) \ - (((type) & 0xff00) == 0x4200) - -/** - * @brief Whether a key type is a key pair containing a private part and a public part. - * - * @param type A key type: a value of type @ref psa_key_type_t. - */ -#define PSA_KEY_TYPE_IS_KEY_PAIR(type) \ - (((type) & 0x7000) == 0x7000) - -/** - * @brief Whether a key type is the public part of a key pair. - * - * @param type A key type: a value of type @ref psa_key_type_t. - */ - -#define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) \ - (((type) & 0x7000) == 0x4000) - -/** - * @brief Whether a key type is an RSA key. This includes both key pairs and public keys. - * - * @param type A key type: a value of type @ref psa_key_type_t. - */ -#define PSA_KEY_TYPE_IS_RSA(type) \ - (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == 0x4001) - -/** - * @brief Whether a key type is an unstructured array of bytes. - * This encompasses both symmetric keys and non-key data. - * - * @param type A key type: a value of type @ref psa_key_type_t. - */ -#define PSA_KEY_TYPE_IS_UNSTRUCTURED(type) \ - (((type) & 0x7000) == 0x1000 || ((type) & 0x7000) == 0x2000) - -/** - * @brief The key pair type corresponding to a public key type. - * - * @details If type is a key pair type, it will be left unchanged. - * - * @param type A public key type or key pair type. - * - * @return The corresponding key pair type. If type is not a public key or a key pair, the return - * value is undefined. - */ -#define PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY(type) \ - ((psa_key_type_t)((type) | 0x3000)) - -/** - * @brief An invalid key type value. - * - * @details Zero is not the encoding of any key type. - */ -#define PSA_KEY_TYPE_NONE ((psa_key_type_t)0x0000) - -/** - * @brief A low-entropy secret for password hashing or key derivation. - * - * @details This key type is suitable for passwords and passphrases which are typically intended to - * be memorizable by humans, and have a low entropy relative to their size. It can be used - * for randomly generated or derived keys with maximum or near-maximum entropy, but - * @ref PSA_KEY_TYPE_DERIVE is more suitable for such keys. It is not suitable for - * passwords with extremely low entropy, such as numerical PINs. - * - * These keys can be used in the @ref PSA_KEY_DERIVATION_INPUT_PASSWORD input step of key - * derivation algorithms. Algorithms that accept such an input were designed to accept - * low-entropy secret and are known as password hashing or key stretching algorithms. - * - * These keys cannot be used in the @ref PSA_KEY_DERIVATION_INPUT_SECRET input step of key - * derivation algorithms, as the algorithms expect such an input to have high entropy. - * - * The key policy determines which key derivation algorithm the key can be used for, among - * the permissible subset defined above. - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_PBKDF2_HMAC() (password input) - * - @ref PSA_ALG_PBKDF2_AES_CMAC_PRF_128 (password input) - */ -#define PSA_KEY_TYPE_PASSWORD ((psa_key_type_t)0x1203) - -/** - * @brief A secret value that can be used to verify a password hash. - * - * @details The key policy determines which key derivation algorithm the key can be used for, among - * the same permissible subset as for @ref PSA_KEY_TYPE_PASSWORD. - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_PBKDF2_HMAC() (key output and verification) - * - @ref PSA_ALG_PBKDF2_AES_CMAC_PRF_128 (key output and verification) - */ -#define PSA_KEY_TYPE_PASSWORD_HASH ((psa_key_type_t)0x1205) - -/** - * @brief A secret value that can be used when computing a password hash. - * - * @details The key policy determines which key derivation algorithm the key can be used for, among - * the subset of algorithms that can use pepper. - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_PBKDF2_HMAC() (salt input) - * - @ref PSA_ALG_PBKDF2_AES_CMAC_PRF_128 (salt input) - */ -#define PSA_KEY_TYPE_PEPPER ((psa_key_type_t)0x1206) - -/** - * @brief Raw data. - * - * @details A “key” of this type cannot be used for any cryptographic operation. Applications can - * use this type to store arbitrary data in the keystore. - * - * The bit size of a raw key must be a non-zero multiple of 8. The maximum size of a raw - * key is implementation defined. - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_HKDF (non-secret inputs) - * - @ref PSA_ALG_TLS12_PRF (non-secret inputs) - * - @ref PSA_ALG_TLS12_PSK_TO_MS (non-secret inputs) - */ -#define PSA_KEY_TYPE_RAW_DATA ((psa_key_type_t)0x1001) - -/** - * @brief RSA key pair: both the private and public key. - * - * @details The size of an RSA key is the bit size of the modulus. - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_RSA_OAEP - * - @ref PSA_ALG_RSA_PKCS1V15_CRYPT - * - @ref PSA_ALG_RSA_PKCS1V15_SIGN - * - @ref PSA_ALG_RSA_PKCS1V15_SIGN_RAW - * - @ref PSA_ALG_RSA_PSS - * - @ref PSA_ALG_RSA_PSS_ANY_SALT - */ -#define PSA_KEY_TYPE_RSA_KEY_PAIR ((psa_key_type_t)0x7001) - -/** - * @brief RSA public key. - * - * @details The size of an RSA key is the bit size of the modulus. - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_RSA_OAEP (encryption only) - * - @ref PSA_ALG_RSA_PKCS1V15_CRYPT (encryption only) - * - @ref PSA_ALG_RSA_PKCS1V15_SIGN (signature verification only) - * - @ref PSA_ALG_RSA_PKCS1V15_SIGN_RAW (signature verification only) - * - @ref PSA_ALG_RSA_PSS (signature verification only) - * - @ref PSA_ALG_RSA_PSS_ANY_SALT (signature verification only) - */ -#define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x4001) - -/** - * @brief Key for a cipher, AEAD or MAC algorithm based on the SM4 block cipher. - * - * @details For algorithms except the XTS block cipher mode, the SM4 key size is 128 bits - * (16 bytes). - * - * For the XTS block cipher mode (@ref PSA_ALG_XTS), the SM4 key size is 256 bits - * (two 16-byte keys). - * - * The SM4 block cipher is defined in GM/T 0002-2012: SM4 block cipher algorithm - * [CSTC0002](http://www.gmbz.org.cn/main/viewfile/20180108015408199368.html) - * (English version [CSTC0002/E](http://www.gmbz.org.cn/main/postDetail.html? - * id=20180404044052)). - * - * @b Compatible @b algorithms - * - @ref PSA_ALG_CBC_MAC - * - @ref PSA_ALG_CMAC - * - @ref PSA_ALG_CTR - * - @ref PSA_ALG_CFB - * - @ref PSA_ALG_OFB - * - @ref PSA_ALG_XTS - * - @ref PSA_ALG_CBC_NO_PADDING - * - @ref PSA_ALG_CBC_PKCS7 - * - @ref PSA_ALG_ECB_NO_PADDING - * - @ref PSA_ALG_CCM - * - @ref PSA_ALG_GCM - */ -#define PSA_KEY_TYPE_SM4 ((psa_key_type_t)0x2405) - -/** - * @brief Permission for the implementation to cache the key. - * - * @details This flag allows the implementation to make additional copies of the key material that - * are not in storage and not for the purpose of an ongoing operation. Applications can - * use it as a hint to keep the key around for repeated access. - * - * An application can request that cached key material is removed from memory by calling - * @ref psa_purge_key(). - * - * The presence of this usage flag when creating a key is a hint: - * - An implementation is not required to cache keys that have this usage flag. - * - An implementation must not report an error if it does not cache keys. - * - * If this usage flag is not present, the implementation must ensure key material is - * removed from memory as soon as it is not required for an operation or for maintenance - * of a volatile key. - * - * This flag must be preserved when reading back the attributes for all keys, regardless - * of key type or implementation behavior. - */ -#define PSA_KEY_USAGE_CACHE ((psa_key_usage_t)0x00000004) - -/** - * @brief Permission to copy the key. - * - * @details This flag allows the use of @ref psa_copy_key() to make a copy of the key with the same - * policy or a more restrictive policy. - * - * For lifetimes for which the key is located in a secure element which enforce the - * non-exportability of keys, copying a key outside the secure element also requires the - * usage flag @ref PSA_KEY_USAGE_EXPORT. Copying the key inside the secure element is - * permitted with just @ref PSA_KEY_USAGE_COPY if the secure element supports it. For keys - * with the lifetime @ref PSA_KEY_LIFETIME_VOLATILE or @ref PSA_KEY_LIFETIME_PERSISTENT, - * the usage flag @ref PSA_KEY_USAGE_COPY is sufficient to permit the copy. - */ -#define PSA_KEY_USAGE_COPY ((psa_key_usage_t)0x00000002) - -/** - * @brief Permission to decrypt a message with the key. - * - * @details This flag allows the key to be used for a symmetric decryption operation, for an AEAD - * decryption-and-verification operation, or for an asymmetric decryption operation, if - * otherwise permitted by the key’s type and policy. The flag must be present on keys used - * with the following APIs: - * - @ref psa_cipher_decrypt() - * - @ref psa_cipher_decrypt_setup() - * - @ref psa_aead_decrypt() - * - @ref psa_aead_decrypt_setup() - * - @ref psa_asymmetric_decrypt() - * - * For a key pair, this concerns the private key. - */ -#define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200) - -/** - * @brief Permission to derive other keys or produce a password hash from this key. - * - * @details This flag allows the key to be used for a key derivation operation or for a key - * agreement operation, if otherwise permitted by the key’s type and policy. - * - * This flag must be present on keys used with the following APIs: - * - @ref psa_key_derivation_key_agreement() - * - @ref psa_raw_key_agreement() - * - * If this flag is present on all keys used in calls to - * @ref psa_key_derivation_input_key() for a key derivation operation, then it permits - * calling @ref psa_key_derivation_output_bytes() or @ref psa_key_derivation_output_key() - * at the end of the operation. - */ -#define PSA_KEY_USAGE_DERIVE ((psa_key_usage_t)0x00004000) - -/** - * @brief Permission to encrypt a message with the key. - * - * @details This flag allows the key to be used for a symmetric encryption operation, for an AEAD - * encryption-and-authentication operation, or for an asymmetric encryption operation, if - * otherwise permitted by the key’s type and policy. The flag must be present on keys used - * with the following APIs: - * - @ref psa_cipher_encrypt() - * - @ref psa_cipher_encrypt_setup() - * - @ref psa_aead_encrypt() - * - @ref psa_aead_encrypt_setup() - * - @ref psa_asymmetric_encrypt() - * - * For a key pair, this concerns the public key. - */ -#define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t)0x00000100) - -/** - * @brief Permission to export the key. - * - * @details This flag allows the use of @ref psa_export_key() to export a key from the - * cryptoprocessor. A public key or the public part of a key pair can always be exported - * regardless of the value of this permission flag. - * - * This flag can also be required to copy a key using @ref psa_copy_key() outside of a - * secure element. See also @ref PSA_KEY_USAGE_COPY. - * - * If a key does not have export permission, implementations must not allow the key to be - * exported in plain form from the cryptoprocessor, whether through @ref psa_export_key() - * or through a proprietary interface. The key might still be exportable in a wrapped - * form, i.e. in a form where it is encrypted by another key. - */ -#define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t)0x00000001) - -/** - * @brief Permission to sign a message hash with the key. - * - * @details This flag allows the key to be used to sign a message hash as part of an asymmetric - * signature operation, if otherwise permitted by the key’s type and policy. The flag must - * be present on keys used when calling @ref psa_sign_hash(). - * - * This flag automatically sets @ref PSA_KEY_USAGE_SIGN_MESSAGE : if an application sets - * the flag @ref PSA_KEY_USAGE_SIGN_HASH when creating a key, then the key always has the - * permissions conveyed by @ref PSA_KEY_USAGE_SIGN_MESSAGE, and the flag - * @ref PSA_KEY_USAGE_SIGN_MESSAGE will also be present when the application queries the - * usage flags of the key. - * - * For a key pair, this concerns the private key. - */ -#define PSA_KEY_USAGE_SIGN_HASH ((psa_key_usage_t)0x00001000) - -/** - * @brief Permission to sign a message with the key. - * - * @details This flag allows the key to be used for a MAC calculation operation or for an - * asymmetric message signature operation, if otherwise permitted by the key’s type and - * policy. The flag must be present on keys used with the following APIs: - * - @ref psa_mac_compute() - * - @ref psa_mac_sign_setup() - * - @ref psa_sign_message() - * - * For a key pair, this concerns the private key. - */ -#define PSA_KEY_USAGE_SIGN_MESSAGE ((psa_key_usage_t)0x00000400) - -/** - * @brief Permission to verify the result of a key derivation, including password hashing. - * - * @details This flag allows the key to be used in a key derivation operation, if otherwise - * permitted by the key’s type and policy. - * - * This flag must be present on keys used with @ref psa_key_derivation_verify_key(). - * - * If this flag is present on all keys used in calls to - * @ref psa_key_derivation_input_key() for a key derivation operation, then it permits - * calling @ref psa_key_derivation_verify_bytes() or @ref psa_key_derivation_verify_key() - * at the end of the operation. - */ -#define PSA_KEY_USAGE_VERIFY_DERIVATION ((psa_key_usage_t)0x00008000) - -/** - * @brief Permission to verify a message hash with the key. - * - * @details This flag allows the key to be used to verify a message hash as part of an asymmetric - * signature verification operation, if otherwise permitted by the key’s type and policy. - * The flag must be present on keys used when calling @ref psa_verify_hash(). - * - * This flag automatically sets @ref PSA_KEY_USAGE_VERIFY_MESSAGE : if an application sets - * the flag @ref PSA_KEY_USAGE_VERIFY_HASH when creating a key, then the key always has - * the permissions conveyed by @ref PSA_KEY_USAGE_VERIFY_MESSAGE, and the flag - * @ref PSA_KEY_USAGE_VERIFY_MESSAGE will also be present when the application queries the - * usage flags of the key. - * - * For a key pair, this concerns the public key. - */ -#define PSA_KEY_USAGE_VERIFY_HASH ((psa_key_usage_t)0x00002000) - -/** - * @brief Permission to verify a message signature with the key. - * - * @details This flag allows the key to be used for a MAC verification operation or for an - * asymmetric message signature verification operation, if otherwise permitted by the - * key’s type and policy. The flag must be present on keys used with the following APIs: - * - @ref psa_mac_verify() - * - @ref psa_mac_verify_setup() - * - @ref psa_verify_message() - * - * For a key pair, this concerns the public key. - */ -#define PSA_KEY_USAGE_VERIFY_MESSAGE ((psa_key_usage_t)0x00000800) - /** * @brief Sufficient output buffer size for @ref psa_raw_key_agreement(), for any of the * supported key types and key agreement algorithms. 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..70f5c33b3a89 --- /dev/null +++ b/sys/include/psa_crypto/psa/key/attributes.h @@ -0,0 +1,186 @@ +/* + * 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" + +/** + * @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; +} + +#ifdef __cplusplus +} +#endif + +#endif /* PSA_CRYPTO_PSA_KEY_ATTRIBUTES_H */ +/** @} */ diff --git a/sys/include/psa_crypto/psa/key/bits.h b/sys/include/psa_crypto/psa/key/bits.h new file mode 100644 index 000000000000..80e90dd29901 --- /dev/null +++ b/sys/include/psa_crypto/psa/key/bits.h @@ -0,0 +1,41 @@ +/* + * 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/bits.h + * @brief Key size definitions for the PSA Crypto API + * + * @author Armin Wolf + * @author Lena Boeckmann + * + */ + +#ifndef PSA_CRYPTO_PSA_KEY_BITS_H +#define PSA_CRYPTO_PSA_KEY_BITS_H + +#ifdef __cplusplus +extern "C" { +#endif + +#include + +/** + * @brief Public interfaces use @c size_t, but internally we use a smaller type. + */ +typedef uint16_t psa_key_bits_t; + +#ifdef __cplusplus +} +#endif + +#endif /* PSA_CRYPTO_PSA_KEY_BITS_H */ +/** @} */ diff --git a/sys/include/psa_crypto/psa/key/id.h b/sys/include/psa_crypto/psa/key/id.h new file mode 100644 index 000000000000..a3df0ea159f9 --- /dev/null +++ b/sys/include/psa_crypto/psa/key/id.h @@ -0,0 +1,72 @@ +/* + * 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/id.h + * @brief Key ID definitions for the PSA Crypto API + * + * @author Armin Wolf + * @author Lena Boeckmann + * + */ + +#ifndef PSA_CRYPTO_PSA_KEY_ID_H +#define PSA_CRYPTO_PSA_KEY_ID_H + +#ifdef __cplusplus +extern "C" { +#endif + +#include + +/** + * @brief Key identifier. + * + * @details A key identifier can be a permanent name for a persistent key, or a transient reference + * to volatile key. + */ +typedef uint32_t psa_key_id_t; + +/** + * @brief The null key identifier. + * + * @details The null key identifier is always invalid, except when used without in a call to + * @ref psa_destroy_key() which will return @ref PSA_SUCCESS. + */ +#define PSA_KEY_ID_NULL ((psa_key_id_t)0) + +/** + * @brief The minimum value for a key identifier chosen by the application. + */ +#define PSA_KEY_ID_USER_MIN ((psa_key_id_t)0x00000001) + +/** + * @brief The maximum value for a key identifier chosen by the application. + */ +#define PSA_KEY_ID_USER_MAX ((psa_key_id_t)0x3fffffff) + +/** + * @brief The minimum value for a key identifier chosen by the implementation. + */ +#define PSA_KEY_ID_VENDOR_MIN ((psa_key_id_t)0x40000000) + +/** + * @brief The maximum value for a key identifier chosen by the implementation. + */ +#define PSA_KEY_ID_VENDOR_MAX ((psa_key_id_t)0x7fffffff) + +#ifdef __cplusplus +} +#endif + +#endif /* PSA_CRYPTO_PSA_KEY_ID_H */ +/** @} */ diff --git a/sys/include/psa_crypto/psa/key/lifetime.h b/sys/include/psa_crypto/psa/key/lifetime.h new file mode 100644 index 000000000000..b5ea672f996f --- /dev/null +++ b/sys/include/psa_crypto/psa/key/lifetime.h @@ -0,0 +1,282 @@ +/* + * 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/lifetime.h + * @brief Key ilfetime definitions for the PSA Crypto API + * + * @author Armin Wolf + * @author Lena Boeckmann + * + */ + +#ifndef PSA_CRYPTO_PSA_KEY_LIFETIME_H +#define PSA_CRYPTO_PSA_KEY_LIFETIME_H + +#ifdef __cplusplus +extern "C" { +#endif + +#include + +/** + * @brief Encoding of key lifetimes. + * + * @details The lifetime of a key indicates where it is stored and which application and system + * actions will create and destroy it. + * + * Lifetime values have the following structure: + * - Bits[7:0]: Persistence level + * This value indicates what device management actions can cause it to be destroyed. + * In particular, it indicates whether the key is volatile or persistent. + * See @ref psa_key_persistence_t for more information. + * @ref PSA_KEY_LIFETIME_GET_PERSISTENCE(@p lifetime) returns the persistence level for + * a key lifetime value. + * - Bits[31:8]: Location indicator + * This value indicates where the key material is stored (or at least where it is + * accessible in cleartext) and where operations on the key are performed. See + * @ref psa_key_location_t for more information. + * @ref PSA_KEY_LIFETIME_GET_LOCATION(@p lifetime) returns the location indicator for a + * key lifetime value. + * + * Volatile keys are automatically destroyed when the application instance terminates or + * on a power reset of the device. Persistent keys are preserved until the application + * explicitly destroys them or until an implementation-specific device management event + * occurs, for example, a factor reset. + * + * Persistent keys have a key identifier of type @ref psa_key_id_t. This identifier + * remains valid throughout the lifetime of the key, even if the application instance + * that created the key terminates. + * + * This specification defines two basic lifetime values: + * - Keys with the lifetime @ref PSA_KEY_LIFETIME_VOLATILE are volatile. All + * implementations should support this lifetime. + * - Keys with the lifetime @ref PSA_KEY_LIFETIME_PERSISTENT are persistent. All + * implementations that have access to persistent storage with appropriate security + * guarantees should support this lifetime. + */ +typedef uint32_t psa_key_lifetime_t; + +/** + * @brief Encoding of key persistence levels. + * + * @details What distinguishes different persistence levels is which device management events can + * cause keys to be destroyed. For example, power reset, transfer of device ownership, + * or a factory reset are device management events that can affect keys at different + * persistence levels. The specific management events which affect persistent keys at + * different levels is outside the scope of the PSA Cryptography specification. + * + * @note Key persistence levels are 8-bit values. Key management interfaces operate on lifetimes + * (type @ref psa_key_lifetime_t), and encode the persistence value as the lower 8 bits of + * a 32-bit value. + * + * Values for persistence levels defined by this specification are shown below: + * - @c 0 = @ref PSA_KEY_PERSISTENCE_VOLATILE : Volatile key. + * A volatile key is automatically destroyed by the implementation when the + * application instance terminates. In particular, a volatile key is + * automatically destroyed on a power reset of the device. + * - @c 1 = @ref PSA_KEY_PERSISTENCE_DEFAULT : Persistent key with a default lifetime. + * Implementations should support this value if they support persistent keys + * at all. Applications should use this value if they have no specific needs + * that are only met by implementation-specific features. + * - @c 2–127: Persistent key with a PSA-specified lifetime. The PSA Cryptography + * specification does not define the meaning of these values, but other PSA + * specifications may do so. + * - @c 128–254: Persistent key with a vendor-specified lifetime. No PSA specification + * will define the meaning of these values, so implementations may choose + * the meaning freely. As a guideline, higher persistence levels should + * cause a key to survive more management events than lower levels. + * - @c 255 = @ref PSA_KEY_PERSISTENCE_READ_ONLY : Read-only or write-once key. + * A key with this persistence level cannot be destroyed. Implementations that + * support such keys may either allow their creation through the PSA + * Cryptography API, preferably only to applications with the appropriate + * privilege, or only expose keys created through implementation-specific + * means such as a factory ROM engraving process. + * @note Keys that are read-only due to policy restrictions rather than + * due to physical limitations should not have this persistence level. + */ +typedef uint8_t psa_key_persistence_t; + +/** + * @brief Encoding of key location indicators. + * + * @details If an implementation of this API can make calls to external cryptoprocessors such as + * secure elements, the location of a key indicates which secure element performs the + * operations on the key. If the key material is not stored persistently inside the secure + * element, it must be stored in a wrapped form such that only the secure element can + * access the key material in cleartext. + * + * @note Key location indicators are 24-bit values. Key management interfaces operate on + * lifetimes (type @ref psa_key_lifetime_t), and encode the location as the upper 24 bits + * of a 32-bit value. + * + * Values for location indicators defined by this specification are shown below: + * - @c 0: Primary local storage. + * All implementations should support this value. The primary local storage is + * typically the same storage area that contains the key metadata. + * - @c 1: Primary secure element. + * @note As of now, this value is not supported by this implementation. + * Use the vendor-defined location values. + * + * Implementations should support this value if there is a secure element + * attached to the operating environment. As a guideline, secure elements may + * provide higher resistance against side channel and physical attacks than the + * primary local storage, but may have restrictions on supported key types, + * sizes, policies and operations and may have different performance + * characteristics. + * - @c 2–0x7fffff: Other locations defined by a PSA specification. + * The PSA Cryptography API does not currently assign any meaning to + * these locations, but future versions of this specification or other + * PSA specifications may do so. + * - @c 0x800000–0xffffff: Vendor-defined locations. No PSA specification will assign a + * meaning to locations in this range. + */ +typedef uint32_t psa_key_location_t; + +/** + * @brief The default lifetime for volatile keys. + * + * @details A volatile key only exists as long as its identifier is not destroyed. The key material + * is guaranteed to be erased on a power reset. + * + * A key with this lifetime is typically stored in the RAM area of the PSA Crypto + * subsystem. However this is an implementation choice. If an implementation stores data + * about the key in a non-volatile memory, it must release all the resources associated + * with the key and erase the key material if the calling application terminates. + */ +#define PSA_KEY_LIFETIME_VOLATILE ((psa_key_lifetime_t)0x00000000) + +/** + * @brief The default lifetime for persistent keys. + * + * @details A persistent key remains in storage until it is explicitly destroyed or until the + * corresponding storage area is wiped. This specification does not define any mechanism + * to wipe a storage area. Implementations are permitted to provide their own mechanism, + * for example, to perform a factory reset, to prepare for device refurbishment, or to + * uninstall an application. + * + * This lifetime value is the default storage area for the calling application. + * Implementations can offer other storage areas designated by other lifetime values as + * implementation-specific extensions. + */ +#define PSA_KEY_LIFETIME_PERSISTENT ((psa_key_lifetime_t)0x00000001) + +/** + * @brief The persistence level of volatile keys. + * + * @details See @ref psa_key_persistence_t for more information. + */ +#define PSA_KEY_PERSISTENCE_VOLATILE ((psa_key_persistence_t)0x00) + +/** + * @brief The default persistence level for persistent keys. + * + * @details See @ref psa_key_persistence_t for more information. + */ +#define PSA_KEY_PERSISTENCE_DEFAULT ((psa_key_persistence_t)0x01) + +/** + * @brief A persistence level indicating that a key is never destroyed. + * + * @details See @ref psa_key_persistence_t for more information. + */ +#define PSA_KEY_PERSISTENCE_READ_ONLY ((psa_key_persistence_t)0xff) + +/** + * @brief The local storage area for persistent keys. + * + * @details This storage area is available on all systems that can store persistent keys without + * delegating the storage to a third-party cryptoprocessor. + * + * See @ref psa_key_location_t for more information. + */ +#define PSA_KEY_LOCATION_LOCAL_STORAGE ((psa_key_location_t)0x000000) + +/** + * @brief The default secure element storage area for persistent keys. + * + * @details This storage location is available on systems that have one or more secure elements + * that are able to store keys. + * + * Vendor-defined locations must be provided by the system for storing keys in additional + * secure elements. + * + * See @ref psa_key_location_t for more information. + */ +#define PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT ((psa_key_location_t)0x000001) + +/** + * @brief Mark vendor defined key locations + */ +#define PSA_KEY_LOCATION_VENDOR_FLAG ((psa_key_location_t)0x800000) + +/** + * @brief Minimum location value for secure elements + */ +#define PSA_KEY_LOCATION_SE_MIN (PSA_KEY_LOCATION_VENDOR_FLAG) + +/** + * @brief Maximum location value for secure elements + */ +#define PSA_KEY_LOCATION_SE_MAX ((psa_key_location_t)0x8000ff) + +/** + * @brief Extract the persistence level from a key lifetime. + * + * @param lifetime The lifetime value to query: a value of type @ref psa_key_lifetime_t. + */ +#define PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) \ + ((psa_key_persistence_t)((lifetime) & 0x000000ff)) + +/** + * @brief Extract the location indicator from a key lifetime. + * + * @param lifetime The lifetime value to query: a value of type @ref psa_key_lifetime_t. + */ +#define PSA_KEY_LIFETIME_GET_LOCATION(lifetime) \ + ((psa_key_location_t)((lifetime) >> 8)) + +/** + * @brief Whether a key lifetime indicates that the key is volatile. + * + * A volatile key is automatically destroyed by the implementation when the application + * instance terminates. In particular, a volatile key is automatically destroyed on a + * power reset of the device. + * + * A key that is not volatile is persistent. Persistent keys are preserved until the + * application explicitly destroys them or until an implementation-specific device + * management event occurs, for example, a factory reset. + * + * @param lifetime The lifetime value to query: a value of type @ref psa_key_lifetime_t. + * + * @return 1 if the key is volatile, otherwise 0. + */ +#define PSA_KEY_LIFETIME_IS_VOLATILE(lifetime) \ + (PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) == PSA_KEY_PERSISTENCE_VOLATILE) + +/** + * @brief Construct a lifetime from a persistence level and a location. + * + * @param persistence The persistence level: a value of type @ref psa_key_persistence_t. + * @param location The location indicator: a value of type @ref psa_key_location_t. + * + * @return The constructed lifetime value. + */ +#define PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(persistence, location) \ + ((location) << 8 | (persistence)) + +#ifdef __cplusplus +} +#endif + +#endif /* PSA_CRYPTO_PSA_KEY_LIFETIME_H */ +/** @} */ diff --git a/sys/include/psa_crypto/psa/key/type.h b/sys/include/psa_crypto/psa/key/type.h new file mode 100644 index 000000000000..46e44bf5039e --- /dev/null +++ b/sys/include/psa_crypto/psa/key/type.h @@ -0,0 +1,881 @@ +/* + * 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/type.h + * @brief Key type definitions for the PSA Crypto API + * + * @author Armin Wolf + * @author Lena Boeckmann + * + */ + +#ifndef PSA_CRYPTO_PSA_KEY_TYPE_H +#define PSA_CRYPTO_PSA_KEY_TYPE_H + +#ifdef __cplusplus +extern "C" { +#endif + +#include + +/** + * @brief Encoding of a key type. + * + * @details This is a structured bitfield that identifies the category and type of key. The range + * of key type values is divided as follows: + * - @ref PSA_KEY_TYPE_NONE == @c 0: + * Reserved as an invalid key type. + * - @c 0x0001–0x7fff: + * Specification-defined key types. Key types defined by this standard always have bit + * 15 clear. Unallocated key type values in this range are reserved for future use. + * - @c 0x8000–0xffff: + * Implementation-defined key types. Implementations that define additional key types + * must use an encoding with bit 15 set. + */ +typedef uint16_t psa_key_type_t; + +/** + * @brief The type of PSA elliptic curve family identifiers. + * + * @details The curve identifier is required to create an ECC key using the + * @ref PSA_KEY_TYPE_ECC_KEY_PAIR() or @ref PSA_KEY_TYPE_ECC_PUBLIC_KEY() + * macros. + * + * The specific ECC curve within a family is identified by the @c key_bits + * attribute of the key. + */ +typedef uint8_t psa_ecc_family_t; + +/** + * @brief The type of PSA finite-field Diffie-Hellman group family identifiers. + * + * @details The group family identifier is required to create a finite-field Diffie-Hellman + * key using the @ref PSA_KEY_TYPE_DH_KEY_PAIR() or @ref PSA_KEY_TYPE_DH_PUBLIC_KEY() + * macros. + * + * The specific Diffie-Hellman group within a family is identified by the @c key_bits + * attribute of the key. + */ +typedef uint8_t psa_dh_family_t; + +/** + * @brief An invalid key type value. + * + * @details Zero is not the encoding of any key type. + */ +#define PSA_KEY_TYPE_NONE ((psa_key_type_t)0x0000) + +/** + * @brief Vendor-defined key type flag. + * + * @details Key types defined by this standard will never have the + * @ref PSA_KEY_TYPE_VENDOR_FLAG bit set. Vendors who define additional key types + * must use an encoding with the @ref PSA_KEY_TYPE_VENDOR_FLAG bit set and should + * respect the bitwise structure used by standard encodings whenever practical. + */ +#define PSA_KEY_TYPE_VENDOR_FLAG ((psa_key_type_t)0x8000) + +/** + * @brief Mask for key type categories. + */ +#define PSA_KEY_TYPE_CATEGORY_MASK ((psa_key_type_t)0x7000) + +/** + * @brief Raw key data type. + */ +#define PSA_KEY_TYPE_CATEGORY_RAW ((psa_key_type_t)0x1000) + +/** + * @brief Symmetric key type. + */ +#define PSA_KEY_TYPE_CATEGORY_SYMMETRIC ((psa_key_type_t)0x2000) + +/** + * @brief Asymmetric public key type. + */ +#define PSA_KEY_TYPE_CATEGORY_PUBLIC_KEY ((psa_key_type_t)0x4000) + +/** + * @brief Asymmetric key pair type. + */ +#define PSA_KEY_TYPE_CATEGORY_KEY_PAIR ((psa_key_type_t)0x7000) + +/** + * @brief Asymmetric key pair flag. + */ +#define PSA_KEY_TYPE_CATEGORY_FLAG_PAIR ((psa_key_type_t)0x3000) + +/** + * @brief Whether a key type is an unstructured array of bytes. + * This encompasses both symmetric keys and non-key data. + * + * @param type A key type: a value of type @ref psa_key_type_t. + */ +#define PSA_KEY_TYPE_IS_UNSTRUCTURED(type) \ + (((type) & 0x7000) == 0x1000 || ((type) & 0x7000) == 0x2000) + +/** + * @brief Whether a key type is asymmetric: either a key pair or a public key. + * + * @param type A key type: a value of type @ref psa_key_type_t. + */ +#define PSA_KEY_TYPE_IS_ASYMMETRIC(type) \ + (((type) & 0x4000) == 0x4000) + +/** + * @brief Whether a key type is the public part of a key pair. + * + * @param type A key type: a value of type @ref psa_key_type_t. + */ +#define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) \ + (((type) & 0x7000) == 0x4000) + +/** + * @brief Whether a key type is a key pair containing a private part and a public part. + * + * @param type A key type: a value of type @ref psa_key_type_t. + */ +#define PSA_KEY_TYPE_IS_KEY_PAIR(type) \ + (((type) & 0x7000) == 0x7000) + +/** + * @brief Raw data. + * + * @details A “key” of this type cannot be used for any cryptographic operation. Applications can + * use this type to store arbitrary data in the keystore. + * + * The bit size of a raw key must be a non-zero multiple of 8. The maximum size of a raw + * key is implementation defined. + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_HKDF (non-secret inputs) + * - @ref PSA_ALG_TLS12_PRF (non-secret inputs) + * - @ref PSA_ALG_TLS12_PSK_TO_MS (non-secret inputs) + */ +#define PSA_KEY_TYPE_RAW_DATA ((psa_key_type_t)0x1001) + +/** + * @brief HMAC key. + * + * @details The key policy determines which underlying hash algorithm the key can be used for. + * + * The bit size of an HMAC key must be a non-zero multiple of 8. An HMAC key is typically + * the same size as the output of the underlying hash algorithm. An HMAC key that is + * longer than the block size of the underlying hash algorithm will be hashed before use. + * + * When an HMAC key is created that is longer than the block size, it is implementation + * defined whether the implementation stores the original HMAC key, or the hash of the + * HMAC key. If the hash of the key is stored, the key size reported by + * @ref psa_get_key_attributes() will be the size of the hashed key. + * + * @note @ref PSA_HASH_LENGTH(@p alg) provides the output size of hash algorithm @c alg, + * in bytes. + * @ref PSA_HASH_BLOCK_LENGTH(@p alg) provides the block size of hash algorithm + * @c alg, in bytes. + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_HMAC + */ +#define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x1100) + +/** + * @brief A secret for key derivation. + * + * @details This key type is for high-entropy secrets only. For low-entropy secrets, + * @ref PSA_KEY_TYPE_PASSWORD should be used instead. + * + * These keys can be used in the @ref PSA_KEY_DERIVATION_INPUT_SECRET or + * @ref PSA_KEY_DERIVATION_INPUT_PASSWORD input step of key derivation algorithms. + * + * The key policy determines which key derivation algorithm the key can be used for. + * + * The bit size of a secret for key derivation must be a non-zero multiple of 8. The + * maximum size of a secret for key derivation is implementation defined. + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_HKDF (secret input) + * - @ref PSA_ALG_TLS12_PRF (secret input) + * - @ref PSA_ALG_TLS12_PSK_TO_MS (secret input) + */ +#define PSA_KEY_TYPE_DERIVE ((psa_key_type_t)0x1200) + +/** + * @brief A low-entropy secret for password hashing or key derivation. + * + * @details This key type is suitable for passwords and passphrases which are typically intended to + * be memorizable by humans, and have a low entropy relative to their size. It can be used + * for randomly generated or derived keys with maximum or near-maximum entropy, but + * @ref PSA_KEY_TYPE_DERIVE is more suitable for such keys. It is not suitable for + * passwords with extremely low entropy, such as numerical PINs. + * + * These keys can be used in the @ref PSA_KEY_DERIVATION_INPUT_PASSWORD input step of key + * derivation algorithms. Algorithms that accept such an input were designed to accept + * low-entropy secret and are known as password hashing or key stretching algorithms. + * + * These keys cannot be used in the @ref PSA_KEY_DERIVATION_INPUT_SECRET input step of key + * derivation algorithms, as the algorithms expect such an input to have high entropy. + * + * The key policy determines which key derivation algorithm the key can be used for, among + * the permissible subset defined above. + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_PBKDF2_HMAC() (password input) + * - @ref PSA_ALG_PBKDF2_AES_CMAC_PRF_128 (password input) + */ +#define PSA_KEY_TYPE_PASSWORD ((psa_key_type_t)0x1203) + +/** + * @brief A secret value that can be used to verify a password hash. + * + * @details The key policy determines which key derivation algorithm the key can be used for, among + * the same permissible subset as for @ref PSA_KEY_TYPE_PASSWORD. + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_PBKDF2_HMAC() (key output and verification) + * - @ref PSA_ALG_PBKDF2_AES_CMAC_PRF_128 (key output and verification) + */ +#define PSA_KEY_TYPE_PASSWORD_HASH ((psa_key_type_t)0x1205) + +/** + * @brief A secret value that can be used when computing a password hash. + * + * @details The key policy determines which key derivation algorithm the key can be used for, among + * the subset of algorithms that can use pepper. + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_PBKDF2_HMAC() (salt input) + * - @ref PSA_ALG_PBKDF2_AES_CMAC_PRF_128 (salt input) + */ +#define PSA_KEY_TYPE_PEPPER ((psa_key_type_t)0x1206) + +/** + * @brief Key for a cipher, AEAD or MAC algorithm based on the AES block cipher. + * + * @details The size of the key is related to the AES algorithm variant. For algorithms except the + * XTS block cipher mode, the following key sizes are used: + * - AES-128 uses a 16-byte key : @c key_bits = 128 + * - AES-192 uses a 24-byte key : @c key_bits = 192 + * - AES-256 uses a 32-byte key : @c key_bits = 256 + * + * For the XTS block cipher mode (@ref PSA_ALG_XTS), the following key sizes are used: + * - AES-128-XTS uses two 16-byte keys : @c key_bits = 256 + * - AES-192-XTS uses two 24-byte keys : @c key_bits = 384 + * - AES-256-XTS uses two 32-byte keys : @c key_bits = 512 + * + * The AES block cipher is defined in FIPS Publication 197: Advanced Encryption Standard + * (AES) [FIPS197](https://doi.org/10.6028/NIST.FIPS.197). + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_CBC_MAC + * - @ref PSA_ALG_CMAC + * - @ref PSA_ALG_CTR + * - @ref PSA_ALG_CFB + * - @ref PSA_ALG_OFB + * - @ref PSA_ALG_XTS + * - @ref PSA_ALG_CBC_NO_PADDING + * - @ref PSA_ALG_CBC_PKCS7 + * - @ref PSA_ALG_ECB_NO_PADDING + * - @ref PSA_ALG_CCM + * - @ref PSA_ALG_GCM + */ +#define PSA_KEY_TYPE_AES ((psa_key_type_t)0x2400) + +/** + * @brief Key for a cipher, AEAD or MAC algorithm based on the ARIA block cipher. + * + * The size of the key is related to the ARIA algorithm variant. For algorithms except the + * XTS block cipher mode, the following key sizes are used: + * - ARIA-128 uses a 16-byte key : @c key_bits = 128 + * - ARIA-192 uses a 24-byte key : @c key_bits = 192 + * - ARIA-256 uses a 32-byte key : @c key_bits = 256 + * + * For the XTS block cipher mode (@ref PSA_ALG_XTS), the following key sizes are used: + * - ARIA-128-XTS uses two 16-byte keys : @c key_bits = 256 + * - ARIA-192-XTS uses two 24-byte keys : @c key_bits = 384 + * - ARIA-256-XTS uses two 32-byte keys : @c key_bits = 512 + * + * The ARIA block cipher is defined in A Description of the ARIA Encryption Algorithm + * [RFC5794](https://datatracker.ietf.org/doc/html/rfc5794). + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_CBC_MAC + * - @ref PSA_ALG_CMAC + * - @ref PSA_ALG_CTR + * - @ref PSA_ALG_CFB + * - @ref PSA_ALG_OFB + * - @ref PSA_ALG_XTS + * - @ref PSA_ALG_CBC_NO_PADDING + * - @ref PSA_ALG_CBC_PKCS7 + * - @ref PSA_ALG_ECB_NO_PADDING + * - @ref PSA_ALG_CCM + * - @ref PSA_ALG_GCM + */ +#define PSA_KEY_TYPE_ARIA ((psa_key_type_t)0x2406) + +/** + * @brief Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES). + * + * @details The size of the key determines which DES algorithm is used: + * - Single DES uses an 8-byte key : @c key_bits = 64 + * - 2-key 3DES uses a 16-byte key : @c key_bits = 128 + * - 3-key 3DES uses a 24-byte key : @c key_bits = 192 + * + * @warning Single DES and 2-key 3DES are weak and strongly deprecated and are only recommended for + * decrypting legacy data. + * 3-key 3DES is weak and deprecated and is only recommended for use in legacy protocols. + * + * The DES and 3DES block ciphers are defined in NIST Special Publication 800-67: + * Recommendation for the Triple Data Encryption Algorithm (TDEA) Block Cipher + * [SP800-67](https://doi.org/10.6028/NIST.SP.800-67r2). + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_CBC_MAC + * - @ref PSA_ALG_CMAC + * - @ref PSA_ALG_CTR + * - @ref PSA_ALG_CFB + * - @ref PSA_ALG_OFB + * - @ref PSA_ALG_XTS + * - @ref PSA_ALG_CBC_NO_PADDING + * - @ref PSA_ALG_CBC_PKCS7 + * - @ref PSA_ALG_ECB_NO_PADDING + */ +#define PSA_KEY_TYPE_DES ((psa_key_type_t)0x2301) + +/** + * @brief Key for a cipher, AEAD or MAC algorithm based on the Camellia block cipher. + * + * @details The size of the key is related to the Camellia algorithm variant. For algorithms except + * the XTS block cipher mode, the following key sizes are used: + * - Camellia-128 uses a 16-byte key : @c key_bits = 128 + * - Camellia-192 uses a 24-byte key : @c key_bits = 192 + * - Camellia-256 uses a 32-byte key : @c key_bits = 256 + * + * For the XTS block cipher mode (@ref PSA_ALG_XTS), the following key sizes are used: + * - Camellia-128-XTS uses two 16-byte keys : @c key_bits = 256 + * - Camellia-192-XTS uses two 24-byte keys : @c key_bits = 384 + * - Camellia-256-XTS uses two 32-byte keys : @c key_bits = 512 + * + * The Camellia block cipher is defined in Specification of Camellia — a 128-bit Block + * Cipher [NTT-CAM](https://info.isl.ntt.co.jp/crypt/eng/camellia/specifications) and + * also described in A Description of the Camellia Encryption + * Algorithm [RFC3713](https://tools.ietf.org/html/rfc3713). + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_CBC_MAC + * - @ref PSA_ALG_CMAC + * - @ref PSA_ALG_CTR + * - @ref PSA_ALG_CFB + * - @ref PSA_ALG_OFB + * - @ref PSA_ALG_XTS + * - @ref PSA_ALG_CBC_NO_PADDING + * - @ref PSA_ALG_CBC_PKCS7 + * - @ref PSA_ALG_ECB_NO_PADDING + * - @ref PSA_ALG_CCM + * - @ref PSA_ALG_GCM + */ +#define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x2403) + +/** + * @brief Key for a cipher, AEAD or MAC algorithm based on the SM4 block cipher. + * + * @details For algorithms except the XTS block cipher mode, the SM4 key size is 128 bits + * (16 bytes). + * + * For the XTS block cipher mode (@ref PSA_ALG_XTS), the SM4 key size is 256 bits + * (two 16-byte keys). + * + * The SM4 block cipher is defined in GM/T 0002-2012: SM4 block cipher algorithm + * [CSTC0002](http://www.gmbz.org.cn/main/viewfile/20180108015408199368.html) + * (English version [CSTC0002/E](http://www.gmbz.org.cn/main/postDetail.html? + * id=20180404044052)). + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_CBC_MAC + * - @ref PSA_ALG_CMAC + * - @ref PSA_ALG_CTR + * - @ref PSA_ALG_CFB + * - @ref PSA_ALG_OFB + * - @ref PSA_ALG_XTS + * - @ref PSA_ALG_CBC_NO_PADDING + * - @ref PSA_ALG_CBC_PKCS7 + * - @ref PSA_ALG_ECB_NO_PADDING + * - @ref PSA_ALG_CCM + * - @ref PSA_ALG_GCM + */ +#define PSA_KEY_TYPE_SM4 ((psa_key_type_t)0x2405) + +/** + * @brief Key for the ARC4 stream cipher. + * + * @warning The ARC4 cipher is weak and deprecated and is only recommended for use in legacy + * protocols. + * + * @details The ARC4 cipher supports key sizes between 40 and 2048 bits, that are multiples of 8. + * (5 to 256 bytes) + * + * Use algorithm @ref PSA_ALG_STREAM_CIPHER to use this key with the ARC4 cipher. + */ +#define PSA_KEY_TYPE_ARC4 ((psa_key_type_t)0x2002) + +/** + * @brief Key for the ChaCha20 stream cipher or the ChaCha20-Poly1305 AEAD algorithm. + * + * @details The ChaCha20 key size is 256 bits (32 bytes). + * - Use algorithm @ref PSA_ALG_STREAM_CIPHER to use this key with the ChaCha20 cipher for + * unauthenticated encryption. See @ref PSA_ALG_STREAM_CIPHER for details of this + * algorithm. + * - Use algorithm @ref PSA_ALG_CHACHA20_POLY1305 to use this key with the ChaCha20 cipher + * and Poly1305 authenticator for AEAD. See @ref PSA_ALG_CHACHA20_POLY1305 for details + * of this algorithm. + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_STREAM_CIPHER + * - @ref PSA_ALG_CHACHA20_POLY1305 + */ +#define PSA_KEY_TYPE_CHACHA20 ((psa_key_type_t)0x2004) + +/** + * @brief RSA key pair: both the private and public key. + * + * @details The size of an RSA key is the bit size of the modulus. + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_RSA_OAEP + * - @ref PSA_ALG_RSA_PKCS1V15_CRYPT + * - @ref PSA_ALG_RSA_PKCS1V15_SIGN + * - @ref PSA_ALG_RSA_PKCS1V15_SIGN_RAW + * - @ref PSA_ALG_RSA_PSS + * - @ref PSA_ALG_RSA_PSS_ANY_SALT + */ +#define PSA_KEY_TYPE_RSA_KEY_PAIR ((psa_key_type_t)0x7001) + +/** + * @brief RSA public key. + * + * @details The size of an RSA key is the bit size of the modulus. + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_RSA_OAEP (encryption only) + * - @ref PSA_ALG_RSA_PKCS1V15_CRYPT (encryption only) + * - @ref PSA_ALG_RSA_PKCS1V15_SIGN (signature verification only) + * - @ref PSA_ALG_RSA_PKCS1V15_SIGN_RAW (signature verification only) + * - @ref PSA_ALG_RSA_PSS (signature verification only) + * - @ref PSA_ALG_RSA_PSS_ANY_SALT (signature verification only) + */ +#define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x4001) + +/** + * @brief Whether a key type is an RSA key. This includes both key pairs and public keys. + * + * @param type A key type: a value of type @ref psa_key_type_t. + */ +#define PSA_KEY_TYPE_IS_RSA(type) \ + (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == 0x4001) + +/** + * @brief Base value for ECC key pairs + */ +#define PSA_KEY_TYPE_ECC_KEY_PAIR_BASE ((psa_key_type_t)0x7100) + +/** + * @brief Elliptic curve key pair: both the private and public key. + * + * @details The size of an elliptic curve key is the bit size associated with the curve, that is, + * the bit size of q for a curve over a field Fq. See the documentation of each Elliptic + * curve family for details. + * + * @b Compatible @b algorithms + * - Elliptic curve key pairs can be used in Asymmetric signature and Key agreement + * algorithms. + * - The set of compatible algorithms depends on the Elliptic curve key family. See the + * Elliptic curve family for details. + * + * @param curve A value of type @ref psa_ecc_family_t that identifies the ECC curve to be used. + */ +#define PSA_KEY_TYPE_ECC_KEY_PAIR(curve) \ + (PSA_KEY_TYPE_ECC_KEY_PAIR_BASE | (curve)) + +/** + * @brief Base value for ECC public keys + */ +#define PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE ((psa_key_type_t)0x4100) + +/** + * @brief Mask for ECC curves + */ +#define PSA_KEY_TYPE_ECC_CURVE_MASK ((psa_key_type_t)0x00ff) + +/** + * @brief Elliptic curve public key. + * + * @details The size of an elliptic curve public key is the same as the corresponding private key. + * See @ref PSA_KEY_TYPE_ECC_KEY_PAIR() and the documentation of each Elliptic curve + * family for details. + * + * @b Compatible @b algorithms + * Elliptic curve public keys can be used for verification in asymmetric signature + * algorithms. + * The set of compatible algorithms depends on the elliptic curve key family. See each + * elliptic curve family for details. + * + * @param curve A value of type @ref psa_ecc_family_t that identifies the ECC curve to be used. + */ +#define PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) \ + (PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE | (curve)) + +/** + * @brief SEC Koblitz curves over prime fields. + * + * @details This family comprises the following curves: + * - `secp192k1` : @c key_bits = 192 + * - `secp224k1` : @c key_bits = 225 + * - `secp256k1` : @c key_bits = 256 + * + * They are defined in SEC 2: Recommended Elliptic Curve Domain Parameters + * [SEC2](https://www.secg.org/sec2-v2.pdf). + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_DETERMINISTIC_ECDSA + * - @ref PSA_ALG_ECDSA + * - @ref PSA_ALG_ECDSA_ANY + * - @ref PSA_ALG_ECDH (key pair only) + */ +#define PSA_ECC_FAMILY_SECP_K1 ((psa_ecc_family_t)0x17) + +/** + * @brief SEC random curves over prime fields. + * + * @details This family comprises the following curves: + * - `secp192r1` : @c key_bits = 192 + * - `secp224r1` : @c key_bits = 224 + * - `secp256r1` : @c key_bits = 256 + * - `secp384r1` : @c key_bits = 384 + * - `secp521r1` : @c key_bits = 521 + * + * They are defined in [SEC2](https://www.secg.org/sec2-v2.pdf). + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_DETERMINISTIC_ECDSA + * - @ref PSA_ALG_ECDSA + * - @ref PSA_ALG_ECDSA_ANY + * - @ref PSA_ALG_ECDH (key pair only) + */ +#define PSA_ECC_FAMILY_SECP_R1 ((psa_ecc_family_t)0x12) + +/** + * @warning This family of curves is weak and deprecated. + * + * @details This family comprises the following curves: + * - `secp160r2` : @c key_bits = 160 (Deprecated) + * + * It is defined in the superseded SEC 2: Recommended Elliptic Curve Domain Parameters, + * Version 1.0 [SEC2v1](https://www.secg.org/SEC2-Ver-1.0.pdf). + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_DETERMINISTIC_ECDSA + * - @ref PSA_ALG_ECDSA + * - @ref PSA_ALG_ECDSA_ANY + * - @ref PSA_ALG_ECDH (key pair only) + */ +#define PSA_ECC_FAMILY_SECP_R2 ((psa_ecc_family_t)0x1b) + +/** + * @brief SEC Koblitz curves over binary fields. + * + * @details This family comprises the following curves: + * - `sect163k1` : @c key_bits = 163 (Deprecated) + * - `sect233k1` : @c key_bits = 233 + * - `sect239k1` : @c key_bits = 239 + * - `sect283k1` : @c key_bits = 283 + * - `sect409k1` : @c key_bits = 409 + * - `sect571k1` : @c key_bits = 571 + * + * They are defined in [SEC2](https://www.secg.org/sec2-v2.pdf). + * + * @warning The 163-bit curve `sect163k1` is weak and deprecated and is only recommended for use in + * legacy protocols. + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_DETERMINISTIC_ECDSA + * - @ref PSA_ALG_ECDSA + * - @ref PSA_ALG_ECDSA_ANY + * - @ref PSA_ALG_ECDH (key pair only) + */ +#define PSA_ECC_FAMILY_SECT_K1 ((psa_ecc_family_t)0x27) + +/** + * @brief SEC random curves over binary fields. + * + * @details This family comprises the following curves: + * - `sect163r1` : @c key_bits = 163 (Deprecated) + * - `sect233r1` : @c key_bits = 233 + * - `sect283r1` : @c key_bits = 283 + * - `sect409r1` : @c key_bits = 409 + * - `sect571r1` : @c key_bits = 571 + * + * They are defined in [SEC2](https://www.secg.org/sec2-v2.pdf). + * + * @warning The 163-bit curve `sect163r1` is weak and deprecated and is only recommended for use in + * legacy protocols. + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_DETERMINISTIC_ECDSA + * - @ref PSA_ALG_ECDSA + * - @ref PSA_ALG_ECDSA_ANY + * - @ref PSA_ALG_ECDH (key pair only) + */ +#define PSA_ECC_FAMILY_SECT_R1 ((psa_ecc_family_t)0x22) + +/** + * @brief SEC additional random curves over binary fields. + * + * @details This family comprises the following curves: + * - `sect163r2` : @c key_bits = 163 (Deprecated) + * + * It is defined in [SEC2](https://www.secg.org/sec2-v2.pdf). + * + * @warning The 163-bit curve `sect163r2` is weak and deprecated and is only recommended for use in + * legacy protocols. + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_DETERMINISTIC_ECDSA + * - @ref PSA_ALG_ECDSA + * - @ref PSA_ALG_ECDSA_ANY + * - @ref PSA_ALG_ECDH (key pair only) + */ +#define PSA_ECC_FAMILY_SECT_R2 ((psa_ecc_family_t)0x2b) + +/** + * @brief Brainpool `P` random curves. + * + * @details This family comprises the following curves: + * - `brainpoolP160r1` : @c key_bits = 160 (Deprecated) + * - `brainpoolP192r1` : @c key_bits = 192 + * - `brainpoolP224r1` : @c key_bits = 224 + * - `brainpoolP256r1` : @c key_bits = 256 + * - `brainpoolP320r1` : @c key_bits = 320 + * - `brainpoolP384r1` : @c key_bits = 384 + * - `brainpoolP512r1` : @c key_bits = 512 + * + * They are defined in Elliptic Curve Cryptography (ECC) Brainpool Standard Curves and + * Curve Generation [RFC5639](https://tools.ietf.org/html/rfc5639.html). + * + * @warning The 160-bit curve `brainpoolP160r1` is weak and deprecated and is only recommended for + * use in legacy protocols. + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_DETERMINISTIC_ECDSA + * - @ref PSA_ALG_ECDSA + * - @ref PSA_ALG_ECDSA_ANY + * - @ref PSA_ALG_ECDH (key pair only) + */ +#define PSA_ECC_FAMILY_BRAINPOOL_P_R1 ((psa_ecc_family_t)0x30) + +/** + * @brief Curve used primarily in France and elsewhere in Europe. + * + * @details This family comprises one 256-bit curve: + * - `FRP256v1` : @c key_bits = 256 + * + * This is defined by Publication d'un paramétrage de courbe elliptique visant des + * applications de passeport électronique et de l'administration électronique française + * [FRP](https://www.ssi.gouv.fr/agence/rayonnement-scientifique/ + * publications-scientifiques/articles-ouvrages-actes). + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_DETERMINISTIC_ECDSA + * - @ref PSA_ALG_ECDSA + * - @ref PSA_ALG_ECDSA_ANY + * - @ref PSA_ALG_ECDH (key pair only) + */ +#define PSA_ECC_FAMILY_FRP ((psa_ecc_family_t)0x33) + +/** + * @brief Montgomery curves. + * + * @details This family comprises the following Montgomery curves: + * - `Curve25519` : @c key_bits = 255 + * - `Curve448` : @c key_bits = 448 + * + * `Curve25519` is defined in Curve25519: new Diffie-Hellman speed records + * [Curve25519](https://www.iacr.org/archive/pkc2006/39580209/39580209.pdf). + * `Curve448` is defined in Ed448-Goldilocks, a new elliptic curve + * [Curve448](https://eprint.iacr.org/2015/625.pdf). + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_ECDH (key pair only) + */ +#define PSA_ECC_FAMILY_MONTGOMERY ((psa_ecc_family_t)0x41) + +/** + * @brief Twisted Edwards curves. + * + * @details This family comprises the following twisted Edwards curves: + * - `Edwards25519` : @c key_bits = 255. This curve is birationally equivalent to + * `Curve25519`. + * - `Edwards448` : @c key_bits = 448. This curve is birationally equivalent to `Curve448`. + * + * Edwards25519 is defined in Twisted Edwards curves + * [Ed25519](https://eprint.iacr.org/2008/013.pdf). Edwards448 is defined in + * Ed448-Goldilocks, a new elliptic curve [Curve448](https://eprint.iacr.org/2015/625.pdf). + * + * @b Compatible @b algorithms + * - @ref PSA_ALG_PURE_EDDSA + * - @ref PSA_ALG_ED25519PH (Edwards25519 only) + * - @ref PSA_ALG_ED448PH (Edwards448 only) + */ +#define PSA_ECC_FAMILY_TWISTED_EDWARDS ((psa_ecc_family_t)0x42) + +/** + * @brief Whether a key type is an elliptic curve key, either a key pair or a public key. + * + * @param type A key type: a value of type @ref psa_key_type_t. + */ +#define PSA_KEY_TYPE_IS_ECC(type) \ + ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff00) == 0x4100) + +/** + * @brief Whether a key type is an elliptic curve key pair. + * + * @param type A key type: a value of type @ref psa_key_type_t. + */ +#define PSA_KEY_TYPE_IS_ECC_KEY_PAIR(type) \ + (((type) & 0xff00) == 0x7100) + +/** + * @brief Whether a key type is an elliptic curve public key. + * + * @param type A key type: a value of type @ref psa_key_type_t. + */ +#define PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(type) \ + (((type) & 0xff00) == 0x4100) + +/** + * @brief Extract the curve family from an elliptic curve key type. + * + * @param type An elliptic curve key type: a value of type @ref psa_key_type_t such that + * @ref PSA_KEY_TYPE_IS_ECC(@p type) is true. + * + * @return The elliptic curve family id, if type is a supported elliptic curve key. + * Unspecified if type is not a supported elliptic curve key. + */ +#define PSA_KEY_TYPE_ECC_GET_FAMILY(type) \ + ((psa_ecc_family_t)((type) & 0x00ff)) + +/** + * @brief Finite-field Diffie-Hellman key pair: both the private key and public key. + * + * @details @b Compatible @b algorithms + * - @ref PSA_ALG_FFDH + * + * @param group A value of type @ref psa_dh_family_t that identifies the Diffie-Hellman group + * family to be used. + */ +#define PSA_KEY_TYPE_DH_KEY_PAIR(group) \ + ((psa_key_type_t)(0x7200 | (group))) + +/** + * @brief Finite-field Diffie-Hellman public key. + * + * @details @b Compatible @b algorithms + * None. Finite-field Diffie-Hellman public keys are exported to use in a key agreement + * algorithm, and the peer key is provided to the @ref PSA_ALG_FFDH key agreement + * algorithm as a buffer of key data. + * + * @param group A value of type @ref psa_dh_family_t that identifies the Diffie-Hellman group + * family to be used. + */ +#define PSA_KEY_TYPE_DH_PUBLIC_KEY(group) \ + ((psa_key_type_t)(0x4200 | (group))) + +/** + * @brief Finite-field Diffie-Hellman groups defined for TLS in RFC 7919. + * + * @details This family includes groups with the following key sizes (in bits): 2048, 3072, 4096, + * 6144, 8192. An implementation can support all of these sizes or only a subset. + * + * Keys is this group can only be used with the @ref PSA_ALG_FFDH key agreement algorithm. + * + * These groups are defined by Negotiated Finite Field Diffie-Hellman Ephemeral Parameters + * for Transport Layer Security (TLS) [RFC7919](https://tools.ietf.org/html/rfc7919.html) + * Appendix A. + */ +#define PSA_DH_FAMILY_RFC7919 ((psa_dh_family_t)0x03) + +/** + * @brief The key pair type corresponding to a public key type. + * + * @details If type is a key pair type, it will be left unchanged. + * + * @param type A public key type or key pair type. + * + * @return The corresponding key pair type. If type is not a public key or a key pair, the return + * value is undefined. + */ +#define PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY(type) \ + ((psa_key_type_t)((type) | 0x3000)) + +/** + * @brief The public key type corresponding to a key pair type. + * You may also pass a key pair type as type, it will be left unchanged. + * + * @param type A public key type or key pair type. + * + * @return The corresponding public key type. + * If type is not a public key or a key pair, the return value is undefined. + */ +#define PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) \ + ((psa_key_type_t)((type) & ~0x3000)) + +/** + * @brief Whether a key type is a Diffie-Hellman key, either a key pair or a public key. + * + * @param type A key type: a value of type @ref psa_key_type_t. + */ +#define PSA_KEY_TYPE_IS_DH(type) \ + ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff00) == 0x4200) + +/** + * @brief Whether a key type is a Diffie-Hellman key pair. + * + * @param type A key type: a value of type @ref psa_key_type_t. + */ +#define PSA_KEY_TYPE_IS_DH_KEY_PAIR(type) \ + (((type) & 0xff00) == 0x7200) + +/** + * @brief Whether a key type is a Diffie-Hellman public key. + * + * @param type A key type: a value of type @ref psa_key_type_t. + */ +#define PSA_KEY_TYPE_IS_DH_PUBLIC_KEY(type) \ + (((type) & 0xff00) == 0x4200) + +/** + * @brief Extract the group family from a Diffie-Hellman key type. + * + * @param type A Diffie-Hellman key type: a value of type @ref psa_key_type_t such that + * @ref PSA_KEY_TYPE_IS_DH(@p type) is true. + * + * @return The Diffie-Hellman group family id, if type is a supported Diffie-Hellman key. + * Unspecified if type is not a supported Diffie-Hellman key. + */ +#define PSA_KEY_TYPE_DH_GET_FAMILY(type) \ + ((psa_dh_family_t)((type) & 0x00ff)) + +#ifdef __cplusplus +} +#endif + +#endif /* PSA_CRYPTO_PSA_KEY_TYPE_H */ +/** @} */ diff --git a/sys/include/psa_crypto/psa/key/usage.h b/sys/include/psa_crypto/psa/key/usage.h new file mode 100644 index 000000000000..1f5d33c7602a --- /dev/null +++ b/sys/include/psa_crypto/psa/key/usage.h @@ -0,0 +1,224 @@ +/* + * 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/usage.h + * @brief Key usage definitions for the PSA Crypto API + * + * @author Armin Wolf + * @author Lena Boeckmann + * + */ + +#ifndef PSA_CRYPTO_PSA_KEY_USAGE_H +#define PSA_CRYPTO_PSA_KEY_USAGE_H + +#ifdef __cplusplus +extern "C" { +#endif + +#include + +/** + * @brief Encoding of permitted usage on a key. + */ +typedef uint32_t psa_key_usage_t; + +/** + * @brief Permission to export the key. + * + * @details This flag allows the use of @ref psa_export_key() to export a key from the + * cryptoprocessor. A public key or the public part of a key pair can always be exported + * regardless of the value of this permission flag. + * + * This flag can also be required to copy a key using @ref psa_copy_key() outside of a + * secure element. See also @ref PSA_KEY_USAGE_COPY. + * + * If a key does not have export permission, implementations must not allow the key to be + * exported in plain form from the cryptoprocessor, whether through @ref psa_export_key() + * or through a proprietary interface. The key might still be exportable in a wrapped + * form, i.e. in a form where it is encrypted by another key. + */ +#define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t)0x00000001) + +/** + * @brief Permission to copy the key. + * + * @details This flag allows the use of @ref psa_copy_key() to make a copy of the key with the same + * policy or a more restrictive policy. + * + * For lifetimes for which the key is located in a secure element which enforce the + * non-exportability of keys, copying a key outside the secure element also requires the + * usage flag @ref PSA_KEY_USAGE_EXPORT. Copying the key inside the secure element is + * permitted with just @ref PSA_KEY_USAGE_COPY if the secure element supports it. For keys + * with the lifetime @ref PSA_KEY_LIFETIME_VOLATILE or @ref PSA_KEY_LIFETIME_PERSISTENT, + * the usage flag @ref PSA_KEY_USAGE_COPY is sufficient to permit the copy. + */ +#define PSA_KEY_USAGE_COPY ((psa_key_usage_t)0x00000002) + +/** + * @brief Permission for the implementation to cache the key. + * + * @details This flag allows the implementation to make additional copies of the key material that + * are not in storage and not for the purpose of an ongoing operation. Applications can + * use it as a hint to keep the key around for repeated access. + * + * An application can request that cached key material is removed from memory by calling + * @ref psa_purge_key(). + * + * The presence of this usage flag when creating a key is a hint: + * - An implementation is not required to cache keys that have this usage flag. + * - An implementation must not report an error if it does not cache keys. + * + * If this usage flag is not present, the implementation must ensure key material is + * removed from memory as soon as it is not required for an operation or for maintenance + * of a volatile key. + * + * This flag must be preserved when reading back the attributes for all keys, regardless + * of key type or implementation behavior. + */ +#define PSA_KEY_USAGE_CACHE ((psa_key_usage_t)0x00000004) + +/** + * @brief Permission to encrypt a message with the key. + * + * @details This flag allows the key to be used for a symmetric encryption operation, for an AEAD + * encryption-and-authentication operation, or for an asymmetric encryption operation, if + * otherwise permitted by the key’s type and policy. The flag must be present on keys used + * with the following APIs: + * - @ref psa_cipher_encrypt() + * - @ref psa_cipher_encrypt_setup() + * - @ref psa_aead_encrypt() + * - @ref psa_aead_encrypt_setup() + * - @ref psa_asymmetric_encrypt() + * + * For a key pair, this concerns the public key. + */ +#define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t)0x00000100) + +/** + * @brief Permission to decrypt a message with the key. + * + * @details This flag allows the key to be used for a symmetric decryption operation, for an AEAD + * decryption-and-verification operation, or for an asymmetric decryption operation, if + * otherwise permitted by the key’s type and policy. The flag must be present on keys used + * with the following APIs: + * - @ref psa_cipher_decrypt() + * - @ref psa_cipher_decrypt_setup() + * - @ref psa_aead_decrypt() + * - @ref psa_aead_decrypt_setup() + * - @ref psa_asymmetric_decrypt() + * + * For a key pair, this concerns the private key. + */ +#define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200) + +/** + * @brief Permission to sign a message with the key. + * + * @details This flag allows the key to be used for a MAC calculation operation or for an + * asymmetric message signature operation, if otherwise permitted by the key’s type and + * policy. The flag must be present on keys used with the following APIs: + * - @ref psa_mac_compute() + * - @ref psa_mac_sign_setup() + * - @ref psa_sign_message() + * + * For a key pair, this concerns the private key. + */ +#define PSA_KEY_USAGE_SIGN_MESSAGE ((psa_key_usage_t)0x00000400) + +/** + * @brief Permission to verify a message signature with the key. + * + * @details This flag allows the key to be used for a MAC verification operation or for an + * asymmetric message signature verification operation, if otherwise permitted by the + * key’s type and policy. The flag must be present on keys used with the following APIs: + * - @ref psa_mac_verify() + * - @ref psa_mac_verify_setup() + * - @ref psa_verify_message() + * + * For a key pair, this concerns the public key. + */ +#define PSA_KEY_USAGE_VERIFY_MESSAGE ((psa_key_usage_t)0x00000800) + +/** + * @brief Permission to sign a message hash with the key. + * + * @details This flag allows the key to be used to sign a message hash as part of an asymmetric + * signature operation, if otherwise permitted by the key’s type and policy. The flag must + * be present on keys used when calling @ref psa_sign_hash(). + * + * This flag automatically sets @ref PSA_KEY_USAGE_SIGN_MESSAGE : if an application sets + * the flag @ref PSA_KEY_USAGE_SIGN_HASH when creating a key, then the key always has the + * permissions conveyed by @ref PSA_KEY_USAGE_SIGN_MESSAGE, and the flag + * @ref PSA_KEY_USAGE_SIGN_MESSAGE will also be present when the application queries the + * usage flags of the key. + * + * For a key pair, this concerns the private key. + */ +#define PSA_KEY_USAGE_SIGN_HASH ((psa_key_usage_t)0x00001000) + +/** + * @brief Permission to verify a message hash with the key. + * + * @details This flag allows the key to be used to verify a message hash as part of an asymmetric + * signature verification operation, if otherwise permitted by the key’s type and policy. + * The flag must be present on keys used when calling @ref psa_verify_hash(). + * + * This flag automatically sets @ref PSA_KEY_USAGE_VERIFY_MESSAGE : if an application sets + * the flag @ref PSA_KEY_USAGE_VERIFY_HASH when creating a key, then the key always has + * the permissions conveyed by @ref PSA_KEY_USAGE_VERIFY_MESSAGE, and the flag + * @ref PSA_KEY_USAGE_VERIFY_MESSAGE will also be present when the application queries the + * usage flags of the key. + * + * For a key pair, this concerns the public key. + */ +#define PSA_KEY_USAGE_VERIFY_HASH ((psa_key_usage_t)0x00002000) + +/** + * @brief Permission to derive other keys or produce a password hash from this key. + * + * @details This flag allows the key to be used for a key derivation operation or for a key + * agreement operation, if otherwise permitted by the key’s type and policy. + * + * This flag must be present on keys used with the following APIs: + * - @ref psa_key_derivation_key_agreement() + * - @ref psa_raw_key_agreement() + * + * If this flag is present on all keys used in calls to + * @ref psa_key_derivation_input_key() for a key derivation operation, then it permits + * calling @ref psa_key_derivation_output_bytes() or @ref psa_key_derivation_output_key() + * at the end of the operation. + */ +#define PSA_KEY_USAGE_DERIVE ((psa_key_usage_t)0x00004000) + +/** + * @brief Permission to verify the result of a key derivation, including password hashing. + * + * @details This flag allows the key to be used in a key derivation operation, if otherwise + * permitted by the key’s type and policy. + * + * This flag must be present on keys used with @ref psa_key_derivation_verify_key(). + * + * If this flag is present on all keys used in calls to + * @ref psa_key_derivation_input_key() for a key derivation operation, then it permits + * calling @ref psa_key_derivation_verify_bytes() or @ref psa_key_derivation_verify_key() + * at the end of the operation. + */ +#define PSA_KEY_USAGE_VERIFY_DERIVATION ((psa_key_usage_t)0x00008000) + +#ifdef __cplusplus +} +#endif + +#endif /* PSA_CRYPTO_PSA_KEY_USAGE_H */ +/** @} */