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