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