1 /* 2 * Copyright (c) 2018-2021, Arm Limited. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 * 6 */ 7 /** 8 * \file psa/crypto_types.h 9 * 10 * \brief PSA cryptography module: type aliases. 11 * 12 * \note This file may not be included directly. Applications must 13 * include psa/crypto.h. Drivers must include the appropriate driver 14 * header file. 15 * 16 * This file contains portable definitions of integral types for properties 17 * of cryptographic keys, designations of cryptographic algorithms, and 18 * error codes returned by the library. 19 * 20 * This header file does not declare any function. 21 */ 22 23 #ifndef PSA_CRYPTO_TYPES_H 24 #define PSA_CRYPTO_TYPES_H 25 26 #include <stdint.h> 27 28 /** \defgroup error Error codes 29 * @{ 30 */ 31 32 /** 33 * \brief Function return status. 34 * 35 * This is either #PSA_SUCCESS (which is zero), indicating success, 36 * or a small negative value indicating that an error occurred. Errors are 37 * encoded as one of the \c PSA_ERROR_xxx values defined here. */ 38 /* If #PSA_SUCCESS is already defined, it means that #psa_status_t 39 * is also defined in an external header, so prevent its multiple 40 * definition. 41 */ 42 #ifndef PSA_SUCCESS 43 typedef int32_t psa_status_t; 44 #endif 45 46 /**@}*/ 47 48 /** \defgroup crypto_types Key and algorithm types 49 * @{ 50 */ 51 52 /** \brief Encoding of a key type. 53 */ 54 typedef uint16_t psa_key_type_t; 55 56 /** The type of PSA elliptic curve family identifiers. 57 * 58 * The curve identifier is required to create an ECC key using the 59 * PSA_KEY_TYPE_ECC_KEY_PAIR() or PSA_KEY_TYPE_ECC_PUBLIC_KEY() 60 * macros. 61 * 62 * Values defined by this standard will never be in the range 0x80-0xff. 63 * Vendors who define additional families must use an encoding in this range. 64 */ 65 typedef uint8_t psa_ecc_family_t; 66 67 /** The type of PSA Diffie-Hellman group family identifiers. 68 * 69 * The group identifier is required to create an Diffie-Hellman key using the 70 * PSA_KEY_TYPE_DH_KEY_PAIR() or PSA_KEY_TYPE_DH_PUBLIC_KEY() 71 * macros. 72 * 73 * Values defined by this standard will never be in the range 0x80-0xff. 74 * Vendors who define additional families must use an encoding in this range. 75 */ 76 typedef uint8_t psa_dh_family_t; 77 78 /** \brief Encoding of a cryptographic algorithm. 79 * 80 * For algorithms that can be applied to multiple key types, this type 81 * does not encode the key type. For example, for symmetric ciphers 82 * based on a block cipher, #psa_algorithm_t encodes the block cipher 83 * mode and the padding mode while the block cipher itself is encoded 84 * via #psa_key_type_t. 85 */ 86 typedef uint32_t psa_algorithm_t; 87 88 /**@}*/ 89 90 /** \defgroup key_lifetimes Key lifetimes 91 * @{ 92 */ 93 94 /** Encoding of key lifetimes. 95 * 96 * The lifetime of a key indicates where it is stored and what system actions 97 * may create and destroy it. 98 * 99 * Lifetime values have the following structure: 100 * - Bits 0-7 (#PSA_KEY_LIFETIME_GET_PERSISTENCE(\c lifetime)): 101 * persistence level. This value indicates what device management 102 * actions can cause it to be destroyed. In particular, it indicates 103 * whether the key is _volatile_ or _persistent_. 104 * See ::psa_key_persistence_t for more information. 105 * - Bits 8-31 (#PSA_KEY_LIFETIME_GET_LOCATION(\c lifetime)): 106 * location indicator. This value indicates where the key is stored 107 * and where operations on the key are performed. 108 * See ::psa_key_location_t for more information. 109 * 110 * Volatile keys are automatically destroyed when the application instance 111 * terminates or on a power reset of the device. Persistent keys are 112 * preserved until the application explicitly destroys them or until an 113 * implementation-specific device management event occurs (for example, 114 * a factory reset). 115 * 116 * Persistent keys have a key identifier of type #psa_key_id_t. 117 * This identifier remains valid throughout the lifetime of the key, 118 * even if the application instance that created the key terminates. 119 * The application can call psa_open_key() to open a persistent key that 120 * it created previously. 121 * 122 * This specification defines two basic lifetime values: 123 * - Keys with the lifetime #PSA_KEY_LIFETIME_VOLATILE are volatile. 124 * All implementations should support this lifetime. 125 * - Keys with the lifetime #PSA_KEY_LIFETIME_PERSISTENT are persistent. 126 * All implementations that have access to persistent storage with 127 * appropriate security guarantees should support this lifetime. 128 */ 129 typedef uint32_t psa_key_lifetime_t; 130 131 /** Encoding of key persistence levels. 132 * 133 * What distinguishes different persistence levels is what device management 134 * events may cause keys to be destroyed. _Volatile_ keys are destroyed 135 * by a power reset. Persistent keys may be destroyed by events such as 136 * a transfer of ownership or a factory reset. What management events 137 * actually affect persistent keys at different levels is outside the 138 * scope of the PSA Cryptography specification. 139 * 140 * This specification defines the following values of persistence levels: 141 * - \c 0 = #PSA_KEY_PERSISTENCE_VOLATILE: volatile key. 142 * A volatile key is automatically destroyed by the implementation when 143 * the application instance terminates. In particular, a volatile key 144 * is automatically destroyed on a power reset of the device. 145 * - \c 1 = #PSA_KEY_PERSISTENCE_DEFAULT: 146 * persistent key with a default lifetime. 147 * Implementations should support this value if they support persistent 148 * keys at all. 149 * Applications should use this value if they have no specific needs that 150 * are only met by implementation-specific features. 151 * - \c 2-127: persistent key with a PSA-specified lifetime. 152 * The PSA Cryptography specification does not define the meaning of these 153 * values, but other PSA specifications may do so. 154 * - \c 128-254: persistent key with a vendor-specified lifetime. 155 * No PSA specification will define the meaning of these values, so 156 * implementations may choose the meaning freely. 157 * As a guideline, higher persistence levels should cause a key to survive 158 * more management events than lower levels. 159 * - \c 255 = #PSA_KEY_PERSISTENCE_READ_ONLY: 160 * read-only or write-once key. 161 * A key with this persistence level cannot be destroyed. 162 * Implementations that support such keys may either allow their creation 163 * through the PSA Cryptography API, preferably only to applications with 164 * the appropriate privilege, or only expose keys created through 165 * implementation-specific means such as a factory ROM engraving process. 166 * Note that keys that are read-only due to policy restrictions 167 * rather than due to physical limitations should not have this 168 * persistence levels. 169 * 170 * \note Key persistence levels are 8-bit values. Key management 171 * interfaces operate on lifetimes (type ::psa_key_lifetime_t) which 172 * encode the persistence as the lower 8 bits of a 32-bit value. 173 */ 174 typedef uint8_t psa_key_persistence_t; 175 176 /** Encoding of key location indicators. 177 * 178 * If an implementation of this API can make calls to external 179 * cryptoprocessors such as secure elements, the location of a key 180 * indicates which secure element performs the operations on the key. 181 * If an implementation offers multiple physical locations for persistent 182 * storage, the location indicator reflects at which physical location 183 * the key is stored. 184 * 185 * This specification defines the following values of location indicators: 186 * - \c 0: primary local storage. 187 * All implementations should support this value. 188 * The primary local storage is typically the same storage area that 189 * contains the key metadata. 190 * - \c 1: primary secure element. 191 * Implementations should support this value if there is a secure element 192 * attached to the operating environment. 193 * As a guideline, secure elements may provide higher resistance against 194 * side channel and physical attacks than the primary local storage, but may 195 * have restrictions on supported key types, sizes, policies and operations 196 * and may have different performance characteristics. 197 * - \c 2-0x7fffff: other locations defined by a PSA specification. 198 * The PSA Cryptography API does not currently assign any meaning to these 199 * locations, but future versions of this specification or other PSA 200 * specifications may do so. 201 * - \c 0x800000-0xffffff: vendor-defined locations. 202 * No PSA specification will assign a meaning to locations in this range. 203 * 204 * \note Key location indicators are 24-bit values. Key management 205 * interfaces operate on lifetimes (type ::psa_key_lifetime_t) which 206 * encode the location as the upper 24 bits of a 32-bit value. 207 */ 208 typedef uint32_t psa_key_location_t; 209 210 /** Encoding of identifiers of persistent keys. 211 * 212 * - Applications may freely choose key identifiers in the range 213 * #PSA_KEY_ID_USER_MIN to #PSA_KEY_ID_USER_MAX. 214 * - Implementations may define additional key identifiers in the range 215 * #PSA_KEY_ID_VENDOR_MIN to #PSA_KEY_ID_VENDOR_MAX. 216 * - 0 is reserved as an invalid key identifier. 217 * - Key identifiers outside these ranges are reserved for future use. 218 */ 219 typedef uint32_t psa_key_id_t; 220 221 /** Key handle for open keys 222 * 223 * This type is used as a handle returned by psa_open_key which is planned 224 * to be deprecated. Until it is, psa_key_handle_t must have the same 225 * number of bits as psa_key_id_t as there are operations where the types 226 * are used interchangeably 227 */ 228 typedef psa_key_id_t psa_key_handle_t; 229 230 /**@}*/ 231 232 /** \defgroup policy Key policies 233 * @{ 234 */ 235 236 /** \brief Encoding of permitted usage on a key. */ 237 typedef uint32_t psa_key_usage_t; 238 239 /**@}*/ 240 241 /** \defgroup attributes Key attributes 242 * @{ 243 */ 244 245 /** The type of a structure containing key attributes. 246 * 247 * This is an opaque structure that can represent the metadata of a key 248 * object. Metadata that can be stored in attributes includes: 249 * - The location of the key in storage, indicated by its key identifier 250 * and its lifetime. 251 * - The key's policy, comprising usage flags and a specification of 252 * the permitted algorithm(s). 253 * - Information about the key itself: the key type and its size. 254 * - Implementations may define additional attributes. 255 * 256 * The actual key material is not considered an attribute of a key. 257 * Key attributes do not contain information that is generally considered 258 * highly confidential. 259 * 260 * An attribute structure can be a simple data structure where each function 261 * `psa_set_key_xxx` sets a field and the corresponding function 262 * `psa_get_key_xxx` retrieves the value of the corresponding field. 263 * However, implementations may report values that are equivalent to the 264 * original one, but have a different encoding. For example, an 265 * implementation may use a more compact representation for types where 266 * many bit-patterns are invalid or not supported, and store all values 267 * that it does not support as a special marker value. In such an 268 * implementation, after setting an invalid value, the corresponding 269 * get function returns an invalid value which may not be the one that 270 * was originally stored. 271 * 272 * An attribute structure may contain references to auxiliary resources, 273 * for example pointers to allocated memory or indirect references to 274 * pre-calculated values. In order to free such resources, the application 275 * must call psa_reset_key_attributes(). As an exception, calling 276 * psa_reset_key_attributes() on an attribute structure is optional if 277 * the structure has only been modified by the following functions 278 * since it was initialized or last reset with psa_reset_key_attributes(): 279 * - psa_set_key_id() 280 * - psa_set_key_lifetime() 281 * - psa_set_key_type() 282 * - psa_set_key_bits() 283 * - psa_set_key_usage_flags() 284 * - psa_set_key_algorithm() 285 * 286 * Before calling any function on a key attribute structure, the application 287 * must initialize it by any of the following means: 288 * - Set the structure to all-bits-zero, for example: 289 * \code 290 * psa_key_attributes_t attributes; 291 * memset(&attributes, 0, sizeof(attributes)); 292 * \endcode 293 * - Initialize the structure to logical zero values, for example: 294 * \code 295 * psa_key_attributes_t attributes = {0}; 296 * \endcode 297 * - Initialize the structure to the initializer #PSA_KEY_ATTRIBUTES_INIT, 298 * for example: 299 * \code 300 * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT; 301 * \endcode 302 * - Assign the result of the function psa_key_attributes_init() 303 * to the structure, for example: 304 * \code 305 * psa_key_attributes_t attributes; 306 * attributes = psa_key_attributes_init(); 307 * \endcode 308 * 309 * A freshly initialized attribute structure contains the following 310 * values: 311 * 312 * - lifetime: #PSA_KEY_LIFETIME_VOLATILE. 313 * - key identifier: 0 (which is not a valid key identifier). 314 * - type: \c 0 (meaning that the type is unspecified). 315 * - key size: \c 0 (meaning that the size is unspecified). 316 * - usage flags: \c 0 (which allows no usage except exporting a public key). 317 * - algorithm: \c 0 (which allows no cryptographic usage, but allows 318 * exporting). 319 * 320 * A typical sequence to create a key is as follows: 321 * -# Create and initialize an attribute structure. 322 * -# If the key is persistent, call psa_set_key_id(). 323 * Also call psa_set_key_lifetime() to place the key in a non-default 324 * location. 325 * -# Set the key policy with psa_set_key_usage_flags() and 326 * psa_set_key_algorithm(). 327 * -# Set the key type with psa_set_key_type(). 328 * Skip this step if copying an existing key with psa_copy_key(). 329 * -# When generating a random key with psa_generate_key() or deriving a key 330 * with psa_key_derivation_output_key(), set the desired key size with 331 * psa_set_key_bits(). 332 * -# Call a key creation function: psa_import_key(), psa_generate_key(), 333 * psa_key_derivation_output_key() or psa_copy_key(). This function reads 334 * the attribute structure, creates a key with these attributes, and 335 * outputs a handle to the newly created key. 336 * -# The attribute structure is now no longer necessary. 337 * You may call psa_reset_key_attributes(), although this is optional 338 * with the workflow presented here because the attributes currently 339 * defined in this specification do not require any additional resources 340 * beyond the structure itself. 341 * 342 * A typical sequence to query a key's attributes is as follows: 343 * -# Call psa_get_key_attributes(). 344 * -# Call `psa_get_key_xxx` functions to retrieve the attribute(s) that 345 * you are interested in. 346 * -# Call psa_reset_key_attributes() to free any resources that may be 347 * used by the attribute structure. 348 * 349 * Once a key has been created, it is impossible to change its attributes. 350 */ 351 typedef struct psa_client_key_attributes_s psa_key_attributes_t; 352 353 /**@}*/ 354 355 /** \defgroup derivation Key derivation 356 * @{ 357 */ 358 359 /** \brief Encoding of the step of a key derivation. */ 360 typedef uint16_t psa_key_derivation_step_t; 361 362 /**@}*/ 363 364 #endif /* PSA_CRYPTO_TYPES_H */ 365