1 /** 2 * \file psa/crypto_types.h 3 * 4 * \brief PSA cryptography module: type aliases. 5 * 6 * \note This file may not be included directly. Applications must 7 * include psa/crypto.h. Drivers must include the appropriate driver 8 * header file. 9 * 10 * This file contains portable definitions of integral types for properties 11 * of cryptographic keys, designations of cryptographic algorithms, and 12 * error codes returned by the library. 13 * 14 * This header file does not declare any function. 15 */ 16 /* 17 * Copyright The Mbed TLS Contributors 18 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 19 */ 20 21 #ifndef PSA_CRYPTO_TYPES_H 22 #define PSA_CRYPTO_TYPES_H 23 24 /* Make sure the Mbed TLS configuration is visible. */ 25 #include "mbedtls/build_info.h" 26 /* Define the MBEDTLS_PRIVATE macro. */ 27 #include "mbedtls/private_access.h" 28 29 #if defined(MBEDTLS_PSA_CRYPTO_PLATFORM_FILE) 30 #include MBEDTLS_PSA_CRYPTO_PLATFORM_FILE 31 #else 32 #include "crypto_platform.h" 33 #endif 34 35 #include <stdint.h> 36 37 /** \defgroup error Error codes 38 * @{ 39 */ 40 41 /** 42 * \brief Function return status. 43 * 44 * This is either #PSA_SUCCESS (which is zero), indicating success, 45 * or a small negative value indicating that an error occurred. Errors are 46 * encoded as one of the \c PSA_ERROR_xxx values defined here. */ 47 /* If #PSA_SUCCESS is already defined, it means that #psa_status_t 48 * is also defined in an external header, so prevent its multiple 49 * definition. 50 */ 51 #ifndef PSA_SUCCESS 52 typedef int32_t psa_status_t; 53 #endif 54 55 /**@}*/ 56 57 /** \defgroup crypto_types Key and algorithm types 58 * @{ 59 */ 60 61 /** \brief Encoding of a key type. 62 * 63 * Values of this type are generally constructed by macros called 64 * `PSA_KEY_TYPE_xxx`. 65 * 66 * \note Values of this type are encoded in the persistent key store. 67 * Any changes to existing values will require bumping the storage 68 * format version and providing a translation when reading the old 69 * format. 70 */ 71 typedef uint16_t psa_key_type_t; 72 73 /** The type of PSA elliptic curve family identifiers. 74 * 75 * Values of this type are generally constructed by macros called 76 * `PSA_ECC_FAMILY_xxx`. 77 * 78 * The curve identifier is required to create an ECC key using the 79 * PSA_KEY_TYPE_ECC_KEY_PAIR() or PSA_KEY_TYPE_ECC_PUBLIC_KEY() 80 * macros. 81 * 82 * Values defined by this standard will never be in the range 0x80-0xff. 83 * Vendors who define additional families must use an encoding in this range. 84 * 85 * \note Values of this type are encoded in the persistent key store. 86 * Any changes to existing values will require bumping the storage 87 * format version and providing a translation when reading the old 88 * format. 89 */ 90 typedef uint8_t psa_ecc_family_t; 91 92 /** The type of PSA Diffie-Hellman group family identifiers. 93 * 94 * Values of this type are generally constructed by macros called 95 * `PSA_DH_FAMILY_xxx`. 96 * 97 * The group identifier is required to create a Diffie-Hellman key using the 98 * PSA_KEY_TYPE_DH_KEY_PAIR() or PSA_KEY_TYPE_DH_PUBLIC_KEY() 99 * macros. 100 * 101 * Values defined by this standard will never be in the range 0x80-0xff. 102 * Vendors who define additional families must use an encoding in this range. 103 * 104 * \note Values of this type are encoded in the persistent key store. 105 * Any changes to existing values will require bumping the storage 106 * format version and providing a translation when reading the old 107 * format. 108 */ 109 typedef uint8_t psa_dh_family_t; 110 111 /** \brief Encoding of a cryptographic algorithm. 112 * 113 * Values of this type are generally constructed by macros called 114 * `PSA_ALG_xxx`. 115 * 116 * For algorithms that can be applied to multiple key types, this type 117 * does not encode the key type. For example, for symmetric ciphers 118 * based on a block cipher, #psa_algorithm_t encodes the block cipher 119 * mode and the padding mode while the block cipher itself is encoded 120 * via #psa_key_type_t. 121 * 122 * \note Values of this type are encoded in the persistent key store. 123 * Any changes to existing values will require bumping the storage 124 * format version and providing a translation when reading the old 125 * format. 126 */ 127 typedef uint32_t psa_algorithm_t; 128 129 /**@}*/ 130 131 /** \defgroup key_lifetimes Key lifetimes 132 * @{ 133 */ 134 135 /** Encoding of key lifetimes. 136 * 137 * The lifetime of a key indicates where it is stored and what system actions 138 * may create and destroy it. 139 * 140 * Lifetime values have the following structure: 141 * - Bits 0-7 (#PSA_KEY_LIFETIME_GET_PERSISTENCE(\c lifetime)): 142 * persistence level. This value indicates what device management 143 * actions can cause it to be destroyed. In particular, it indicates 144 * whether the key is _volatile_ or _persistent_. 145 * See ::psa_key_persistence_t for more information. 146 * - Bits 8-31 (#PSA_KEY_LIFETIME_GET_LOCATION(\c lifetime)): 147 * location indicator. This value indicates which part of the system 148 * has access to the key material and can perform operations using the key. 149 * See ::psa_key_location_t for more information. 150 * 151 * Volatile keys are automatically destroyed when the application instance 152 * terminates or on a power reset of the device. Persistent keys are 153 * preserved until the application explicitly destroys them or until an 154 * integration-specific device management event occurs (for example, 155 * a factory reset). 156 * 157 * Persistent keys have a key identifier of type #mbedtls_svc_key_id_t. 158 * This identifier remains valid throughout the lifetime of the key, 159 * even if the application instance that created the key terminates. 160 * The application can call psa_open_key() to open a persistent key that 161 * it created previously. 162 * 163 * The default lifetime of a key is #PSA_KEY_LIFETIME_VOLATILE. The lifetime 164 * #PSA_KEY_LIFETIME_PERSISTENT is supported if persistent storage is 165 * available. Other lifetime values may be supported depending on the 166 * library configuration. 167 * 168 * Values of this type are generally constructed by macros called 169 * `PSA_KEY_LIFETIME_xxx`. 170 * 171 * \note Values of this type are encoded in the persistent key store. 172 * Any changes to existing values will require bumping the storage 173 * format version and providing a translation when reading the old 174 * format. 175 */ 176 typedef uint32_t psa_key_lifetime_t; 177 178 /** Encoding of key persistence levels. 179 * 180 * What distinguishes different persistence levels is what device management 181 * events may cause keys to be destroyed. _Volatile_ keys are destroyed 182 * by a power reset. Persistent keys may be destroyed by events such as 183 * a transfer of ownership or a factory reset. What management events 184 * actually affect persistent keys at different levels is outside the 185 * scope of the PSA Cryptography specification. 186 * 187 * The PSA Cryptography specification defines the following values of 188 * persistence levels: 189 * - \c 0 = #PSA_KEY_PERSISTENCE_VOLATILE: volatile key. 190 * A volatile key is automatically destroyed by the implementation when 191 * the application instance terminates. In particular, a volatile key 192 * is automatically destroyed on a power reset of the device. 193 * - \c 1 = #PSA_KEY_PERSISTENCE_DEFAULT: 194 * persistent key with a default lifetime. 195 * - \c 2-254: currently not supported by Mbed TLS. 196 * - \c 255 = #PSA_KEY_PERSISTENCE_READ_ONLY: 197 * read-only or write-once key. 198 * A key with this persistence level cannot be destroyed. 199 * Mbed TLS does not currently offer a way to create such keys, but 200 * integrations of Mbed TLS can use it for built-in keys that the 201 * application cannot modify (for example, a hardware unique key (HUK)). 202 * 203 * \note Key persistence levels are 8-bit values. Key management 204 * interfaces operate on lifetimes (type ::psa_key_lifetime_t) which 205 * encode the persistence as the lower 8 bits of a 32-bit value. 206 * 207 * \note Values of this type are encoded in the persistent key store. 208 * Any changes to existing values will require bumping the storage 209 * format version and providing a translation when reading the old 210 * format. 211 */ 212 typedef uint8_t psa_key_persistence_t; 213 214 /** Encoding of key location indicators. 215 * 216 * If an integration of Mbed TLS can make calls to external 217 * cryptoprocessors such as secure elements, the location of a key 218 * indicates which secure element performs the operations on the key. 219 * Depending on the design of the secure element, the key 220 * material may be stored either in the secure element, or 221 * in wrapped (encrypted) form alongside the key metadata in the 222 * primary local storage. 223 * 224 * The PSA Cryptography API specification defines the following values of 225 * location indicators: 226 * - \c 0: primary local storage. 227 * This location is always available. 228 * The primary local storage is typically the same storage area that 229 * contains the key metadata. 230 * - \c 1: primary secure element. 231 * Integrations of Mbed TLS should support this value if there is a secure 232 * element attached to the operating environment. 233 * As a guideline, secure elements may provide higher resistance against 234 * side channel and physical attacks than the primary local storage, but may 235 * have restrictions on supported key types, sizes, policies and operations 236 * and may have different performance characteristics. 237 * - \c 2-0x7fffff: other locations defined by a PSA specification. 238 * The PSA Cryptography API does not currently assign any meaning to these 239 * locations, but future versions of that specification or other PSA 240 * specifications may do so. 241 * - \c 0x800000-0xffffff: vendor-defined locations. 242 * No PSA specification will assign a meaning to locations in this range. 243 * 244 * \note Key location indicators are 24-bit values. Key management 245 * interfaces operate on lifetimes (type ::psa_key_lifetime_t) which 246 * encode the location as the upper 24 bits of a 32-bit value. 247 * 248 * \note Values of this type are encoded in the persistent key store. 249 * Any changes to existing values will require bumping the storage 250 * format version and providing a translation when reading the old 251 * format. 252 */ 253 typedef uint32_t psa_key_location_t; 254 255 /** Encoding of identifiers of persistent keys. 256 * 257 * - Applications may freely choose key identifiers in the range 258 * #PSA_KEY_ID_USER_MIN to #PSA_KEY_ID_USER_MAX. 259 * - The implementation may define additional key identifiers in the range 260 * #PSA_KEY_ID_VENDOR_MIN to #PSA_KEY_ID_VENDOR_MAX. 261 * - 0 is reserved as an invalid key identifier. 262 * - Key identifiers outside these ranges are reserved for future use. 263 * 264 * \note Values of this type are encoded in the persistent key store. 265 * Any changes to how values are allocated must require careful 266 * consideration to allow backward compatibility. 267 */ 268 typedef uint32_t psa_key_id_t; 269 270 /** Encoding of key identifiers as seen inside the PSA Crypto implementation. 271 * 272 * When PSA Crypto is built as a library inside an application, this type 273 * is identical to #psa_key_id_t. When PSA Crypto is built as a service 274 * that can store keys on behalf of multiple clients, this type 275 * encodes the #psa_key_id_t value seen by each client application as 276 * well as extra information that identifies the client that owns 277 * the key. 278 * 279 * \note Values of this type are encoded in the persistent key store. 280 * Any changes to existing values will require bumping the storage 281 * format version and providing a translation when reading the old 282 * format. 283 */ 284 #if !defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER) 285 typedef psa_key_id_t mbedtls_svc_key_id_t; 286 287 #else /* MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER */ 288 /* Implementation-specific: The Mbed TLS library can be built as 289 * part of a multi-client service that exposes the PSA Cryptography API in each 290 * client and encodes the client identity in the key identifier argument of 291 * functions such as psa_open_key(). 292 */ 293 typedef struct { 294 psa_key_id_t MBEDTLS_PRIVATE(key_id); 295 mbedtls_key_owner_id_t MBEDTLS_PRIVATE(owner); 296 } mbedtls_svc_key_id_t; 297 298 #endif /* !MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER */ 299 300 /**@}*/ 301 302 /** \defgroup policy Key policies 303 * @{ 304 */ 305 306 /** \brief Encoding of permitted usage on a key. 307 * 308 * Values of this type are generally constructed as bitwise-ors of macros 309 * called `PSA_KEY_USAGE_xxx`. 310 * 311 * \note Values of this type are encoded in the persistent key store. 312 * Any changes to existing values will require bumping the storage 313 * format version and providing a translation when reading the old 314 * format. 315 */ 316 typedef uint32_t psa_key_usage_t; 317 318 /**@}*/ 319 320 /** \defgroup attributes Key attributes 321 * @{ 322 */ 323 324 /** The type of a structure containing key attributes. 325 * 326 * This is an opaque structure that can represent the metadata of a key 327 * object. Metadata that can be stored in attributes includes: 328 * - The location of the key in storage, indicated by its key identifier 329 * and its lifetime. 330 * - The key's policy, comprising usage flags and a specification of 331 * the permitted algorithm(s). 332 * - Information about the key itself: the key type and its size. 333 * - Additional implementation-defined attributes. 334 * 335 * The actual key material is not considered an attribute of a key. 336 * Key attributes do not contain information that is generally considered 337 * highly confidential. 338 * 339 * An attribute structure works like a simple data structure where each function 340 * `psa_set_key_xxx` sets a field and the corresponding function 341 * `psa_get_key_xxx` retrieves the value of the corresponding field. 342 * However, a future version of the library may report values that are 343 * equivalent to the original one, but have a different encoding. Invalid 344 * values may be mapped to different, also invalid values. 345 * 346 * An attribute structure may contain references to auxiliary resources, 347 * for example pointers to allocated memory or indirect references to 348 * pre-calculated values. In order to free such resources, the application 349 * must call psa_reset_key_attributes(). As an exception, calling 350 * psa_reset_key_attributes() on an attribute structure is optional if 351 * the structure has only been modified by the following functions 352 * since it was initialized or last reset with psa_reset_key_attributes(): 353 * - psa_set_key_id() 354 * - psa_set_key_lifetime() 355 * - psa_set_key_type() 356 * - psa_set_key_bits() 357 * - psa_set_key_usage_flags() 358 * - psa_set_key_algorithm() 359 * 360 * Before calling any function on a key attribute structure, the application 361 * must initialize it by any of the following means: 362 * - Set the structure to all-bits-zero, for example: 363 * \code 364 * psa_key_attributes_t attributes; 365 * memset(&attributes, 0, sizeof(attributes)); 366 * \endcode 367 * - Initialize the structure to logical zero values, for example: 368 * \code 369 * psa_key_attributes_t attributes = {0}; 370 * \endcode 371 * - Initialize the structure to the initializer #PSA_KEY_ATTRIBUTES_INIT, 372 * for example: 373 * \code 374 * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT; 375 * \endcode 376 * - Assign the result of the function psa_key_attributes_init() 377 * to the structure, for example: 378 * \code 379 * psa_key_attributes_t attributes; 380 * attributes = psa_key_attributes_init(); 381 * \endcode 382 * 383 * A freshly initialized attribute structure contains the following 384 * values: 385 * 386 * - lifetime: #PSA_KEY_LIFETIME_VOLATILE. 387 * - key identifier: 0 (which is not a valid key identifier). 388 * - type: \c 0 (meaning that the type is unspecified). 389 * - key size: \c 0 (meaning that the size is unspecified). 390 * - usage flags: \c 0 (which allows no usage except exporting a public key). 391 * - algorithm: \c 0 (which allows no cryptographic usage, but allows 392 * exporting). 393 * 394 * A typical sequence to create a key is as follows: 395 * -# Create and initialize an attribute structure. 396 * -# If the key is persistent, call psa_set_key_id(). 397 * Also call psa_set_key_lifetime() to place the key in a non-default 398 * location. 399 * -# Set the key policy with psa_set_key_usage_flags() and 400 * psa_set_key_algorithm(). 401 * -# Set the key type with psa_set_key_type(). 402 * Skip this step if copying an existing key with psa_copy_key(). 403 * -# When generating a random key with psa_generate_key() or deriving a key 404 * with psa_key_derivation_output_key(), set the desired key size with 405 * psa_set_key_bits(). 406 * -# Call a key creation function: psa_import_key(), psa_generate_key(), 407 * psa_key_derivation_output_key() or psa_copy_key(). This function reads 408 * the attribute structure, creates a key with these attributes, and 409 * outputs a key identifier to the newly created key. 410 * -# The attribute structure is now no longer necessary. 411 * You may call psa_reset_key_attributes(), although this is optional 412 * with the workflow presented here because the attributes currently 413 * defined in this specification do not require any additional resources 414 * beyond the structure itself. 415 * 416 * A typical sequence to query a key's attributes is as follows: 417 * -# Call psa_get_key_attributes(). 418 * -# Call `psa_get_key_xxx` functions to retrieve the attribute(s) that 419 * you are interested in. 420 * -# Call psa_reset_key_attributes() to free any resources that may be 421 * used by the attribute structure. 422 * 423 * Once a key has been created, it is impossible to change its attributes. 424 */ 425 typedef struct psa_key_attributes_s psa_key_attributes_t; 426 427 428 #ifndef __DOXYGEN_ONLY__ 429 #if defined(MBEDTLS_PSA_CRYPTO_SE_C) 430 /* Mbed TLS defines this type in crypto_types.h because it is also 431 * visible to applications through an implementation-specific extension. 432 * For the PSA Cryptography specification, this type is only visible 433 * via crypto_se_driver.h. */ 434 typedef uint64_t psa_key_slot_number_t; 435 #endif /* MBEDTLS_PSA_CRYPTO_SE_C */ 436 #endif /* !__DOXYGEN_ONLY__ */ 437 438 /**@}*/ 439 440 /** \defgroup derivation Key derivation 441 * @{ 442 */ 443 444 /** \brief Encoding of the step of a key derivation. 445 * 446 * Values of this type are generally constructed by macros called 447 * `PSA_KEY_DERIVATION_INPUT_xxx`. 448 */ 449 typedef uint16_t psa_key_derivation_step_t; 450 451 /**@}*/ 452 453 #endif /* PSA_CRYPTO_TYPES_H */ 454
