1/** 2 * \file psa/crypto_values.h 3 * 4 * \brief PSA cryptography module: macros to build and analyze integer values. 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 macros to build and analyze 11 * values of integral types that encode properties of cryptographic keys, 12 * designations of cryptographic algorithms, and error codes returned by 13 * the library. 14 * 15 * Note that many of the constants defined in this file are embedded in 16 * the persistent key store, as part of key metadata (including usage 17 * policies). As a consequence, they must not be changed (unless the storage 18 * format version changes). 19 * 20 * This header file only defines preprocessor macros. 21 */ 22/* 23 * Copyright The Mbed TLS Contributors 24 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 25 */ 26 27#ifndef PSA_CRYPTO_VALUES_H 28#define PSA_CRYPTO_VALUES_H 29#include "mbedtls/private_access.h" 30 31/** \defgroup error Error codes 32 * @{ 33 */ 34 35/* PSA error codes */ 36 37/* Error codes are standardized across PSA domains (framework, crypto, storage, 38 * etc.). Do not change the values in this section or even the expansions 39 * of each macro: it must be possible to `#include` both this header 40 * and some other PSA component's headers in the same C source, 41 * which will lead to duplicate definitions of the `PSA_SUCCESS` and 42 * `PSA_ERROR_xxx` macros, which is ok if and only if the macros expand 43 * to the same sequence of tokens. 44 * 45 * If you must add a new 46 * value, check with the Arm PSA framework group to pick one that other 47 * domains aren't already using. */ 48 49/* Tell uncrustify not to touch the constant definitions, otherwise 50 * it might change the spacing to something that is not PSA-compliant 51 * (e.g. adding a space after casts). 52 * 53 * *INDENT-OFF* 54 */ 55 56/** The action was completed successfully. */ 57#define PSA_SUCCESS ((psa_status_t)0) 58 59/** An error occurred that does not correspond to any defined 60 * failure cause. 61 * 62 * Implementations may use this error code if none of the other standard 63 * error codes are applicable. */ 64#define PSA_ERROR_GENERIC_ERROR ((psa_status_t)-132) 65 66/** The requested operation or a parameter is not supported 67 * by this implementation. 68 * 69 * Implementations should return this error code when an enumeration 70 * parameter such as a key type, algorithm, etc. is not recognized. 71 * If a combination of parameters is recognized and identified as 72 * not valid, return #PSA_ERROR_INVALID_ARGUMENT instead. */ 73#define PSA_ERROR_NOT_SUPPORTED ((psa_status_t)-134) 74 75/** The requested action is denied by a policy. 76 * 77 * Implementations should return this error code when the parameters 78 * are recognized as valid and supported, and a policy explicitly 79 * denies the requested operation. 80 * 81 * If a subset of the parameters of a function call identify a 82 * forbidden operation, and another subset of the parameters are 83 * not valid or not supported, it is unspecified whether the function 84 * returns #PSA_ERROR_NOT_PERMITTED, #PSA_ERROR_NOT_SUPPORTED or 85 * #PSA_ERROR_INVALID_ARGUMENT. */ 86#define PSA_ERROR_NOT_PERMITTED ((psa_status_t)-133) 87 88/** An output buffer is too small. 89 * 90 * Applications can call the \c PSA_xxx_SIZE macro listed in the function 91 * description to determine a sufficient buffer size. 92 * 93 * Implementations should preferably return this error code only 94 * in cases when performing the operation with a larger output 95 * buffer would succeed. However implementations may return this 96 * error if a function has invalid or unsupported parameters in addition 97 * to the parameters that determine the necessary output buffer size. */ 98#define PSA_ERROR_BUFFER_TOO_SMALL ((psa_status_t)-138) 99 100/** Asking for an item that already exists 101 * 102 * Implementations should return this error, when attempting 103 * to write an item (like a key) that already exists. */ 104#define PSA_ERROR_ALREADY_EXISTS ((psa_status_t)-139) 105 106/** Asking for an item that doesn't exist 107 * 108 * Implementations should return this error, if a requested item (like 109 * a key) does not exist. */ 110#define PSA_ERROR_DOES_NOT_EXIST ((psa_status_t)-140) 111 112/** The requested action cannot be performed in the current state. 113 * 114 * Multipart operations return this error when one of the 115 * functions is called out of sequence. Refer to the function 116 * descriptions for permitted sequencing of functions. 117 * 118 * Implementations shall not return this error code to indicate 119 * that a key either exists or not, 120 * but shall instead return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST 121 * as applicable. 122 * 123 * Implementations shall not return this error code to indicate that a 124 * key identifier is invalid, but shall return #PSA_ERROR_INVALID_HANDLE 125 * instead. */ 126#define PSA_ERROR_BAD_STATE ((psa_status_t)-137) 127 128/** The parameters passed to the function are invalid. 129 * 130 * Implementations may return this error any time a parameter or 131 * combination of parameters are recognized as invalid. 132 * 133 * Implementations shall not return this error code to indicate that a 134 * key identifier is invalid, but shall return #PSA_ERROR_INVALID_HANDLE 135 * instead. 136 */ 137#define PSA_ERROR_INVALID_ARGUMENT ((psa_status_t)-135) 138 139/** There is not enough runtime memory. 140 * 141 * If the action is carried out across multiple security realms, this 142 * error can refer to available memory in any of the security realms. */ 143#define PSA_ERROR_INSUFFICIENT_MEMORY ((psa_status_t)-141) 144 145/** There is not enough persistent storage. 146 * 147 * Functions that modify the key storage return this error code if 148 * there is insufficient storage space on the host media. In addition, 149 * many functions that do not otherwise access storage may return this 150 * error code if the implementation requires a mandatory log entry for 151 * the requested action and the log storage space is full. */ 152#define PSA_ERROR_INSUFFICIENT_STORAGE ((psa_status_t)-142) 153 154/** There was a communication failure inside the implementation. 155 * 156 * This can indicate a communication failure between the application 157 * and an external cryptoprocessor or between the cryptoprocessor and 158 * an external volatile or persistent memory. A communication failure 159 * may be transient or permanent depending on the cause. 160 * 161 * \warning If a function returns this error, it is undetermined 162 * whether the requested action has completed or not. Implementations 163 * should return #PSA_SUCCESS on successful completion whenever 164 * possible, however functions may return #PSA_ERROR_COMMUNICATION_FAILURE 165 * if the requested action was completed successfully in an external 166 * cryptoprocessor but there was a breakdown of communication before 167 * the cryptoprocessor could report the status to the application. 168 */ 169#define PSA_ERROR_COMMUNICATION_FAILURE ((psa_status_t)-145) 170 171/** There was a storage failure that may have led to data loss. 172 * 173 * This error indicates that some persistent storage is corrupted. 174 * It should not be used for a corruption of volatile memory 175 * (use #PSA_ERROR_CORRUPTION_DETECTED), for a communication error 176 * between the cryptoprocessor and its external storage (use 177 * #PSA_ERROR_COMMUNICATION_FAILURE), or when the storage is 178 * in a valid state but is full (use #PSA_ERROR_INSUFFICIENT_STORAGE). 179 * 180 * Note that a storage failure does not indicate that any data that was 181 * previously read is invalid. However this previously read data may no 182 * longer be readable from storage. 183 * 184 * When a storage failure occurs, it is no longer possible to ensure 185 * the global integrity of the keystore. Depending on the global 186 * integrity guarantees offered by the implementation, access to other 187 * data may or may not fail even if the data is still readable but 188 * its integrity cannot be guaranteed. 189 * 190 * Implementations should only use this error code to report a 191 * permanent storage corruption. However application writers should 192 * keep in mind that transient errors while reading the storage may be 193 * reported using this error code. */ 194#define PSA_ERROR_STORAGE_FAILURE ((psa_status_t)-146) 195 196/** A hardware failure was detected. 197 * 198 * A hardware failure may be transient or permanent depending on the 199 * cause. */ 200#define PSA_ERROR_HARDWARE_FAILURE ((psa_status_t)-147) 201 202/** A tampering attempt was detected. 203 * 204 * If an application receives this error code, there is no guarantee 205 * that previously accessed or computed data was correct and remains 206 * confidential. Applications should not perform any security function 207 * and should enter a safe failure state. 208 * 209 * Implementations may return this error code if they detect an invalid 210 * state that cannot happen during normal operation and that indicates 211 * that the implementation's security guarantees no longer hold. Depending 212 * on the implementation architecture and on its security and safety goals, 213 * the implementation may forcibly terminate the application. 214 * 215 * This error code is intended as a last resort when a security breach 216 * is detected and it is unsure whether the keystore data is still 217 * protected. Implementations shall only return this error code 218 * to report an alarm from a tampering detector, to indicate that 219 * the confidentiality of stored data can no longer be guaranteed, 220 * or to indicate that the integrity of previously returned data is now 221 * considered compromised. Implementations shall not use this error code 222 * to indicate a hardware failure that merely makes it impossible to 223 * perform the requested operation (use #PSA_ERROR_COMMUNICATION_FAILURE, 224 * #PSA_ERROR_STORAGE_FAILURE, #PSA_ERROR_HARDWARE_FAILURE, 225 * #PSA_ERROR_INSUFFICIENT_ENTROPY or other applicable error code 226 * instead). 227 * 228 * This error indicates an attack against the application. Implementations 229 * shall not return this error code as a consequence of the behavior of 230 * the application itself. */ 231#define PSA_ERROR_CORRUPTION_DETECTED ((psa_status_t)-151) 232 233/** There is not enough entropy to generate random data needed 234 * for the requested action. 235 * 236 * This error indicates a failure of a hardware random generator. 237 * Application writers should note that this error can be returned not 238 * only by functions whose purpose is to generate random data, such 239 * as key, IV or nonce generation, but also by functions that execute 240 * an algorithm with a randomized result, as well as functions that 241 * use randomization of intermediate computations as a countermeasure 242 * to certain attacks. 243 * 244 * Implementations should avoid returning this error after psa_crypto_init() 245 * has succeeded. Implementations should generate sufficient 246 * entropy during initialization and subsequently use a cryptographically 247 * secure pseudorandom generator (PRNG). However implementations may return 248 * this error at any time if a policy requires the PRNG to be reseeded 249 * during normal operation. */ 250#define PSA_ERROR_INSUFFICIENT_ENTROPY ((psa_status_t)-148) 251 252/** The signature, MAC or hash is incorrect. 253 * 254 * Verification functions return this error if the verification 255 * calculations completed successfully, and the value to be verified 256 * was determined to be incorrect. 257 * 258 * If the value to verify has an invalid size, implementations may return 259 * either #PSA_ERROR_INVALID_ARGUMENT or #PSA_ERROR_INVALID_SIGNATURE. */ 260#define PSA_ERROR_INVALID_SIGNATURE ((psa_status_t)-149) 261 262/** The decrypted padding is incorrect. 263 * 264 * \warning In some protocols, when decrypting data, it is essential that 265 * the behavior of the application does not depend on whether the padding 266 * is correct, down to precise timing. Applications should prefer 267 * protocols that use authenticated encryption rather than plain 268 * encryption. If the application must perform a decryption of 269 * unauthenticated data, the application writer should take care not 270 * to reveal whether the padding is invalid. 271 * 272 * Implementations should strive to make valid and invalid padding 273 * as close as possible to indistinguishable to an external observer. 274 * In particular, the timing of a decryption operation should not 275 * depend on the validity of the padding. */ 276#define PSA_ERROR_INVALID_PADDING ((psa_status_t)-150) 277 278/** Return this error when there's insufficient data when attempting 279 * to read from a resource. */ 280#define PSA_ERROR_INSUFFICIENT_DATA ((psa_status_t)-143) 281 282/** This can be returned if a function can no longer operate correctly. 283 * For example, if an essential initialization operation failed or 284 * a mutex operation failed. */ 285#define PSA_ERROR_SERVICE_FAILURE ((psa_status_t)-144) 286 287/** The key identifier is not valid. See also :ref:\`key-handles\`. 288 */ 289#define PSA_ERROR_INVALID_HANDLE ((psa_status_t)-136) 290 291/** Stored data has been corrupted. 292 * 293 * This error indicates that some persistent storage has suffered corruption. 294 * It does not indicate the following situations, which have specific error 295 * codes: 296 * 297 * - A corruption of volatile memory - use #PSA_ERROR_CORRUPTION_DETECTED. 298 * - A communication error between the cryptoprocessor and its external 299 * storage - use #PSA_ERROR_COMMUNICATION_FAILURE. 300 * - When the storage is in a valid state but is full - use 301 * #PSA_ERROR_INSUFFICIENT_STORAGE. 302 * - When the storage fails for other reasons - use 303 * #PSA_ERROR_STORAGE_FAILURE. 304 * - When the stored data is not valid - use #PSA_ERROR_DATA_INVALID. 305 * 306 * \note A storage corruption does not indicate that any data that was 307 * previously read is invalid. However this previously read data might no 308 * longer be readable from storage. 309 * 310 * When a storage failure occurs, it is no longer possible to ensure the 311 * global integrity of the keystore. 312 */ 313#define PSA_ERROR_DATA_CORRUPT ((psa_status_t)-152) 314 315/** Data read from storage is not valid for the implementation. 316 * 317 * This error indicates that some data read from storage does not have a valid 318 * format. It does not indicate the following situations, which have specific 319 * error codes: 320 * 321 * - When the storage or stored data is corrupted - use #PSA_ERROR_DATA_CORRUPT 322 * - When the storage fails for other reasons - use #PSA_ERROR_STORAGE_FAILURE 323 * - An invalid argument to the API - use #PSA_ERROR_INVALID_ARGUMENT 324 * 325 * This error is typically a result of either storage corruption on a 326 * cleartext storage backend, or an attempt to read data that was 327 * written by an incompatible version of the library. 328 */ 329#define PSA_ERROR_DATA_INVALID ((psa_status_t)-153) 330 331/** The function that returns this status is defined as interruptible and 332 * still has work to do, thus the user should call the function again with the 333 * same operation context until it either returns #PSA_SUCCESS or any other 334 * error. This is not an error per se, more a notification of status. 335 */ 336#define PSA_OPERATION_INCOMPLETE ((psa_status_t)-248) 337 338/* *INDENT-ON* */ 339 340/**@}*/ 341 342/** \defgroup crypto_types Key and algorithm types 343 * @{ 344 */ 345 346/* Note that key type values, including ECC family and DH group values, are 347 * embedded in the persistent key store, as part of key metadata. As a 348 * consequence, they must not be changed (unless the storage format version 349 * changes). 350 */ 351 352/** An invalid key type value. 353 * 354 * Zero is not the encoding of any key type. 355 */ 356#define PSA_KEY_TYPE_NONE ((psa_key_type_t) 0x0000) 357 358/** Vendor-defined key type flag. 359 * 360 * Key types defined by this standard will never have the 361 * #PSA_KEY_TYPE_VENDOR_FLAG bit set. Vendors who define additional key types 362 * must use an encoding with the #PSA_KEY_TYPE_VENDOR_FLAG bit set and should 363 * respect the bitwise structure used by standard encodings whenever practical. 364 */ 365#define PSA_KEY_TYPE_VENDOR_FLAG ((psa_key_type_t) 0x8000) 366 367#define PSA_KEY_TYPE_CATEGORY_MASK ((psa_key_type_t) 0x7000) 368#define PSA_KEY_TYPE_CATEGORY_RAW ((psa_key_type_t) 0x1000) 369#define PSA_KEY_TYPE_CATEGORY_SYMMETRIC ((psa_key_type_t) 0x2000) 370#define PSA_KEY_TYPE_CATEGORY_PUBLIC_KEY ((psa_key_type_t) 0x4000) 371#define PSA_KEY_TYPE_CATEGORY_KEY_PAIR ((psa_key_type_t) 0x7000) 372 373#define PSA_KEY_TYPE_CATEGORY_FLAG_PAIR ((psa_key_type_t) 0x3000) 374 375/** Whether a key type is vendor-defined. 376 * 377 * See also #PSA_KEY_TYPE_VENDOR_FLAG. 378 */ 379#define PSA_KEY_TYPE_IS_VENDOR_DEFINED(type) \ 380 (((type) & PSA_KEY_TYPE_VENDOR_FLAG) != 0) 381 382/** Whether a key type is an unstructured array of bytes. 383 * 384 * This encompasses both symmetric keys and non-key data. 385 */ 386#define PSA_KEY_TYPE_IS_UNSTRUCTURED(type) \ 387 (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_RAW || \ 388 ((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_SYMMETRIC) 389 390/** Whether a key type is asymmetric: either a key pair or a public key. */ 391#define PSA_KEY_TYPE_IS_ASYMMETRIC(type) \ 392 (((type) & PSA_KEY_TYPE_CATEGORY_MASK \ 393 & ~PSA_KEY_TYPE_CATEGORY_FLAG_PAIR) == \ 394 PSA_KEY_TYPE_CATEGORY_PUBLIC_KEY) 395/** Whether a key type is the public part of a key pair. */ 396#define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) \ 397 (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_PUBLIC_KEY) 398/** Whether a key type is a key pair containing a private part and a public 399 * part. */ 400#define PSA_KEY_TYPE_IS_KEY_PAIR(type) \ 401 (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_KEY_PAIR) 402/** The key pair type corresponding to a public key type. 403 * 404 * You may also pass a key pair type as \p type, it will be left unchanged. 405 * 406 * \param type A public key type or key pair type. 407 * 408 * \return The corresponding key pair type. 409 * If \p type is not a public key or a key pair, 410 * the return value is undefined. 411 */ 412#define PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY(type) \ 413 ((type) | PSA_KEY_TYPE_CATEGORY_FLAG_PAIR) 414/** The public key type corresponding to a key pair type. 415 * 416 * You may also pass a public key type as \p type, it will be left unchanged. 417 * 418 * \param type A public key type or key pair type. 419 * 420 * \return The corresponding public key type. 421 * If \p type is not a public key or a key pair, 422 * the return value is undefined. 423 */ 424#define PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) \ 425 ((type) & ~PSA_KEY_TYPE_CATEGORY_FLAG_PAIR) 426 427/** Raw data. 428 * 429 * A "key" of this type cannot be used for any cryptographic operation. 430 * Applications may use this type to store arbitrary data in the keystore. */ 431#define PSA_KEY_TYPE_RAW_DATA ((psa_key_type_t) 0x1001) 432 433/** HMAC key. 434 * 435 * The key policy determines which underlying hash algorithm the key can be 436 * used for. 437 * 438 * HMAC keys should generally have the same size as the underlying hash. 439 * This size can be calculated with #PSA_HASH_LENGTH(\c alg) where 440 * \c alg is the HMAC algorithm or the underlying hash algorithm. */ 441#define PSA_KEY_TYPE_HMAC ((psa_key_type_t) 0x1100) 442 443/** A secret for key derivation. 444 * 445 * This key type is for high-entropy secrets only. For low-entropy secrets, 446 * #PSA_KEY_TYPE_PASSWORD should be used instead. 447 * 448 * These keys can be used as the #PSA_KEY_DERIVATION_INPUT_SECRET or 449 * #PSA_KEY_DERIVATION_INPUT_PASSWORD input of key derivation algorithms. 450 * 451 * The key policy determines which key derivation algorithm the key 452 * can be used for. 453 */ 454#define PSA_KEY_TYPE_DERIVE ((psa_key_type_t) 0x1200) 455 456/** A low-entropy secret for password hashing or key derivation. 457 * 458 * This key type is suitable for passwords and passphrases which are typically 459 * intended to be memorizable by humans, and have a low entropy relative to 460 * their size. It can be used for randomly generated or derived keys with 461 * maximum or near-maximum entropy, but #PSA_KEY_TYPE_DERIVE is more suitable 462 * for such keys. It is not suitable for passwords with extremely low entropy, 463 * such as numerical PINs. 464 * 465 * These keys can be used as the #PSA_KEY_DERIVATION_INPUT_PASSWORD input of 466 * key derivation algorithms. Algorithms that accept such an input were 467 * designed to accept low-entropy secret and are known as password hashing or 468 * key stretching algorithms. 469 * 470 * These keys cannot be used as the #PSA_KEY_DERIVATION_INPUT_SECRET input of 471 * key derivation algorithms, as the algorithms that take such an input expect 472 * it to be high-entropy. 473 * 474 * The key policy determines which key derivation algorithm the key can be 475 * used for, among the permissible subset defined above. 476 */ 477#define PSA_KEY_TYPE_PASSWORD ((psa_key_type_t) 0x1203) 478 479/** A secret value that can be used to verify a password hash. 480 * 481 * The key policy determines which key derivation algorithm the key 482 * can be used for, among the same permissible subset as for 483 * #PSA_KEY_TYPE_PASSWORD. 484 */ 485#define PSA_KEY_TYPE_PASSWORD_HASH ((psa_key_type_t) 0x1205) 486 487/** A secret value that can be used in when computing a password hash. 488 * 489 * The key policy determines which key derivation algorithm the key 490 * can be used for, among the subset of algorithms that can use pepper. 491 */ 492#define PSA_KEY_TYPE_PEPPER ((psa_key_type_t) 0x1206) 493 494/** Key for a cipher, AEAD or MAC algorithm based on the AES block cipher. 495 * 496 * The size of the key can be 16 bytes (AES-128), 24 bytes (AES-192) or 497 * 32 bytes (AES-256). 498 */ 499#define PSA_KEY_TYPE_AES ((psa_key_type_t) 0x2400) 500 501/** Key for a cipher, AEAD or MAC algorithm based on the 502 * ARIA block cipher. */ 503#define PSA_KEY_TYPE_ARIA ((psa_key_type_t) 0x2406) 504 505/** Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES). 506 * 507 * The size of the key can be 64 bits (single DES), 128 bits (2-key 3DES) or 508 * 192 bits (3-key 3DES). 509 * 510 * Note that single DES and 2-key 3DES are weak and strongly 511 * deprecated and should only be used to decrypt legacy data. 3-key 3DES 512 * is weak and deprecated and should only be used in legacy protocols. 513 */ 514#define PSA_KEY_TYPE_DES ((psa_key_type_t) 0x2301) 515 516/** Key for a cipher, AEAD or MAC algorithm based on the 517 * Camellia block cipher. */ 518#define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t) 0x2403) 519 520/** Key for the ChaCha20 stream cipher or the Chacha20-Poly1305 AEAD algorithm. 521 * 522 * ChaCha20 and the ChaCha20_Poly1305 construction are defined in RFC 7539. 523 * 524 * \note For ChaCha20 and ChaCha20_Poly1305, Mbed TLS only supports 525 * 12-byte nonces. 526 * 527 * \note For ChaCha20, the initial counter value is 0. To encrypt or decrypt 528 * with the initial counter value 1, you can process and discard a 529 * 64-byte block before the real data. 530 */ 531#define PSA_KEY_TYPE_CHACHA20 ((psa_key_type_t) 0x2004) 532 533/** RSA public key. 534 * 535 * The size of an RSA key is the bit size of the modulus. 536 */ 537#define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t) 0x4001) 538/** RSA key pair (private and public key). 539 * 540 * The size of an RSA key is the bit size of the modulus. 541 */ 542#define PSA_KEY_TYPE_RSA_KEY_PAIR ((psa_key_type_t) 0x7001) 543/** Whether a key type is an RSA key (pair or public-only). */ 544#define PSA_KEY_TYPE_IS_RSA(type) \ 545 (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_RSA_PUBLIC_KEY) 546 547#define PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE ((psa_key_type_t) 0x4100) 548#define PSA_KEY_TYPE_ECC_KEY_PAIR_BASE ((psa_key_type_t) 0x7100) 549#define PSA_KEY_TYPE_ECC_CURVE_MASK ((psa_key_type_t) 0x00ff) 550/** Elliptic curve key pair. 551 * 552 * The size of an elliptic curve key is the bit size associated with the curve, 553 * i.e. the bit size of *q* for a curve over a field *F<sub>q</sub>*. 554 * See the documentation of `PSA_ECC_FAMILY_xxx` curve families for details. 555 * 556 * \param curve A value of type ::psa_ecc_family_t that 557 * identifies the ECC curve to be used. 558 */ 559#define PSA_KEY_TYPE_ECC_KEY_PAIR(curve) \ 560 (PSA_KEY_TYPE_ECC_KEY_PAIR_BASE | (curve)) 561/** Elliptic curve public key. 562 * 563 * The size of an elliptic curve public key is the same as the corresponding 564 * private key (see #PSA_KEY_TYPE_ECC_KEY_PAIR and the documentation of 565 * `PSA_ECC_FAMILY_xxx` curve families). 566 * 567 * \param curve A value of type ::psa_ecc_family_t that 568 * identifies the ECC curve to be used. 569 */ 570#define PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) \ 571 (PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE | (curve)) 572 573/** Whether a key type is an elliptic curve key (pair or public-only). */ 574#define PSA_KEY_TYPE_IS_ECC(type) \ 575 ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & \ 576 ~PSA_KEY_TYPE_ECC_CURVE_MASK) == PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE) 577/** Whether a key type is an elliptic curve key pair. */ 578#define PSA_KEY_TYPE_IS_ECC_KEY_PAIR(type) \ 579 (((type) & ~PSA_KEY_TYPE_ECC_CURVE_MASK) == \ 580 PSA_KEY_TYPE_ECC_KEY_PAIR_BASE) 581/** Whether a key type is an elliptic curve public key. */ 582#define PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(type) \ 583 (((type) & ~PSA_KEY_TYPE_ECC_CURVE_MASK) == \ 584 PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE) 585 586/** Extract the curve from an elliptic curve key type. */ 587#define PSA_KEY_TYPE_ECC_GET_FAMILY(type) \ 588 ((psa_ecc_family_t) (PSA_KEY_TYPE_IS_ECC(type) ? \ 589 ((type) & PSA_KEY_TYPE_ECC_CURVE_MASK) : \ 590 0)) 591 592/** Check if the curve of given family is Weierstrass elliptic curve. */ 593#define PSA_ECC_FAMILY_IS_WEIERSTRASS(family) ((family & 0xc0) == 0) 594 595/** SEC Koblitz curves over prime fields. 596 * 597 * This family comprises the following curves: 598 * secp192k1, secp224k1, secp256k1. 599 * They are defined in _Standards for Efficient Cryptography_, 600 * _SEC 2: Recommended Elliptic Curve Domain Parameters_. 601 * https://www.secg.org/sec2-v2.pdf 602 * 603 * \note For secp224k1, the bit-size is 225 (size of a private value). 604 * 605 * \note Mbed TLS only supports secp192k1 and secp256k1. 606 */ 607#define PSA_ECC_FAMILY_SECP_K1 ((psa_ecc_family_t) 0x17) 608 609/** SEC random curves over prime fields. 610 * 611 * This family comprises the following curves: 612 * secp192r1, secp224r1, secp256r1, secp384r1, secp521r1. 613 * They are defined in _Standards for Efficient Cryptography_, 614 * _SEC 2: Recommended Elliptic Curve Domain Parameters_. 615 * https://www.secg.org/sec2-v2.pdf 616 */ 617#define PSA_ECC_FAMILY_SECP_R1 ((psa_ecc_family_t) 0x12) 618/* SECP160R2 (SEC2 v1, obsolete, not supported in Mbed TLS) */ 619#define PSA_ECC_FAMILY_SECP_R2 ((psa_ecc_family_t) 0x1b) 620 621/** SEC Koblitz curves over binary fields. 622 * 623 * This family comprises the following curves: 624 * sect163k1, sect233k1, sect239k1, sect283k1, sect409k1, sect571k1. 625 * They are defined in _Standards for Efficient Cryptography_, 626 * _SEC 2: Recommended Elliptic Curve Domain Parameters_. 627 * https://www.secg.org/sec2-v2.pdf 628 * 629 * \note Mbed TLS does not support any curve in this family. 630 */ 631#define PSA_ECC_FAMILY_SECT_K1 ((psa_ecc_family_t) 0x27) 632 633/** SEC random curves over binary fields. 634 * 635 * This family comprises the following curves: 636 * sect163r1, sect233r1, sect283r1, sect409r1, sect571r1. 637 * They are defined in _Standards for Efficient Cryptography_, 638 * _SEC 2: Recommended Elliptic Curve Domain Parameters_. 639 * https://www.secg.org/sec2-v2.pdf 640 * 641 * \note Mbed TLS does not support any curve in this family. 642 */ 643#define PSA_ECC_FAMILY_SECT_R1 ((psa_ecc_family_t) 0x22) 644 645/** SEC additional random curves over binary fields. 646 * 647 * This family comprises the following curve: 648 * sect163r2. 649 * It is defined in _Standards for Efficient Cryptography_, 650 * _SEC 2: Recommended Elliptic Curve Domain Parameters_. 651 * https://www.secg.org/sec2-v2.pdf 652 * 653 * \note Mbed TLS does not support any curve in this family. 654 */ 655#define PSA_ECC_FAMILY_SECT_R2 ((psa_ecc_family_t) 0x2b) 656 657/** Brainpool P random curves. 658 * 659 * This family comprises the following curves: 660 * brainpoolP160r1, brainpoolP192r1, brainpoolP224r1, brainpoolP256r1, 661 * brainpoolP320r1, brainpoolP384r1, brainpoolP512r1. 662 * It is defined in RFC 5639. 663 * 664 * \note Mbed TLS only supports the 256-bit, 384-bit and 512-bit curves 665 * in this family. 666 */ 667#define PSA_ECC_FAMILY_BRAINPOOL_P_R1 ((psa_ecc_family_t) 0x30) 668 669/** Curve25519 and Curve448. 670 * 671 * This family comprises the following Montgomery curves: 672 * - 255-bit: Bernstein et al., 673 * _Curve25519: new Diffie-Hellman speed records_, LNCS 3958, 2006. 674 * The algorithm #PSA_ALG_ECDH performs X25519 when used with this curve. 675 * - 448-bit: Hamburg, 676 * _Ed448-Goldilocks, a new elliptic curve_, NIST ECC Workshop, 2015. 677 * The algorithm #PSA_ALG_ECDH performs X448 when used with this curve. 678 */ 679#define PSA_ECC_FAMILY_MONTGOMERY ((psa_ecc_family_t) 0x41) 680 681/** The twisted Edwards curves Ed25519 and Ed448. 682 * 683 * These curves are suitable for EdDSA (#PSA_ALG_PURE_EDDSA for both curves, 684 * #PSA_ALG_ED25519PH for the 255-bit curve, 685 * #PSA_ALG_ED448PH for the 448-bit curve). 686 * 687 * This family comprises the following twisted Edwards curves: 688 * - 255-bit: Edwards25519, the twisted Edwards curve birationally equivalent 689 * to Curve25519. 690 * Bernstein et al., _Twisted Edwards curves_, Africacrypt 2008. 691 * - 448-bit: Edwards448, the twisted Edwards curve birationally equivalent 692 * to Curve448. 693 * Hamburg, _Ed448-Goldilocks, a new elliptic curve_, NIST ECC Workshop, 2015. 694 * 695 * \note Mbed TLS does not support Edwards curves yet. 696 */ 697#define PSA_ECC_FAMILY_TWISTED_EDWARDS ((psa_ecc_family_t) 0x42) 698 699#define PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE ((psa_key_type_t) 0x4200) 700#define PSA_KEY_TYPE_DH_KEY_PAIR_BASE ((psa_key_type_t) 0x7200) 701#define PSA_KEY_TYPE_DH_GROUP_MASK ((psa_key_type_t) 0x00ff) 702/** Diffie-Hellman key pair. 703 * 704 * \param group A value of type ::psa_dh_family_t that identifies the 705 * Diffie-Hellman group to be used. 706 */ 707#define PSA_KEY_TYPE_DH_KEY_PAIR(group) \ 708 (PSA_KEY_TYPE_DH_KEY_PAIR_BASE | (group)) 709/** Diffie-Hellman public key. 710 * 711 * \param group A value of type ::psa_dh_family_t that identifies the 712 * Diffie-Hellman group to be used. 713 */ 714#define PSA_KEY_TYPE_DH_PUBLIC_KEY(group) \ 715 (PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE | (group)) 716 717/** Whether a key type is a Diffie-Hellman key (pair or public-only). */ 718#define PSA_KEY_TYPE_IS_DH(type) \ 719 ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & \ 720 ~PSA_KEY_TYPE_DH_GROUP_MASK) == PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE) 721/** Whether a key type is a Diffie-Hellman key pair. */ 722#define PSA_KEY_TYPE_IS_DH_KEY_PAIR(type) \ 723 (((type) & ~PSA_KEY_TYPE_DH_GROUP_MASK) == \ 724 PSA_KEY_TYPE_DH_KEY_PAIR_BASE) 725/** Whether a key type is a Diffie-Hellman public key. */ 726#define PSA_KEY_TYPE_IS_DH_PUBLIC_KEY(type) \ 727 (((type) & ~PSA_KEY_TYPE_DH_GROUP_MASK) == \ 728 PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE) 729 730/** Extract the group from a Diffie-Hellman key type. */ 731#define PSA_KEY_TYPE_DH_GET_FAMILY(type) \ 732 ((psa_dh_family_t) (PSA_KEY_TYPE_IS_DH(type) ? \ 733 ((type) & PSA_KEY_TYPE_DH_GROUP_MASK) : \ 734 0)) 735 736/** Diffie-Hellman groups defined in RFC 7919 Appendix A. 737 * 738 * This family includes groups with the following key sizes (in bits): 739 * 2048, 3072, 4096, 6144, 8192. A given implementation may support 740 * all of these sizes or only a subset. 741 */ 742#define PSA_DH_FAMILY_RFC7919 ((psa_dh_family_t) 0x03) 743 744#define PSA_GET_KEY_TYPE_BLOCK_SIZE_EXPONENT(type) \ 745 (((type) >> 8) & 7) 746/** The block size of a block cipher. 747 * 748 * \param type A cipher key type (value of type #psa_key_type_t). 749 * 750 * \return The block size for a block cipher, or 1 for a stream cipher. 751 * The return value is undefined if \p type is not a supported 752 * cipher key type. 753 * 754 * \note It is possible to build stream cipher algorithms on top of a block 755 * cipher, for example CTR mode (#PSA_ALG_CTR). 756 * This macro only takes the key type into account, so it cannot be 757 * used to determine the size of the data that #psa_cipher_update() 758 * might buffer for future processing in general. 759 * 760 * \note This macro returns a compile-time constant if its argument is one. 761 * 762 * \warning This macro may evaluate its argument multiple times. 763 */ 764#define PSA_BLOCK_CIPHER_BLOCK_LENGTH(type) \ 765 (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_SYMMETRIC ? \ 766 1u << PSA_GET_KEY_TYPE_BLOCK_SIZE_EXPONENT(type) : \ 767 0u) 768 769/* Note that algorithm values are embedded in the persistent key store, 770 * as part of key metadata. As a consequence, they must not be changed 771 * (unless the storage format version changes). 772 */ 773 774/** Vendor-defined algorithm flag. 775 * 776 * Algorithms defined by this standard will never have the #PSA_ALG_VENDOR_FLAG 777 * bit set. Vendors who define additional algorithms must use an encoding with 778 * the #PSA_ALG_VENDOR_FLAG bit set and should respect the bitwise structure 779 * used by standard encodings whenever practical. 780 */ 781#define PSA_ALG_VENDOR_FLAG ((psa_algorithm_t) 0x80000000) 782 783#define PSA_ALG_CATEGORY_MASK ((psa_algorithm_t) 0x7f000000) 784#define PSA_ALG_CATEGORY_HASH ((psa_algorithm_t) 0x02000000) 785#define PSA_ALG_CATEGORY_MAC ((psa_algorithm_t) 0x03000000) 786#define PSA_ALG_CATEGORY_CIPHER ((psa_algorithm_t) 0x04000000) 787#define PSA_ALG_CATEGORY_AEAD ((psa_algorithm_t) 0x05000000) 788#define PSA_ALG_CATEGORY_SIGN ((psa_algorithm_t) 0x06000000) 789#define PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION ((psa_algorithm_t) 0x07000000) 790#define PSA_ALG_CATEGORY_KEY_DERIVATION ((psa_algorithm_t) 0x08000000) 791#define PSA_ALG_CATEGORY_KEY_AGREEMENT ((psa_algorithm_t) 0x09000000) 792 793/** Whether an algorithm is vendor-defined. 794 * 795 * See also #PSA_ALG_VENDOR_FLAG. 796 */ 797#define PSA_ALG_IS_VENDOR_DEFINED(alg) \ 798 (((alg) & PSA_ALG_VENDOR_FLAG) != 0) 799 800/** Whether the specified algorithm is a hash algorithm. 801 * 802 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 803 * 804 * \return 1 if \p alg is a hash algorithm, 0 otherwise. 805 * This macro may return either 0 or 1 if \p alg is not a supported 806 * algorithm identifier. 807 */ 808#define PSA_ALG_IS_HASH(alg) \ 809 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_HASH) 810 811/** Whether the specified algorithm is a MAC algorithm. 812 * 813 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 814 * 815 * \return 1 if \p alg is a MAC algorithm, 0 otherwise. 816 * This macro may return either 0 or 1 if \p alg is not a supported 817 * algorithm identifier. 818 */ 819#define PSA_ALG_IS_MAC(alg) \ 820 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_MAC) 821 822/** Whether the specified algorithm is a symmetric cipher algorithm. 823 * 824 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 825 * 826 * \return 1 if \p alg is a symmetric cipher algorithm, 0 otherwise. 827 * This macro may return either 0 or 1 if \p alg is not a supported 828 * algorithm identifier. 829 */ 830#define PSA_ALG_IS_CIPHER(alg) \ 831 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_CIPHER) 832 833/** Whether the specified algorithm is an authenticated encryption 834 * with associated data (AEAD) algorithm. 835 * 836 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 837 * 838 * \return 1 if \p alg is an AEAD algorithm, 0 otherwise. 839 * This macro may return either 0 or 1 if \p alg is not a supported 840 * algorithm identifier. 841 */ 842#define PSA_ALG_IS_AEAD(alg) \ 843 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_AEAD) 844 845/** Whether the specified algorithm is an asymmetric signature algorithm, 846 * also known as public-key signature algorithm. 847 * 848 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 849 * 850 * \return 1 if \p alg is an asymmetric signature algorithm, 0 otherwise. 851 * This macro may return either 0 or 1 if \p alg is not a supported 852 * algorithm identifier. 853 */ 854#define PSA_ALG_IS_SIGN(alg) \ 855 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_SIGN) 856 857/** Whether the specified algorithm is an asymmetric encryption algorithm, 858 * also known as public-key encryption algorithm. 859 * 860 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 861 * 862 * \return 1 if \p alg is an asymmetric encryption algorithm, 0 otherwise. 863 * This macro may return either 0 or 1 if \p alg is not a supported 864 * algorithm identifier. 865 */ 866#define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg) \ 867 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION) 868 869/** Whether the specified algorithm is a key agreement algorithm. 870 * 871 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 872 * 873 * \return 1 if \p alg is a key agreement algorithm, 0 otherwise. 874 * This macro may return either 0 or 1 if \p alg is not a supported 875 * algorithm identifier. 876 */ 877#define PSA_ALG_IS_KEY_AGREEMENT(alg) \ 878 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_AGREEMENT) 879 880/** Whether the specified algorithm is a key derivation algorithm. 881 * 882 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 883 * 884 * \return 1 if \p alg is a key derivation algorithm, 0 otherwise. 885 * This macro may return either 0 or 1 if \p alg is not a supported 886 * algorithm identifier. 887 */ 888#define PSA_ALG_IS_KEY_DERIVATION(alg) \ 889 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_DERIVATION) 890 891/** Whether the specified algorithm is a key stretching / password hashing 892 * algorithm. 893 * 894 * A key stretching / password hashing algorithm is a key derivation algorithm 895 * that is suitable for use with a low-entropy secret such as a password. 896 * Equivalently, it's a key derivation algorithm that uses a 897 * #PSA_KEY_DERIVATION_INPUT_PASSWORD input step. 898 * 899 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 900 * 901 * \return 1 if \p alg is a key stretching / password hashing algorithm, 0 902 * otherwise. This macro may return either 0 or 1 if \p alg is not a 903 * supported algorithm identifier. 904 */ 905#define PSA_ALG_IS_KEY_DERIVATION_STRETCHING(alg) \ 906 (PSA_ALG_IS_KEY_DERIVATION(alg) && \ 907 (alg) & PSA_ALG_KEY_DERIVATION_STRETCHING_FLAG) 908 909/** An invalid algorithm identifier value. */ 910/* *INDENT-OFF* (https://github.com/ARM-software/psa-arch-tests/issues/337) */ 911#define PSA_ALG_NONE ((psa_algorithm_t)0) 912/* *INDENT-ON* */ 913 914#define PSA_ALG_HASH_MASK ((psa_algorithm_t) 0x000000ff) 915/** MD5 */ 916#define PSA_ALG_MD5 ((psa_algorithm_t) 0x02000003) 917/** PSA_ALG_RIPEMD160 */ 918#define PSA_ALG_RIPEMD160 ((psa_algorithm_t) 0x02000004) 919/** SHA1 */ 920#define PSA_ALG_SHA_1 ((psa_algorithm_t) 0x02000005) 921/** SHA2-224 */ 922#define PSA_ALG_SHA_224 ((psa_algorithm_t) 0x02000008) 923/** SHA2-256 */ 924#define PSA_ALG_SHA_256 ((psa_algorithm_t) 0x02000009) 925/** SHA2-384 */ 926#define PSA_ALG_SHA_384 ((psa_algorithm_t) 0x0200000a) 927/** SHA2-512 */ 928#define PSA_ALG_SHA_512 ((psa_algorithm_t) 0x0200000b) 929/** SHA2-512/224 */ 930#define PSA_ALG_SHA_512_224 ((psa_algorithm_t) 0x0200000c) 931/** SHA2-512/256 */ 932#define PSA_ALG_SHA_512_256 ((psa_algorithm_t) 0x0200000d) 933/** SHA3-224 */ 934#define PSA_ALG_SHA3_224 ((psa_algorithm_t) 0x02000010) 935/** SHA3-256 */ 936#define PSA_ALG_SHA3_256 ((psa_algorithm_t) 0x02000011) 937/** SHA3-384 */ 938#define PSA_ALG_SHA3_384 ((psa_algorithm_t) 0x02000012) 939/** SHA3-512 */ 940#define PSA_ALG_SHA3_512 ((psa_algorithm_t) 0x02000013) 941/** The first 512 bits (64 bytes) of the SHAKE256 output. 942 * 943 * This is the prehashing for Ed448ph (see #PSA_ALG_ED448PH). For other 944 * scenarios where a hash function based on SHA3/SHAKE is desired, SHA3-512 945 * has the same output size and a (theoretically) higher security strength. 946 */ 947#define PSA_ALG_SHAKE256_512 ((psa_algorithm_t) 0x02000015) 948 949/** In a hash-and-sign algorithm policy, allow any hash algorithm. 950 * 951 * This value may be used to form the algorithm usage field of a policy 952 * for a signature algorithm that is parametrized by a hash. The key 953 * may then be used to perform operations using the same signature 954 * algorithm parametrized with any supported hash. 955 * 956 * That is, suppose that `PSA_xxx_SIGNATURE` is one of the following macros: 957 * - #PSA_ALG_RSA_PKCS1V15_SIGN, #PSA_ALG_RSA_PSS, #PSA_ALG_RSA_PSS_ANY_SALT, 958 * - #PSA_ALG_ECDSA, #PSA_ALG_DETERMINISTIC_ECDSA. 959 * Then you may create and use a key as follows: 960 * - Set the key usage field using #PSA_ALG_ANY_HASH, for example: 961 * ``` 962 * psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN_HASH); // or VERIFY 963 * psa_set_key_algorithm(&attributes, PSA_xxx_SIGNATURE(PSA_ALG_ANY_HASH)); 964 * ``` 965 * - Import or generate key material. 966 * - Call psa_sign_hash() or psa_verify_hash(), passing 967 * an algorithm built from `PSA_xxx_SIGNATURE` and a specific hash. Each 968 * call to sign or verify a message may use a different hash. 969 * ``` 970 * psa_sign_hash(key, PSA_xxx_SIGNATURE(PSA_ALG_SHA_256), ...); 971 * psa_sign_hash(key, PSA_xxx_SIGNATURE(PSA_ALG_SHA_512), ...); 972 * psa_sign_hash(key, PSA_xxx_SIGNATURE(PSA_ALG_SHA3_256), ...); 973 * ``` 974 * 975 * This value may not be used to build other algorithms that are 976 * parametrized over a hash. For any valid use of this macro to build 977 * an algorithm \c alg, #PSA_ALG_IS_HASH_AND_SIGN(\c alg) is true. 978 * 979 * This value may not be used to build an algorithm specification to 980 * perform an operation. It is only valid to build policies. 981 */ 982#define PSA_ALG_ANY_HASH ((psa_algorithm_t) 0x020000ff) 983 984#define PSA_ALG_MAC_SUBCATEGORY_MASK ((psa_algorithm_t) 0x00c00000) 985#define PSA_ALG_HMAC_BASE ((psa_algorithm_t) 0x03800000) 986/** Macro to build an HMAC algorithm. 987 * 988 * For example, #PSA_ALG_HMAC(#PSA_ALG_SHA_256) is HMAC-SHA-256. 989 * 990 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 991 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 992 * 993 * \return The corresponding HMAC algorithm. 994 * \return Unspecified if \p hash_alg is not a supported 995 * hash algorithm. 996 */ 997#define PSA_ALG_HMAC(hash_alg) \ 998 (PSA_ALG_HMAC_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 999 1000#define PSA_ALG_HMAC_GET_HASH(hmac_alg) \ 1001 (PSA_ALG_CATEGORY_HASH | ((hmac_alg) & PSA_ALG_HASH_MASK)) 1002 1003/** Whether the specified algorithm is an HMAC algorithm. 1004 * 1005 * HMAC is a family of MAC algorithms that are based on a hash function. 1006 * 1007 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 1008 * 1009 * \return 1 if \p alg is an HMAC algorithm, 0 otherwise. 1010 * This macro may return either 0 or 1 if \p alg is not a supported 1011 * algorithm identifier. 1012 */ 1013#define PSA_ALG_IS_HMAC(alg) \ 1014 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_MAC_SUBCATEGORY_MASK)) == \ 1015 PSA_ALG_HMAC_BASE) 1016 1017/* In the encoding of a MAC algorithm, the bits corresponding to 1018 * PSA_ALG_MAC_TRUNCATION_MASK encode the length to which the MAC is 1019 * truncated. As an exception, the value 0 means the untruncated algorithm, 1020 * whatever its length is. The length is encoded in 6 bits, so it can 1021 * reach up to 63; the largest MAC is 64 bytes so its trivial truncation 1022 * to full length is correctly encoded as 0 and any non-trivial truncation 1023 * is correctly encoded as a value between 1 and 63. */ 1024#define PSA_ALG_MAC_TRUNCATION_MASK ((psa_algorithm_t) 0x003f0000) 1025#define PSA_MAC_TRUNCATION_OFFSET 16 1026 1027/* In the encoding of a MAC algorithm, the bit corresponding to 1028 * #PSA_ALG_MAC_AT_LEAST_THIS_LENGTH_FLAG encodes the fact that the algorithm 1029 * is a wildcard algorithm. A key with such wildcard algorithm as permitted 1030 * algorithm policy can be used with any algorithm corresponding to the 1031 * same base class and having a (potentially truncated) MAC length greater or 1032 * equal than the one encoded in #PSA_ALG_MAC_TRUNCATION_MASK. */ 1033#define PSA_ALG_MAC_AT_LEAST_THIS_LENGTH_FLAG ((psa_algorithm_t) 0x00008000) 1034 1035/** Macro to build a truncated MAC algorithm. 1036 * 1037 * A truncated MAC algorithm is identical to the corresponding MAC 1038 * algorithm except that the MAC value for the truncated algorithm 1039 * consists of only the first \p mac_length bytes of the MAC value 1040 * for the untruncated algorithm. 1041 * 1042 * \note This macro may allow constructing algorithm identifiers that 1043 * are not valid, either because the specified length is larger 1044 * than the untruncated MAC or because the specified length is 1045 * smaller than permitted by the implementation. 1046 * 1047 * \note It is implementation-defined whether a truncated MAC that 1048 * is truncated to the same length as the MAC of the untruncated 1049 * algorithm is considered identical to the untruncated algorithm 1050 * for policy comparison purposes. 1051 * 1052 * \param mac_alg A MAC algorithm identifier (value of type 1053 * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg) 1054 * is true). This may be a truncated or untruncated 1055 * MAC algorithm. 1056 * \param mac_length Desired length of the truncated MAC in bytes. 1057 * This must be at most the full length of the MAC 1058 * and must be at least an implementation-specified 1059 * minimum. The implementation-specified minimum 1060 * shall not be zero. 1061 * 1062 * \return The corresponding MAC algorithm with the specified 1063 * length. 1064 * \return Unspecified if \p mac_alg is not a supported 1065 * MAC algorithm or if \p mac_length is too small or 1066 * too large for the specified MAC algorithm. 1067 */ 1068#define PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length) \ 1069 (((mac_alg) & ~(PSA_ALG_MAC_TRUNCATION_MASK | \ 1070 PSA_ALG_MAC_AT_LEAST_THIS_LENGTH_FLAG)) | \ 1071 ((mac_length) << PSA_MAC_TRUNCATION_OFFSET & PSA_ALG_MAC_TRUNCATION_MASK)) 1072 1073/** Macro to build the base MAC algorithm corresponding to a truncated 1074 * MAC algorithm. 1075 * 1076 * \param mac_alg A MAC algorithm identifier (value of type 1077 * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg) 1078 * is true). This may be a truncated or untruncated 1079 * MAC algorithm. 1080 * 1081 * \return The corresponding base MAC algorithm. 1082 * \return Unspecified if \p mac_alg is not a supported 1083 * MAC algorithm. 1084 */ 1085#define PSA_ALG_FULL_LENGTH_MAC(mac_alg) \ 1086 ((mac_alg) & ~(PSA_ALG_MAC_TRUNCATION_MASK | \ 1087 PSA_ALG_MAC_AT_LEAST_THIS_LENGTH_FLAG)) 1088 1089/** Length to which a MAC algorithm is truncated. 1090 * 1091 * \param mac_alg A MAC algorithm identifier (value of type 1092 * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg) 1093 * is true). 1094 * 1095 * \return Length of the truncated MAC in bytes. 1096 * \return 0 if \p mac_alg is a non-truncated MAC algorithm. 1097 * \return Unspecified if \p mac_alg is not a supported 1098 * MAC algorithm. 1099 */ 1100#define PSA_MAC_TRUNCATED_LENGTH(mac_alg) \ 1101 (((mac_alg) & PSA_ALG_MAC_TRUNCATION_MASK) >> PSA_MAC_TRUNCATION_OFFSET) 1102 1103/** Macro to build a MAC minimum-MAC-length wildcard algorithm. 1104 * 1105 * A minimum-MAC-length MAC wildcard algorithm permits all MAC algorithms 1106 * sharing the same base algorithm, and where the (potentially truncated) MAC 1107 * length of the specific algorithm is equal to or larger then the wildcard 1108 * algorithm's minimum MAC length. 1109 * 1110 * \note When setting the minimum required MAC length to less than the 1111 * smallest MAC length allowed by the base algorithm, this effectively 1112 * becomes an 'any-MAC-length-allowed' policy for that base algorithm. 1113 * 1114 * \param mac_alg A MAC algorithm identifier (value of type 1115 * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg) 1116 * is true). 1117 * \param min_mac_length Desired minimum length of the message authentication 1118 * code in bytes. This must be at most the untruncated 1119 * length of the MAC and must be at least 1. 1120 * 1121 * \return The corresponding MAC wildcard algorithm with the 1122 * specified minimum length. 1123 * \return Unspecified if \p mac_alg is not a supported MAC 1124 * algorithm or if \p min_mac_length is less than 1 or 1125 * too large for the specified MAC algorithm. 1126 */ 1127#define PSA_ALG_AT_LEAST_THIS_LENGTH_MAC(mac_alg, min_mac_length) \ 1128 (PSA_ALG_TRUNCATED_MAC(mac_alg, min_mac_length) | \ 1129 PSA_ALG_MAC_AT_LEAST_THIS_LENGTH_FLAG) 1130 1131#define PSA_ALG_CIPHER_MAC_BASE ((psa_algorithm_t) 0x03c00000) 1132/** The CBC-MAC construction over a block cipher 1133 * 1134 * \warning CBC-MAC is insecure in many cases. 1135 * A more secure mode, such as #PSA_ALG_CMAC, is recommended. 1136 */ 1137#define PSA_ALG_CBC_MAC ((psa_algorithm_t) 0x03c00100) 1138/** The CMAC construction over a block cipher */ 1139#define PSA_ALG_CMAC ((psa_algorithm_t) 0x03c00200) 1140 1141/** Whether the specified algorithm is a MAC algorithm based on a block cipher. 1142 * 1143 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 1144 * 1145 * \return 1 if \p alg is a MAC algorithm based on a block cipher, 0 otherwise. 1146 * This macro may return either 0 or 1 if \p alg is not a supported 1147 * algorithm identifier. 1148 */ 1149#define PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) \ 1150 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_MAC_SUBCATEGORY_MASK)) == \ 1151 PSA_ALG_CIPHER_MAC_BASE) 1152 1153#define PSA_ALG_CIPHER_STREAM_FLAG ((psa_algorithm_t) 0x00800000) 1154#define PSA_ALG_CIPHER_FROM_BLOCK_FLAG ((psa_algorithm_t) 0x00400000) 1155 1156/** Whether the specified algorithm is a stream cipher. 1157 * 1158 * A stream cipher is a symmetric cipher that encrypts or decrypts messages 1159 * by applying a bitwise-xor with a stream of bytes that is generated 1160 * from a key. 1161 * 1162 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 1163 * 1164 * \return 1 if \p alg is a stream cipher algorithm, 0 otherwise. 1165 * This macro may return either 0 or 1 if \p alg is not a supported 1166 * algorithm identifier or if it is not a symmetric cipher algorithm. 1167 */ 1168#define PSA_ALG_IS_STREAM_CIPHER(alg) \ 1169 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_CIPHER_STREAM_FLAG)) == \ 1170 (PSA_ALG_CATEGORY_CIPHER | PSA_ALG_CIPHER_STREAM_FLAG)) 1171 1172/** The stream cipher mode of a stream cipher algorithm. 1173 * 1174 * The underlying stream cipher is determined by the key type. 1175 * - To use ChaCha20, use a key type of #PSA_KEY_TYPE_CHACHA20. 1176 */ 1177#define PSA_ALG_STREAM_CIPHER ((psa_algorithm_t) 0x04800100) 1178 1179/** The CTR stream cipher mode. 1180 * 1181 * CTR is a stream cipher which is built from a block cipher. 1182 * The underlying block cipher is determined by the key type. 1183 * For example, to use AES-128-CTR, use this algorithm with 1184 * a key of type #PSA_KEY_TYPE_AES and a length of 128 bits (16 bytes). 1185 */ 1186#define PSA_ALG_CTR ((psa_algorithm_t) 0x04c01000) 1187 1188/** The CFB stream cipher mode. 1189 * 1190 * The underlying block cipher is determined by the key type. 1191 */ 1192#define PSA_ALG_CFB ((psa_algorithm_t) 0x04c01100) 1193 1194/** The OFB stream cipher mode. 1195 * 1196 * The underlying block cipher is determined by the key type. 1197 */ 1198#define PSA_ALG_OFB ((psa_algorithm_t) 0x04c01200) 1199 1200/** The XTS cipher mode. 1201 * 1202 * XTS is a cipher mode which is built from a block cipher. It requires at 1203 * least one full block of input, but beyond this minimum the input 1204 * does not need to be a whole number of blocks. 1205 */ 1206#define PSA_ALG_XTS ((psa_algorithm_t) 0x0440ff00) 1207 1208/** The Electronic Code Book (ECB) mode of a block cipher, with no padding. 1209 * 1210 * \warning ECB mode does not protect the confidentiality of the encrypted data 1211 * except in extremely narrow circumstances. It is recommended that applications 1212 * only use ECB if they need to construct an operating mode that the 1213 * implementation does not provide. Implementations are encouraged to provide 1214 * the modes that applications need in preference to supporting direct access 1215 * to ECB. 1216 * 1217 * The underlying block cipher is determined by the key type. 1218 * 1219 * This symmetric cipher mode can only be used with messages whose lengths are a 1220 * multiple of the block size of the chosen block cipher. 1221 * 1222 * ECB mode does not accept an initialization vector (IV). When using a 1223 * multi-part cipher operation with this algorithm, psa_cipher_generate_iv() 1224 * and psa_cipher_set_iv() must not be called. 1225 */ 1226#define PSA_ALG_ECB_NO_PADDING ((psa_algorithm_t) 0x04404400) 1227 1228/** The CBC block cipher chaining mode, with no padding. 1229 * 1230 * The underlying block cipher is determined by the key type. 1231 * 1232 * This symmetric cipher mode can only be used with messages whose lengths 1233 * are whole number of blocks for the chosen block cipher. 1234 */ 1235#define PSA_ALG_CBC_NO_PADDING ((psa_algorithm_t) 0x04404000) 1236 1237/** The CBC block cipher chaining mode with PKCS#7 padding. 1238 * 1239 * The underlying block cipher is determined by the key type. 1240 * 1241 * This is the padding method defined by PKCS#7 (RFC 2315) §10.3. 1242 */ 1243#define PSA_ALG_CBC_PKCS7 ((psa_algorithm_t) 0x04404100) 1244 1245#define PSA_ALG_AEAD_FROM_BLOCK_FLAG ((psa_algorithm_t) 0x00400000) 1246 1247/** Whether the specified algorithm is an AEAD mode on a block cipher. 1248 * 1249 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 1250 * 1251 * \return 1 if \p alg is an AEAD algorithm which is an AEAD mode based on 1252 * a block cipher, 0 otherwise. 1253 * This macro may return either 0 or 1 if \p alg is not a supported 1254 * algorithm identifier. 1255 */ 1256#define PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) \ 1257 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_AEAD_FROM_BLOCK_FLAG)) == \ 1258 (PSA_ALG_CATEGORY_AEAD | PSA_ALG_AEAD_FROM_BLOCK_FLAG)) 1259 1260/** The CCM authenticated encryption algorithm. 1261 * 1262 * The underlying block cipher is determined by the key type. 1263 */ 1264#define PSA_ALG_CCM ((psa_algorithm_t) 0x05500100) 1265 1266/** The CCM* cipher mode without authentication. 1267 * 1268 * This is CCM* as specified in IEEE 802.15.4 §7, with a tag length of 0. 1269 * For CCM* with a nonzero tag length, use the AEAD algorithm #PSA_ALG_CCM. 1270 * 1271 * The underlying block cipher is determined by the key type. 1272 * 1273 * Currently only 13-byte long IV's are supported. 1274 */ 1275#define PSA_ALG_CCM_STAR_NO_TAG ((psa_algorithm_t) 0x04c01300) 1276 1277/** The GCM authenticated encryption algorithm. 1278 * 1279 * The underlying block cipher is determined by the key type. 1280 */ 1281#define PSA_ALG_GCM ((psa_algorithm_t) 0x05500200) 1282 1283/** The Chacha20-Poly1305 AEAD algorithm. 1284 * 1285 * The ChaCha20_Poly1305 construction is defined in RFC 7539. 1286 * 1287 * Implementations must support 12-byte nonces, may support 8-byte nonces, 1288 * and should reject other sizes. 1289 * 1290 * Implementations must support 16-byte tags and should reject other sizes. 1291 */ 1292#define PSA_ALG_CHACHA20_POLY1305 ((psa_algorithm_t) 0x05100500) 1293 1294/* In the encoding of an AEAD algorithm, the bits corresponding to 1295 * PSA_ALG_AEAD_TAG_LENGTH_MASK encode the length of the AEAD tag. 1296 * The constants for default lengths follow this encoding. 1297 */ 1298#define PSA_ALG_AEAD_TAG_LENGTH_MASK ((psa_algorithm_t) 0x003f0000) 1299#define PSA_AEAD_TAG_LENGTH_OFFSET 16 1300 1301/* In the encoding of an AEAD algorithm, the bit corresponding to 1302 * #PSA_ALG_AEAD_AT_LEAST_THIS_LENGTH_FLAG encodes the fact that the algorithm 1303 * is a wildcard algorithm. A key with such wildcard algorithm as permitted 1304 * algorithm policy can be used with any algorithm corresponding to the 1305 * same base class and having a tag length greater than or equal to the one 1306 * encoded in #PSA_ALG_AEAD_TAG_LENGTH_MASK. */ 1307#define PSA_ALG_AEAD_AT_LEAST_THIS_LENGTH_FLAG ((psa_algorithm_t) 0x00008000) 1308 1309/** Macro to build a shortened AEAD algorithm. 1310 * 1311 * A shortened AEAD algorithm is similar to the corresponding AEAD 1312 * algorithm, but has an authentication tag that consists of fewer bytes. 1313 * Depending on the algorithm, the tag length may affect the calculation 1314 * of the ciphertext. 1315 * 1316 * \param aead_alg An AEAD algorithm identifier (value of type 1317 * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p aead_alg) 1318 * is true). 1319 * \param tag_length Desired length of the authentication tag in bytes. 1320 * 1321 * \return The corresponding AEAD algorithm with the specified 1322 * length. 1323 * \return Unspecified if \p aead_alg is not a supported 1324 * AEAD algorithm or if \p tag_length is not valid 1325 * for the specified AEAD algorithm. 1326 */ 1327#define PSA_ALG_AEAD_WITH_SHORTENED_TAG(aead_alg, tag_length) \ 1328 (((aead_alg) & ~(PSA_ALG_AEAD_TAG_LENGTH_MASK | \ 1329 PSA_ALG_AEAD_AT_LEAST_THIS_LENGTH_FLAG)) | \ 1330 ((tag_length) << PSA_AEAD_TAG_LENGTH_OFFSET & \ 1331 PSA_ALG_AEAD_TAG_LENGTH_MASK)) 1332 1333/** Retrieve the tag length of a specified AEAD algorithm 1334 * 1335 * \param aead_alg An AEAD algorithm identifier (value of type 1336 * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p aead_alg) 1337 * is true). 1338 * 1339 * \return The tag length specified by the input algorithm. 1340 * \return Unspecified if \p aead_alg is not a supported 1341 * AEAD algorithm. 1342 */ 1343#define PSA_ALG_AEAD_GET_TAG_LENGTH(aead_alg) \ 1344 (((aead_alg) & PSA_ALG_AEAD_TAG_LENGTH_MASK) >> \ 1345 PSA_AEAD_TAG_LENGTH_OFFSET) 1346 1347/** Calculate the corresponding AEAD algorithm with the default tag length. 1348 * 1349 * \param aead_alg An AEAD algorithm (\c PSA_ALG_XXX value such that 1350 * #PSA_ALG_IS_AEAD(\p aead_alg) is true). 1351 * 1352 * \return The corresponding AEAD algorithm with the default 1353 * tag length for that algorithm. 1354 */ 1355#define PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG(aead_alg) \ 1356 ( \ 1357 PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG_CASE(aead_alg, PSA_ALG_CCM) \ 1358 PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG_CASE(aead_alg, PSA_ALG_GCM) \ 1359 PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG_CASE(aead_alg, PSA_ALG_CHACHA20_POLY1305) \ 1360 0) 1361#define PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG_CASE(aead_alg, ref) \ 1362 PSA_ALG_AEAD_WITH_SHORTENED_TAG(aead_alg, 0) == \ 1363 PSA_ALG_AEAD_WITH_SHORTENED_TAG(ref, 0) ? \ 1364 ref : 1365 1366/** Macro to build an AEAD minimum-tag-length wildcard algorithm. 1367 * 1368 * A minimum-tag-length AEAD wildcard algorithm permits all AEAD algorithms 1369 * sharing the same base algorithm, and where the tag length of the specific 1370 * algorithm is equal to or larger then the minimum tag length specified by the 1371 * wildcard algorithm. 1372 * 1373 * \note When setting the minimum required tag length to less than the 1374 * smallest tag length allowed by the base algorithm, this effectively 1375 * becomes an 'any-tag-length-allowed' policy for that base algorithm. 1376 * 1377 * \param aead_alg An AEAD algorithm identifier (value of type 1378 * #psa_algorithm_t such that 1379 * #PSA_ALG_IS_AEAD(\p aead_alg) is true). 1380 * \param min_tag_length Desired minimum length of the authentication tag in 1381 * bytes. This must be at least 1 and at most the largest 1382 * allowed tag length of the algorithm. 1383 * 1384 * \return The corresponding AEAD wildcard algorithm with the 1385 * specified minimum length. 1386 * \return Unspecified if \p aead_alg is not a supported 1387 * AEAD algorithm or if \p min_tag_length is less than 1 1388 * or too large for the specified AEAD algorithm. 1389 */ 1390#define PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG(aead_alg, min_tag_length) \ 1391 (PSA_ALG_AEAD_WITH_SHORTENED_TAG(aead_alg, min_tag_length) | \ 1392 PSA_ALG_AEAD_AT_LEAST_THIS_LENGTH_FLAG) 1393 1394#define PSA_ALG_RSA_PKCS1V15_SIGN_BASE ((psa_algorithm_t) 0x06000200) 1395/** RSA PKCS#1 v1.5 signature with hashing. 1396 * 1397 * This is the signature scheme defined by RFC 8017 1398 * (PKCS#1: RSA Cryptography Specifications) under the name 1399 * RSASSA-PKCS1-v1_5. 1400 * 1401 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 1402 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 1403 * This includes #PSA_ALG_ANY_HASH 1404 * when specifying the algorithm in a usage policy. 1405 * 1406 * \return The corresponding RSA PKCS#1 v1.5 signature algorithm. 1407 * \return Unspecified if \p hash_alg is not a supported 1408 * hash algorithm. 1409 */ 1410#define PSA_ALG_RSA_PKCS1V15_SIGN(hash_alg) \ 1411 (PSA_ALG_RSA_PKCS1V15_SIGN_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 1412/** Raw PKCS#1 v1.5 signature. 1413 * 1414 * The input to this algorithm is the DigestInfo structure used by 1415 * RFC 8017 (PKCS#1: RSA Cryptography Specifications), §9.2 1416 * steps 3–6. 1417 */ 1418#define PSA_ALG_RSA_PKCS1V15_SIGN_RAW PSA_ALG_RSA_PKCS1V15_SIGN_BASE 1419#define PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) \ 1420 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_PKCS1V15_SIGN_BASE) 1421 1422#define PSA_ALG_RSA_PSS_BASE ((psa_algorithm_t) 0x06000300) 1423#define PSA_ALG_RSA_PSS_ANY_SALT_BASE ((psa_algorithm_t) 0x06001300) 1424/** RSA PSS signature with hashing. 1425 * 1426 * This is the signature scheme defined by RFC 8017 1427 * (PKCS#1: RSA Cryptography Specifications) under the name 1428 * RSASSA-PSS, with the message generation function MGF1, and with 1429 * a salt length equal to the length of the hash, or the largest 1430 * possible salt length for the algorithm and key size if that is 1431 * smaller than the hash length. The specified hash algorithm is 1432 * used to hash the input message, to create the salted hash, and 1433 * for the mask generation. 1434 * 1435 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 1436 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 1437 * This includes #PSA_ALG_ANY_HASH 1438 * when specifying the algorithm in a usage policy. 1439 * 1440 * \return The corresponding RSA PSS signature algorithm. 1441 * \return Unspecified if \p hash_alg is not a supported 1442 * hash algorithm. 1443 */ 1444#define PSA_ALG_RSA_PSS(hash_alg) \ 1445 (PSA_ALG_RSA_PSS_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 1446 1447/** RSA PSS signature with hashing with relaxed verification. 1448 * 1449 * This algorithm has the same behavior as #PSA_ALG_RSA_PSS when signing, 1450 * but allows an arbitrary salt length (including \c 0) when verifying a 1451 * signature. 1452 * 1453 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 1454 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 1455 * This includes #PSA_ALG_ANY_HASH 1456 * when specifying the algorithm in a usage policy. 1457 * 1458 * \return The corresponding RSA PSS signature algorithm. 1459 * \return Unspecified if \p hash_alg is not a supported 1460 * hash algorithm. 1461 */ 1462#define PSA_ALG_RSA_PSS_ANY_SALT(hash_alg) \ 1463 (PSA_ALG_RSA_PSS_ANY_SALT_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 1464 1465/** Whether the specified algorithm is RSA PSS with standard salt. 1466 * 1467 * \param alg An algorithm value or an algorithm policy wildcard. 1468 * 1469 * \return 1 if \p alg is of the form 1470 * #PSA_ALG_RSA_PSS(\c hash_alg), 1471 * where \c hash_alg is a hash algorithm or 1472 * #PSA_ALG_ANY_HASH. 0 otherwise. 1473 * This macro may return either 0 or 1 if \p alg is not 1474 * a supported algorithm identifier or policy. 1475 */ 1476#define PSA_ALG_IS_RSA_PSS_STANDARD_SALT(alg) \ 1477 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_PSS_BASE) 1478 1479/** Whether the specified algorithm is RSA PSS with any salt. 1480 * 1481 * \param alg An algorithm value or an algorithm policy wildcard. 1482 * 1483 * \return 1 if \p alg is of the form 1484 * #PSA_ALG_RSA_PSS_ANY_SALT_BASE(\c hash_alg), 1485 * where \c hash_alg is a hash algorithm or 1486 * #PSA_ALG_ANY_HASH. 0 otherwise. 1487 * This macro may return either 0 or 1 if \p alg is not 1488 * a supported algorithm identifier or policy. 1489 */ 1490#define PSA_ALG_IS_RSA_PSS_ANY_SALT(alg) \ 1491 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_PSS_ANY_SALT_BASE) 1492 1493/** Whether the specified algorithm is RSA PSS. 1494 * 1495 * This includes any of the RSA PSS algorithm variants, regardless of the 1496 * constraints on salt length. 1497 * 1498 * \param alg An algorithm value or an algorithm policy wildcard. 1499 * 1500 * \return 1 if \p alg is of the form 1501 * #PSA_ALG_RSA_PSS(\c hash_alg) or 1502 * #PSA_ALG_RSA_PSS_ANY_SALT_BASE(\c hash_alg), 1503 * where \c hash_alg is a hash algorithm or 1504 * #PSA_ALG_ANY_HASH. 0 otherwise. 1505 * This macro may return either 0 or 1 if \p alg is not 1506 * a supported algorithm identifier or policy. 1507 */ 1508#define PSA_ALG_IS_RSA_PSS(alg) \ 1509 (PSA_ALG_IS_RSA_PSS_STANDARD_SALT(alg) || \ 1510 PSA_ALG_IS_RSA_PSS_ANY_SALT(alg)) 1511 1512#define PSA_ALG_ECDSA_BASE ((psa_algorithm_t) 0x06000600) 1513/** ECDSA signature with hashing. 1514 * 1515 * This is the ECDSA signature scheme defined by ANSI X9.62, 1516 * with a random per-message secret number (*k*). 1517 * 1518 * The representation of the signature as a byte string consists of 1519 * the concatenation of the signature values *r* and *s*. Each of 1520 * *r* and *s* is encoded as an *N*-octet string, where *N* is the length 1521 * of the base point of the curve in octets. Each value is represented 1522 * in big-endian order (most significant octet first). 1523 * 1524 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 1525 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 1526 * This includes #PSA_ALG_ANY_HASH 1527 * when specifying the algorithm in a usage policy. 1528 * 1529 * \return The corresponding ECDSA signature algorithm. 1530 * \return Unspecified if \p hash_alg is not a supported 1531 * hash algorithm. 1532 */ 1533#define PSA_ALG_ECDSA(hash_alg) \ 1534 (PSA_ALG_ECDSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 1535/** ECDSA signature without hashing. 1536 * 1537 * This is the same signature scheme as #PSA_ALG_ECDSA(), but 1538 * without specifying a hash algorithm. This algorithm may only be 1539 * used to sign or verify a sequence of bytes that should be an 1540 * already-calculated hash. Note that the input is padded with 1541 * zeros on the left or truncated on the left as required to fit 1542 * the curve size. 1543 */ 1544#define PSA_ALG_ECDSA_ANY PSA_ALG_ECDSA_BASE 1545#define PSA_ALG_DETERMINISTIC_ECDSA_BASE ((psa_algorithm_t) 0x06000700) 1546/** Deterministic ECDSA signature with hashing. 1547 * 1548 * This is the deterministic ECDSA signature scheme defined by RFC 6979. 1549 * 1550 * The representation of a signature is the same as with #PSA_ALG_ECDSA(). 1551 * 1552 * Note that when this algorithm is used for verification, signatures 1553 * made with randomized ECDSA (#PSA_ALG_ECDSA(\p hash_alg)) with the 1554 * same private key are accepted. In other words, 1555 * #PSA_ALG_DETERMINISTIC_ECDSA(\p hash_alg) differs from 1556 * #PSA_ALG_ECDSA(\p hash_alg) only for signature, not for verification. 1557 * 1558 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 1559 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 1560 * This includes #PSA_ALG_ANY_HASH 1561 * when specifying the algorithm in a usage policy. 1562 * 1563 * \return The corresponding deterministic ECDSA signature 1564 * algorithm. 1565 * \return Unspecified if \p hash_alg is not a supported 1566 * hash algorithm. 1567 */ 1568#define PSA_ALG_DETERMINISTIC_ECDSA(hash_alg) \ 1569 (PSA_ALG_DETERMINISTIC_ECDSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 1570#define PSA_ALG_ECDSA_DETERMINISTIC_FLAG ((psa_algorithm_t) 0x00000100) 1571#define PSA_ALG_IS_ECDSA(alg) \ 1572 (((alg) & ~PSA_ALG_HASH_MASK & ~PSA_ALG_ECDSA_DETERMINISTIC_FLAG) == \ 1573 PSA_ALG_ECDSA_BASE) 1574#define PSA_ALG_ECDSA_IS_DETERMINISTIC(alg) \ 1575 (((alg) & PSA_ALG_ECDSA_DETERMINISTIC_FLAG) != 0) 1576#define PSA_ALG_IS_DETERMINISTIC_ECDSA(alg) \ 1577 (PSA_ALG_IS_ECDSA(alg) && PSA_ALG_ECDSA_IS_DETERMINISTIC(alg)) 1578#define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) \ 1579 (PSA_ALG_IS_ECDSA(alg) && !PSA_ALG_ECDSA_IS_DETERMINISTIC(alg)) 1580 1581/** Edwards-curve digital signature algorithm without prehashing (PureEdDSA), 1582 * using standard parameters. 1583 * 1584 * Contexts are not supported in the current version of this specification 1585 * because there is no suitable signature interface that can take the 1586 * context as a parameter. A future version of this specification may add 1587 * suitable functions and extend this algorithm to support contexts. 1588 * 1589 * PureEdDSA requires an elliptic curve key on a twisted Edwards curve. 1590 * In this specification, the following curves are supported: 1591 * - #PSA_ECC_FAMILY_TWISTED_EDWARDS, 255-bit: Ed25519 as specified 1592 * in RFC 8032. 1593 * The curve is Edwards25519. 1594 * The hash function used internally is SHA-512. 1595 * - #PSA_ECC_FAMILY_TWISTED_EDWARDS, 448-bit: Ed448 as specified 1596 * in RFC 8032. 1597 * The curve is Edwards448. 1598 * The hash function used internally is the first 114 bytes of the 1599 * SHAKE256 output. 1600 * 1601 * This algorithm can be used with psa_sign_message() and 1602 * psa_verify_message(). Since there is no prehashing, it cannot be used 1603 * with psa_sign_hash() or psa_verify_hash(). 1604 * 1605 * The signature format is the concatenation of R and S as defined by 1606 * RFC 8032 §5.1.6 and §5.2.6 (a 64-byte string for Ed25519, a 114-byte 1607 * string for Ed448). 1608 */ 1609#define PSA_ALG_PURE_EDDSA ((psa_algorithm_t) 0x06000800) 1610 1611#define PSA_ALG_HASH_EDDSA_BASE ((psa_algorithm_t) 0x06000900) 1612#define PSA_ALG_IS_HASH_EDDSA(alg) \ 1613 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HASH_EDDSA_BASE) 1614 1615/** Edwards-curve digital signature algorithm with prehashing (HashEdDSA), 1616 * using SHA-512 and the Edwards25519 curve. 1617 * 1618 * See #PSA_ALG_PURE_EDDSA regarding context support and the signature format. 1619 * 1620 * This algorithm is Ed25519 as specified in RFC 8032. 1621 * The curve is Edwards25519. 1622 * The prehash is SHA-512. 1623 * The hash function used internally is SHA-512. 1624 * 1625 * This is a hash-and-sign algorithm: to calculate a signature, 1626 * you can either: 1627 * - call psa_sign_message() on the message; 1628 * - or calculate the SHA-512 hash of the message 1629 * with psa_hash_compute() 1630 * or with a multi-part hash operation started with psa_hash_setup(), 1631 * using the hash algorithm #PSA_ALG_SHA_512, 1632 * then sign the calculated hash with psa_sign_hash(). 1633 * Verifying a signature is similar, using psa_verify_message() or 1634 * psa_verify_hash() instead of the signature function. 1635 */ 1636#define PSA_ALG_ED25519PH \ 1637 (PSA_ALG_HASH_EDDSA_BASE | (PSA_ALG_SHA_512 & PSA_ALG_HASH_MASK)) 1638 1639/** Edwards-curve digital signature algorithm with prehashing (HashEdDSA), 1640 * using SHAKE256 and the Edwards448 curve. 1641 * 1642 * See #PSA_ALG_PURE_EDDSA regarding context support and the signature format. 1643 * 1644 * This algorithm is Ed448 as specified in RFC 8032. 1645 * The curve is Edwards448. 1646 * The prehash is the first 64 bytes of the SHAKE256 output. 1647 * The hash function used internally is the first 114 bytes of the 1648 * SHAKE256 output. 1649 * 1650 * This is a hash-and-sign algorithm: to calculate a signature, 1651 * you can either: 1652 * - call psa_sign_message() on the message; 1653 * - or calculate the first 64 bytes of the SHAKE256 output of the message 1654 * with psa_hash_compute() 1655 * or with a multi-part hash operation started with psa_hash_setup(), 1656 * using the hash algorithm #PSA_ALG_SHAKE256_512, 1657 * then sign the calculated hash with psa_sign_hash(). 1658 * Verifying a signature is similar, using psa_verify_message() or 1659 * psa_verify_hash() instead of the signature function. 1660 */ 1661#define PSA_ALG_ED448PH \ 1662 (PSA_ALG_HASH_EDDSA_BASE | (PSA_ALG_SHAKE256_512 & PSA_ALG_HASH_MASK)) 1663 1664/* Default definition, to be overridden if the library is extended with 1665 * more hash-and-sign algorithms that we want to keep out of this header 1666 * file. */ 1667#define PSA_ALG_IS_VENDOR_HASH_AND_SIGN(alg) 0 1668 1669/** Whether the specified algorithm is a signature algorithm that can be used 1670 * with psa_sign_hash() and psa_verify_hash(). 1671 * 1672 * This encompasses all strict hash-and-sign algorithms categorized by 1673 * PSA_ALG_IS_HASH_AND_SIGN(), as well as algorithms that follow the 1674 * paradigm more loosely: 1675 * - #PSA_ALG_RSA_PKCS1V15_SIGN_RAW (expects its input to be an encoded hash) 1676 * - #PSA_ALG_ECDSA_ANY (doesn't specify what kind of hash the input is) 1677 * 1678 * \param alg An algorithm identifier (value of type psa_algorithm_t). 1679 * 1680 * \return 1 if alg is a signature algorithm that can be used to sign a 1681 * hash. 0 if alg is a signature algorithm that can only be used 1682 * to sign a message. 0 if alg is not a signature algorithm. 1683 * This macro can return either 0 or 1 if alg is not a 1684 * supported algorithm identifier. 1685 */ 1686#define PSA_ALG_IS_SIGN_HASH(alg) \ 1687 (PSA_ALG_IS_RSA_PSS(alg) || PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) || \ 1688 PSA_ALG_IS_ECDSA(alg) || PSA_ALG_IS_HASH_EDDSA(alg) || \ 1689 PSA_ALG_IS_VENDOR_HASH_AND_SIGN(alg)) 1690 1691/** Whether the specified algorithm is a signature algorithm that can be used 1692 * with psa_sign_message() and psa_verify_message(). 1693 * 1694 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 1695 * 1696 * \return 1 if alg is a signature algorithm that can be used to sign a 1697 * message. 0 if \p alg is a signature algorithm that can only be used 1698 * to sign an already-calculated hash. 0 if \p alg is not a signature 1699 * algorithm. This macro can return either 0 or 1 if \p alg is not a 1700 * supported algorithm identifier. 1701 */ 1702#define PSA_ALG_IS_SIGN_MESSAGE(alg) \ 1703 (PSA_ALG_IS_SIGN_HASH(alg) || (alg) == PSA_ALG_PURE_EDDSA) 1704 1705/** Whether the specified algorithm is a hash-and-sign algorithm. 1706 * 1707 * Hash-and-sign algorithms are asymmetric (public-key) signature algorithms 1708 * structured in two parts: first the calculation of a hash in a way that 1709 * does not depend on the key, then the calculation of a signature from the 1710 * hash value and the key. Hash-and-sign algorithms encode the hash 1711 * used for the hashing step, and you can call #PSA_ALG_SIGN_GET_HASH 1712 * to extract this algorithm. 1713 * 1714 * Thus, for a hash-and-sign algorithm, 1715 * `psa_sign_message(key, alg, input, ...)` is equivalent to 1716 * ``` 1717 * psa_hash_compute(PSA_ALG_SIGN_GET_HASH(alg), input, ..., hash, ...); 1718 * psa_sign_hash(key, alg, hash, ..., signature, ...); 1719 * ``` 1720 * Most usefully, separating the hash from the signature allows the hash 1721 * to be calculated in multiple steps with psa_hash_setup(), psa_hash_update() 1722 * and psa_hash_finish(). Likewise psa_verify_message() is equivalent to 1723 * calculating the hash and then calling psa_verify_hash(). 1724 * 1725 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 1726 * 1727 * \return 1 if \p alg is a hash-and-sign algorithm, 0 otherwise. 1728 * This macro may return either 0 or 1 if \p alg is not a supported 1729 * algorithm identifier. 1730 */ 1731#define PSA_ALG_IS_HASH_AND_SIGN(alg) \ 1732 (PSA_ALG_IS_SIGN_HASH(alg) && \ 1733 ((alg) & PSA_ALG_HASH_MASK) != 0) 1734 1735/** Get the hash used by a hash-and-sign signature algorithm. 1736 * 1737 * A hash-and-sign algorithm is a signature algorithm which is 1738 * composed of two phases: first a hashing phase which does not use 1739 * the key and produces a hash of the input message, then a signing 1740 * phase which only uses the hash and the key and not the message 1741 * itself. 1742 * 1743 * \param alg A signature algorithm (\c PSA_ALG_XXX value such that 1744 * #PSA_ALG_IS_SIGN(\p alg) is true). 1745 * 1746 * \return The underlying hash algorithm if \p alg is a hash-and-sign 1747 * algorithm. 1748 * \return 0 if \p alg is a signature algorithm that does not 1749 * follow the hash-and-sign structure. 1750 * \return Unspecified if \p alg is not a signature algorithm or 1751 * if it is not supported by the implementation. 1752 */ 1753#define PSA_ALG_SIGN_GET_HASH(alg) \ 1754 (PSA_ALG_IS_HASH_AND_SIGN(alg) ? \ 1755 ((alg) & PSA_ALG_HASH_MASK) | PSA_ALG_CATEGORY_HASH : \ 1756 0) 1757 1758/** RSA PKCS#1 v1.5 encryption. 1759 * 1760 * \warning Calling psa_asymmetric_decrypt() with this algorithm as a 1761 * parameter is considered an inherently dangerous function 1762 * (CWE-242). Unless it is used in a side channel free and safe 1763 * way (eg. implementing the TLS protocol as per 7.4.7.1 of 1764 * RFC 5246), the calling code is vulnerable. 1765 * 1766 */ 1767#define PSA_ALG_RSA_PKCS1V15_CRYPT ((psa_algorithm_t) 0x07000200) 1768 1769#define PSA_ALG_RSA_OAEP_BASE ((psa_algorithm_t) 0x07000300) 1770/** RSA OAEP encryption. 1771 * 1772 * This is the encryption scheme defined by RFC 8017 1773 * (PKCS#1: RSA Cryptography Specifications) under the name 1774 * RSAES-OAEP, with the message generation function MGF1. 1775 * 1776 * \param hash_alg The hash algorithm (\c PSA_ALG_XXX value such that 1777 * #PSA_ALG_IS_HASH(\p hash_alg) is true) to use 1778 * for MGF1. 1779 * 1780 * \return The corresponding RSA OAEP encryption algorithm. 1781 * \return Unspecified if \p hash_alg is not a supported 1782 * hash algorithm. 1783 */ 1784#define PSA_ALG_RSA_OAEP(hash_alg) \ 1785 (PSA_ALG_RSA_OAEP_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 1786#define PSA_ALG_IS_RSA_OAEP(alg) \ 1787 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_OAEP_BASE) 1788#define PSA_ALG_RSA_OAEP_GET_HASH(alg) \ 1789 (PSA_ALG_IS_RSA_OAEP(alg) ? \ 1790 ((alg) & PSA_ALG_HASH_MASK) | PSA_ALG_CATEGORY_HASH : \ 1791 0) 1792 1793#define PSA_ALG_HKDF_BASE ((psa_algorithm_t) 0x08000100) 1794/** Macro to build an HKDF algorithm. 1795 * 1796 * For example, `PSA_ALG_HKDF(PSA_ALG_SHA_256)` is HKDF using HMAC-SHA-256. 1797 * 1798 * This key derivation algorithm uses the following inputs: 1799 * - #PSA_KEY_DERIVATION_INPUT_SALT is the salt used in the "extract" step. 1800 * It is optional; if omitted, the derivation uses an empty salt. 1801 * - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key used in the "extract" step. 1802 * - #PSA_KEY_DERIVATION_INPUT_INFO is the info string used in the "expand" step. 1803 * You must pass #PSA_KEY_DERIVATION_INPUT_SALT before #PSA_KEY_DERIVATION_INPUT_SECRET. 1804 * You may pass #PSA_KEY_DERIVATION_INPUT_INFO at any time after steup and before 1805 * starting to generate output. 1806 * 1807 * \warning HKDF processes the salt as follows: first hash it with hash_alg 1808 * if the salt is longer than the block size of the hash algorithm; then 1809 * pad with null bytes up to the block size. As a result, it is possible 1810 * for distinct salt inputs to result in the same outputs. To ensure 1811 * unique outputs, it is recommended to use a fixed length for salt values. 1812 * 1813 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 1814 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 1815 * 1816 * \return The corresponding HKDF algorithm. 1817 * \return Unspecified if \p hash_alg is not a supported 1818 * hash algorithm. 1819 */ 1820#define PSA_ALG_HKDF(hash_alg) \ 1821 (PSA_ALG_HKDF_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 1822/** Whether the specified algorithm is an HKDF algorithm. 1823 * 1824 * HKDF is a family of key derivation algorithms that are based on a hash 1825 * function and the HMAC construction. 1826 * 1827 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 1828 * 1829 * \return 1 if \c alg is an HKDF algorithm, 0 otherwise. 1830 * This macro may return either 0 or 1 if \c alg is not a supported 1831 * key derivation algorithm identifier. 1832 */ 1833#define PSA_ALG_IS_HKDF(alg) \ 1834 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_BASE) 1835#define PSA_ALG_HKDF_GET_HASH(hkdf_alg) \ 1836 (PSA_ALG_CATEGORY_HASH | ((hkdf_alg) & PSA_ALG_HASH_MASK)) 1837 1838#define PSA_ALG_HKDF_EXTRACT_BASE ((psa_algorithm_t) 0x08000400) 1839/** Macro to build an HKDF-Extract algorithm. 1840 * 1841 * For example, `PSA_ALG_HKDF_EXTRACT(PSA_ALG_SHA_256)` is 1842 * HKDF-Extract using HMAC-SHA-256. 1843 * 1844 * This key derivation algorithm uses the following inputs: 1845 * - PSA_KEY_DERIVATION_INPUT_SALT is the salt. 1846 * - PSA_KEY_DERIVATION_INPUT_SECRET is the input keying material used in the 1847 * "extract" step. 1848 * The inputs are mandatory and must be passed in the order above. 1849 * Each input may only be passed once. 1850 * 1851 * \warning HKDF-Extract is not meant to be used on its own. PSA_ALG_HKDF 1852 * should be used instead if possible. PSA_ALG_HKDF_EXTRACT is provided 1853 * as a separate algorithm for the sake of protocols that use it as a 1854 * building block. It may also be a slight performance optimization 1855 * in applications that use HKDF with the same salt and key but many 1856 * different info strings. 1857 * 1858 * \warning HKDF processes the salt as follows: first hash it with hash_alg 1859 * if the salt is longer than the block size of the hash algorithm; then 1860 * pad with null bytes up to the block size. As a result, it is possible 1861 * for distinct salt inputs to result in the same outputs. To ensure 1862 * unique outputs, it is recommended to use a fixed length for salt values. 1863 * 1864 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 1865 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 1866 * 1867 * \return The corresponding HKDF-Extract algorithm. 1868 * \return Unspecified if \p hash_alg is not a supported 1869 * hash algorithm. 1870 */ 1871#define PSA_ALG_HKDF_EXTRACT(hash_alg) \ 1872 (PSA_ALG_HKDF_EXTRACT_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 1873/** Whether the specified algorithm is an HKDF-Extract algorithm. 1874 * 1875 * HKDF-Extract is a family of key derivation algorithms that are based 1876 * on a hash function and the HMAC construction. 1877 * 1878 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 1879 * 1880 * \return 1 if \c alg is an HKDF-Extract algorithm, 0 otherwise. 1881 * This macro may return either 0 or 1 if \c alg is not a supported 1882 * key derivation algorithm identifier. 1883 */ 1884#define PSA_ALG_IS_HKDF_EXTRACT(alg) \ 1885 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_EXTRACT_BASE) 1886 1887#define PSA_ALG_HKDF_EXPAND_BASE ((psa_algorithm_t) 0x08000500) 1888/** Macro to build an HKDF-Expand algorithm. 1889 * 1890 * For example, `PSA_ALG_HKDF_EXPAND(PSA_ALG_SHA_256)` is 1891 * HKDF-Expand using HMAC-SHA-256. 1892 * 1893 * This key derivation algorithm uses the following inputs: 1894 * - PSA_KEY_DERIVATION_INPUT_SECRET is the pseudorandom key (PRK). 1895 * - PSA_KEY_DERIVATION_INPUT_INFO is the info string. 1896 * 1897 * The inputs are mandatory and must be passed in the order above. 1898 * Each input may only be passed once. 1899 * 1900 * \warning HKDF-Expand is not meant to be used on its own. `PSA_ALG_HKDF` 1901 * should be used instead if possible. `PSA_ALG_HKDF_EXPAND` is provided as 1902 * a separate algorithm for the sake of protocols that use it as a building 1903 * block. It may also be a slight performance optimization in applications 1904 * that use HKDF with the same salt and key but many different info strings. 1905 * 1906 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 1907 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 1908 * 1909 * \return The corresponding HKDF-Expand algorithm. 1910 * \return Unspecified if \p hash_alg is not a supported 1911 * hash algorithm. 1912 */ 1913#define PSA_ALG_HKDF_EXPAND(hash_alg) \ 1914 (PSA_ALG_HKDF_EXPAND_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 1915/** Whether the specified algorithm is an HKDF-Expand algorithm. 1916 * 1917 * HKDF-Expand is a family of key derivation algorithms that are based 1918 * on a hash function and the HMAC construction. 1919 * 1920 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 1921 * 1922 * \return 1 if \c alg is an HKDF-Expand algorithm, 0 otherwise. 1923 * This macro may return either 0 or 1 if \c alg is not a supported 1924 * key derivation algorithm identifier. 1925 */ 1926#define PSA_ALG_IS_HKDF_EXPAND(alg) \ 1927 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_EXPAND_BASE) 1928 1929/** Whether the specified algorithm is an HKDF or HKDF-Extract or 1930 * HKDF-Expand algorithm. 1931 * 1932 * 1933 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 1934 * 1935 * \return 1 if \c alg is any HKDF type algorithm, 0 otherwise. 1936 * This macro may return either 0 or 1 if \c alg is not a supported 1937 * key derivation algorithm identifier. 1938 */ 1939#define PSA_ALG_IS_ANY_HKDF(alg) \ 1940 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_BASE || \ 1941 ((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_EXTRACT_BASE || \ 1942 ((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_EXPAND_BASE) 1943 1944#define PSA_ALG_TLS12_PRF_BASE ((psa_algorithm_t) 0x08000200) 1945/** Macro to build a TLS-1.2 PRF algorithm. 1946 * 1947 * TLS 1.2 uses a custom pseudorandom function (PRF) for key schedule, 1948 * specified in Section 5 of RFC 5246. It is based on HMAC and can be 1949 * used with either SHA-256 or SHA-384. 1950 * 1951 * This key derivation algorithm uses the following inputs, which must be 1952 * passed in the order given here: 1953 * - #PSA_KEY_DERIVATION_INPUT_SEED is the seed. 1954 * - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key. 1955 * - #PSA_KEY_DERIVATION_INPUT_LABEL is the label. 1956 * 1957 * For the application to TLS-1.2 key expansion, the seed is the 1958 * concatenation of ServerHello.Random + ClientHello.Random, 1959 * and the label is "key expansion". 1960 * 1961 * For example, `PSA_ALG_TLS12_PRF(PSA_ALG_SHA_256)` represents the 1962 * TLS 1.2 PRF using HMAC-SHA-256. 1963 * 1964 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 1965 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 1966 * 1967 * \return The corresponding TLS-1.2 PRF algorithm. 1968 * \return Unspecified if \p hash_alg is not a supported 1969 * hash algorithm. 1970 */ 1971#define PSA_ALG_TLS12_PRF(hash_alg) \ 1972 (PSA_ALG_TLS12_PRF_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 1973 1974/** Whether the specified algorithm is a TLS-1.2 PRF algorithm. 1975 * 1976 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 1977 * 1978 * \return 1 if \c alg is a TLS-1.2 PRF algorithm, 0 otherwise. 1979 * This macro may return either 0 or 1 if \c alg is not a supported 1980 * key derivation algorithm identifier. 1981 */ 1982#define PSA_ALG_IS_TLS12_PRF(alg) \ 1983 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_TLS12_PRF_BASE) 1984#define PSA_ALG_TLS12_PRF_GET_HASH(hkdf_alg) \ 1985 (PSA_ALG_CATEGORY_HASH | ((hkdf_alg) & PSA_ALG_HASH_MASK)) 1986 1987#define PSA_ALG_TLS12_PSK_TO_MS_BASE ((psa_algorithm_t) 0x08000300) 1988/** Macro to build a TLS-1.2 PSK-to-MasterSecret algorithm. 1989 * 1990 * In a pure-PSK handshake in TLS 1.2, the master secret is derived 1991 * from the PreSharedKey (PSK) through the application of padding 1992 * (RFC 4279, Section 2) and the TLS-1.2 PRF (RFC 5246, Section 5). 1993 * The latter is based on HMAC and can be used with either SHA-256 1994 * or SHA-384. 1995 * 1996 * This key derivation algorithm uses the following inputs, which must be 1997 * passed in the order given here: 1998 * - #PSA_KEY_DERIVATION_INPUT_SEED is the seed. 1999 * - #PSA_KEY_DERIVATION_INPUT_OTHER_SECRET is the other secret for the 2000 * computation of the premaster secret. This input is optional; 2001 * if omitted, it defaults to a string of null bytes with the same length 2002 * as the secret (PSK) input. 2003 * - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key. 2004 * - #PSA_KEY_DERIVATION_INPUT_LABEL is the label. 2005 * 2006 * For the application to TLS-1.2, the seed (which is 2007 * forwarded to the TLS-1.2 PRF) is the concatenation of the 2008 * ClientHello.Random + ServerHello.Random, 2009 * the label is "master secret" or "extended master secret" and 2010 * the other secret depends on the key exchange specified in the cipher suite: 2011 * - for a plain PSK cipher suite (RFC 4279, Section 2), omit 2012 * PSA_KEY_DERIVATION_INPUT_OTHER_SECRET 2013 * - for a DHE-PSK (RFC 4279, Section 3) or ECDHE-PSK cipher suite 2014 * (RFC 5489, Section 2), the other secret should be the output of the 2015 * PSA_ALG_FFDH or PSA_ALG_ECDH key agreement performed with the peer. 2016 * The recommended way to pass this input is to use a key derivation 2017 * algorithm constructed as 2018 * PSA_ALG_KEY_AGREEMENT(ka_alg, PSA_ALG_TLS12_PSK_TO_MS(hash_alg)) 2019 * and to call psa_key_derivation_key_agreement(). Alternatively, 2020 * this input may be an output of `psa_raw_key_agreement()` passed with 2021 * psa_key_derivation_input_bytes(), or an equivalent input passed with 2022 * psa_key_derivation_input_bytes() or psa_key_derivation_input_key(). 2023 * - for a RSA-PSK cipher suite (RFC 4279, Section 4), the other secret 2024 * should be the 48-byte client challenge (the PreMasterSecret of 2025 * (RFC 5246, Section 7.4.7.1)) concatenation of the TLS version and 2026 * a 46-byte random string chosen by the client. On the server, this is 2027 * typically an output of psa_asymmetric_decrypt() using 2028 * PSA_ALG_RSA_PKCS1V15_CRYPT, passed to the key derivation operation 2029 * with `psa_key_derivation_input_bytes()`. 2030 * 2031 * For example, `PSA_ALG_TLS12_PSK_TO_MS(PSA_ALG_SHA_256)` represents the 2032 * TLS-1.2 PSK to MasterSecret derivation PRF using HMAC-SHA-256. 2033 * 2034 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 2035 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 2036 * 2037 * \return The corresponding TLS-1.2 PSK to MS algorithm. 2038 * \return Unspecified if \p hash_alg is not a supported 2039 * hash algorithm. 2040 */ 2041#define PSA_ALG_TLS12_PSK_TO_MS(hash_alg) \ 2042 (PSA_ALG_TLS12_PSK_TO_MS_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 2043 2044/** Whether the specified algorithm is a TLS-1.2 PSK to MS algorithm. 2045 * 2046 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 2047 * 2048 * \return 1 if \c alg is a TLS-1.2 PSK to MS algorithm, 0 otherwise. 2049 * This macro may return either 0 or 1 if \c alg is not a supported 2050 * key derivation algorithm identifier. 2051 */ 2052#define PSA_ALG_IS_TLS12_PSK_TO_MS(alg) \ 2053 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_TLS12_PSK_TO_MS_BASE) 2054#define PSA_ALG_TLS12_PSK_TO_MS_GET_HASH(hkdf_alg) \ 2055 (PSA_ALG_CATEGORY_HASH | ((hkdf_alg) & PSA_ALG_HASH_MASK)) 2056 2057/* The TLS 1.2 ECJPAKE-to-PMS KDF. It takes the shared secret K (an EC point 2058 * in case of EC J-PAKE) and calculates SHA256(K.X) that the rest of TLS 1.2 2059 * will use to derive the session secret, as defined by step 2 of 2060 * https://datatracker.ietf.org/doc/html/draft-cragie-tls-ecjpake-01#section-8.7. 2061 * Uses PSA_ALG_SHA_256. 2062 * This function takes a single input: 2063 * #PSA_KEY_DERIVATION_INPUT_SECRET is the shared secret K from EC J-PAKE. 2064 * The only supported curve is secp256r1 (the 256-bit curve in 2065 * #PSA_ECC_FAMILY_SECP_R1), so the input must be exactly 65 bytes. 2066 * The output has to be read as a single chunk of 32 bytes, defined as 2067 * PSA_TLS12_ECJPAKE_TO_PMS_DATA_SIZE. 2068 */ 2069#define PSA_ALG_TLS12_ECJPAKE_TO_PMS ((psa_algorithm_t) 0x08000609) 2070 2071/* This flag indicates whether the key derivation algorithm is suitable for 2072 * use on low-entropy secrets such as password - these algorithms are also 2073 * known as key stretching or password hashing schemes. These are also the 2074 * algorithms that accepts inputs of type #PSA_KEY_DERIVATION_INPUT_PASSWORD. 2075 * 2076 * Those algorithms cannot be combined with a key agreement algorithm. 2077 */ 2078#define PSA_ALG_KEY_DERIVATION_STRETCHING_FLAG ((psa_algorithm_t) 0x00800000) 2079 2080#define PSA_ALG_PBKDF2_HMAC_BASE ((psa_algorithm_t) 0x08800100) 2081/** Macro to build a PBKDF2-HMAC password hashing / key stretching algorithm. 2082 * 2083 * PBKDF2 is defined by PKCS#5, republished as RFC 8018 (section 5.2). 2084 * This macro specifies the PBKDF2 algorithm constructed using a PRF based on 2085 * HMAC with the specified hash. 2086 * For example, `PSA_ALG_PBKDF2_HMAC(PSA_ALG_SHA_256)` specifies PBKDF2 2087 * using the PRF HMAC-SHA-256. 2088 * 2089 * This key derivation algorithm uses the following inputs, which must be 2090 * provided in the following order: 2091 * - #PSA_KEY_DERIVATION_INPUT_COST is the iteration count. 2092 * This input step must be used exactly once. 2093 * - #PSA_KEY_DERIVATION_INPUT_SALT is the salt. 2094 * This input step must be used one or more times; if used several times, the 2095 * inputs will be concatenated. This can be used to build the final salt 2096 * from multiple sources, both public and secret (also known as pepper). 2097 * - #PSA_KEY_DERIVATION_INPUT_PASSWORD is the password to be hashed. 2098 * This input step must be used exactly once. 2099 * 2100 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 2101 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 2102 * 2103 * \return The corresponding PBKDF2-HMAC-XXX algorithm. 2104 * \return Unspecified if \p hash_alg is not a supported 2105 * hash algorithm. 2106 */ 2107#define PSA_ALG_PBKDF2_HMAC(hash_alg) \ 2108 (PSA_ALG_PBKDF2_HMAC_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 2109 2110/** Whether the specified algorithm is a PBKDF2-HMAC algorithm. 2111 * 2112 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 2113 * 2114 * \return 1 if \c alg is a PBKDF2-HMAC algorithm, 0 otherwise. 2115 * This macro may return either 0 or 1 if \c alg is not a supported 2116 * key derivation algorithm identifier. 2117 */ 2118#define PSA_ALG_IS_PBKDF2_HMAC(alg) \ 2119 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_PBKDF2_HMAC_BASE) 2120#define PSA_ALG_PBKDF2_HMAC_GET_HASH(pbkdf2_alg) \ 2121 (PSA_ALG_CATEGORY_HASH | ((pbkdf2_alg) & PSA_ALG_HASH_MASK)) 2122/** The PBKDF2-AES-CMAC-PRF-128 password hashing / key stretching algorithm. 2123 * 2124 * PBKDF2 is defined by PKCS#5, republished as RFC 8018 (section 5.2). 2125 * This macro specifies the PBKDF2 algorithm constructed using the 2126 * AES-CMAC-PRF-128 PRF specified by RFC 4615. 2127 * 2128 * This key derivation algorithm uses the same inputs as 2129 * #PSA_ALG_PBKDF2_HMAC() with the same constraints. 2130 */ 2131#define PSA_ALG_PBKDF2_AES_CMAC_PRF_128 ((psa_algorithm_t) 0x08800200) 2132 2133#define PSA_ALG_IS_PBKDF2(kdf_alg) \ 2134 (PSA_ALG_IS_PBKDF2_HMAC(kdf_alg) || \ 2135 ((kdf_alg) == PSA_ALG_PBKDF2_AES_CMAC_PRF_128)) 2136 2137#define PSA_ALG_KEY_DERIVATION_MASK ((psa_algorithm_t) 0xfe00ffff) 2138#define PSA_ALG_KEY_AGREEMENT_MASK ((psa_algorithm_t) 0xffff0000) 2139 2140/** Macro to build a combined algorithm that chains a key agreement with 2141 * a key derivation. 2142 * 2143 * \param ka_alg A key agreement algorithm (\c PSA_ALG_XXX value such 2144 * that #PSA_ALG_IS_KEY_AGREEMENT(\p ka_alg) is true). 2145 * \param kdf_alg A key derivation algorithm (\c PSA_ALG_XXX value such 2146 * that #PSA_ALG_IS_KEY_DERIVATION(\p kdf_alg) is true). 2147 * 2148 * \return The corresponding key agreement and derivation 2149 * algorithm. 2150 * \return Unspecified if \p ka_alg is not a supported 2151 * key agreement algorithm or \p kdf_alg is not a 2152 * supported key derivation algorithm. 2153 */ 2154#define PSA_ALG_KEY_AGREEMENT(ka_alg, kdf_alg) \ 2155 ((ka_alg) | (kdf_alg)) 2156 2157#define PSA_ALG_KEY_AGREEMENT_GET_KDF(alg) \ 2158 (((alg) & PSA_ALG_KEY_DERIVATION_MASK) | PSA_ALG_CATEGORY_KEY_DERIVATION) 2159 2160#define PSA_ALG_KEY_AGREEMENT_GET_BASE(alg) \ 2161 (((alg) & PSA_ALG_KEY_AGREEMENT_MASK) | PSA_ALG_CATEGORY_KEY_AGREEMENT) 2162 2163/** Whether the specified algorithm is a raw key agreement algorithm. 2164 * 2165 * A raw key agreement algorithm is one that does not specify 2166 * a key derivation function. 2167 * Usually, raw key agreement algorithms are constructed directly with 2168 * a \c PSA_ALG_xxx macro while non-raw key agreement algorithms are 2169 * constructed with #PSA_ALG_KEY_AGREEMENT(). 2170 * 2171 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 2172 * 2173 * \return 1 if \p alg is a raw key agreement algorithm, 0 otherwise. 2174 * This macro may return either 0 or 1 if \p alg is not a supported 2175 * algorithm identifier. 2176 */ 2177#define PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) \ 2178 (PSA_ALG_IS_KEY_AGREEMENT(alg) && \ 2179 PSA_ALG_KEY_AGREEMENT_GET_KDF(alg) == PSA_ALG_CATEGORY_KEY_DERIVATION) 2180 2181#define PSA_ALG_IS_KEY_DERIVATION_OR_AGREEMENT(alg) \ 2182 ((PSA_ALG_IS_KEY_DERIVATION(alg) || PSA_ALG_IS_KEY_AGREEMENT(alg))) 2183 2184/** The finite-field Diffie-Hellman (DH) key agreement algorithm. 2185 * 2186 * The shared secret produced by key agreement is 2187 * `g^{ab}` in big-endian format. 2188 * It is `ceiling(m / 8)` bytes long where `m` is the size of the prime `p` 2189 * in bits. 2190 */ 2191#define PSA_ALG_FFDH ((psa_algorithm_t) 0x09010000) 2192 2193/** Whether the specified algorithm is a finite field Diffie-Hellman algorithm. 2194 * 2195 * This includes the raw finite field Diffie-Hellman algorithm as well as 2196 * finite-field Diffie-Hellman followed by any supporter key derivation 2197 * algorithm. 2198 * 2199 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 2200 * 2201 * \return 1 if \c alg is a finite field Diffie-Hellman algorithm, 0 otherwise. 2202 * This macro may return either 0 or 1 if \c alg is not a supported 2203 * key agreement algorithm identifier. 2204 */ 2205#define PSA_ALG_IS_FFDH(alg) \ 2206 (PSA_ALG_KEY_AGREEMENT_GET_BASE(alg) == PSA_ALG_FFDH) 2207 2208/** The elliptic curve Diffie-Hellman (ECDH) key agreement algorithm. 2209 * 2210 * The shared secret produced by key agreement is the x-coordinate of 2211 * the shared secret point. It is always `ceiling(m / 8)` bytes long where 2212 * `m` is the bit size associated with the curve, i.e. the bit size of the 2213 * order of the curve's coordinate field. When `m` is not a multiple of 8, 2214 * the byte containing the most significant bit of the shared secret 2215 * is padded with zero bits. The byte order is either little-endian 2216 * or big-endian depending on the curve type. 2217 * 2218 * - For Montgomery curves (curve types `PSA_ECC_FAMILY_CURVEXXX`), 2219 * the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A` 2220 * in little-endian byte order. 2221 * The bit size is 448 for Curve448 and 255 for Curve25519. 2222 * - For Weierstrass curves over prime fields (curve types 2223 * `PSA_ECC_FAMILY_SECPXXX` and `PSA_ECC_FAMILY_BRAINPOOL_PXXX`), 2224 * the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A` 2225 * in big-endian byte order. 2226 * The bit size is `m = ceiling(log_2(p))` for the field `F_p`. 2227 * - For Weierstrass curves over binary fields (curve types 2228 * `PSA_ECC_FAMILY_SECTXXX`), 2229 * the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A` 2230 * in big-endian byte order. 2231 * The bit size is `m` for the field `F_{2^m}`. 2232 */ 2233#define PSA_ALG_ECDH ((psa_algorithm_t) 0x09020000) 2234 2235/** Whether the specified algorithm is an elliptic curve Diffie-Hellman 2236 * algorithm. 2237 * 2238 * This includes the raw elliptic curve Diffie-Hellman algorithm as well as 2239 * elliptic curve Diffie-Hellman followed by any supporter key derivation 2240 * algorithm. 2241 * 2242 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 2243 * 2244 * \return 1 if \c alg is an elliptic curve Diffie-Hellman algorithm, 2245 * 0 otherwise. 2246 * This macro may return either 0 or 1 if \c alg is not a supported 2247 * key agreement algorithm identifier. 2248 */ 2249#define PSA_ALG_IS_ECDH(alg) \ 2250 (PSA_ALG_KEY_AGREEMENT_GET_BASE(alg) == PSA_ALG_ECDH) 2251 2252/** Whether the specified algorithm encoding is a wildcard. 2253 * 2254 * Wildcard values may only be used to set the usage algorithm field in 2255 * a policy, not to perform an operation. 2256 * 2257 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 2258 * 2259 * \return 1 if \c alg is a wildcard algorithm encoding. 2260 * \return 0 if \c alg is a non-wildcard algorithm encoding (suitable for 2261 * an operation). 2262 * \return This macro may return either 0 or 1 if \c alg is not a supported 2263 * algorithm identifier. 2264 */ 2265#define PSA_ALG_IS_WILDCARD(alg) \ 2266 (PSA_ALG_IS_HASH_AND_SIGN(alg) ? \ 2267 PSA_ALG_SIGN_GET_HASH(alg) == PSA_ALG_ANY_HASH : \ 2268 PSA_ALG_IS_MAC(alg) ? \ 2269 (alg & PSA_ALG_MAC_AT_LEAST_THIS_LENGTH_FLAG) != 0 : \ 2270 PSA_ALG_IS_AEAD(alg) ? \ 2271 (alg & PSA_ALG_AEAD_AT_LEAST_THIS_LENGTH_FLAG) != 0 : \ 2272 (alg) == PSA_ALG_ANY_HASH) 2273 2274/** Get the hash used by a composite algorithm. 2275 * 2276 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 2277 * 2278 * \return The underlying hash algorithm if alg is a composite algorithm that 2279 * uses a hash algorithm. 2280 * 2281 * \return \c 0 if alg is not a composite algorithm that uses a hash. 2282 */ 2283#define PSA_ALG_GET_HASH(alg) \ 2284 (((alg) & 0x000000ff) == 0 ? ((psa_algorithm_t) 0) : 0x02000000 | ((alg) & 0x000000ff)) 2285 2286/**@}*/ 2287 2288/** \defgroup key_lifetimes Key lifetimes 2289 * @{ 2290 */ 2291 2292/* Note that location and persistence level values are embedded in the 2293 * persistent key store, as part of key metadata. As a consequence, they 2294 * must not be changed (unless the storage format version changes). 2295 */ 2296 2297/** The default lifetime for volatile keys. 2298 * 2299 * A volatile key only exists as long as the identifier to it is not destroyed. 2300 * The key material is guaranteed to be erased on a power reset. 2301 * 2302 * A key with this lifetime is typically stored in the RAM area of the 2303 * PSA Crypto subsystem. However this is an implementation choice. 2304 * If an implementation stores data about the key in a non-volatile memory, 2305 * it must release all the resources associated with the key and erase the 2306 * key material if the calling application terminates. 2307 */ 2308#define PSA_KEY_LIFETIME_VOLATILE ((psa_key_lifetime_t) 0x00000000) 2309 2310/** The default lifetime for persistent keys. 2311 * 2312 * A persistent key remains in storage until it is explicitly destroyed or 2313 * until the corresponding storage area is wiped. This specification does 2314 * not define any mechanism to wipe a storage area, but integrations may 2315 * provide their own mechanism (for example to perform a factory reset, 2316 * to prepare for device refurbishment, or to uninstall an application). 2317 * 2318 * This lifetime value is the default storage area for the calling 2319 * application. Integrations of Mbed TLS may support other persistent lifetimes. 2320 * See ::psa_key_lifetime_t for more information. 2321 */ 2322#define PSA_KEY_LIFETIME_PERSISTENT ((psa_key_lifetime_t) 0x00000001) 2323 2324/** The persistence level of volatile keys. 2325 * 2326 * See ::psa_key_persistence_t for more information. 2327 */ 2328#define PSA_KEY_PERSISTENCE_VOLATILE ((psa_key_persistence_t) 0x00) 2329 2330/** The default persistence level for persistent keys. 2331 * 2332 * See ::psa_key_persistence_t for more information. 2333 */ 2334#define PSA_KEY_PERSISTENCE_DEFAULT ((psa_key_persistence_t) 0x01) 2335 2336/** A persistence level indicating that a key is never destroyed. 2337 * 2338 * See ::psa_key_persistence_t for more information. 2339 */ 2340#define PSA_KEY_PERSISTENCE_READ_ONLY ((psa_key_persistence_t) 0xff) 2341 2342#define PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) \ 2343 ((psa_key_persistence_t) ((lifetime) & 0x000000ff)) 2344 2345#define PSA_KEY_LIFETIME_GET_LOCATION(lifetime) \ 2346 ((psa_key_location_t) ((lifetime) >> 8)) 2347 2348/** Whether a key lifetime indicates that the key is volatile. 2349 * 2350 * A volatile key is automatically destroyed by the implementation when 2351 * the application instance terminates. In particular, a volatile key 2352 * is automatically destroyed on a power reset of the device. 2353 * 2354 * A key that is not volatile is persistent. Persistent keys are 2355 * preserved until the application explicitly destroys them or until an 2356 * implementation-specific device management event occurs (for example, 2357 * a factory reset). 2358 * 2359 * \param lifetime The lifetime value to query (value of type 2360 * ::psa_key_lifetime_t). 2361 * 2362 * \return \c 1 if the key is volatile, otherwise \c 0. 2363 */ 2364#define PSA_KEY_LIFETIME_IS_VOLATILE(lifetime) \ 2365 (PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) == \ 2366 PSA_KEY_PERSISTENCE_VOLATILE) 2367 2368/** Whether a key lifetime indicates that the key is read-only. 2369 * 2370 * Read-only keys cannot be created or destroyed through the PSA Crypto API. 2371 * They must be created through platform-specific means that bypass the API. 2372 * 2373 * Some platforms may offer ways to destroy read-only keys. For example, 2374 * consider a platform with multiple levels of privilege, where a 2375 * low-privilege application can use a key but is not allowed to destroy 2376 * it, and the platform exposes the key to the application with a read-only 2377 * lifetime. High-privilege code can destroy the key even though the 2378 * application sees the key as read-only. 2379 * 2380 * \param lifetime The lifetime value to query (value of type 2381 * ::psa_key_lifetime_t). 2382 * 2383 * \return \c 1 if the key is read-only, otherwise \c 0. 2384 */ 2385#define PSA_KEY_LIFETIME_IS_READ_ONLY(lifetime) \ 2386 (PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) == \ 2387 PSA_KEY_PERSISTENCE_READ_ONLY) 2388 2389/** Construct a lifetime from a persistence level and a location. 2390 * 2391 * \param persistence The persistence level 2392 * (value of type ::psa_key_persistence_t). 2393 * \param location The location indicator 2394 * (value of type ::psa_key_location_t). 2395 * 2396 * \return The constructed lifetime value. 2397 */ 2398#define PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(persistence, location) \ 2399 ((location) << 8 | (persistence)) 2400 2401/** The local storage area for persistent keys. 2402 * 2403 * This storage area is available on all systems that can store persistent 2404 * keys without delegating the storage to a third-party cryptoprocessor. 2405 * 2406 * See ::psa_key_location_t for more information. 2407 */ 2408#define PSA_KEY_LOCATION_LOCAL_STORAGE ((psa_key_location_t) 0x000000) 2409 2410#define PSA_KEY_LOCATION_VENDOR_FLAG ((psa_key_location_t) 0x800000) 2411 2412/* Note that key identifier values are embedded in the 2413 * persistent key store, as part of key metadata. As a consequence, they 2414 * must not be changed (unless the storage format version changes). 2415 */ 2416 2417/** The null key identifier. 2418 */ 2419/* *INDENT-OFF* (https://github.com/ARM-software/psa-arch-tests/issues/337) */ 2420#define PSA_KEY_ID_NULL ((psa_key_id_t)0) 2421/* *INDENT-ON* */ 2422/** The minimum value for a key identifier chosen by the application. 2423 */ 2424#define PSA_KEY_ID_USER_MIN ((psa_key_id_t) 0x00000001) 2425/** The maximum value for a key identifier chosen by the application. 2426 */ 2427#define PSA_KEY_ID_USER_MAX ((psa_key_id_t) 0x3fffffff) 2428/** The minimum value for a key identifier chosen by the implementation. 2429 */ 2430#define PSA_KEY_ID_VENDOR_MIN ((psa_key_id_t) 0x40000000) 2431/** The maximum value for a key identifier chosen by the implementation. 2432 */ 2433#define PSA_KEY_ID_VENDOR_MAX ((psa_key_id_t) 0x7fffffff) 2434 2435 2436#if !defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER) 2437 2438#define MBEDTLS_SVC_KEY_ID_INIT ((psa_key_id_t) 0) 2439#define MBEDTLS_SVC_KEY_ID_GET_KEY_ID(id) (id) 2440#define MBEDTLS_SVC_KEY_ID_GET_OWNER_ID(id) (0) 2441 2442/** Utility to initialize a key identifier at runtime. 2443 * 2444 * \param unused Unused parameter. 2445 * \param key_id Identifier of the key. 2446 */ 2447static inline mbedtls_svc_key_id_t mbedtls_svc_key_id_make( 2448 unsigned int unused, psa_key_id_t key_id) 2449{ 2450 (void) unused; 2451 2452 return key_id; 2453} 2454 2455/** Compare two key identifiers. 2456 * 2457 * \param id1 First key identifier. 2458 * \param id2 Second key identifier. 2459 * 2460 * \return Non-zero if the two key identifier are equal, zero otherwise. 2461 */ 2462static inline int mbedtls_svc_key_id_equal(mbedtls_svc_key_id_t id1, 2463 mbedtls_svc_key_id_t id2) 2464{ 2465 return id1 == id2; 2466} 2467 2468/** Check whether a key identifier is null. 2469 * 2470 * \param key Key identifier. 2471 * 2472 * \return Non-zero if the key identifier is null, zero otherwise. 2473 */ 2474static inline int mbedtls_svc_key_id_is_null(mbedtls_svc_key_id_t key) 2475{ 2476 return key == 0; 2477} 2478 2479#else /* MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER */ 2480 2481#define MBEDTLS_SVC_KEY_ID_INIT ((mbedtls_svc_key_id_t){ 0, 0 }) 2482#define MBEDTLS_SVC_KEY_ID_GET_KEY_ID(id) ((id).MBEDTLS_PRIVATE(key_id)) 2483#define MBEDTLS_SVC_KEY_ID_GET_OWNER_ID(id) ((id).MBEDTLS_PRIVATE(owner)) 2484 2485/** Utility to initialize a key identifier at runtime. 2486 * 2487 * \param owner_id Identifier of the key owner. 2488 * \param key_id Identifier of the key. 2489 */ 2490static inline mbedtls_svc_key_id_t mbedtls_svc_key_id_make( 2491 mbedtls_key_owner_id_t owner_id, psa_key_id_t key_id) 2492{ 2493 return (mbedtls_svc_key_id_t){ .MBEDTLS_PRIVATE(key_id) = key_id, 2494 .MBEDTLS_PRIVATE(owner) = owner_id }; 2495} 2496 2497/** Compare two key identifiers. 2498 * 2499 * \param id1 First key identifier. 2500 * \param id2 Second key identifier. 2501 * 2502 * \return Non-zero if the two key identifier are equal, zero otherwise. 2503 */ 2504static inline int mbedtls_svc_key_id_equal(mbedtls_svc_key_id_t id1, 2505 mbedtls_svc_key_id_t id2) 2506{ 2507 return (id1.MBEDTLS_PRIVATE(key_id) == id2.MBEDTLS_PRIVATE(key_id)) && 2508 mbedtls_key_owner_id_equal(id1.MBEDTLS_PRIVATE(owner), id2.MBEDTLS_PRIVATE(owner)); 2509} 2510 2511/** Check whether a key identifier is null. 2512 * 2513 * \param key Key identifier. 2514 * 2515 * \return Non-zero if the key identifier is null, zero otherwise. 2516 */ 2517static inline int mbedtls_svc_key_id_is_null(mbedtls_svc_key_id_t key) 2518{ 2519 return key.MBEDTLS_PRIVATE(key_id) == 0; 2520} 2521 2522#endif /* !MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER */ 2523 2524/**@}*/ 2525 2526/** \defgroup policy Key policies 2527 * @{ 2528 */ 2529 2530/* Note that key usage flags are embedded in the 2531 * persistent key store, as part of key metadata. As a consequence, they 2532 * must not be changed (unless the storage format version changes). 2533 */ 2534 2535/** Whether the key may be exported. 2536 * 2537 * A public key or the public part of a key pair may always be exported 2538 * regardless of the value of this permission flag. 2539 * 2540 * If a key does not have export permission, implementations shall not 2541 * allow the key to be exported in plain form from the cryptoprocessor, 2542 * whether through psa_export_key() or through a proprietary interface. 2543 * The key may however be exportable in a wrapped form, i.e. in a form 2544 * where it is encrypted by another key. 2545 */ 2546#define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t) 0x00000001) 2547 2548/** Whether the key may be copied. 2549 * 2550 * This flag allows the use of psa_copy_key() to make a copy of the key 2551 * with the same policy or a more restrictive policy. 2552 * 2553 * For lifetimes for which the key is located in a secure element which 2554 * enforce the non-exportability of keys, copying a key outside the secure 2555 * element also requires the usage flag #PSA_KEY_USAGE_EXPORT. 2556 * Copying the key inside the secure element is permitted with just 2557 * #PSA_KEY_USAGE_COPY if the secure element supports it. 2558 * For keys with the lifetime #PSA_KEY_LIFETIME_VOLATILE or 2559 * #PSA_KEY_LIFETIME_PERSISTENT, the usage flag #PSA_KEY_USAGE_COPY 2560 * is sufficient to permit the copy. 2561 */ 2562#define PSA_KEY_USAGE_COPY ((psa_key_usage_t) 0x00000002) 2563 2564/** Whether the key may be used to encrypt a message. 2565 * 2566 * This flag allows the key to be used for a symmetric encryption operation, 2567 * for an AEAD encryption-and-authentication operation, 2568 * or for an asymmetric encryption operation, 2569 * if otherwise permitted by the key's type and policy. 2570 * 2571 * For a key pair, this concerns the public key. 2572 */ 2573#define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t) 0x00000100) 2574 2575/** Whether the key may be used to decrypt a message. 2576 * 2577 * This flag allows the key to be used for a symmetric decryption operation, 2578 * for an AEAD decryption-and-verification operation, 2579 * or for an asymmetric decryption operation, 2580 * if otherwise permitted by the key's type and policy. 2581 * 2582 * For a key pair, this concerns the private key. 2583 */ 2584#define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t) 0x00000200) 2585 2586/** Whether the key may be used to sign a message. 2587 * 2588 * This flag allows the key to be used for a MAC calculation operation or for 2589 * an asymmetric message signature operation, if otherwise permitted by the 2590 * key’s type and policy. 2591 * 2592 * For a key pair, this concerns the private key. 2593 */ 2594#define PSA_KEY_USAGE_SIGN_MESSAGE ((psa_key_usage_t) 0x00000400) 2595 2596/** Whether the key may be used to verify a message. 2597 * 2598 * This flag allows the key to be used for a MAC verification operation or for 2599 * an asymmetric message signature verification operation, if otherwise 2600 * permitted by the key’s type and policy. 2601 * 2602 * For a key pair, this concerns the public key. 2603 */ 2604#define PSA_KEY_USAGE_VERIFY_MESSAGE ((psa_key_usage_t) 0x00000800) 2605 2606/** Whether the key may be used to sign a message. 2607 * 2608 * This flag allows the key to be used for a MAC calculation operation 2609 * or for an asymmetric signature operation, 2610 * if otherwise permitted by the key's type and policy. 2611 * 2612 * For a key pair, this concerns the private key. 2613 */ 2614#define PSA_KEY_USAGE_SIGN_HASH ((psa_key_usage_t) 0x00001000) 2615 2616/** Whether the key may be used to verify a message signature. 2617 * 2618 * This flag allows the key to be used for a MAC verification operation 2619 * or for an asymmetric signature verification operation, 2620 * if otherwise permitted by the key's type and policy. 2621 * 2622 * For a key pair, this concerns the public key. 2623 */ 2624#define PSA_KEY_USAGE_VERIFY_HASH ((psa_key_usage_t) 0x00002000) 2625 2626/** Whether the key may be used to derive other keys or produce a password 2627 * hash. 2628 * 2629 * This flag allows the key to be used for a key derivation operation or for 2630 * a key agreement operation, if otherwise permitted by the key's type and 2631 * policy. 2632 * 2633 * If this flag is present on all keys used in calls to 2634 * psa_key_derivation_input_key() for a key derivation operation, then it 2635 * permits calling psa_key_derivation_output_bytes() or 2636 * psa_key_derivation_output_key() at the end of the operation. 2637 */ 2638#define PSA_KEY_USAGE_DERIVE ((psa_key_usage_t) 0x00004000) 2639 2640/** Whether the key may be used to verify the result of a key derivation, 2641 * including password hashing. 2642 * 2643 * This flag allows the key to be used: 2644 * 2645 * This flag allows the key to be used in a key derivation operation, if 2646 * otherwise permitted by the key's type and policy. 2647 * 2648 * If this flag is present on all keys used in calls to 2649 * psa_key_derivation_input_key() for a key derivation operation, then it 2650 * permits calling psa_key_derivation_verify_bytes() or 2651 * psa_key_derivation_verify_key() at the end of the operation. 2652 */ 2653#define PSA_KEY_USAGE_VERIFY_DERIVATION ((psa_key_usage_t) 0x00008000) 2654 2655/**@}*/ 2656 2657/** \defgroup derivation Key derivation 2658 * @{ 2659 */ 2660 2661/* Key input steps are not embedded in the persistent storage, so you can 2662 * change them if needed: it's only an ABI change. */ 2663 2664/** A secret input for key derivation. 2665 * 2666 * This should be a key of type #PSA_KEY_TYPE_DERIVE 2667 * (passed to psa_key_derivation_input_key()) 2668 * or the shared secret resulting from a key agreement 2669 * (obtained via psa_key_derivation_key_agreement()). 2670 * 2671 * The secret can also be a direct input (passed to 2672 * key_derivation_input_bytes()). In this case, the derivation operation 2673 * may not be used to derive keys: the operation will only allow 2674 * psa_key_derivation_output_bytes(), 2675 * psa_key_derivation_verify_bytes(), or 2676 * psa_key_derivation_verify_key(), but not 2677 * psa_key_derivation_output_key(). 2678 */ 2679#define PSA_KEY_DERIVATION_INPUT_SECRET ((psa_key_derivation_step_t) 0x0101) 2680 2681/** A low-entropy secret input for password hashing / key stretching. 2682 * 2683 * This is usually a key of type #PSA_KEY_TYPE_PASSWORD (passed to 2684 * psa_key_derivation_input_key()) or a direct input (passed to 2685 * psa_key_derivation_input_bytes()) that is a password or passphrase. It can 2686 * also be high-entropy secret such as a key of type #PSA_KEY_TYPE_DERIVE or 2687 * the shared secret resulting from a key agreement. 2688 * 2689 * The secret can also be a direct input (passed to 2690 * key_derivation_input_bytes()). In this case, the derivation operation 2691 * may not be used to derive keys: the operation will only allow 2692 * psa_key_derivation_output_bytes(), 2693 * psa_key_derivation_verify_bytes(), or 2694 * psa_key_derivation_verify_key(), but not 2695 * psa_key_derivation_output_key(). 2696 */ 2697#define PSA_KEY_DERIVATION_INPUT_PASSWORD ((psa_key_derivation_step_t) 0x0102) 2698 2699/** A high-entropy additional secret input for key derivation. 2700 * 2701 * This is typically the shared secret resulting from a key agreement obtained 2702 * via `psa_key_derivation_key_agreement()`. It may alternatively be a key of 2703 * type `PSA_KEY_TYPE_DERIVE` passed to `psa_key_derivation_input_key()`, or 2704 * a direct input passed to `psa_key_derivation_input_bytes()`. 2705 */ 2706#define PSA_KEY_DERIVATION_INPUT_OTHER_SECRET \ 2707 ((psa_key_derivation_step_t) 0x0103) 2708 2709/** A label for key derivation. 2710 * 2711 * This should be a direct input. 2712 * It can also be a key of type #PSA_KEY_TYPE_RAW_DATA. 2713 */ 2714#define PSA_KEY_DERIVATION_INPUT_LABEL ((psa_key_derivation_step_t) 0x0201) 2715 2716/** A salt for key derivation. 2717 * 2718 * This should be a direct input. 2719 * It can also be a key of type #PSA_KEY_TYPE_RAW_DATA or 2720 * #PSA_KEY_TYPE_PEPPER. 2721 */ 2722#define PSA_KEY_DERIVATION_INPUT_SALT ((psa_key_derivation_step_t) 0x0202) 2723 2724/** An information string for key derivation. 2725 * 2726 * This should be a direct input. 2727 * It can also be a key of type #PSA_KEY_TYPE_RAW_DATA. 2728 */ 2729#define PSA_KEY_DERIVATION_INPUT_INFO ((psa_key_derivation_step_t) 0x0203) 2730 2731/** A seed for key derivation. 2732 * 2733 * This should be a direct input. 2734 * It can also be a key of type #PSA_KEY_TYPE_RAW_DATA. 2735 */ 2736#define PSA_KEY_DERIVATION_INPUT_SEED ((psa_key_derivation_step_t) 0x0204) 2737 2738/** A cost parameter for password hashing / key stretching. 2739 * 2740 * This must be a direct input, passed to psa_key_derivation_input_integer(). 2741 */ 2742#define PSA_KEY_DERIVATION_INPUT_COST ((psa_key_derivation_step_t) 0x0205) 2743 2744/**@}*/ 2745 2746/** \defgroup helper_macros Helper macros 2747 * @{ 2748 */ 2749 2750/* Helper macros */ 2751 2752/** Check if two AEAD algorithm identifiers refer to the same AEAD algorithm 2753 * regardless of the tag length they encode. 2754 * 2755 * \param aead_alg_1 An AEAD algorithm identifier. 2756 * \param aead_alg_2 An AEAD algorithm identifier. 2757 * 2758 * \return 1 if both identifiers refer to the same AEAD algorithm, 2759 * 0 otherwise. 2760 * Unspecified if neither \p aead_alg_1 nor \p aead_alg_2 are 2761 * a supported AEAD algorithm. 2762 */ 2763#define MBEDTLS_PSA_ALG_AEAD_EQUAL(aead_alg_1, aead_alg_2) \ 2764 (!(((aead_alg_1) ^ (aead_alg_2)) & \ 2765 ~(PSA_ALG_AEAD_TAG_LENGTH_MASK | PSA_ALG_AEAD_AT_LEAST_THIS_LENGTH_FLAG))) 2766 2767/**@}*/ 2768 2769/**@}*/ 2770 2771/** \defgroup interruptible Interruptible operations 2772 * @{ 2773 */ 2774 2775/** Maximum value for use with \c psa_interruptible_set_max_ops() to determine 2776 * the maximum number of ops allowed to be executed by an interruptible 2777 * function in a single call. 2778 */ 2779#define PSA_INTERRUPTIBLE_MAX_OPS_UNLIMITED UINT32_MAX 2780 2781/**@}*/ 2782 2783#endif /* PSA_CRYPTO_VALUES_H */ 2784