1 /* 2 * Copyright (c) 2022-2024, Texas Instruments Incorporated 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of Texas Instruments Incorporated nor the names of 17 * its contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 /** ============================================================================ 34 * @file CryptoKeyKeyStore_PSA.h 35 * @brief CryptoKeyKeyStore_PSA driver header 36 * 37 * @warning This is a beta API. It may change in future releases. 38 * 39 * # Overview # 40 * This file contains the APIs to import, export, copy, and destroy key store 41 * CryptoKeys. Key store CryptoKeys reference keying material stored in flash or 42 * RAM using a key identifier. These CryptoKeys are subject to enforced usage 43 * restrictions as defined by the key attributes assigned during key import. 44 * This file provides definitions that are common between the Non-Secure 45 * Processing Environment (NSPE) and Secure Processing Environment (SPE). 46 * 47 * # Usage # 48 * 49 * After calling the key store initialization function, a CryptoKey must be 50 * imported into the key store before it can be used for a crypto operation APIs 51 * which takes a CryptoKey as an input. 52 53 * @anchor ti_drivers_cryptoutils_cryptokey_CryptoKeyKeyStore_PSA_Example 54 * 55 * ## Importing and destroying a persistent AES-CCM KeyStore key # 56 * 57 * @code 58 * 59 * #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyKeyStore_PSA.h> 60 * #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyKeyStore_PSA_helpers.h> 61 * .... 62 * 63 * uint8_t keyingMaterial[16] = {0x1f, 0x8e, 0x49, 0x73, 0x95, 0x3f, 0x3f, 0xb0, 64 * 0xbd, 0x6b, 0x16, 0x66, 0x2e, 0x9a, 0x3c, 0x17}; 65 * CryptoKey cryptoKey; 66 * KeyStore_PSA_KeyFileId keyID; 67 * int_fast16_t status; 68 * KeyStore_PSA_KeyAttributes attributes = KEYSTORE_PSA_KEY_ATTRIBUTES_INIT; 69 * 70 * // Assign key attributes 71 * KeyStore_PSA_setKeyUsageFlags(&attributes, (KEYSTORE_PSA_KEY_USAGE_DECRYPT | KEYSTORE_PSA_KEY_USAGE_ENCRYPT)); 72 * KeyStore_PSA_setKeyAlgorithm(&attributes, KEYSTORE_PSA_ALG_CCM); 73 * KeyStore_PSA_setKeyType(&attributes, KEYSTORE_PSA_KEY_TYPE_AES); 74 * KeyStore_PSA_setKeyLifetime(&attributes, KEYSTORE_PSA_KEY_LIFETIME_PERSISTENT); 75 * 76 * // Set key ID 77 * GET_KEY_ID(keyID, KEYSTORE_PSA_KEY_ID_USER_MIN); 78 * KeyStore_PSA_setKeyId(&attributes, keyID); 79 * 80 * // Import the keyingMaterial 81 * status = KeyStore_PSA_importKey(&attributes, keyingMaterial, sizeof(keyingMaterial), &keyID); 82 * 83 * if (status != KEYSTORE_PSA_STATUS_SUCCESS) 84 * { 85 * // Handle error 86 * } 87 * 88 * // Initialize cryptoKey for crypto operations 89 * KeyStore_PSA_initKey(&cryptoKey, keyID, sizeof(keyingMaterial), NULL); 90 * 91 * // Use the cryptoKey for AESCCM operations 92 * 93 * // Destroy key after use 94 * status = KeyStore_PSA_destroyKey(keyID); 95 * 96 * if (status != KEYSTORE_PSA_STATUS_SUCCESS) 97 * { 98 * // Handle error 99 * } 100 * @endcode 101 * 102 */ 103 104 #ifndef ti_drivers_CryptoKeyKeyStore_PSA__include 105 #define ti_drivers_CryptoKeyKeyStore_PSA__include 106 107 #if (TFM_ENABLED == 0) || defined(TFM_BUILD) /* TFM_BUILD indicates this is a TF-M build */ 108 #include <third_party/mbedtls/include/psa/crypto.h> 109 #include <third_party/mbedtls/include/psa/crypto_extra.h> 110 #include <third_party/mbedtls/include/mbedtls/build_info.h> 111 #include <third_party/mbedtls/include/mbedtls/private_access.h> 112 #include <third_party/mbedtls/ti/driver/ti_sl_transparent_driver_entrypoints.h> 113 #else 114 #include <third_party/tfm/interface/include/psa/crypto.h> 115 #endif /* #if (TFM_ENABLED == 0) || defined(TFM_BUILD) */ 116 117 #ifdef __cplusplus 118 extern "C" { 119 #endif 120 121 /** @brief Encoding of permitted usage on a key. */ 122 typedef psa_key_usage_t KeyStore_PSA_KeyUsage; 123 124 /** Encoding of key lifetimes. 125 * 126 * The lifetime of a key indicates where it is stored and what system 127 * actions may create and destroy it. 128 * 129 * Lifetime values have the following structure: 130 * - Bits 0-7 (#KEYSTORE_PSA_KEY_LIFETIME_GET_PERSISTENCE(\c lifetime)): 131 * persistence level. This value indicates what device management 132 * actions can cause it to be destroyed. In particular, it indicates 133 * whether the key is _volatile_ or _persistent_. 134 * See ::KeyStore_PSA_KeyPersistence for more information. 135 * - Bits 8-31 (#KEYSTORE_PSA_KEY_LIFETIME_GET_LOCATION(\c lifetime)): 136 * location indicator. This value indicates which part of the system 137 * has access to the key material and can perform operations using the key. 138 * See ::KeyStore_PSA_KeyLocation for more information. 139 * 140 * Volatile keys are automatically destroyed when the application instance 141 * terminates or on a power reset of the device. Persistent keys are 142 * preserved until the application explicitly destroys them or until an 143 * integration-specific device management event occurs (for example, 144 * a factory reset). 145 * 146 * Persistent keys have a key identifier of type #KeyStore_PSA_KeyFileId. 147 * This identifier remains valid throughout the lifetime of the key, 148 * even if the application instance that created the key terminates. 149 * 150 * The default lifetime of a key is #KEYSTORE_PSA_KEY_LIFETIME_VOLATILE. The lifetime 151 * #KEYSTORE_PSA_KEY_LIFETIME_PERSISTENT is supported if persistent storage is 152 * available. Other lifetime values may be supported depending on the 153 * library configuration. 154 * 155 * Values of this type are generally constructed by macros called 156 * `KEYSTORE_PSA_KEY_LIFETIME_xxx`. 157 * 158 * @note Values of this type are encoded in the persistent key store. 159 * Any changes to existing values will require bumping the storage 160 * format version and providing a translation when reading the old 161 * format. 162 */ 163 typedef psa_key_lifetime_t KeyStore_PSA_KeyLifetime; 164 165 /** Encoding of key persistence levels. 166 * 167 * What distinguishes different persistence levels is what device management 168 * events may cause keys to be destroyed. _Volatile_ keys are destroyed 169 * by a power reset. Persistent keys may be destroyed by events such as 170 * a transfer of ownership or a factory reset. What management events 171 * actually affect persistent keys at different levels is outside the 172 * scope of the PSA Cryptography specification. 173 * 174 * The PSA Cryptography specification defines the following values of 175 * persistence levels: 176 * - \c 0 = #KEYSTORE_PSA_KEY_PERSISTENCE_VOLATILE: volatile key. 177 * A volatile key is automatically destroyed by the implementation when 178 * the application instance terminates. In particular, a volatile key 179 * is automatically destroyed on a power reset of the device. 180 * - \c 1 = #KEYSTORE_PSA_KEY_PERSISTENCE_DEFAULT: 181 * persistent key with a default lifetime. 182 * - \c 2-254: currently not supported by Mbed TLS. 183 * - \c 255 = #KEYSTORE_PSA_KEY_PERSISTENCE_READ_ONLY: 184 * read-only or write-once key. 185 * A key with this persistence level cannot be destroyed. 186 * Mbed TLS does not currently offer a way to create such keys, but 187 * integrations of Mbed TLS can use it for built-in keys that the 188 * application cannot modify (for example, a hardware unique key (HUK)). 189 * 190 * @note Key persistence levels are 8-bit values. Key management 191 * interfaces operate on lifetimes (type ::KeyStore_PSA_KeyLifetime) which 192 * encode the persistence as the lower 8 bits of a 32-bit value. 193 * 194 * @note Values of this type are encoded in the persistent key store. 195 * Any changes to existing values will require bumping the storage 196 * format version and providing a translation when reading the old 197 * format. 198 */ 199 typedef psa_key_persistence_t KeyStore_PSA_KeyPersistence; 200 201 /** Encoding of key location indicators. 202 * 203 * If an application can make calls to external 204 * cryptoprocessors such as secure elements, the location of a key 205 * indicates which secure element performs the operations on the key. 206 * Depending on the design of the secure element, the key 207 * material may be stored either in the secure element, or 208 * in wrapped (encrypted) form alongside the key metadata in the 209 * primary local storage. 210 * 211 * The PSA Cryptography API specification defines the following values of 212 * location indicators: 213 * - \c 0: primary local storage. 214 * This location is always available. 215 * The primary local storage is typically the same storage area that 216 * contains the key metadata. 217 * - \c 1: primary secure element. 218 * Integrations of Mbed TLS should support this value if there is a secure 219 * element attached to the operating environment. 220 * As a guideline, secure elements may provide higher resistance against 221 * side channel and physical attacks than the primary local storage, but may 222 * have restrictions on supported key types, sizes, policies and operations 223 * and may have different performance characteristics. 224 * - \c 2-0x7fffff: other locations defined by a PSA specification. 225 * The PSA Cryptography API does not currently assign any meaning to these 226 * locations, but future versions of that specification or other PSA 227 * specifications may do so. 228 * - \c 0x800000-0xffffff: vendor-defined locations. 229 * No PSA specification will assign a meaning to locations in this range. 230 * 231 * @note Key location indicators are 24-bit values. Key management 232 * interfaces operate on lifetimes (type ::KeyStore_PSA_KeyLifetime) which 233 * encode the location as the upper 24 bits of a 32-bit value. 234 * 235 * @note Values of this type are encoded in the persistent key store. 236 * Any changes to existing values will require bumping the storage 237 * format version and providing a translation when reading the old 238 * format. 239 */ 240 typedef psa_key_location_t KeyStore_PSA_KeyLocation; 241 242 /** @defgroup KeyStore_PSA_Statuses Key Store status return values. 243 */ 244 /** The action was completed successfully. */ 245 #define KEYSTORE_PSA_STATUS_SUCCESS ((int_fast16_t)PSA_SUCCESS) 246 247 /** An error occurred that does not correspond to any defined 248 * failure cause. 249 * 250 * Implementations may use this error code if none of the other standard 251 * error codes are applicable. */ 252 #define KEYSTORE_PSA_STATUS_GENERIC_ERROR ((int_fast16_t)PSA_ERROR_GENERIC_ERROR) 253 254 /** The requested operation or a parameter is not supported 255 * by this implementation. 256 * 257 * Implementations should return this error code when an enumeration 258 * parameter such as a key type, algorithm, etc. is not recognized. 259 * If a combination of parameters is recognized and identified as 260 * not valid, return #KEYSTORE_PSA_STATUS_INVALID_ARGUMENT instead. */ 261 #define KEYSTORE_PSA_STATUS_NOT_SUPPORTED ((int_fast16_t)PSA_ERROR_NOT_SUPPORTED) 262 263 /** The requested action is denied by a policy. 264 * 265 * Implementations should return this error code when the parameters 266 * are recognized as valid and supported, and a policy explicitly 267 * denies the requested operation. 268 * 269 * If a subset of the parameters of a function call identify a 270 * forbidden operation, and another subset of the parameters are 271 * not valid or not supported, it is unspecified whether the function 272 * returns #KEYSTORE_PSA_STATUS_NOT_PERMITTED, #KEYSTORE_PSA_STATUS_NOT_SUPPORTED or 273 * #KEYSTORE_PSA_STATUS_INVALID_ARGUMENT. */ 274 #define KEYSTORE_PSA_STATUS_NOT_PERMITTED ((int_fast16_t)PSA_ERROR_NOT_PERMITTED) 275 276 /** The key ID is not valid or does not exist. 277 */ 278 #define KEYSTORE_PSA_STATUS_INVALID_KEY_ID ((int_fast16_t)PSA_ERROR_INVALID_HANDLE) 279 280 /** An output buffer is too small. 281 * 282 * Applications can call the @c PSA_xxx_SIZE macro listed in the function 283 * description to determine a sufficient buffer size. 284 * 285 * Implementations should preferably return this error code only 286 * in cases when performing the operation with a larger output 287 * buffer would succeed. However implementations may return this 288 * error if a function has invalid or unsupported parameters in addition 289 * to the parameters that determine the necessary output buffer size. */ 290 #define KEYSTORE_PSA_STATUS_BUFFER_TOO_SMALL ((int_fast16_t)PSA_ERROR_BUFFER_TOO_SMALL) 291 292 /** Asking for an item that already exists 293 * 294 * Implementations should return this error, when attempting 295 * to write an item (like a key) that already exists. */ 296 #define KEYSTORE_PSA_STATUS_ALREADY_EXISTS ((int_fast16_t)PSA_ERROR_ALREADY_EXISTS) 297 298 /** Asking for an item that doesn't exist 299 * 300 * Implementations should return this error, if a requested item (like 301 * a key) does not exist. */ 302 #define KEYSTORE_PSA_STATUS_DOES_NOT_EXIST ((int_fast16_t)PSA_ERROR_DOES_NOT_EXIST) 303 304 /** The requested action cannot be performed in the current state. 305 * 306 * Multipart operations return this error when one of the 307 * functions is called out of sequence. Refer to the function 308 * descriptions for permitted sequencing of functions. 309 * 310 * Implementations shall not return this error code to indicate that a key 311 * either exists or not, but shall instead return 312 * #KEYSTORE_PSA_STATUS_ALREADY_EXISTS or #KEYSTORE_PSA_STATUS_DOES_NOT_EXIST as 313 * applicable. 314 * 315 * Implementations shall not return this error code to indicate that a 316 * key ID is invalid, but shall return #KEYSTORE_PSA_STATUS_INVALID_KEY_ID 317 * instead. */ 318 #define KEYSTORE_PSA_STATUS_BAD_STATE ((int_fast16_t)PSA_ERROR_BAD_STATE) 319 320 /** The parameters passed to the function are invalid. 321 * 322 * Implementations may return this error any time a parameter or 323 * combination of parameters are recognized as invalid. 324 * 325 * Implementations shall not return this error code to indicate that a 326 * key ID is invalid, but shall return #KEYSTORE_PSA_STATUS_INVALID_KEY_ID 327 * instead. 328 */ 329 #define KEYSTORE_PSA_STATUS_INVALID_ARGUMENT ((int_fast16_t)PSA_ERROR_INVALID_ARGUMENT) 330 331 /** There is not enough runtime memory. 332 * 333 * If the action is carried out across multiple security realms, this 334 * error can refer to available memory in any of the security realms. */ 335 #define KEYSTORE_PSA_STATUS_INSUFFICIENT_MEMORY ((int_fast16_t)PSA_ERROR_INSUFFICIENT_MEMORY) 336 337 /** There is not enough persistent storage. 338 * 339 * Functions that modify the key storage return this error code if 340 * there is insufficient storage space on the host media. In addition, 341 * many functions that do not otherwise access storage may return this 342 * error code if the implementation requires a mandatory log entry for 343 * the requested action and the log storage space is full. */ 344 #define KEYSTORE_PSA_STATUS_INSUFFICIENT_STORAGE ((int_fast16_t)PSA_ERROR_INSUFFICIENT_STORAGE) 345 346 /** There was a communication failure inside the implementation. 347 * 348 * This can indicate a communication failure between the application 349 * and an external cryptoprocessor or between the cryptoprocessor and 350 * an external volatile or persistent memory. A communication failure 351 * may be transient or permanent depending on the cause. 352 * 353 * @warning If a function returns this error, it is undetermined 354 * whether the requested action has completed or not. Implementations 355 * should return #KEYSTORE_PSA_STATUS_SUCCESS on successful completion 356 * whenever possible, however functions may return 357 * #KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE if the requested action was completed 358 * successfully in an external cryptoprocessor but there was a breakdown of 359 * communication before the cryptoprocessor could report the status to the 360 * application. 361 */ 362 #define KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE ((int_fast16_t)PSA_ERROR_COMMUNICATION_FAILURE) 363 364 /** There was a storage failure that may have led to data loss. 365 * 366 * This error indicates that some persistent storage is corrupted. 367 * It should not be used for a corruption of volatile memory 368 * (use #KEYSTORE_PSA_STATUS_CORRUPTION_DETECTED), for a communication error 369 * between the cryptoprocessor and its external storage (use 370 * #KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE), or when the storage is 371 * in a valid state but is full (use #KEYSTORE_PSA_STATUS_INSUFFICIENT_STORAGE). 372 * 373 * Note that a storage failure does not indicate that any data that was 374 * previously read is invalid. However this previously read data may no 375 * longer be readable from storage. 376 * 377 * When a storage failure occurs, it is no longer possible to ensure 378 * the global integrity of the keystore. Depending on the global 379 * integrity guarantees offered by the implementation, access to other 380 * data may or may not fail even if the data is still readable but 381 * its integrity cannot be guaranteed. 382 * 383 * Implementations should only use this error code to report a 384 * permanent storage corruption. However application writers should 385 * keep in mind that transient errors while reading the storage may be 386 * reported using this error code. */ 387 #define KEYSTORE_PSA_STATUS_STORAGE_FAILURE ((int_fast16_t)PSA_ERROR_STORAGE_FAILURE) 388 389 /** A hardware failure was detected. 390 * 391 * A hardware failure may be transient or permanent depending on the 392 * cause. */ 393 #define KEYSTORE_PSA_STATUS_HARDWARE_FAILURE ((int_fast16_t)PSA_ERROR_HARDWARE_FAILURE) 394 395 /** There is not enough entropy to generate random data needed 396 * for the requested action. 397 * 398 * This error indicates a failure of a hardware random generator. 399 * Application writers should note that this error can be returned not 400 * only by functions whose purpose is to generate random data, such 401 * as key, IV or nonce generation, but also by functions that execute 402 * an algorithm with a randomized result, as well as functions that 403 * use randomization of intermediate computations as a countermeasure 404 * to certain attacks. 405 * 406 * Implementations should avoid returning this error after KeyStore_PSA_init() 407 * has succeeded. Implementations should generate sufficient 408 * entropy during initialization and subsequently use a cryptographically 409 * secure pseudorandom generator (PRNG). However implementations may return 410 * this error at any time if a policy requires the PRNG to be reseeded 411 * during normal operation. */ 412 #define KEYSTORE_PSA_STATUS_INSUFFICIENT_ENTROPY ((int_fast16_t)PSA_ERROR_INSUFFICIENT_ENTROPY) 413 414 /** A tampering attempt was detected. 415 * 416 * If an application receives this error code, there is no guarantee 417 * that previously accessed or computed data was correct and remains 418 * confidential. Applications should not perform any security function 419 * and should enter a safe failure state. 420 * 421 * Implementations may return this error code if they detect an invalid 422 * state that cannot happen during normal operation and that indicates 423 * that the implementation's security guarantees no longer hold. Depending 424 * on the implementation architecture and on its security and safety goals, 425 * the implementation may forcibly terminate the application. 426 * 427 * This error code is intended as a last resort when a security breach 428 * is detected and it is unsure whether the keystore data is still 429 * protected. Implementations shall only return this error code 430 * to report an alarm from a tampering detector, to indicate that 431 * the confidentiality of stored data can no longer be guaranteed, 432 * or to indicate that the integrity of previously returned data is now 433 * considered compromised. Implementations shall not use this error code 434 * to indicate a hardware failure that merely makes it impossible to 435 * perform the requested operation (use #KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE, 436 * #KEYSTORE_PSA_STATUS_STORAGE_FAILURE, #KEYSTORE_PSA_STATUS_HARDWARE_FAILURE or other 437 * applicable error code instead). 438 * 439 * This error indicates an attack against the application. Implementations 440 * shall not return this error code as a consequence of the behavior of 441 * the application itself. */ 442 #define KEYSTORE_PSA_STATUS_CORRUPTION_DETECTED ((int_fast16_t)PSA_ERROR_CORRUPTION_DETECTED) 443 444 /*! 445 * @brief An error status code returned if the hardware or software resource 446 * is currently unavailable. 447 * 448 * KeyStore driver implementation may have limitations on how 449 * many clients can simultaneously perform operations on the same key. This status code is 450 * returned if the mutual exclusion mechanism signals that an operation cannot 451 * currently be performed. 452 */ 453 454 #define KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE ((int_fast16_t)-250) 455 456 /** @brief Encoding of a key type. 457 */ 458 typedef psa_key_type_t KeyStore_PSA_KeyType; 459 460 /** Raw data. 461 * 462 * A "key" of this type cannot be used for any cryptographic operation. 463 * Applications may use this type to store arbitrary data in the keystore. */ 464 #define KEYSTORE_PSA_KEY_TYPE_RAW_DATA ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_RAW_DATA) 465 466 /** HMAC key. 467 * 468 * The key policy determines which underlying hash algorithm the key can be 469 * used for. 470 * 471 * HMAC keys should generally have the same size as the underlying hash. */ 472 #define KEYSTORE_PSA_KEY_TYPE_HMAC ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_HMAC) 473 474 /** A secret for key derivation. 475 * 476 * The key policy determines which key derivation algorithm the key 477 * can be used for. 478 */ 479 #define KEYSTORE_PSA_KEY_TYPE_DERIVE ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_DERIVE) 480 481 /** Key for a cipher, AEAD or MAC algorithm based on the AES block cipher. 482 * 483 * The size of the key can be 16 bytes (AES-128), 24 bytes (AES-192) or 484 * 32 bytes (AES-256). 485 */ 486 #define KEYSTORE_PSA_KEY_TYPE_AES ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_AES) 487 488 /** Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES). 489 * 490 * The size of the key can be 64 bits (single DES), 128 bits (2-key 3DES) or 491 * 192 bits (3-key 3DES). 492 * 493 * Note that single DES and 2-key 3DES are weak and strongly 494 * deprecated and should only be used to decrypt legacy data. 3-key 3DES 495 * is weak and deprecated and should only be used in legacy protocols. 496 */ 497 #define KEYSTORE_PSA_KEY_TYPE_DES ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_DES) 498 499 /** Key for a cipher, AEAD or MAC algorithm based on the 500 * Camellia block cipher. */ 501 #define KEYSTORE_PSA_KEY_TYPE_CAMELLIA ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_CAMELLIA) 502 503 /** Key for the RC4 stream cipher. 504 * 505 * Note that RC4 is weak and deprecated and should only be used in 506 * legacy protocols. */ 507 #define KEYSTORE_PSA_KEY_TYPE_ARC4 ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_ARC4) 508 509 /** Key for the ChaCha20 stream cipher or the Chacha20-Poly1305 AEAD algorithm. 510 * 511 * ChaCha20 and the ChaCha20_Poly1305 construction are defined in RFC 7539. 512 * 513 * Implementations must support 12-byte nonces, may support 8-byte nonces, 514 * and should reject other sizes. 515 */ 516 #define KEYSTORE_PSA_KEY_TYPE_CHACHA20 ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_CHACHA20) 517 518 /** RSA public key. 519 * 520 * The size of an RSA key is the bit size of the modulus. 521 */ 522 #define KEYSTORE_PSA_KEY_TYPE_RSA_PUBLIC_KEY ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_RSA_PUBLIC_KEY) 523 /** RSA key pair (private and public key). 524 * 525 * The size of an RSA key is the bit size of the modulus. 526 */ 527 #define KEYSTORE_PSA_KEY_TYPE_RSA_KEY_PAIR ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_RSA_KEY_PAIR) 528 /** Whether a key type is an RSA key (pair or public-only). */ 529 #define PSA_KEY_TYPE_IS_RSA(type) (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_RSA_PUBLIC_KEY) 530 531 #define KEYSTORE_PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE) 532 #define KEYSTORE_PSA_KEY_TYPE_ECC_KEY_PAIR_BASE ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_ECC_KEY_PAIR_BASE) 533 534 /** A low-entropy secret for password hashing or key derivation. 535 * 536 * This key type is suitable for passwords and passphrases which are typically 537 * intended to be memorizable by humans, and have a low entropy relative to 538 * their size. It can be used for randomly generated or derived keys with 539 * maximum or near-maximum entropy, but #KEYSTORE_PSA_KEY_TYPE_PASSWORD is more suitable 540 * for such keys. It is not suitable for passwords with extremely low entropy, 541 * such as numerical PINs. 542 * 543 * The key policy determines which key derivation algorithm the key can be 544 * used for. 545 */ 546 #define KEYSTORE_PSA_KEY_TYPE_PASSWORD ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_PASSWORD) 547 548 /** A secret value that can be used to verify a password hash. 549 * 550 * The key policy determines which key derivation algorithm the key 551 * can be used for, among the same permissible subset as for 552 * #KEYSTORE_PSA_KEY_TYPE_PASSWORD. 553 */ 554 #define KEYSTORE_PSA_KEY_TYPE_PASSWORD_HASH ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_PASSWORD_HASH) 555 556 /** @brief Encoding of a cryptographic algorithm. 557 * 558 * For algorithms that can be applied to multiple key types, this type 559 * does not encode the key type. For example, for symmetric ciphers 560 * based on a block cipher, #KeyStore_PSA_Algorithm encodes the block cipher 561 * mode and the padding mode while the block cipher itself is encoded 562 * via #KeyStore_PSA_KeyType. 563 */ 564 typedef psa_algorithm_t KeyStore_PSA_Algorithm; 565 566 /** SHA2-224 */ 567 #define KEYSTORE_PSA_ALG_SHA_224 ((KeyStore_PSA_Algorithm)PSA_ALG_SHA_224) 568 /** SHA2-256 */ 569 #define KEYSTORE_PSA_ALG_SHA_256 ((KeyStore_PSA_Algorithm)PSA_ALG_SHA_256) 570 /** SHA2-384 */ 571 #define KEYSTORE_PSA_ALG_SHA_384 ((KeyStore_PSA_Algorithm)PSA_ALG_SHA_384) 572 /** SHA2-512 */ 573 #define KEYSTORE_PSA_ALG_SHA_512 ((KeyStore_PSA_Algorithm)PSA_ALG_SHA_512) 574 /** SHA2-512/224 */ 575 #define KEYSTORE_PSA_ALG_SHA_512_224 ((KeyStore_PSA_Algorithm)PSA_ALG_SHA_512_224) 576 /** SHA2-512/256 */ 577 #define KEYSTORE_PSA_ALG_SHA_512_256 ((KeyStore_PSA_Algorithm)PSA_ALG_SHA_512_256) 578 579 /** The CBC-MAC construction over a block cipher 580 * 581 * @warning CBC-MAC is insecure in many cases. 582 * A more secure mode, such as #KEYSTORE_PSA_ALG_CMAC, is recommended. 583 */ 584 #define KEYSTORE_PSA_ALG_CBC_MAC ((KeyStore_PSA_Algorithm)PSA_ALG_CBC_MAC) 585 /** The CMAC construction over a block cipher */ 586 #define KEYSTORE_PSA_ALG_CMAC ((KeyStore_PSA_Algorithm)PSA_ALG_CMAC) 587 588 /** The CTR stream cipher mode. 589 * 590 * CTR is a stream cipher which is built from a block cipher. 591 * The underlying block cipher is determined by the key type. 592 * For example, to use AES-128-CTR, use this algorithm with 593 * a key of type #KEYSTORE_PSA_KEY_TYPE_AES and a length of 128 bits (16 bytes). 594 */ 595 #define KEYSTORE_PSA_ALG_CTR ((KeyStore_PSA_Algorithm)PSA_ALG_CTR) 596 597 /** The Electronic Code Book (ECB) mode of a block cipher, with no padding. 598 * 599 * \warning ECB mode does not protect the confidentiality of the encrypted data 600 * except in extremely narrow circumstances. It is recommended that applications 601 * only use ECB if they need to construct an operating mode that the 602 * implementation does not provide. Implementations are encouraged to provide 603 * the modes that applications need in preference to supporting direct access 604 * to ECB. 605 * 606 * The underlying block cipher is determined by the key type. 607 * 608 * This symmetric cipher mode can only be used with messages whose lengths are a 609 * multiple of the block size of the chosen block cipher. 610 */ 611 #define KEYSTORE_PSA_ALG_ECB_NO_PADDING ((KeyStore_PSA_Algorithm)PSA_ALG_ECB_NO_PADDING) 612 613 /** The CBC block cipher chaining mode, with no padding. 614 * 615 * The underlying block cipher is determined by the key type. 616 * 617 * This symmetric cipher mode can only be used with messages whose lengths 618 * are whole number of blocks for the chosen block cipher. 619 */ 620 #define KEYSTORE_PSA_ALG_CBC_NO_PADDING ((KeyStore_PSA_Algorithm)PSA_ALG_CBC_NO_PADDING) 621 622 /** The CCM authenticated encryption algorithm. 623 * 624 * The underlying block cipher is determined by the key type. 625 */ 626 #define KEYSTORE_PSA_ALG_CCM ((KeyStore_PSA_Algorithm)PSA_ALG_CCM) 627 628 /** The GCM authenticated encryption algorithm. 629 * 630 * The underlying block cipher is determined by the key type. 631 */ 632 #define KEYSTORE_PSA_ALG_GCM ((KeyStore_PSA_Algorithm)PSA_ALG_GCM) 633 634 /** The Chacha20-Poly1305 AEAD algorithm. 635 * 636 * The ChaCha20_Poly1305 construction is defined in RFC 7539. 637 * 638 * Implementations must support 12-byte nonces, may support 8-byte nonces, 639 * and should reject other sizes. 640 * 641 * Implementations must support 16-byte tags and should reject other sizes. 642 */ 643 #define KEYSTORE_PSA_ALG_CHACHA20_POLY1305 ((KeyStore_PSA_Algorithm)PSA_ALG_CHACHA20_POLY1305) 644 645 /** The elliptic curve Diffie-Hellman (ECDH) key agreement algorithm. 646 * 647 * The shared secret produced by key agreement is the x-coordinate of 648 * the shared secret point. It is always `ceiling(m / 8)` bytes long where 649 * `m` is the bit size associated with the curve, i.e. the bit size of the 650 * order of the curve's coordinate field. When `m` is not a multiple of 8, 651 * the byte containing the most significant bit of the shared secret 652 * is padded with zero bits. The byte order is either little-endian 653 * or big-endian depending on the curve type. 654 * 655 * - For Montgomery curves (curve types `PSA_ECC_FAMILY_CURVEXXX`), 656 * the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A` 657 * in little-endian byte order. 658 * The bit size is 448 for Curve448 and 255 for Curve25519. 659 * - For Weierstrass curves over prime fields (curve types 660 * `PSA_ECC_FAMILY_SECPXXX` and `PSA_ECC_FAMILY_BRAINPOOL_PXXX`), 661 * the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A` 662 * in big-endian byte order. 663 * The bit size is `m = ceiling(log_2(p))` for the field `F_p`. 664 * - For Weierstrass curves over binary fields (curve types 665 * `PSA_ECC_FAMILY_SECTXXX`), 666 * the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A` 667 * in big-endian byte order. 668 * The bit size is `m` for the field `F_{2^m}`. 669 */ 670 #define KEYSTORE_PSA_ALG_ECDH ((KeyStore_PSA_Algorithm)PSA_ALG_ECDH) 671 672 /** ECDSA signature without hashing. 673 * 674 * This is the same signature scheme without specifying a hash algorithm. 675 * This algorithm may only be used to sign or verify a sequence of bytes 676 * that should be an pre-calculated hash. 677 */ 678 #define KEYSTORE_PSA_ALG_ECDSA ((KeyStore_PSA_Algorithm)PSA_ALG_ECDSA_ANY) 679 680 /** The Password-authenticated key exchange by juggling (J-PAKE) algorithm. */ 681 #define KEYSTORE_PSA_ALG_PAKE ((KeyStore_PSA_Algorithm)PSA_ALG_JPAKE) 682 683 /** Edwards-curve digital signature algorithm without prehashing (PureEdDSA), 684 * using standard parameters. 685 * 686 * PureEdDSA requires an elliptic curve key on a twisted Edwards curve. 687 * In this specification, the following curves are supported: 688 * - PSA_ECC_FAMILY_TWISTED_EDWARDS, 255-bit: Ed25519 as specified 689 * in RFC 8032. 690 * The curve is Edwards25519. 691 * The hash function used internally is SHA-512. 692 * 693 * This algorithm can be used with #KEYSTORE_PSA_KEY_USAGE_SIGN_MESSAGE and 694 * #KEYSTORE_PSA_KEY_USAGE_VERIFY_MESSAGE. Since there is no prehashing, it cannot be used 695 * with #KEYSTORE_PSA_KEY_USAGE_SIGN_HASH and #KEYSTORE_PSA_KEY_USAGE_VERIFY_HASH. 696 * 697 */ 698 #define KEYSTORE_PSA_ALG_PURE_EDDSA ((KeyStore_PSA_Algorithm)PSA_ALG_PURE_EDDSA) 699 700 /* The encoding of curve identifiers is currently aligned with the 701 * TLS Supported Groups Registry (formerly known as the 702 * TLS EC Named Curve Registry) 703 * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8 704 * The values are defined by RFC 8422 and RFC 7027. */ 705 #define KEYSTORE_PSA_ECC_CURVE_SECT163K1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_K1) 706 #define KEYSTORE_PSA_ECC_CURVE_SECT163R1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_R1) 707 #define KEYSTORE_PSA_ECC_CURVE_SECT163R2 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_R2) 708 #define KEYSTORE_PSA_ECC_CURVE_SECT193R1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_R1) 709 #define KEYSTORE_PSA_ECC_CURVE_SECT193R2 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_R2) 710 #define KEYSTORE_PSA_ECC_CURVE_SECT233K1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_K1) 711 #define KEYSTORE_PSA_ECC_CURVE_SECT233R1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_R1) 712 #define KEYSTORE_PSA_ECC_CURVE_SECT239K1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_K1) 713 #define KEYSTORE_PSA_ECC_CURVE_SECT283K1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_K1) 714 #define KEYSTORE_PSA_ECC_CURVE_SECT283R1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_R1) 715 #define KEYSTORE_PSA_ECC_CURVE_SECT409K1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_K1) 716 #define KEYSTORE_PSA_ECC_CURVE_SECT409R1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_R1) 717 #define KEYSTORE_PSA_ECC_CURVE_SECT571K1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_K1) 718 #define KEYSTORE_PSA_ECC_CURVE_SECT571R1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_R1) 719 #define KEYSTORE_PSA_ECC_CURVE_SECP160K1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_K1) 720 #define KEYSTORE_PSA_ECC_CURVE_SECP160R1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_R1) 721 #define KEYSTORE_PSA_ECC_CURVE_SECP160R2 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_R2) 722 #define KEYSTORE_PSA_ECC_CURVE_SECP192K1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_K1) 723 #define KEYSTORE_PSA_ECC_CURVE_SECP192R1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_R1) 724 #define KEYSTORE_PSA_ECC_CURVE_SECP224K1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_K1) 725 #define KEYSTORE_PSA_ECC_CURVE_SECP224R1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_R1) 726 #define KEYSTORE_PSA_ECC_CURVE_SECP256K1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_K1) 727 #define KEYSTORE_PSA_ECC_CURVE_SECP256R1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_R1) 728 #define KEYSTORE_PSA_ECC_CURVE_SECP384R1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_R1) 729 #define KEYSTORE_PSA_ECC_CURVE_SECP521R1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_SECP_R1) 730 #define KEYSTRORE_ECC_CURVE_BRAINPOOL_P256R1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_BRAINPOOL_P_R1) 731 #define KEYSTRORE_ECC_CURVE_BRAINPOOL_P384R1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_BRAINPOOL_P_R1) 732 #define KEYSTRORE_ECC_CURVE_BRAINPOOL_P512R1 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_BRAINPOOL_P_R1) 733 /** Cur KEYSTRORE_ECC_CURVE_SECPv((KeyStore_PSA_KeyType)e25519. 734 * 735 * This is the curve defined in Bernstein et al., 736 * _Curve25519: new Diffie-Hellman speed records_, LNCS 3958, 2006. 737 * The algorithm #KEYSTORE_PSA_ALG_ECDH performs X25519 when used with this curve. 738 */ 739 #define KEYSTORE_PSA_ECC_CURVE_CURVE25519 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_MONTGOMERY) 740 /** Curve448 741 * 742 * This is the curve defined in Hamburg, 743 * _Ed448-Goldilocks, a new elliptic curve_, NIST ECC Workshop, 2015. 744 * The algorithm #KEYSTORE_PSA_ALG_ECDH performs X448 when used with this curve. 745 */ 746 #define KEYSTORE_PSA_ECC_CURVE_CURVE448 ((KeyStore_PSA_KeyType)PSA_ECC_FAMILY_MONTGOMERY) 747 748 /** Minimum value for a vendor-defined ECC curve identifier 749 * 750 * The range for vendor-defined curve identifiers is a subset of the IANA 751 * registry private use range, `0xfe00` - `0xfeff`. 752 */ 753 #define KEYSTORE_PSA_ECC_CURVE_VENDOR_MIN ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_VENDOR_MIN) 754 /** Maximum value for a vendor-defined ECC curve identifier 755 * 756 * The range for vendor-defined curve identifiers is a subset of the IANA 757 * registry private use range, `0xfe00` - `0xfeff`. 758 */ 759 #define KEYSTORE_PSA_ECC_CURVE_VENDOR_MAX ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_VENDOR_MAX) 760 761 /** Volatile Key Limit [KEYSTORE_PSA_MIN_VOLATILE_KEY_ID, KEYSTORE_PSA_MAX_VOLATILE_KEY_ID] 762 * 763 * Upper limit for volatile key ID, KEYSTORE_PSA_MIN_VOLATILE_KEY_ID, is KEYSTORE_PSA_KEY_ID_VENDOR_MAX. 764 * Lower limit for volatile key ID, KEYSTORE_PSA_MIN_VOLATILE_KEY_ID, is the last 765 * MBEDTLS_PSA_KEY_SLOT_COUNT identifiers of provided by implementation reserved for vendors. 766 */ 767 #if (TFM_ENABLED == 0) || defined(TFM_BUILD) /* TFM_BUILD indicates this is a TF-M build */ 768 #define KEYSTORE_PSA_MIN_VOLATILE_KEY_ID PSA_KEY_ID_VOLATILE_MIN 769 #define KEYSTORE_PSA_MAX_VOLATILE_KEY_ID PSA_KEY_ID_VOLATILE_MAX 770 #else 771 /* PSA_KEY_SLOT_COUNT is not available in TF-M's crypto.h so we must 772 * hardcode it to match the value in Mbed TLS's header. 773 */ 774 #define KEYSTORE_PSA_MIN_VOLATILE_KEY_ID (PSA_KEY_ID_VENDOR_MAX - MBEDTLS_PSA_KEY_SLOT_COUNT + 1) 775 #define KEYSTORE_PSA_MAX_VOLATILE_KEY_ID PSA_KEY_ID_VENDOR_MAX 776 #endif 777 778 /* Macro to obtain size of struct member */ 779 #define MEMBER_SIZE(type, member) sizeof(((type *)0)->member) 780 781 /** \defgroup key_lifetimes Key lifetimes 782 * @{ 783 */ 784 785 /** The default lifetime for volatile keys. 786 * 787 * A volatile key only exists as long as the identifier to it is not destroyed. 788 * The key material is guaranteed to be erased on a power reset. 789 * 790 * A key with this lifetime is stored in RAM. 791 * 792 * Equivalent to 793 * #KEYSTORE_PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(#KEYSTORE_PSA_KEY_PERSISTENCE_VOLATILE, 794 * #KEYSTORE_PSA_KEY_LOCATION_LOCAL_STORAGE) 795 */ 796 #define KEYSTORE_PSA_KEY_LIFETIME_VOLATILE ((KeyStore_PSA_KeyLifetime)PSA_KEY_LIFETIME_VOLATILE) 797 798 /** The default lifetime for persistent keys. 799 * 800 * A persistent key remains in storage until it is explicitly destroyed or 801 * until the corresponding storage area is wiped. This specification does 802 * not define any mechanism to wipe a storage area, but implementations may 803 * provide their own mechanism (for example to perform a factory reset, 804 * to prepare for device refurbishment, or to uninstall an application). 805 * 806 * This lifetime value is the default storage area for the calling 807 * application. Implementations may offer other storage areas designated 808 * by other lifetime values as implementation-specific extensions. 809 * 810 * Equivalent to 811 * #KEYSTORE_PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(#KEYSTORE_PSA_KEY_PERSISTENCE_DEFAULT, 812 * #KEYSTORE_PSA_KEY_LOCATION_LOCAL_STORAGE) 813 */ 814 #define KEYSTORE_PSA_KEY_LIFETIME_PERSISTENT ((KeyStore_PSA_KeyLifetime)PSA_KEY_LIFETIME_PERSISTENT) 815 816 /** The persistence level of volatile keys. 817 * 818 * See ::KeyStore_PSA_KeyPersistence for more information. 819 */ 820 #define KEYSTORE_PSA_KEY_PERSISTENCE_VOLATILE ((KeyStore_PSA_KeyPersistence)PSA_KEY_PERSISTENCE_VOLATILE) 821 822 /** The default persistence level for persistent keys. 823 * 824 * See ::KeyStore_PSA_KeyPersistence for more information. 825 */ 826 #define KEYSTORE_PSA_KEY_PERSISTENCE_DEFAULT ((KeyStore_PSA_KeyPersistence)PSA_KEY_PERSISTENCE_DEFAULT) 827 828 /** A persistence level indicating that a key is never destroyed. 829 * 830 * See ::KeyStore_PSA_KeyPersistence for more information. 831 */ 832 #define KEYSTORE_PSA_KEY_PERSISTENCE_READ_ONLY ((KeyStore_PSA_KeyPersistence)PSA_KEY_PERSISTENCE_READ_ONLY) 833 834 #define KEYSTORE_PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) ((KeyStore_PSA_KeyPersistence)((lifetime)&0x000000ff)) 835 836 #define KEYSTORE_PSA_KEY_LIFETIME_GET_LOCATION(lifetime) ((KeyStore_PSA_KeyLocation)((lifetime) >> 8)) 837 838 /** Whether a key lifetime indicates that the key is volatile. 839 * 840 * A volatile key is automatically destroyed by the implementation when 841 * the application instance terminates. In particular, a volatile key 842 * is automatically destroyed on a power reset of the device. 843 * 844 * A key that is not volatile is persistent. Persistent keys are 845 * preserved until the application explicitly destroys them or until an 846 * implementation-specific device management event occurs (for example, 847 * a factory reset). 848 * 849 * @param lifetime The lifetime value to query (value of type 850 * ::KeyStore_PSA_KeyLifetime). 851 * 852 * @return \c 1 if the key is volatile, otherwise \c 0. 853 */ 854 #define KEYSTORE_PSA_KEY_LIFETIME_IS_VOLATILE(lifetime) \ 855 (KEYSTORE_PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) == KEYSTORE_PSA_KEY_PERSISTENCE_VOLATILE) 856 857 /** Whether a key lifetime indicates that the key is read-only. 858 * 859 * Read-only keys cannot be created or destroyed through the PSA Crypto API. 860 * They must be created through platform-specific means that bypass the API. 861 * 862 * Some platforms may offer ways to destroy read-only keys. For example, 863 * consider a platform with multiple levels of privilege, where a 864 * low-privilege application can use a key but is not allowed to destroy 865 * it, and the platform exposes the key to the application with a read-only 866 * lifetime. High-privilege code can destroy the key even though the 867 * application sees the key as read-only. 868 * 869 * @param lifetime The lifetime value to query (value of type 870 * ::KeyStore_PSA_KeyLifetime). 871 * 872 * @return \c 1 if the key is read-only, otherwise \c 0. 873 */ 874 #define KEYSTORE_PSA_KEY_LIFETIME_IS_READ_ONLY(lifetime) \ 875 (KEYSTORE_PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) == KEYSTORE_PSA_KEY_PERSISTENCE_READ_ONLY) 876 877 /** Construct a lifetime from a persistence level and a location. 878 * 879 * @param persistence The persistence level 880 * (value of type ::KeyStore_PSA_KeyPersistence). 881 * @param location The location indicator 882 * (value of type ::KeyStore_PSA_KeyLocation). 883 * 884 * @return The constructed lifetime value. 885 */ 886 #define KEYSTORE_PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(persistence, location) \ 887 (PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(persistence, location)) 888 889 /** The local storage area for persistent keys. 890 * 891 * This storage area is available on all systems that can store persistent 892 * keys without delegating the storage to a third-party cryptoprocessor. 893 * 894 * See ::KeyStore_PSA_KeyLocation for more information. 895 */ 896 #define KEYSTORE_PSA_KEY_LOCATION_LOCAL_STORAGE ((KeyStore_PSA_KeyLocation)PSA_KEY_LOCATION_LOCAL_STORAGE) 897 898 /** The null key identifier. 899 */ 900 #define KEYSTORE_PSA_KEY_ID_NULL ((KeyStore_PSA_keyID)0x0) 901 902 /** The minimum value for a key identifier chosen by the application. 903 */ 904 #define KEYSTORE_PSA_KEY_ID_USER_MIN ((KeyStore_PSA_keyID)PSA_KEY_ID_USER_MIN) 905 906 /** The minimum value for a key identifier chosen by the implementation. 907 */ 908 #define KEYSTORE_PSA_KEY_ID_VENDOR_MIN ((KeyStore_PSA_keyID)PSA_KEY_ID_VENDOR_MIN) 909 910 /** The maximum value for a key identifier chosen by the implementation. 911 */ 912 #define KEYSTORE_PSA_KEY_ID_VENDOR_MAX ((KeyStore_PSA_keyID)PSA_KEY_ID_VENDOR_MAX) 913 914 /** Default Key Owner 915 */ 916 #define KEYSTORE_PSA_DEFAULT_OWNER MBEDTLS_PSA_CRYPTO_KEY_ID_DEFAULT_OWNER 917 918 /**@}*/ 919 920 /** \defgroup key_policies Key policies 921 * @{ 922 */ 923 924 /** Whether the key may be exported. 925 * 926 * A public key or the public part of a key pair may always be exported 927 * regardless of the value of this permission flag. 928 * 929 * If a key does not have export permission, implementations shall not 930 * allow the key to be exported in plain form from the cryptoprocessor, 931 * whether through KeyStore_PSA_exportKey() or through a proprietary interface. 932 * The key may however be exportable in a wrapped form, i.e. in a form 933 * where it is encrypted by another key. 934 */ 935 #define KEYSTORE_PSA_KEY_USAGE_EXPORT ((KeyStore_PSA_KeyUsage)PSA_KEY_USAGE_EXPORT) 936 937 /** Whether the key may be copied. 938 * 939 * This flag allows the use of KeyStore_PSA_copyKey() to make a copy of the key 940 * with the same policy or a more restrictive policy. 941 * 942 * For lifetimes for which the key is located in a secure element which 943 * enforce the non-exportability of keys, copying a key outside the secure 944 * element also requires the usage flag #KEYSTORE_PSA_KEY_USAGE_EXPORT. 945 * Copying the key inside the secure element is permitted with just 946 * #KEYSTORE_PSA_KEY_USAGE_COPY if the secure element supports it. 947 * For keys with the lifetime #KEYSTORE_PSA_KEY_LIFETIME_VOLATILE or 948 * #KEYSTORE_PSA_KEY_LIFETIME_PERSISTENT, the usage flag #KEYSTORE_PSA_KEY_USAGE_COPY 949 * is sufficient to permit the copy. 950 */ 951 #define KEYSTORE_PSA_KEY_USAGE_COPY ((KeyStore_PSA_KeyUsage)PSA_KEY_USAGE_COPY) 952 953 /** Whether the key may be used to encrypt a message. 954 * 955 * This flag allows the key to be used for a symmetric encryption operation, 956 * for an AEAD encryption-and-authentication operation, 957 * or for an asymmetric encryption operation, 958 * if otherwise permitted by the key's type and policy. 959 * 960 * For a key pair, this concerns the public key. 961 */ 962 #define KEYSTORE_PSA_KEY_USAGE_ENCRYPT ((KeyStore_PSA_KeyUsage)PSA_KEY_USAGE_ENCRYPT) 963 964 /** Whether the key may be used to decrypt a message. 965 * 966 * This flag allows the key to be used for a symmetric decryption operation, 967 * for an AEAD decryption-and-verification operation, 968 * or for an asymmetric decryption operation, 969 * if otherwise permitted by the key's type and policy. 970 * 971 * For a key pair, this concerns the private key. 972 */ 973 #define KEYSTORE_PSA_KEY_USAGE_DECRYPT ((KeyStore_PSA_KeyUsage)PSA_KEY_USAGE_DECRYPT) 974 975 /** Whether the key may be used to sign a message. 976 * 977 * This flag allows the key to be used for a MAC calculation operation or for 978 * an asymmetric message signature operation, if otherwise permitted by the 979 * keys type and policy. 980 * 981 * For a key pair, this concerns the private key. 982 */ 983 #define KEYSTORE_PSA_KEY_USAGE_SIGN_MESSAGE ((KeyStore_PSA_KeyUsage)PSA_KEY_USAGE_SIGN_MESSAGE) 984 985 /** Whether the key may be used to verify a message. 986 * 987 * This flag allows the key to be used for a MAC verification operation or for 988 * an asymmetric message signature verification operation, if otherwise 989 * permitted by the keys type and policy. 990 * 991 * For a key pair, this concerns the public key. 992 */ 993 #define KEYSTORE_PSA_KEY_USAGE_VERIFY_MESSAGE ((KeyStore_PSA_KeyUsage)PSA_KEY_USAGE_VERIFY_MESSAGE) 994 995 /** Whether the key may be used to sign a message hash. 996 * 997 * This flag allows the key to be used for an asymmetric signature operation, 998 * if otherwise permitted by the key's type and policy. 999 * 1000 * For a key pair, this concerns the private key. 1001 */ 1002 #define KEYSTORE_PSA_KEY_USAGE_SIGN_HASH ((KeyStore_PSA_KeyUsage)PSA_KEY_USAGE_SIGN_HASH) 1003 1004 /** Whether the key may be used to verify a message hash. 1005 * 1006 * This flag allows the key to be used for an asymmetric signature verification operation, 1007 * if otherwise permitted by by the key's type and policy. 1008 * 1009 * For a key pair, this concerns the public key. 1010 */ 1011 #define KEYSTORE_PSA_KEY_USAGE_VERIFY_HASH ((KeyStore_PSA_KeyUsage)PSA_KEY_USAGE_VERIFY_HASH) 1012 1013 /** Whether the key may be used to derive other keys. 1014 */ 1015 #define KEYSTORE_PSA_KEY_USAGE_DERIVE ((KeyStore_PSA_KeyUsage)PSA_KEY_USAGE_DERIVE) 1016 /**@}*/ 1017 1018 /** \defgroup attributes Key attributes 1019 * @{ 1020 */ 1021 /** The type of a structure containing key attributes. 1022 * 1023 * This is an opaque structure that can represent the metadata of a key 1024 * object. Metadata that can be stored in attributes includes: 1025 * - The location of the key in storage, indicated by its key identifier 1026 * and its lifetime. 1027 * - The key's policy, comprising usage flags and a specification of 1028 * the permitted algorithm(s). 1029 * - Information about the key itself: the key type and its size. 1030 * 1031 * The actual key material is not considered an attribute of a key. 1032 * Key attributes do not contain information that is generally considered 1033 * highly confidential. 1034 * 1035 * An attribute structure can be a simple data structure where each function 1036 * `KeyStore_PSA_setKeyXXX` sets a field and the corresponding function 1037 * `KeyStore_PSA_getKeyXXX` retrieves the value of the corresponding field. 1038 * However, implementations may report values that are equivalent to the 1039 * original one, but have a different encoding. For example, an 1040 * implementation may use a more compact representation for types where 1041 * many bit-patterns are invalid or not supported, and store all values 1042 * that it does not support as a special marker value. In such an 1043 * implementation, after setting an invalid value, the corresponding 1044 * get function returns an invalid value which may not be the one that 1045 * was originally stored. 1046 * 1047 * An attribute structure may contain references to auxiliary resources, 1048 * for example pointers to allocated memory or indirect references to 1049 * pre-calculated values. In order to free such resources, the application 1050 * must call KeyStore_PSA_resetKeyAttributes(). As an exception, calling 1051 * KeyStore_PSA_resetKeyAttributes() on an attribute structure is optional if 1052 * the structure has only been modified by the following functions 1053 * since it was initialized or last reset with 1054 * KeyStore_PSA_resetKeyAttributes(): 1055 * - KeyStore_PSA_setKeyId() 1056 * - KeyStore_PSA_setKeyLifetime() 1057 * - KeyStore_PSA_setKeyType() 1058 * - KeyStore_PSA_setKeyBits() 1059 * - KeyStore_PSA_setKeyUsageFlags() 1060 * - KeyStore_PSA_setKeyAlgorithm() 1061 * 1062 * Before calling any function on a key attribute structure, the application 1063 * must initialize it by any of the following means: 1064 * - Set the structure to all-bits-zero, for example: 1065 * \code 1066 * KeyStore_PSA_KeyAttributes attributes; 1067 * memset(&attributes, 0, sizeof(attributes)); 1068 * \endcode 1069 * - Initialize the structure to logical zero values, for example: 1070 * \code 1071 * KeyStore_PSA_KeyAttributes attributes = {0}; 1072 * \endcode 1073 * - Initialize the structure to the initializer 1074 * #KEYSTORE_PSA_KEY_ATTRIBUTES_INIT, for example: \code 1075 * KeyStore_PSA_KeyAttributes attributes = KEYSTORE_PSA_KEY_ATTRIBUTES_INIT; 1076 * \endcode 1077 * 1078 * A freshly initialized attribute structure contains the following 1079 * values: 1080 * 1081 * - lifetime: #KEYSTORE_PSA_KEY_LIFETIME_VOLATILE. 1082 * - key identifier: @c 0 (which is not a valid key identifier). 1083 * - type: @c 0 (meaning that the type is unspecified). 1084 * - key size: @c 0 (meaning that the size is unspecified). 1085 * - usage flags: @c 0 (which allows no usage except exporting a public 1086 * key). 1087 * - algorithm: @c 0 (which allows no cryptographic usage, but allows 1088 * exporting). 1089 * 1090 * A typical sequence to create a key is as follows: 1091 * -# Create and initialize an attribute structure. 1092 * -# If the key is persistent, call KeyStore_PSA_setKeyId(). 1093 * Also call KeyStore_PSA_setKeyLifetime() to place the key in a non-default 1094 * location. 1095 * -# Set the key policy with KeyStore_PSA_setKeyUsageFlags() and 1096 * KeyStore_PSA_setKeyAlgorithm(). 1097 * -# Set the key type with KeyStore_PSA_setKeyType(). 1098 * -# When generating a random key with KeyStore_PSA_generateKey() or deriving a 1099 * key with KeyStore_PSA_key_derivation_output_key(), set the desired key size 1100 * with KeyStore_PSA_setKeyBits(). 1101 * -# Call a key creation function: KeyStore_PSA_importKey(), 1102 * KeyStore_PSA_generateKey(), KeyStore_PSA_key_derivation_output_key(). This 1103 * function reads the attribute structure, creates a key with these 1104 * attributes, and outputs a handle to the newly created key. 1105 * -# The attribute structure is now no longer necessary. 1106 * You may call KeyStore_PSA_resetKeyAttributes(), although this is optional 1107 * with the workflow presented here because the attributes currently 1108 * defined in this specification do not require any additional resources 1109 * beyond the structure itself. 1110 * 1111 * A typical sequence to query a key's attributes is as follows: 1112 * -# Call KeyStore_PSA_getKeyAttributes(). 1113 * -# Call `KeyStore_PSA_get_key_xxx` functions to retrieve the attribute(s) 1114 * that you are interested in. 1115 * -# Call KeyStore_PSA_resetKeyAttributes() to free any resources that may be 1116 * used by the attribute structure. 1117 * 1118 * Once a key has been created, it is impossible to change its attributes. 1119 */ 1120 typedef psa_key_attributes_t KeyStore_PSA_KeyAttributes; 1121 #if (TFM_ENABLED == 0) || defined(TFM_BUILD) /* TFM_BUILD indicates this is a TF-M build */ 1122 /** A Key owner is a PSA partition identifier. This definition follow 1123 * 'psa_key_owner_id_t' from crypto_platform.h */ 1124 #if defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER) 1125 /* Building for the PSA Crypto service on a PSA platform. */ 1126 /* A key owner is a PSA partition identifier. */ 1127 typedef mbedtls_key_owner_id_t KeyStore_PSA_key_owner_id_t; 1128 1129 typedef psa_key_id_t KeyStore_PSA_keyID; 1130 #endif /* defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER) */ 1131 1132 typedef mbedtls_svc_key_id_t KeyStore_PSA_KeyFileId; 1133 1134 #define KEYSTORE_PSA_KEY_ATTRIBUTES_INIT PSA_KEY_ATTRIBUTES_INIT 1135 1136 /** Macro to assign and get keyID 1137 * 1138 * It depends on MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER to assign keyID and 1139 * owner if multiple partition supported by mbedtls 1140 */ 1141 #if defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER) 1142 #define GET_KEY_ID(keyID, ID) \ 1143 keyID.MBEDTLS_PRIVATE(key_id) = ID; \ 1144 keyID.MBEDTLS_PRIVATE(owner) = KEYSTORE_PSA_DEFAULT_OWNER; 1145 1146 #define SET_KEY_ID(ID, keyID) ID = keyID.MBEDTLS_PRIVATE(key_id) 1147 #else 1148 #define GET_KEY_ID(keyID, ID) keyID = ID 1149 1150 #define SET_KEY_ID(ID, keyID) ID = keyID 1151 #endif /* defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER) */ 1152 1153 #else 1154 1155 typedef psa_key_id_t KeyStore_PSA_keyID; 1156 1157 /** Encoding of identifiers of persistent keys for client side. 1158 * 1159 * - Applications may freely choose key identifiers in the range 1160 * #KEYSTORE_PSA_KEY_ID_USER_MIN to #KEYSTORE_PSA_KEY_ID_USER_MAX 1161 * - Implementations may define additional key identifiers in the range 1162 * #KEYSTORE_PSA_KEY_ID_VENDOR_MIN to #KEYSTORE_PSA_KEY_ID_VENDOR_MAX. 1163 * - 0 is reserved as an invalid key identifier. 1164 * - Key identifiers outside these ranges are reserved for future use. 1165 */ 1166 typedef mbedtls_svc_key_id_t KeyStore_PSA_KeyFileId; 1167 1168 /** Macro to assign and get keyID */ 1169 #define GET_KEY_ID(keyID, ID) keyID = ID 1170 #define SET_KEY_ID(ID, keyID) ID = keyID 1171 1172 #define KEYSTORE_PSA_KEY_ATTRIBUTES_INIT PSA_CLIENT_KEY_ATTRIBUTES_INIT 1173 #endif /* #if (TFM_ENABLED == 0) || defined(TFM_BUILD) */ 1174 /**@}*/ 1175 1176 /**@}*/ 1177 1178 /** 1179 * Starting address of Pre-provisioned keys. 1180 * 1181 * The Immutable platform Root of Trust stores the pre-provisioned key's programmed at 1182 * production. SKS implementation will read this address to obtain the 1183 * KeyStore_PSA_KeyFileId and other relevant meta data of all the pre-provisioned keys stored at this address 1184 */ 1185 #define KEYSTORE_PSA_PREPROVISIONED_AREA_ADDR 0x0000 1186 /** 1187 * @brief Area size for pre-provisioned keys, 2KB - 256B (reserved for attestation data) 1188 */ 1189 #define KEYSTORE_PSA_PREPROVISIONED_AREA_SIZE (0x700) /* 1792 B */ 1190 1191 /** 1192 * @brief Macro to indicate empty pre-provisioned key memory 1193 */ 1194 #define KEYSTORE_PSA_PREPROVISIONED_KEYS_EMPTY 0xFFFF 1195 1196 /** 1197 * @brief Pre-provisioned key storage magic header. 1198 */ 1199 #define KEYSTORE_PSA_PRE_PROVISIONED_KEY_MAGIC_HEADER "HUK\0KEY" 1200 #define KEYSTORE_PSA_PRE_PROVISIONED_KEYS_END 0 1201 #define KEYSTORE_PSA_PRE_PROVISIONED_KEY_MAGIC_HEADER_LENGTH (sizeof(KEYSTORE_PSA_PRE_PROVISIONED_KEY_MAGIC_HEADER)) 1202 #define KEYSTORE_PSA_PRE_PROVISIONED_KEYS_END_LENGTH (sizeof(KEYSTORE_PSA_PRE_PROVISIONED_KEYS_END)) 1203 #define KEYSTORE_PSA_MAX_PREPROVISIONED_KEYS 0x10 1204 1205 /** 1206 * @brief Pre-provisioned key Lifetime 1207 */ 1208 #define KEYSTORE_PSA_PRE_PROVISIONED_KEY_VALID_LIFETIME 0xAAAA 1209 #define KEYSTORE_PSA_PRE_PROVISIONED_KEY_INVALID_LIFETIME 0x8888 1210 1211 /** 1212 * @brief Admissible key ID range for Pre-provisioned keys 1213 * 1214 * 0x7fff0000 - 0x7fffefff is reserved to store pre-provisioned keys. 1215 */ 1216 #define KEYSTORE_PSA_PRE_PROVISIONED_KEY_ID_MAX MBEDTLS_PSA_KEY_ID_BUILTIN_MAX 1217 #define KEYSTORE_PSA_PRE_PROVISIONED_KEY_ID_MIN MBEDTLS_PSA_KEY_ID_BUILTIN_MIN 1218 1219 /** 1220 * @brief Declare a key as persistent and set its key identifier. 1221 * 1222 * If the attribute structure currently declares the key as volatile (which 1223 * is the default content of an attribute structure), this function sets 1224 * the lifetime attribute to #KEYSTORE_PSA_KEY_LIFETIME_PERSISTENT. 1225 * 1226 * This function does not access storage, it merely stores the given 1227 * value in the structure. 1228 * The persistent key will be written to storage when the attribute 1229 * structure is passed to a key creation function such as 1230 * KeyStore_PSA_import_key(), KeyStore_PSA_generate_key(), 1231 * KeyStore_PSA_key_derivation_output_key() or KeyStore_PSA_copy_key(). 1232 * 1233 * This function may be declared as `static` (i.e. without external 1234 * linkage). This function may be provided as a function-like macro, 1235 * but in this case it must evaluate each of its arguments exactly once. 1236 * 1237 * @param [out] attributes The attribute structure to write to. 1238 * @param key The persistent identifier for the key. 1239 */ 1240 void KeyStore_PSA_setKeyId(KeyStore_PSA_KeyAttributes *attributes, KeyStore_PSA_KeyFileId key); 1241 1242 /** 1243 * @brief Set the location of a persistent key. 1244 * 1245 * To make a key persistent, you must give it a persistent key identifier 1246 * with KeyStore_PSA_setKeyId(). By default, a key that has a persistent 1247 * identifier is stored in the default storage area identifier by 1248 * #KEYSTORE_PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage 1249 * area, or to explicitly declare the key as volatile. 1250 * 1251 * This function does not access storage, it merely stores the given 1252 * value in the structure. 1253 * The persistent key will be written to storage when the attribute 1254 * structure is passed to a key creation function such as 1255 * KeyStore_PSA_import_key(), KeyStore_PSA_generate_key(), 1256 * KeyStore_PSA_key_derivation_output_key() or KeyStore_PSA_copy_key(). 1257 * 1258 * This function may be declared as `static` (i.e. without external 1259 * linkage). This function may be provided as a function-like macro, 1260 * but in this case it must evaluate each of its arguments exactly once. 1261 * 1262 * @param [out] attributes The attribute structure to write to. 1263 * @param lifetime The lifetime for the key. 1264 * If this is #KEYSTORE_PSA_KEY_LIFETIME_VOLATILE, the 1265 * key will be volatile, and the key identifier 1266 * attribute is reset to 0. 1267 */ 1268 void KeyStore_PSA_setKeyLifetime(KeyStore_PSA_KeyAttributes *attributes, KeyStore_PSA_KeyLifetime lifetime); 1269 1270 /** 1271 * @brief Retrieve the key identifier from key attributes. 1272 * 1273 * This function may be declared as `static` (i.e. without external 1274 * linkage). This function may be provided as a function-like macro, 1275 * but in this case it must evaluate its argument exactly once. 1276 * 1277 * @param [in] attributes The key attribute structure to query. 1278 * 1279 * @return The persistent identifier stored in the attribute structure. 1280 * This value is unspecified if the attribute structure declares 1281 * the key as volatile. 1282 */ 1283 KeyStore_PSA_KeyFileId KeyStore_PSA_getKeyId(KeyStore_PSA_KeyAttributes *attributes); 1284 1285 /** 1286 * @brief Retrieve the lifetime from key attributes. 1287 * 1288 * This function may be declared as `static` (i.e. without external 1289 * linkage). This function may be provided as a function-like macro, 1290 * but in this case it must evaluate its argument exactly once. 1291 * 1292 * @param [in] attributes The key attribute structure to query. 1293 * 1294 * @return The lifetime value stored in the attribute structure. 1295 */ 1296 KeyStore_PSA_KeyLifetime KeyStore_PSA_getKeyLifetime(KeyStore_PSA_KeyAttributes *attributes); 1297 1298 /** 1299 * @brief Declare usage flags for a key. 1300 * 1301 * Usage flags are part of a key's usage policy. They encode what 1302 * kind of operations are permitted on the key. For more details, 1303 * refer to the documentation of the type #KeyStore_PSA_KeyUsage. 1304 * 1305 * This function overwrites any usage flags 1306 * previously set in @p attributes. 1307 * 1308 * This function may be declared as `static` (i.e. without external 1309 * linkage). This function may be provided as a function-like macro, 1310 * but in this case it must evaluate each of its arguments exactly once. 1311 * 1312 * @param [out] attributes The attribute structure to write to. 1313 * @param usageFlags The usage flags to write. 1314 */ 1315 void KeyStore_PSA_setKeyUsageFlags(KeyStore_PSA_KeyAttributes *attributes, KeyStore_PSA_KeyUsage usageFlags); 1316 1317 /** 1318 * @brief Retrieve the usage flags from key attributes. 1319 * 1320 * This function may be declared as `static` (i.e. without external 1321 * linkage). This function may be provided as a function-like macro, 1322 * but in this case it must evaluate its argument exactly once. 1323 * 1324 * @param [in] attributes The key attribute structure to query. 1325 * 1326 * @return The usage flags stored in the attribute structure. 1327 */ 1328 KeyStore_PSA_KeyUsage KeyStore_PSA_getKeyUsageFlags(KeyStore_PSA_KeyAttributes *attributes); 1329 1330 /** 1331 * @brief Declare the permitted algorithm policy for a key. 1332 * 1333 * The permitted algorithm policy of a key encodes which algorithm or 1334 * algorithms are permitted to be used with this key. The following 1335 * algorithm policies are supported: 1336 * - 0 does not allow any cryptographic operation with the key. The key 1337 * may be used for non-cryptographic actions such as exporting (if 1338 * permitted by the usage flags). 1339 * - An algorithm value permits this particular algorithm. 1340 * 1341 * This function overwrites any algorithm policy 1342 * previously set in @p attributes. 1343 * 1344 * This function may be declared as `static` (i.e. without external 1345 * linkage). This function may be provided as a function-like macro, 1346 * but in this case it must evaluate each of its arguments exactly once. 1347 * 1348 * @param [out] attributes The attribute structure to write to. 1349 * @param alg The permitted algorithm policy to write. 1350 */ 1351 void KeyStore_PSA_setKeyAlgorithm(KeyStore_PSA_KeyAttributes *attributes, KeyStore_PSA_Algorithm alg); 1352 1353 /** 1354 * @brief Retrieve the algorithm policy from key attributes. 1355 * 1356 * This function may be declared as `static` (i.e. without external 1357 * linkage). This function may be provided as a function-like macro, 1358 * but in this case it must evaluate its argument exactly once. 1359 * 1360 * @param [in] attributes The key attribute structure to query. 1361 * 1362 * @return The algorithm stored in the attribute structure. 1363 */ 1364 KeyStore_PSA_Algorithm KeyStore_PSA_getKeyAlgorithm(KeyStore_PSA_KeyAttributes *attributes); 1365 1366 /** 1367 * @brief Declare the type of a key. 1368 * 1369 * This function overwrites any key type 1370 * previously set in @p attributes. 1371 * 1372 * This function may be declared as `static` (i.e. without external 1373 * linkage). This function may be provided as a function-like macro, 1374 * but in this case it must evaluate each of its arguments exactly once. 1375 * 1376 * @param [out] attributes The attribute structure to write to. 1377 * @param type The key type to write. 1378 * If this is 0, the key type in @p attributes 1379 * becomes unspecified. 1380 */ 1381 void KeyStore_PSA_setKeyType(KeyStore_PSA_KeyAttributes *attributes, KeyStore_PSA_KeyType type); 1382 1383 /** 1384 * @brief Declare the size of a key. 1385 * 1386 * This function overwrites any key size previously set in @p attributes. 1387 * 1388 * This function may be declared as `static` (i.e. without external 1389 * linkage). This function may be provided as a function-like macro, 1390 * but in this case it must evaluate each of its arguments exactly once. 1391 * 1392 * @param [out] attributes The attribute structure to write to. 1393 * @param bits The key size in bits. 1394 * If this is 0, the key size in @p attributes 1395 * becomes unspecified. Keys of size 0 are 1396 * not supported. 1397 */ 1398 void KeyStore_PSA_setKeyBits(KeyStore_PSA_KeyAttributes *attributes, size_t bits); 1399 1400 /** 1401 * @brief Retrieve the key type from key attributes. 1402 * 1403 * This function may be declared as `static` (i.e. without external 1404 * linkage). This function may be provided as a function-like macro, 1405 * but in this case it must evaluate its argument exactly once. 1406 * 1407 * @param [in] attributes The key attribute structure to query. 1408 * 1409 * @return The key type stored in the attribute structure. 1410 */ 1411 KeyStore_PSA_KeyType KeyStore_PSA_getKeyType(KeyStore_PSA_KeyAttributes *attributes); 1412 1413 /** @brief Retrieve the key size from key attributes. 1414 * 1415 * This function may be declared as `static` (i.e. without external 1416 * linkage). This function may be provided as a function-like macro, 1417 * but in this case it must evaluate its argument exactly once. 1418 * 1419 * @param [in] attributes The key attribute structure to query. 1420 * 1421 * @return The key size stored in the attribute structure, in bits. 1422 */ 1423 size_t KeyStore_PSA_getKeyBits(KeyStore_PSA_KeyAttributes *attributes); 1424 1425 /** @brief Reset a key attribute structure to a freshly initialized state. 1426 * 1427 * You must initialize the attribute structure as described in the 1428 * documentation of the type #KeyStore_PSA_KeyAttributes before calling this 1429 * function. Once the structure has been initialized, you may call this 1430 * function at any time. 1431 * 1432 * This function frees any auxiliary resources that the structure 1433 * may contain. 1434 * 1435 * @param [in,out] attributes The attribute structure to reset. 1436 */ 1437 void KeyStore_PSA_resetKeyAttributes(KeyStore_PSA_KeyAttributes *attributes); 1438 1439 /** 1440 * @brief Export a public key or the public part of a key pair in binary 1441 * format. 1442 * 1443 * The output of this function can be passed to KeyStore_PSA_importKey() to 1444 * create an object that is equivalent to the public key. 1445 * 1446 * This specification supports a single format for each key type. 1447 * Implementations may support other formats as long as the standard 1448 * format is supported. Implementations that support other formats 1449 * should ensure that the formats are clearly unambiguous so as to 1450 * minimize the risk that an invalid input is accidentally interpreted 1451 * according to a different format. 1452 * 1453 * - For elliptic curve public keys, the format for: 1454 * - Montgomery curves (curve types `PSA_ECC_CURVE_CURVEXXX`), is 1455 * - `x_P` as a `ceiling(m/8)`-byte string, little-endian; 1456 * - Weierstrass curves (curve types `PSA_ECC_CURVE_SECTXXX`, 1457 * `PSA_ECC_CURVE_SECPXXX` and `PSA_ECC_CURVE_BRAINPOOL_PXXX`), is the 1458 * uncompressed representation defined by SEC1 §2.3.3 as the content of 1459 * an ECPoint. Let `m` be the bit size associated with the curve, i.e. the 1460 * bit size of `q` for a curve over `F_q`. The representation consists of: 1461 * - The byte 0x04; 1462 * - `x_P` as a `ceiling(m/8)`-byte string, big-endian; 1463 * - `y_P` as a `ceiling(m/8)`-byte string, big-endian. 1464 * - For Diffie-Hellman key exchange public keys, 1465 * the format is the representation of the public key `y = g^x mod p` as a 1466 * big-endian byte string. The length of the byte string is the length of 1467 * the base prime `p` in bytes. 1468 * 1469 * Exporting a public key object or the public part of a key pair is 1470 * always permitted, regardless of the key's usage flags. 1471 * 1472 * @param [in] key Key file ID of the key to export. 1473 * @param [out] data Buffer where the key data is to be written. 1474 * @param [in] dataSize Size of the @p data buffer in bytes. 1475 * @param [out] dataLength On success, the number of bytes 1476 * that make up the key data. 1477 * 1478 * @retval #KEYSTORE_PSA_STATUS_SUCCESS 1479 * @retval KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE 1480 * @retval #KEYSTORE_PSA_STATUS_INVALID_KEY_ID 1481 * @retval #KEYSTORE_PSA_STATUS_INVALID_ARGUMENT 1482 * The key is neither a public key nor a key pair. 1483 * @retval #KEYSTORE_PSA_STATUS_NOT_SUPPORTED 1484 * @retval #KEYSTORE_PSA_STATUS_BUFFER_TOO_SMALL 1485 * The size of the @p data buffer is too small. 1486 * @retval #KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE 1487 * @retval #KEYSTORE_PSA_STATUS_HARDWARE_FAILURE 1488 * @retval #KEYSTORE_PSA_STATUS_CORRUPTION_DETECTED 1489 * @retval #KEYSTORE_PSA_STATUS_STORAGE_FAILURE 1490 * @retval #KEYSTORE_PSA_STATUS_INSUFFICIENT_MEMORY 1491 * @retval #KEYSTORE_PSA_STATUS_BAD_STATE 1492 * The library has not been previously initialized by 1493 * KeyStore_PSA_init(). It is implementation-dependent whether a failure to 1494 * initialize results in this error code. 1495 */ 1496 int_fast16_t KeyStore_PSA_exportPublicKey(KeyStore_PSA_KeyFileId key, 1497 uint8_t *data, 1498 size_t dataSize, 1499 size_t *dataLength); 1500 1501 /** 1502 * @brief Export a key in binary format. 1503 * 1504 * The key must designated as exportable. The output of this function can be 1505 * passed to KeyStore_PSA_importKey() to create an equivalent object. 1506 * 1507 * If the implementation of KeyStore_PSA_importKey() supports other formats 1508 * beyond the format specified here, the output from KeyStore_PSA_exportKey() 1509 * must use the representation specified here, not the original 1510 * representation. 1511 * 1512 * For standard key types, the output format is as follows: 1513 * 1514 * - For symmetric keys (including MAC keys), the format is the 1515 * raw bytes of the key. 1516 * 1517 * - For elliptic curve key pairs, the format is 1518 * a representation of the private value as a `ceiling(m/8)`-byte string 1519 * where `m` is the bit size associated with the curve, i.e. the bit size 1520 * of the order of the curve's coordinate field. This byte string is 1521 * in little-endian order for Montgomery curves (curve types 1522 * `PSA_ECC_CURVE_CURVEXXX`), and in big-endian order for Weierstrass 1523 * curves (curve types `PSA_ECC_CURVE_SECTXXX`, `PSA_ECC_CURVE_SECPXXX` 1524 * and `PSA_ECC_CURVE_BRAINPOOL_PXXX`). 1525 * This is the content of the `privateKey` field of the `ECPrivateKey` 1526 * format defined by RFC 5915. 1527 * - For Diffie-Hellman key exchange key pairs, the 1528 * format is the representation of the private key `x` as a big-endian 1529 * byte string. The length of the byte string is the private key size in 1530 * bytes (leading zeroes are not stripped). 1531 * - For public keys, the format is the same as for KeyStore_PSA_exportPublicKey(). 1532 * 1533 * This function can also be used to export other sensitive data, such as 1534 * certificates using its corresponding key file ID. 1535 * 1536 * The policy on the key must have the usage flag #KEYSTORE_PSA_KEY_USAGE_EXPORT 1537 * set. 1538 * 1539 * @param [in] key Key file ID of the key to export. 1540 * @param [out] data Buffer where the key data is to be written. 1541 * @param [in] dataSize Size of the @p data buffer in bytes. 1542 * @param [out] dataLength On success, the number of bytes 1543 * that make up the key data. 1544 * 1545 * @retval #KEYSTORE_PSA_STATUS_SUCCESS 1546 * @retval KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE 1547 * @retval #KEYSTORE_PSA_STATUS_INVALID_KEY_ID 1548 * The key identifier does not exist. 1549 * @retval #KEYSTORE_PSA_STATUS_NOT_PERMITTED 1550 * The key does not have the #KEYSTORE_PSA_KEY_USAGE_EXPORT flag. 1551 * @retval #KEYSTORE_PSA_STATUS_NOT_SUPPORTED 1552 * @retval #KEYSTORE_PSA_STATUS_BUFFER_TOO_SMALL 1553 * The size of the @p data buffer is too small. 1554 * @retval #KEYSTORE_PSA_STATUS_STORAGE_FAILURE 1555 * @retval #KEYSTORE_PSA_STATUS_INSUFFICIENT_MEMORY 1556 * @retval #KEYSTORE_PSA_STATUS_BAD_STATE 1557 * The library has not been previously initialized by 1558 * KeyStore_PSA_init(). It is implementation-dependent whether a failure to 1559 * initialize results in this error code. 1560 */ 1561 int_fast16_t KeyStore_PSA_exportKey(KeyStore_PSA_KeyFileId key, uint8_t *data, size_t dataSize, size_t *dataLength); 1562 1563 /** 1564 * @brief Import a key in binary format. 1565 * 1566 * This function supports any output from KeyStore_PSA_exportKey(). Refer to the 1567 * documentation of KeyStore_PSA_exportPublicKey() for the format of public keys 1568 * and to the documentation of KeyStore_PSA_exportKey() for the format for 1569 * other key types. 1570 * 1571 * The dataLength determines the key size. The attributes may optionally 1572 * specify a key size; in this case it must match the dataLength. A key 1573 * size of 0 in @p attributes indicates that the key size is solely 1574 * determined by the key data. 1575 * 1576 * Implementations must reject an attempt to import a key of size 0. 1577 * 1578 * This specification supports a single format for each key type. 1579 * Implementations may support other formats as long as the standard 1580 * format is supported. Implementations that support other formats 1581 * should ensure that the formats are clearly unambiguous so as to 1582 * minimize the risk that an invalid input is accidentally interpreted 1583 * according to a different format. 1584 * 1585 * This function can also be used to store other sensitive data, such as 1586 * certificate using key type #KEYSTORE_PSA_KEY_TYPE_RAW_DATA. 1587 * 1588 * @param [in] attributes The attributes for the new key. 1589 * The key size is always determined from the 1590 * @p data buffer. 1591 * If the key size in @p attributes is nonzero, 1592 * it must be equal to the size from @p data. 1593 * @param [in] data Buffer containing the key data. The content of this 1594 * buffer is interpreted according to the type declared 1595 * in @p attributes. 1596 * All implementations must support at least the format 1597 * described in the documentation 1598 * of KeyStore_PSA_exportKey() or KeyStore_PSA_exportPublicKey() 1599 * for the chosen type. Implementations may allow other formats, but should 1600 * be conservative: implementations should err on the side of rejecting 1601 * content if it may be erroneous (e.g. wrong type or truncated data). 1602 * @param [in] dataLength Size of the @p data buffer in bytes. 1603 * @param [out] key On success, the key file ID of the newly created key. 1604 * @c 0 on failure. 1605 * 1606 * @retval #KEYSTORE_PSA_STATUS_SUCCESS 1607 * Success. 1608 * If the key is persistent, the key material and the key's metadata 1609 * have been saved to persistent storage. 1610 * @retval KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE 1611 * @retval #KEYSTORE_PSA_STATUS_ALREADY_EXISTS 1612 * This is an attempt to create a key, and there is 1613 * already a key with the given key file identifier. 1614 * @retval #KEYSTORE_PSA_STATUS_NOT_SUPPORTED 1615 * The key type or key size is not supported, either by the 1616 * implementation in general or in this particular persistent 1617 * location. @retval #KEYSTORE_PSA_STATUS_INVALID_ARGUMENT The key attributes, 1618 * as a whole, are invalid. @retval #KEYSTORE_PSA_STATUS_INVALID_ARGUMENT The 1619 * key data is not correctly formatted. @retval 1620 * #KEYSTORE_PSA_STATUS_INVALID_ARGUMENT The size in @p attributes is nonzero 1621 * and does not match the size of the key data. @retval 1622 * #KEYSTORE_PSA_STATUS_INSUFFICIENT_MEMORY @retval 1623 * #KEYSTORE_PSA_STATUS_INSUFFICIENT_STORAGE @retval 1624 * #KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE @retval 1625 * #KEYSTORE_PSA_STATUS_STORAGE_FAILURE @retval 1626 * #KEYSTORE_PSA_STATUS_HARDWARE_FAILURE @retval 1627 * #KEYSTORE_PSA_STATUS_CORRUPTION_DETECTED @retval #KEYSTORE_PSA_STATUS_BAD_STATE 1628 * The library has not been previously initialized by 1629 * KeyStore_PSA_init(). It is implementation-dependent whether a failure to 1630 * initialize results in this error code. 1631 */ 1632 int_fast16_t KeyStore_PSA_importKey(KeyStore_PSA_KeyAttributes *attributes, 1633 uint8_t *data, 1634 size_t dataLength, 1635 KeyStore_PSA_KeyFileId *key); 1636 1637 /** @brief Retrieve the attributes of a key. 1638 * 1639 * This function first resets the attribute structure as with 1640 * KeyStore_PSA_resetKeyAttributes(). It then copies the attributes of 1641 * the given key into the given attribute structure. 1642 * 1643 * @note This function may allocate memory or other resources. 1644 * Once you have called this function on an attribute structure, 1645 * you must call KeyStore_PSA_resetKeyAttributes() to free these 1646 * resources. 1647 * 1648 * @param [in] key Identifier of the key to query. 1649 * @param [in,out] attributes On success, the attributes of the key. 1650 * On failure, equivalent to a 1651 * freshly-initialized structure. 1652 * 1653 * @retval #KEYSTORE_PSA_STATUS_SUCCESS 1654 * @retval #KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE 1655 * @retval #KEYSTORE_PSA_STATUS_INVALID_KEY_ID 1656 * @retval #KEYSTORE_PSA_STATUS_INSUFFICIENT_MEMORY 1657 * @retval #KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE 1658 * @retval #KEYSTORE_PSA_STATUS_CORRUPTION_DETECTED 1659 * @retval #KEYSTORE_PSA_STATUS_STORAGE_FAILURE 1660 * @retval #KEYSTORE_PSA_STATUS_BAD_STATE 1661 * The library has not been previously initialized by 1662 * KeyStore_PSA_crypto_init(). It is implementation-dependent whether a failure 1663 * to initialize results in this error code. 1664 */ 1665 int_fast16_t KeyStore_PSA_getKeyAttributes(KeyStore_PSA_KeyFileId key, KeyStore_PSA_KeyAttributes *attributes); 1666 1667 /** 1668 * @brief Remove non-essential copies of key material from memory. 1669 * 1670 * An implementation is permitted to make additional copies of key material 1671 * for keys that have been created with the cache policy, an implementation 1672 * is permitted to make additional copies of the key material that are not 1673 * in storage and not for the purpose of ongoing operations. This function 1674 * will remove these extra copies of the key material from memory. 1675 * 1676 * This function is not required to remove key material from memory in any 1677 * of the following situations: 1678 * - The key is currently in use in a cryptographic operation. 1679 * - The key is volatile 1680 * 1681 * @param [in] key Key handle to close. . 1682 * If this is @c 0, do nothing and return @c 1683 * KEYSTORE_PSA_STATUS_SUCCESS. 1684 * 1685 * @retval #KEYSTORE_PSA_STATUS_SUCCESS 1686 * @p Handle was valid and the key material that it 1687 * referred to has been closed. 1688 * Alternatively, @p Handle is @c 0. 1689 * @retval KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE 1690 * @retval #KEYSTORE_PSA_STATUS_INVALID_KEY_ID 1691 * @p handle is not a valid handle nor @c 0. 1692 * @retval #KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE 1693 * There was an failure in communication with the cryptoprocessor. 1694 * The key material may still be present in the cryptoprocessor. 1695 * @retval #KEYSTORE_PSA_STATUS_STORAGE_FAILURE 1696 * The storage is corrupted. Implementations shall make a best 1697 * effort to erase key material even in this stage, however applications 1698 * should be aware that it may be impossible to guarantee that the 1699 * key material is not recoverable in such cases. 1700 * @retval #KEYSTORE_PSA_STATUS_CORRUPTION_DETECTED 1701 * An unexpected condition which is not a storage corruption or 1702 * a communication failure occurred. The cryptoprocessor may have 1703 * been compromised. 1704 * @retval #KEYSTORE_PSA_STATUS_BAD_STATE 1705 * The library has not been previously initialized by 1706 * KeyStore_PSA_init(). It is implementation-dependent whether a failure to 1707 * initialize results in this error code. 1708 */ 1709 int_fast16_t KeyStore_PSA_purgeKey(KeyStore_PSA_KeyFileId key); 1710 1711 /** 1712 * @brief Destroy a key. 1713 * 1714 * This function destroys a key from both volatile memory and, if 1715 * applicable, non-volatile storage. Implementations shall make a best 1716 * effort to ensure that that the key material cannot be recovered. 1717 * 1718 * This function also erases any metadata such as policies and frees 1719 * resources associated with the key. 1720 * 1721 * Destroying the key makes the ID invalid, and the key ID must not be used 1722 * again by the application. 1723 * 1724 * If a key is currently in use in a multipart operation, then destroying 1725 * the key will cause the multipart operation to fail. 1726 * 1727 * After a volatile key is destroyed, it is recommended that the 1728 * implementation does not immediately reuse the same key ID value for a 1729 * different key. This reduces the risk of an attack that is able to exploit 1730 * a key identifier reuse vulnerability within an application. 1731 * 1732 * This function can also be used to destroy other sensitive data, such as 1733 * certificates using its corresponding key file ID. 1734 * 1735 * @param [in] key Key file ID of the key to erase. 1736 * If key ID portion is @c 0, do nothing and return @c 1737 * KEYSTORE_PSA_STATUS_SUCCESS. 1738 * 1739 * @retval #KEYSTORE_PSA_STATUS_SUCCESS 1740 * @p ID was a valid ID and the key material that it 1741 * referred to has been erased. 1742 * Alternatively, @p ID is @c 0. 1743 * @retval KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE 1744 * @retval #KEYSTORE_PSA_STATUS_NOT_PERMITTED 1745 * The key cannot be erased because it is read-only, 1746 * either due to a policy or due to physical restrictions. 1747 * @retval #KEYSTORE_PSA_STATUS_INVALID_KEY_ID 1748 * @p ID is not a valid ID. 1749 * @retval #KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE 1750 * There was an failure in communication with the cryptoprocessor. 1751 * The key material may still be present in the cryptoprocessor. 1752 * @retval #KEYSTORE_PSA_STATUS_STORAGE_FAILURE 1753 * The storage is corrupted. Implementations shall make a best 1754 * effort to erase key material even in this stage, however applications 1755 * should be aware that it may be impossible to guarantee that the 1756 * key material is not recoverable in such cases. 1757 * @retval #KEYSTORE_PSA_STATUS_CORRUPTION_DETECTED 1758 * An unexpected condition which is not a storage corruption or 1759 * a communication failure occurred. The cryptoprocessor may have 1760 * been compromised. 1761 * @retval #KEYSTORE_PSA_STATUS_BAD_STATE 1762 * The library has not been previously initialized by 1763 * KeyStore_PSA_init(). It is implementation-dependent whether a failure to 1764 * initialize results in this error code. 1765 */ 1766 int_fast16_t KeyStore_PSA_destroyKey(KeyStore_PSA_KeyFileId key); 1767 1768 #ifdef __cplusplus 1769 } 1770 #endif 1771 1772 #endif /* ti_drivers_KeyStore_PSA__include */ 1773
