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