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