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