1 /** 2 * \file psa/crypto.h 3 * \brief Platform Security Architecture cryptography module 4 */ 5 /* 6 * Copyright The Mbed TLS Contributors 7 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 8 */ 9 10 #ifndef PSA_CRYPTO_H 11 #define PSA_CRYPTO_H 12 13 #if defined(MBEDTLS_PSA_CRYPTO_PLATFORM_FILE) 14 #include MBEDTLS_PSA_CRYPTO_PLATFORM_FILE 15 #else 16 #include "crypto_platform.h" 17 #endif 18 19 #include <stddef.h> 20 21 #ifdef __DOXYGEN_ONLY__ 22 /* This __DOXYGEN_ONLY__ block contains mock definitions for things that 23 * must be defined in the crypto_platform.h header. These mock definitions 24 * are present in this file as a convenience to generate pretty-printed 25 * documentation that includes those definitions. */ 26 27 /** \defgroup platform Implementation-specific definitions 28 * @{ 29 */ 30 31 /**@}*/ 32 #endif /* __DOXYGEN_ONLY__ */ 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /* The file "crypto_types.h" declares types that encode errors, 39 * algorithms, key types, policies, etc. */ 40 #include "crypto_types.h" 41 42 /** \defgroup version API version 43 * @{ 44 */ 45 46 /** 47 * The major version of this implementation of the PSA Crypto API 48 */ 49 #define PSA_CRYPTO_API_VERSION_MAJOR 1 50 51 /** 52 * The minor version of this implementation of the PSA Crypto API 53 */ 54 #define PSA_CRYPTO_API_VERSION_MINOR 0 55 56 /**@}*/ 57 58 /* The file "crypto_values.h" declares macros to build and analyze values 59 * of integral types defined in "crypto_types.h". */ 60 #include "crypto_values.h" 61 62 /* The file "crypto_sizes.h" contains definitions for size calculation 63 * macros whose definitions are implementation-specific. */ 64 #include "crypto_sizes.h" 65 66 /* The file "crypto_struct.h" contains definitions for 67 * implementation-specific structs that are declared above. */ 68 #if defined(MBEDTLS_PSA_CRYPTO_STRUCT_FILE) 69 #include MBEDTLS_PSA_CRYPTO_STRUCT_FILE 70 #else 71 #include "crypto_struct.h" 72 #endif 73 74 /** \defgroup initialization Library initialization 75 * @{ 76 */ 77 78 /** 79 * \brief Library initialization. 80 * 81 * Applications must call this function before calling any other 82 * function in this module. 83 * 84 * Applications may call this function more than once. Once a call 85 * succeeds, subsequent calls are guaranteed to succeed. 86 * 87 * If the application calls other functions before calling psa_crypto_init(), 88 * the behavior is undefined. Implementations are encouraged to either perform 89 * the operation as if the library had been initialized or to return 90 * #PSA_ERROR_BAD_STATE or some other applicable error. In particular, 91 * implementations should not return a success status if the lack of 92 * initialization may have security implications, for example due to improper 93 * seeding of the random number generator. 94 * 95 * \retval #PSA_SUCCESS \emptydescription 96 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 97 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription 98 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 99 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 100 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 101 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 102 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 103 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 104 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 105 */ 106 psa_status_t psa_crypto_init(void); 107 108 /**@}*/ 109 110 /** \addtogroup attributes 111 * @{ 112 */ 113 114 /** \def PSA_KEY_ATTRIBUTES_INIT 115 * 116 * This macro returns a suitable initializer for a key attribute structure 117 * of type #psa_key_attributes_t. 118 */ 119 120 /** Return an initial value for a key attributes structure. 121 */ 122 static psa_key_attributes_t psa_key_attributes_init(void); 123 124 /** Declare a key as persistent and set its key identifier. 125 * 126 * If the attribute structure currently declares the key as volatile (which 127 * is the default content of an attribute structure), this function sets 128 * the lifetime attribute to #PSA_KEY_LIFETIME_PERSISTENT. 129 * 130 * This function does not access storage, it merely stores the given 131 * value in the structure. 132 * The persistent key will be written to storage when the attribute 133 * structure is passed to a key creation function such as 134 * psa_import_key(), psa_generate_key(), psa_generate_key_custom(), 135 * psa_key_derivation_output_key(), psa_key_derivation_output_key_custom() 136 * or psa_copy_key(). 137 * 138 * This function may be declared as `static` (i.e. without external 139 * linkage). This function may be provided as a function-like macro, 140 * but in this case it must evaluate each of its arguments exactly once. 141 * 142 * \param[out] attributes The attribute structure to write to. 143 * \param key The persistent identifier for the key. 144 * This can be any value in the range from 145 * #PSA_KEY_ID_USER_MIN to #PSA_KEY_ID_USER_MAX 146 * inclusive. 147 */ 148 static void psa_set_key_id(psa_key_attributes_t *attributes, 149 mbedtls_svc_key_id_t key); 150 151 #ifdef MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER 152 /** Set the owner identifier of a key. 153 * 154 * When key identifiers encode key owner identifiers, psa_set_key_id() does 155 * not allow to define in key attributes the owner of volatile keys as 156 * psa_set_key_id() enforces the key to be persistent. 157 * 158 * This function allows to set in key attributes the owner identifier of a 159 * key. It is intended to be used for volatile keys. For persistent keys, 160 * it is recommended to use the PSA Cryptography API psa_set_key_id() to define 161 * the owner of a key. 162 * 163 * \param[out] attributes The attribute structure to write to. 164 * \param owner The key owner identifier. 165 */ 166 static void mbedtls_set_key_owner_id(psa_key_attributes_t *attributes, 167 mbedtls_key_owner_id_t owner); 168 #endif 169 170 /** Set the location of a persistent key. 171 * 172 * To make a key persistent, you must give it a persistent key identifier 173 * with psa_set_key_id(). By default, a key that has a persistent identifier 174 * is stored in the default storage area identifier by 175 * #PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage 176 * area, or to explicitly declare the key as volatile. 177 * 178 * This function does not access storage, it merely stores the given 179 * value in the structure. 180 * The persistent key will be written to storage when the attribute 181 * structure is passed to a key creation function such as 182 * psa_import_key(), psa_generate_key(), psa_generate_key_custom(), 183 * psa_key_derivation_output_key(), psa_key_derivation_output_key_custom() 184 * or psa_copy_key(). 185 * 186 * This function may be declared as `static` (i.e. without external 187 * linkage). This function may be provided as a function-like macro, 188 * but in this case it must evaluate each of its arguments exactly once. 189 * 190 * \param[out] attributes The attribute structure to write to. 191 * \param lifetime The lifetime for the key. 192 * If this is #PSA_KEY_LIFETIME_VOLATILE, the 193 * key will be volatile, and the key identifier 194 * attribute is reset to 0. 195 */ 196 static void psa_set_key_lifetime(psa_key_attributes_t *attributes, 197 psa_key_lifetime_t lifetime); 198 199 /** Retrieve the key identifier from key attributes. 200 * 201 * This function may be declared as `static` (i.e. without external 202 * linkage). This function may be provided as a function-like macro, 203 * but in this case it must evaluate its argument exactly once. 204 * 205 * \param[in] attributes The key attribute structure to query. 206 * 207 * \return The persistent identifier stored in the attribute structure. 208 * This value is unspecified if the attribute structure declares 209 * the key as volatile. 210 */ 211 static mbedtls_svc_key_id_t psa_get_key_id( 212 const psa_key_attributes_t *attributes); 213 214 /** Retrieve the lifetime from key attributes. 215 * 216 * This function may be declared as `static` (i.e. without external 217 * linkage). This function may be provided as a function-like macro, 218 * but in this case it must evaluate its argument exactly once. 219 * 220 * \param[in] attributes The key attribute structure to query. 221 * 222 * \return The lifetime value stored in the attribute structure. 223 */ 224 static psa_key_lifetime_t psa_get_key_lifetime( 225 const psa_key_attributes_t *attributes); 226 227 /** Declare usage flags for a key. 228 * 229 * Usage flags are part of a key's usage policy. They encode what 230 * kind of operations are permitted on the key. For more details, 231 * refer to the documentation of the type #psa_key_usage_t. 232 * 233 * This function overwrites any usage flags 234 * previously set in \p attributes. 235 * 236 * This function may be declared as `static` (i.e. without external 237 * linkage). This function may be provided as a function-like macro, 238 * but in this case it must evaluate each of its arguments exactly once. 239 * 240 * \param[out] attributes The attribute structure to write to. 241 * \param usage_flags The usage flags to write. 242 */ 243 static void psa_set_key_usage_flags(psa_key_attributes_t *attributes, 244 psa_key_usage_t usage_flags); 245 246 /** Retrieve the usage flags from key attributes. 247 * 248 * This function may be declared as `static` (i.e. without external 249 * linkage). This function may be provided as a function-like macro, 250 * but in this case it must evaluate its argument exactly once. 251 * 252 * \param[in] attributes The key attribute structure to query. 253 * 254 * \return The usage flags stored in the attribute structure. 255 */ 256 static psa_key_usage_t psa_get_key_usage_flags( 257 const psa_key_attributes_t *attributes); 258 259 /** Declare the permitted algorithm policy for a key. 260 * 261 * The permitted algorithm policy of a key encodes which algorithm or 262 * algorithms are permitted to be used with this key. The following 263 * algorithm policies are supported: 264 * - 0 does not allow any cryptographic operation with the key. The key 265 * may be used for non-cryptographic actions such as exporting (if 266 * permitted by the usage flags). 267 * - An algorithm value permits this particular algorithm. 268 * - An algorithm wildcard built from #PSA_ALG_ANY_HASH allows the specified 269 * signature scheme with any hash algorithm. 270 * - An algorithm built from #PSA_ALG_AT_LEAST_THIS_LENGTH_MAC allows 271 * any MAC algorithm from the same base class (e.g. CMAC) which 272 * generates/verifies a MAC length greater than or equal to the length 273 * encoded in the wildcard algorithm. 274 * - An algorithm built from #PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG 275 * allows any AEAD algorithm from the same base class (e.g. CCM) which 276 * generates/verifies a tag length greater than or equal to the length 277 * encoded in the wildcard algorithm. 278 * 279 * This function overwrites any algorithm policy 280 * previously set in \p attributes. 281 * 282 * This function may be declared as `static` (i.e. without external 283 * linkage). This function may be provided as a function-like macro, 284 * but in this case it must evaluate each of its arguments exactly once. 285 * 286 * \param[out] attributes The attribute structure to write to. 287 * \param alg The permitted algorithm policy to write. 288 */ 289 static void psa_set_key_algorithm(psa_key_attributes_t *attributes, 290 psa_algorithm_t alg); 291 292 293 /** Retrieve the algorithm policy from key attributes. 294 * 295 * This function may be declared as `static` (i.e. without external 296 * linkage). This function may be provided as a function-like macro, 297 * but in this case it must evaluate its argument exactly once. 298 * 299 * \param[in] attributes The key attribute structure to query. 300 * 301 * \return The algorithm stored in the attribute structure. 302 */ 303 static psa_algorithm_t psa_get_key_algorithm( 304 const psa_key_attributes_t *attributes); 305 306 /** Declare the type of a key. 307 * 308 * This function overwrites any key type 309 * previously set in \p attributes. 310 * 311 * This function may be declared as `static` (i.e. without external 312 * linkage). This function may be provided as a function-like macro, 313 * but in this case it must evaluate each of its arguments exactly once. 314 * 315 * \param[out] attributes The attribute structure to write to. 316 * \param type The key type to write. 317 * If this is 0, the key type in \p attributes 318 * becomes unspecified. 319 */ 320 static void psa_set_key_type(psa_key_attributes_t *attributes, 321 psa_key_type_t type); 322 323 324 /** Declare the size of a key. 325 * 326 * This function overwrites any key size previously set in \p attributes. 327 * 328 * This function may be declared as `static` (i.e. without external 329 * linkage). This function may be provided as a function-like macro, 330 * but in this case it must evaluate each of its arguments exactly once. 331 * 332 * \param[out] attributes The attribute structure to write to. 333 * \param bits The key size in bits. 334 * If this is 0, the key size in \p attributes 335 * becomes unspecified. Keys of size 0 are 336 * not supported. 337 */ 338 static void psa_set_key_bits(psa_key_attributes_t *attributes, 339 size_t bits); 340 341 /** Retrieve the key type from key attributes. 342 * 343 * This function may be declared as `static` (i.e. without external 344 * linkage). This function may be provided as a function-like macro, 345 * but in this case it must evaluate its argument exactly once. 346 * 347 * \param[in] attributes The key attribute structure to query. 348 * 349 * \return The key type stored in the attribute structure. 350 */ 351 static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes); 352 353 /** Retrieve the key size from key attributes. 354 * 355 * This function may be declared as `static` (i.e. without external 356 * linkage). This function may be provided as a function-like macro, 357 * but in this case it must evaluate its argument exactly once. 358 * 359 * \param[in] attributes The key attribute structure to query. 360 * 361 * \return The key size stored in the attribute structure, in bits. 362 */ 363 static size_t psa_get_key_bits(const psa_key_attributes_t *attributes); 364 365 /** Retrieve the attributes of a key. 366 * 367 * This function first resets the attribute structure as with 368 * psa_reset_key_attributes(). It then copies the attributes of 369 * the given key into the given attribute structure. 370 * 371 * \note This function may allocate memory or other resources. 372 * Once you have called this function on an attribute structure, 373 * you must call psa_reset_key_attributes() to free these resources. 374 * 375 * \param[in] key Identifier of the key to query. 376 * \param[in,out] attributes On success, the attributes of the key. 377 * On failure, equivalent to a 378 * freshly-initialized structure. 379 * 380 * \retval #PSA_SUCCESS \emptydescription 381 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 382 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 383 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 384 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 385 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 386 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 387 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 388 * \retval #PSA_ERROR_BAD_STATE 389 * The library has not been previously initialized by psa_crypto_init(). 390 * It is implementation-dependent whether a failure to initialize 391 * results in this error code. 392 */ 393 psa_status_t psa_get_key_attributes(mbedtls_svc_key_id_t key, 394 psa_key_attributes_t *attributes); 395 396 /** Reset a key attribute structure to a freshly initialized state. 397 * 398 * You must initialize the attribute structure as described in the 399 * documentation of the type #psa_key_attributes_t before calling this 400 * function. Once the structure has been initialized, you may call this 401 * function at any time. 402 * 403 * This function frees any auxiliary resources that the structure 404 * may contain. 405 * 406 * \param[in,out] attributes The attribute structure to reset. 407 */ 408 void psa_reset_key_attributes(psa_key_attributes_t *attributes); 409 410 /**@}*/ 411 412 /** \defgroup key_management Key management 413 * @{ 414 */ 415 416 /** Remove non-essential copies of key material from memory. 417 * 418 * If the key identifier designates a volatile key, this functions does not do 419 * anything and returns successfully. 420 * 421 * If the key identifier designates a persistent key, then this function will 422 * free all resources associated with the key in volatile memory. The key 423 * data in persistent storage is not affected and the key can still be used. 424 * 425 * \param key Identifier of the key to purge. 426 * 427 * \retval #PSA_SUCCESS 428 * The key material will have been removed from memory if it is not 429 * currently required. 430 * \retval #PSA_ERROR_INVALID_ARGUMENT 431 * \p key is not a valid key identifier. 432 * \retval #PSA_ERROR_BAD_STATE 433 * The library has not been previously initialized by psa_crypto_init(). 434 * It is implementation-dependent whether a failure to initialize 435 * results in this error code. 436 */ 437 psa_status_t psa_purge_key(mbedtls_svc_key_id_t key); 438 439 /** Make a copy of a key. 440 * 441 * Copy key material from one location to another. 442 * 443 * This function is primarily useful to copy a key from one location 444 * to another, since it populates a key using the material from 445 * another key which may have a different lifetime. 446 * 447 * This function may be used to share a key with a different party, 448 * subject to implementation-defined restrictions on key sharing. 449 * 450 * The policy on the source key must have the usage flag 451 * #PSA_KEY_USAGE_COPY set. 452 * This flag is sufficient to permit the copy if the key has the lifetime 453 * #PSA_KEY_LIFETIME_VOLATILE or #PSA_KEY_LIFETIME_PERSISTENT. 454 * Some secure elements do not provide a way to copy a key without 455 * making it extractable from the secure element. If a key is located 456 * in such a secure element, then the key must have both usage flags 457 * #PSA_KEY_USAGE_COPY and #PSA_KEY_USAGE_EXPORT in order to make 458 * a copy of the key outside the secure element. 459 * 460 * The resulting key may only be used in a way that conforms to 461 * both the policy of the original key and the policy specified in 462 * the \p attributes parameter: 463 * - The usage flags on the resulting key are the bitwise-and of the 464 * usage flags on the source policy and the usage flags in \p attributes. 465 * - If both allow the same algorithm or wildcard-based 466 * algorithm policy, the resulting key has the same algorithm policy. 467 * - If either of the policies allows an algorithm and the other policy 468 * allows a wildcard-based algorithm policy that includes this algorithm, 469 * the resulting key allows the same algorithm. 470 * - If the policies do not allow any algorithm in common, this function 471 * fails with the status #PSA_ERROR_INVALID_ARGUMENT. 472 * 473 * The effect of this function on implementation-defined attributes is 474 * implementation-defined. 475 * 476 * \param source_key The key to copy. It must allow the usage 477 * #PSA_KEY_USAGE_COPY. If a private or secret key is 478 * being copied outside of a secure element it must 479 * also allow #PSA_KEY_USAGE_EXPORT. 480 * \param[in] attributes The attributes for the new key. 481 * They are used as follows: 482 * - The key type and size may be 0. If either is 483 * nonzero, it must match the corresponding 484 * attribute of the source key. 485 * - The key location (the lifetime and, for 486 * persistent keys, the key identifier) is 487 * used directly. 488 * - The policy constraints (usage flags and 489 * algorithm policy) are combined from 490 * the source key and \p attributes so that 491 * both sets of restrictions apply, as 492 * described in the documentation of this function. 493 * \param[out] target_key On success, an identifier for the newly created 494 * key. For persistent keys, this is the key 495 * identifier defined in \p attributes. 496 * \c 0 on failure. 497 * 498 * \retval #PSA_SUCCESS \emptydescription 499 * \retval #PSA_ERROR_INVALID_HANDLE 500 * \p source_key is invalid. 501 * \retval #PSA_ERROR_ALREADY_EXISTS 502 * This is an attempt to create a persistent key, and there is 503 * already a persistent key with the given identifier. 504 * \retval #PSA_ERROR_INVALID_ARGUMENT 505 * The lifetime or identifier in \p attributes are invalid, or 506 * the policy constraints on the source and specified in 507 * \p attributes are incompatible, or 508 * \p attributes specifies a key type or key size 509 * which does not match the attributes of the source key. 510 * \retval #PSA_ERROR_NOT_PERMITTED 511 * The source key does not have the #PSA_KEY_USAGE_COPY usage flag, or 512 * the source key is not exportable and its lifetime does not 513 * allow copying it to the target's lifetime. 514 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 515 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription 516 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 517 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 518 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 519 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 520 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 521 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 522 * \retval #PSA_ERROR_BAD_STATE 523 * The library has not been previously initialized by psa_crypto_init(). 524 * It is implementation-dependent whether a failure to initialize 525 * results in this error code. 526 */ 527 psa_status_t psa_copy_key(mbedtls_svc_key_id_t source_key, 528 const psa_key_attributes_t *attributes, 529 mbedtls_svc_key_id_t *target_key); 530 531 532 /** 533 * \brief Destroy a key. 534 * 535 * This function destroys a key from both volatile 536 * memory and, if applicable, non-volatile storage. Implementations shall 537 * make a best effort to ensure that the key material cannot be recovered. 538 * 539 * This function also erases any metadata such as policies and frees 540 * resources associated with the key. 541 * 542 * If a key is currently in use in a multipart operation, then destroying the 543 * key will cause the multipart operation to fail. 544 * 545 * \warning We can only guarantee that the the key material will 546 * eventually be wiped from memory. With threading enabled 547 * and during concurrent execution, copies of the key material may 548 * still exist until all threads have finished using the key. 549 * 550 * \param key Identifier of the key to erase. If this is \c 0, do nothing and 551 * return #PSA_SUCCESS. 552 * 553 * \retval #PSA_SUCCESS 554 * \p key was a valid identifier and the key material that it 555 * referred to has been erased. Alternatively, \p key is \c 0. 556 * \retval #PSA_ERROR_NOT_PERMITTED 557 * The key cannot be erased because it is 558 * read-only, either due to a policy or due to physical restrictions. 559 * \retval #PSA_ERROR_INVALID_HANDLE 560 * \p key is not a valid identifier nor \c 0. 561 * \retval #PSA_ERROR_COMMUNICATION_FAILURE 562 * There was a failure in communication with the cryptoprocessor. 563 * The key material may still be present in the cryptoprocessor. 564 * \retval #PSA_ERROR_DATA_INVALID 565 * This error is typically a result of either storage corruption on a 566 * cleartext storage backend, or an attempt to read data that was 567 * written by an incompatible version of the library. 568 * \retval #PSA_ERROR_STORAGE_FAILURE 569 * The storage is corrupted. Implementations shall make a best effort 570 * to erase key material even in this stage, however applications 571 * should be aware that it may be impossible to guarantee that the 572 * key material is not recoverable in such cases. 573 * \retval #PSA_ERROR_CORRUPTION_DETECTED 574 * An unexpected condition which is not a storage corruption or 575 * a communication failure occurred. The cryptoprocessor may have 576 * been compromised. 577 * \retval #PSA_ERROR_BAD_STATE 578 * The library has not been previously initialized by psa_crypto_init(). 579 * It is implementation-dependent whether a failure to initialize 580 * results in this error code. 581 */ 582 psa_status_t psa_destroy_key(mbedtls_svc_key_id_t key); 583 584 /**@}*/ 585 586 /** \defgroup import_export Key import and export 587 * @{ 588 */ 589 590 /** 591 * \brief Import a key in binary format. 592 * 593 * This function supports any output from psa_export_key(). Refer to the 594 * documentation of psa_export_public_key() for the format of public keys 595 * and to the documentation of psa_export_key() for the format for 596 * other key types. 597 * 598 * The key data determines the key size. The attributes may optionally 599 * specify a key size; in this case it must match the size determined 600 * from the key data. A key size of 0 in \p attributes indicates that 601 * the key size is solely determined by the key data. 602 * 603 * Implementations must reject an attempt to import a key of size 0. 604 * 605 * This specification supports a single format for each key type. 606 * Implementations may support other formats as long as the standard 607 * format is supported. Implementations that support other formats 608 * should ensure that the formats are clearly unambiguous so as to 609 * minimize the risk that an invalid input is accidentally interpreted 610 * according to a different format. 611 * 612 * \param[in] attributes The attributes for the new key. 613 * The key size is always determined from the 614 * \p data buffer. 615 * If the key size in \p attributes is nonzero, 616 * it must be equal to the size from \p data. 617 * \param[out] key On success, an identifier to the newly created key. 618 * For persistent keys, this is the key identifier 619 * defined in \p attributes. 620 * \c 0 on failure. 621 * \param[in] data Buffer containing the key data. The content of this 622 * buffer is interpreted according to the type declared 623 * in \p attributes. 624 * All implementations must support at least the format 625 * described in the documentation 626 * of psa_export_key() or psa_export_public_key() for 627 * the chosen type. Implementations may allow other 628 * formats, but should be conservative: implementations 629 * should err on the side of rejecting content if it 630 * may be erroneous (e.g. wrong type or truncated data). 631 * \param data_length Size of the \p data buffer in bytes. 632 * 633 * \retval #PSA_SUCCESS 634 * Success. 635 * If the key is persistent, the key material and the key's metadata 636 * have been saved to persistent storage. 637 * \retval #PSA_ERROR_ALREADY_EXISTS 638 * This is an attempt to create a persistent key, and there is 639 * already a persistent key with the given identifier. 640 * \retval #PSA_ERROR_NOT_SUPPORTED 641 * The key type or key size is not supported, either by the 642 * implementation in general or in this particular persistent location. 643 * \retval #PSA_ERROR_INVALID_ARGUMENT 644 * The key attributes, as a whole, are invalid, or 645 * the key data is not correctly formatted, or 646 * the size in \p attributes is nonzero and does not match the size 647 * of the key data. 648 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 649 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription 650 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 651 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 652 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 653 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 654 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 655 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 656 * \retval #PSA_ERROR_BAD_STATE 657 * The library has not been previously initialized by psa_crypto_init(). 658 * It is implementation-dependent whether a failure to initialize 659 * results in this error code. 660 */ 661 psa_status_t psa_import_key(const psa_key_attributes_t *attributes, 662 const uint8_t *data, 663 size_t data_length, 664 mbedtls_svc_key_id_t *key); 665 666 667 668 /** 669 * \brief Export a key in binary format. 670 * 671 * The output of this function can be passed to psa_import_key() to 672 * create an equivalent object. 673 * 674 * If the implementation of psa_import_key() supports other formats 675 * beyond the format specified here, the output from psa_export_key() 676 * must use the representation specified here, not the original 677 * representation. 678 * 679 * For standard key types, the output format is as follows: 680 * 681 * - For symmetric keys (including MAC keys), the format is the 682 * raw bytes of the key. 683 * - For DES, the key data consists of 8 bytes. The parity bits must be 684 * correct. 685 * - For Triple-DES, the format is the concatenation of the 686 * two or three DES keys. 687 * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEY_PAIR), the format 688 * is the non-encrypted DER encoding of the representation defined by 689 * PKCS\#1 (RFC 8017) as `RSAPrivateKey`, version 0. 690 * ``` 691 * RSAPrivateKey ::= SEQUENCE { 692 * version INTEGER, -- must be 0 693 * modulus INTEGER, -- n 694 * publicExponent INTEGER, -- e 695 * privateExponent INTEGER, -- d 696 * prime1 INTEGER, -- p 697 * prime2 INTEGER, -- q 698 * exponent1 INTEGER, -- d mod (p-1) 699 * exponent2 INTEGER, -- d mod (q-1) 700 * coefficient INTEGER, -- (inverse of q) mod p 701 * } 702 * ``` 703 * - For elliptic curve key pairs (key types for which 704 * #PSA_KEY_TYPE_IS_ECC_KEY_PAIR is true), the format is 705 * a representation of the private value as a `ceiling(m/8)`-byte string 706 * where `m` is the bit size associated with the curve, i.e. the bit size 707 * of the order of the curve's coordinate field. This byte string is 708 * in little-endian order for Montgomery curves (curve types 709 * `PSA_ECC_FAMILY_CURVEXXX`), and in big-endian order for Weierstrass 710 * curves (curve types `PSA_ECC_FAMILY_SECTXXX`, `PSA_ECC_FAMILY_SECPXXX` 711 * and `PSA_ECC_FAMILY_BRAINPOOL_PXXX`). 712 * For Weierstrass curves, this is the content of the `privateKey` field of 713 * the `ECPrivateKey` format defined by RFC 5915. For Montgomery curves, 714 * the format is defined by RFC 7748, and output is masked according to §5. 715 * For twisted Edwards curves, the private key is as defined by RFC 8032 716 * (a 32-byte string for Edwards25519, a 57-byte string for Edwards448). 717 * - For Diffie-Hellman key exchange key pairs (key types for which 718 * #PSA_KEY_TYPE_IS_DH_KEY_PAIR is true), the 719 * format is the representation of the private key `x` as a big-endian byte 720 * string. The length of the byte string is the private key size in bytes 721 * (leading zeroes are not stripped). 722 * - For public keys (key types for which #PSA_KEY_TYPE_IS_PUBLIC_KEY is 723 * true), the format is the same as for psa_export_public_key(). 724 * 725 * The policy on the key must have the usage flag #PSA_KEY_USAGE_EXPORT set. 726 * 727 * \param key Identifier of the key to export. It must allow the 728 * usage #PSA_KEY_USAGE_EXPORT, unless it is a public 729 * key. 730 * \param[out] data Buffer where the key data is to be written. 731 * \param data_size Size of the \p data buffer in bytes. 732 * \param[out] data_length On success, the number of bytes 733 * that make up the key data. 734 * 735 * \retval #PSA_SUCCESS \emptydescription 736 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 737 * \retval #PSA_ERROR_NOT_PERMITTED 738 * The key does not have the #PSA_KEY_USAGE_EXPORT flag. 739 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 740 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 741 * The size of the \p data buffer is too small. You can determine a 742 * sufficient buffer size by calling 743 * #PSA_EXPORT_KEY_OUTPUT_SIZE(\c type, \c bits) 744 * where \c type is the key type 745 * and \c bits is the key size in bits. 746 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 747 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 748 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 749 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 750 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 751 * \retval #PSA_ERROR_BAD_STATE 752 * The library has not been previously initialized by psa_crypto_init(). 753 * It is implementation-dependent whether a failure to initialize 754 * results in this error code. 755 */ 756 psa_status_t psa_export_key(mbedtls_svc_key_id_t key, 757 uint8_t *data, 758 size_t data_size, 759 size_t *data_length); 760 761 /** 762 * \brief Export a public key or the public part of a key pair in binary format. 763 * 764 * The output of this function can be passed to psa_import_key() to 765 * create an object that is equivalent to the public key. 766 * 767 * This specification supports a single format for each key type. 768 * Implementations may support other formats as long as the standard 769 * format is supported. Implementations that support other formats 770 * should ensure that the formats are clearly unambiguous so as to 771 * minimize the risk that an invalid input is accidentally interpreted 772 * according to a different format. 773 * 774 * For standard key types, the output format is as follows: 775 * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the DER encoding of 776 * the representation defined by RFC 3279 §2.3.1 as `RSAPublicKey`. 777 * ``` 778 * RSAPublicKey ::= SEQUENCE { 779 * modulus INTEGER, -- n 780 * publicExponent INTEGER } -- e 781 * ``` 782 * - For elliptic curve keys on a twisted Edwards curve (key types for which 783 * #PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true and #PSA_KEY_TYPE_ECC_GET_FAMILY 784 * returns #PSA_ECC_FAMILY_TWISTED_EDWARDS), the public key is as defined 785 * by RFC 8032 786 * (a 32-byte string for Edwards25519, a 57-byte string for Edwards448). 787 * - For other elliptic curve public keys (key types for which 788 * #PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true), the format is the uncompressed 789 * representation defined by SEC1 §2.3.3 as the content of an ECPoint. 790 * Let `m` be the bit size associated with the curve, i.e. the bit size of 791 * `q` for a curve over `F_q`. The representation consists of: 792 * - The byte 0x04; 793 * - `x_P` as a `ceiling(m/8)`-byte string, big-endian; 794 * - `y_P` as a `ceiling(m/8)`-byte string, big-endian. 795 * - For Diffie-Hellman key exchange public keys (key types for which 796 * #PSA_KEY_TYPE_IS_DH_PUBLIC_KEY is true), 797 * the format is the representation of the public key `y = g^x mod p` as a 798 * big-endian byte string. The length of the byte string is the length of the 799 * base prime `p` in bytes. 800 * 801 * Exporting a public key object or the public part of a key pair is 802 * always permitted, regardless of the key's usage flags. 803 * 804 * \param key Identifier of the key to export. 805 * \param[out] data Buffer where the key data is to be written. 806 * \param data_size Size of the \p data buffer in bytes. 807 * \param[out] data_length On success, the number of bytes 808 * that make up the key data. 809 * 810 * \retval #PSA_SUCCESS \emptydescription 811 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 812 * \retval #PSA_ERROR_INVALID_ARGUMENT 813 * The key is neither a public key nor a key pair. 814 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 815 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 816 * The size of the \p data buffer is too small. You can determine a 817 * sufficient buffer size by calling 818 * #PSA_EXPORT_KEY_OUTPUT_SIZE(#PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(\c type), \c bits) 819 * where \c type is the key type 820 * and \c bits is the key size in bits. 821 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 822 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 823 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 824 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 825 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 826 * \retval #PSA_ERROR_BAD_STATE 827 * The library has not been previously initialized by psa_crypto_init(). 828 * It is implementation-dependent whether a failure to initialize 829 * results in this error code. 830 */ 831 psa_status_t psa_export_public_key(mbedtls_svc_key_id_t key, 832 uint8_t *data, 833 size_t data_size, 834 size_t *data_length); 835 836 837 838 /**@}*/ 839 840 /** \defgroup hash Message digests 841 * @{ 842 */ 843 844 /** Calculate the hash (digest) of a message. 845 * 846 * \note To verify the hash of a message against an 847 * expected value, use psa_hash_compare() instead. 848 * 849 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value 850 * such that #PSA_ALG_IS_HASH(\p alg) is true). 851 * \param[in] input Buffer containing the message to hash. 852 * \param input_length Size of the \p input buffer in bytes. 853 * \param[out] hash Buffer where the hash is to be written. 854 * \param hash_size Size of the \p hash buffer in bytes. 855 * \param[out] hash_length On success, the number of bytes 856 * that make up the hash value. This is always 857 * #PSA_HASH_LENGTH(\p alg). 858 * 859 * \retval #PSA_SUCCESS 860 * Success. 861 * \retval #PSA_ERROR_NOT_SUPPORTED 862 * \p alg is not supported or is not a hash algorithm. 863 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 864 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 865 * \p hash_size is too small 866 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 867 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 868 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 869 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 870 * \retval #PSA_ERROR_BAD_STATE 871 * The library has not been previously initialized by psa_crypto_init(). 872 * It is implementation-dependent whether a failure to initialize 873 * results in this error code. 874 */ 875 psa_status_t psa_hash_compute(psa_algorithm_t alg, 876 const uint8_t *input, 877 size_t input_length, 878 uint8_t *hash, 879 size_t hash_size, 880 size_t *hash_length); 881 882 /** Calculate the hash (digest) of a message and compare it with a 883 * reference value. 884 * 885 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value 886 * such that #PSA_ALG_IS_HASH(\p alg) is true). 887 * \param[in] input Buffer containing the message to hash. 888 * \param input_length Size of the \p input buffer in bytes. 889 * \param[in] hash Buffer containing the expected hash value. 890 * \param hash_length Size of the \p hash buffer in bytes. 891 * 892 * \retval #PSA_SUCCESS 893 * The expected hash is identical to the actual hash of the input. 894 * \retval #PSA_ERROR_INVALID_SIGNATURE 895 * The hash of the message was calculated successfully, but it 896 * differs from the expected hash. 897 * \retval #PSA_ERROR_NOT_SUPPORTED 898 * \p alg is not supported or is not a hash algorithm. 899 * \retval #PSA_ERROR_INVALID_ARGUMENT 900 * \p input_length or \p hash_length do not match the hash size for \p alg 901 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 902 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 903 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 904 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 905 * \retval #PSA_ERROR_BAD_STATE 906 * The library has not been previously initialized by psa_crypto_init(). 907 * It is implementation-dependent whether a failure to initialize 908 * results in this error code. 909 */ 910 psa_status_t psa_hash_compare(psa_algorithm_t alg, 911 const uint8_t *input, 912 size_t input_length, 913 const uint8_t *hash, 914 size_t hash_length); 915 916 /** The type of the state data structure for multipart hash operations. 917 * 918 * Before calling any function on a hash operation object, the application must 919 * initialize it by any of the following means: 920 * - Set the structure to all-bits-zero, for example: 921 * \code 922 * psa_hash_operation_t operation; 923 * memset(&operation, 0, sizeof(operation)); 924 * \endcode 925 * - Initialize the structure to logical zero values, for example: 926 * \code 927 * psa_hash_operation_t operation = {0}; 928 * \endcode 929 * - Initialize the structure to the initializer #PSA_HASH_OPERATION_INIT, 930 * for example: 931 * \code 932 * psa_hash_operation_t operation = PSA_HASH_OPERATION_INIT; 933 * \endcode 934 * - Assign the result of the function psa_hash_operation_init() 935 * to the structure, for example: 936 * \code 937 * psa_hash_operation_t operation; 938 * operation = psa_hash_operation_init(); 939 * \endcode 940 * 941 * This is an implementation-defined \c struct. Applications should not 942 * make any assumptions about the content of this structure. 943 * Implementation details can change in future versions without notice. */ 944 typedef struct psa_hash_operation_s psa_hash_operation_t; 945 946 /** \def PSA_HASH_OPERATION_INIT 947 * 948 * This macro returns a suitable initializer for a hash operation object 949 * of type #psa_hash_operation_t. 950 */ 951 952 /** Return an initial value for a hash operation object. 953 */ 954 static psa_hash_operation_t psa_hash_operation_init(void); 955 956 /** Set up a multipart hash operation. 957 * 958 * The sequence of operations to calculate a hash (message digest) 959 * is as follows: 960 * -# Allocate an operation object which will be passed to all the functions 961 * listed here. 962 * -# Initialize the operation object with one of the methods described in the 963 * documentation for #psa_hash_operation_t, e.g. #PSA_HASH_OPERATION_INIT. 964 * -# Call psa_hash_setup() to specify the algorithm. 965 * -# Call psa_hash_update() zero, one or more times, passing a fragment 966 * of the message each time. The hash that is calculated is the hash 967 * of the concatenation of these messages in order. 968 * -# To calculate the hash, call psa_hash_finish(). 969 * To compare the hash with an expected value, call psa_hash_verify(). 970 * 971 * If an error occurs at any step after a call to psa_hash_setup(), the 972 * operation will need to be reset by a call to psa_hash_abort(). The 973 * application may call psa_hash_abort() at any time after the operation 974 * has been initialized. 975 * 976 * After a successful call to psa_hash_setup(), the application must 977 * eventually terminate the operation. The following events terminate an 978 * operation: 979 * - A successful call to psa_hash_finish() or psa_hash_verify(). 980 * - A call to psa_hash_abort(). 981 * 982 * \param[in,out] operation The operation object to set up. It must have 983 * been initialized as per the documentation for 984 * #psa_hash_operation_t and not yet in use. 985 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value 986 * such that #PSA_ALG_IS_HASH(\p alg) is true). 987 * 988 * \retval #PSA_SUCCESS 989 * Success. 990 * \retval #PSA_ERROR_NOT_SUPPORTED 991 * \p alg is not a supported hash algorithm. 992 * \retval #PSA_ERROR_INVALID_ARGUMENT 993 * \p alg is not a hash algorithm. 994 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 995 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 996 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 997 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 998 * \retval #PSA_ERROR_BAD_STATE 999 * The operation state is not valid (it must be inactive), or 1000 * the library has not been previously initialized by psa_crypto_init(). 1001 * It is implementation-dependent whether a failure to initialize 1002 * results in this error code. 1003 */ 1004 psa_status_t psa_hash_setup(psa_hash_operation_t *operation, 1005 psa_algorithm_t alg); 1006 1007 /** Add a message fragment to a multipart hash operation. 1008 * 1009 * The application must call psa_hash_setup() before calling this function. 1010 * 1011 * If this function returns an error status, the operation enters an error 1012 * state and must be aborted by calling psa_hash_abort(). 1013 * 1014 * \param[in,out] operation Active hash operation. 1015 * \param[in] input Buffer containing the message fragment to hash. 1016 * \param input_length Size of the \p input buffer in bytes. 1017 * 1018 * \retval #PSA_SUCCESS 1019 * Success. 1020 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1021 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1022 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1023 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1024 * \retval #PSA_ERROR_BAD_STATE 1025 * The operation state is not valid (it must be active), or 1026 * the library has not been previously initialized by psa_crypto_init(). 1027 * It is implementation-dependent whether a failure to initialize 1028 * results in this error code. 1029 */ 1030 psa_status_t psa_hash_update(psa_hash_operation_t *operation, 1031 const uint8_t *input, 1032 size_t input_length); 1033 1034 /** Finish the calculation of the hash of a message. 1035 * 1036 * The application must call psa_hash_setup() before calling this function. 1037 * This function calculates the hash of the message formed by concatenating 1038 * the inputs passed to preceding calls to psa_hash_update(). 1039 * 1040 * When this function returns successfully, the operation becomes inactive. 1041 * If this function returns an error status, the operation enters an error 1042 * state and must be aborted by calling psa_hash_abort(). 1043 * 1044 * \warning Applications should not call this function if they expect 1045 * a specific value for the hash. Call psa_hash_verify() instead. 1046 * Beware that comparing integrity or authenticity data such as 1047 * hash values with a function such as \c memcmp is risky 1048 * because the time taken by the comparison may leak information 1049 * about the hashed data which could allow an attacker to guess 1050 * a valid hash and thereby bypass security controls. 1051 * 1052 * \param[in,out] operation Active hash operation. 1053 * \param[out] hash Buffer where the hash is to be written. 1054 * \param hash_size Size of the \p hash buffer in bytes. 1055 * \param[out] hash_length On success, the number of bytes 1056 * that make up the hash value. This is always 1057 * #PSA_HASH_LENGTH(\c alg) where \c alg is the 1058 * hash algorithm that is calculated. 1059 * 1060 * \retval #PSA_SUCCESS 1061 * Success. 1062 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 1063 * The size of the \p hash buffer is too small. You can determine a 1064 * sufficient buffer size by calling #PSA_HASH_LENGTH(\c alg) 1065 * where \c alg is the hash algorithm that is calculated. 1066 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1067 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1068 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1069 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1070 * \retval #PSA_ERROR_BAD_STATE 1071 * The operation state is not valid (it must be active), or 1072 * the library has not been previously initialized by psa_crypto_init(). 1073 * It is implementation-dependent whether a failure to initialize 1074 * results in this error code. 1075 */ 1076 psa_status_t psa_hash_finish(psa_hash_operation_t *operation, 1077 uint8_t *hash, 1078 size_t hash_size, 1079 size_t *hash_length); 1080 1081 /** Finish the calculation of the hash of a message and compare it with 1082 * an expected value. 1083 * 1084 * The application must call psa_hash_setup() before calling this function. 1085 * This function calculates the hash of the message formed by concatenating 1086 * the inputs passed to preceding calls to psa_hash_update(). It then 1087 * compares the calculated hash with the expected hash passed as a 1088 * parameter to this function. 1089 * 1090 * When this function returns successfully, the operation becomes inactive. 1091 * If this function returns an error status, the operation enters an error 1092 * state and must be aborted by calling psa_hash_abort(). 1093 * 1094 * \note Implementations shall make the best effort to ensure that the 1095 * comparison between the actual hash and the expected hash is performed 1096 * in constant time. 1097 * 1098 * \param[in,out] operation Active hash operation. 1099 * \param[in] hash Buffer containing the expected hash value. 1100 * \param hash_length Size of the \p hash buffer in bytes. 1101 * 1102 * \retval #PSA_SUCCESS 1103 * The expected hash is identical to the actual hash of the message. 1104 * \retval #PSA_ERROR_INVALID_SIGNATURE 1105 * The hash of the message was calculated successfully, but it 1106 * differs from the expected hash. 1107 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1108 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1109 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1110 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1111 * \retval #PSA_ERROR_BAD_STATE 1112 * The operation state is not valid (it must be active), or 1113 * the library has not been previously initialized by psa_crypto_init(). 1114 * It is implementation-dependent whether a failure to initialize 1115 * results in this error code. 1116 */ 1117 psa_status_t psa_hash_verify(psa_hash_operation_t *operation, 1118 const uint8_t *hash, 1119 size_t hash_length); 1120 1121 /** Abort a hash operation. 1122 * 1123 * Aborting an operation frees all associated resources except for the 1124 * \p operation structure itself. Once aborted, the operation object 1125 * can be reused for another operation by calling 1126 * psa_hash_setup() again. 1127 * 1128 * You may call this function any time after the operation object has 1129 * been initialized by one of the methods described in #psa_hash_operation_t. 1130 * 1131 * In particular, calling psa_hash_abort() after the operation has been 1132 * terminated by a call to psa_hash_abort(), psa_hash_finish() or 1133 * psa_hash_verify() is safe and has no effect. 1134 * 1135 * \param[in,out] operation Initialized hash operation. 1136 * 1137 * \retval #PSA_SUCCESS \emptydescription 1138 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1139 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1140 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1141 * \retval #PSA_ERROR_BAD_STATE 1142 * The library has not been previously initialized by psa_crypto_init(). 1143 * It is implementation-dependent whether a failure to initialize 1144 * results in this error code. 1145 */ 1146 psa_status_t psa_hash_abort(psa_hash_operation_t *operation); 1147 1148 /** Clone a hash operation. 1149 * 1150 * This function copies the state of an ongoing hash operation to 1151 * a new operation object. In other words, this function is equivalent 1152 * to calling psa_hash_setup() on \p target_operation with the same 1153 * algorithm that \p source_operation was set up for, then 1154 * psa_hash_update() on \p target_operation with the same input that 1155 * that was passed to \p source_operation. After this function returns, the 1156 * two objects are independent, i.e. subsequent calls involving one of 1157 * the objects do not affect the other object. 1158 * 1159 * \param[in] source_operation The active hash operation to clone. 1160 * \param[in,out] target_operation The operation object to set up. 1161 * It must be initialized but not active. 1162 * 1163 * \retval #PSA_SUCCESS \emptydescription 1164 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1165 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1166 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1167 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1168 * \retval #PSA_ERROR_BAD_STATE 1169 * The \p source_operation state is not valid (it must be active), or 1170 * the \p target_operation state is not valid (it must be inactive), or 1171 * the library has not been previously initialized by psa_crypto_init(). 1172 * It is implementation-dependent whether a failure to initialize 1173 * results in this error code. 1174 */ 1175 psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation, 1176 psa_hash_operation_t *target_operation); 1177 1178 /**@}*/ 1179 1180 /** \defgroup MAC Message authentication codes 1181 * @{ 1182 */ 1183 1184 /** Calculate the MAC (message authentication code) of a message. 1185 * 1186 * \note To verify the MAC of a message against an 1187 * expected value, use psa_mac_verify() instead. 1188 * Beware that comparing integrity or authenticity data such as 1189 * MAC values with a function such as \c memcmp is risky 1190 * because the time taken by the comparison may leak information 1191 * about the MAC value which could allow an attacker to guess 1192 * a valid MAC and thereby bypass security controls. 1193 * 1194 * \param key Identifier of the key to use for the operation. It 1195 * must allow the usage PSA_KEY_USAGE_SIGN_MESSAGE. 1196 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value 1197 * such that #PSA_ALG_IS_MAC(\p alg) is true). 1198 * \param[in] input Buffer containing the input message. 1199 * \param input_length Size of the \p input buffer in bytes. 1200 * \param[out] mac Buffer where the MAC value is to be written. 1201 * \param mac_size Size of the \p mac buffer in bytes. 1202 * \param[out] mac_length On success, the number of bytes 1203 * that make up the MAC value. 1204 * 1205 * \retval #PSA_SUCCESS 1206 * Success. 1207 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 1208 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 1209 * \retval #PSA_ERROR_INVALID_ARGUMENT 1210 * \p key is not compatible with \p alg. 1211 * \retval #PSA_ERROR_NOT_SUPPORTED 1212 * \p alg is not supported or is not a MAC algorithm. 1213 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 1214 * \p mac_size is too small 1215 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1216 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1217 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1218 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1219 * \retval #PSA_ERROR_STORAGE_FAILURE 1220 * The key could not be retrieved from storage. 1221 * \retval #PSA_ERROR_BAD_STATE 1222 * The library has not been previously initialized by psa_crypto_init(). 1223 * It is implementation-dependent whether a failure to initialize 1224 * results in this error code. 1225 */ 1226 psa_status_t psa_mac_compute(mbedtls_svc_key_id_t key, 1227 psa_algorithm_t alg, 1228 const uint8_t *input, 1229 size_t input_length, 1230 uint8_t *mac, 1231 size_t mac_size, 1232 size_t *mac_length); 1233 1234 /** Calculate the MAC of a message and compare it with a reference value. 1235 * 1236 * \param key Identifier of the key to use for the operation. It 1237 * must allow the usage PSA_KEY_USAGE_VERIFY_MESSAGE. 1238 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value 1239 * such that #PSA_ALG_IS_MAC(\p alg) is true). 1240 * \param[in] input Buffer containing the input message. 1241 * \param input_length Size of the \p input buffer in bytes. 1242 * \param[in] mac Buffer containing the expected MAC value. 1243 * \param mac_length Size of the \p mac buffer in bytes. 1244 * 1245 * \retval #PSA_SUCCESS 1246 * The expected MAC is identical to the actual MAC of the input. 1247 * \retval #PSA_ERROR_INVALID_SIGNATURE 1248 * The MAC of the message was calculated successfully, but it 1249 * differs from the expected value. 1250 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 1251 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 1252 * \retval #PSA_ERROR_INVALID_ARGUMENT 1253 * \p key is not compatible with \p alg. 1254 * \retval #PSA_ERROR_NOT_SUPPORTED 1255 * \p alg is not supported or is not a MAC algorithm. 1256 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1257 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1258 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1259 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1260 * \retval #PSA_ERROR_STORAGE_FAILURE 1261 * The key could not be retrieved from storage. 1262 * \retval #PSA_ERROR_BAD_STATE 1263 * The library has not been previously initialized by psa_crypto_init(). 1264 * It is implementation-dependent whether a failure to initialize 1265 * results in this error code. 1266 */ 1267 psa_status_t psa_mac_verify(mbedtls_svc_key_id_t key, 1268 psa_algorithm_t alg, 1269 const uint8_t *input, 1270 size_t input_length, 1271 const uint8_t *mac, 1272 size_t mac_length); 1273 1274 /** The type of the state data structure for multipart MAC operations. 1275 * 1276 * Before calling any function on a MAC operation object, the application must 1277 * initialize it by any of the following means: 1278 * - Set the structure to all-bits-zero, for example: 1279 * \code 1280 * psa_mac_operation_t operation; 1281 * memset(&operation, 0, sizeof(operation)); 1282 * \endcode 1283 * - Initialize the structure to logical zero values, for example: 1284 * \code 1285 * psa_mac_operation_t operation = {0}; 1286 * \endcode 1287 * - Initialize the structure to the initializer #PSA_MAC_OPERATION_INIT, 1288 * for example: 1289 * \code 1290 * psa_mac_operation_t operation = PSA_MAC_OPERATION_INIT; 1291 * \endcode 1292 * - Assign the result of the function psa_mac_operation_init() 1293 * to the structure, for example: 1294 * \code 1295 * psa_mac_operation_t operation; 1296 * operation = psa_mac_operation_init(); 1297 * \endcode 1298 * 1299 * 1300 * This is an implementation-defined \c struct. Applications should not 1301 * make any assumptions about the content of this structure. 1302 * Implementation details can change in future versions without notice. */ 1303 typedef struct psa_mac_operation_s psa_mac_operation_t; 1304 1305 /** \def PSA_MAC_OPERATION_INIT 1306 * 1307 * This macro returns a suitable initializer for a MAC operation object of type 1308 * #psa_mac_operation_t. 1309 */ 1310 1311 /** Return an initial value for a MAC operation object. 1312 */ 1313 static psa_mac_operation_t psa_mac_operation_init(void); 1314 1315 /** Set up a multipart MAC calculation operation. 1316 * 1317 * This function sets up the calculation of the MAC 1318 * (message authentication code) of a byte string. 1319 * To verify the MAC of a message against an 1320 * expected value, use psa_mac_verify_setup() instead. 1321 * 1322 * The sequence of operations to calculate a MAC is as follows: 1323 * -# Allocate an operation object which will be passed to all the functions 1324 * listed here. 1325 * -# Initialize the operation object with one of the methods described in the 1326 * documentation for #psa_mac_operation_t, e.g. #PSA_MAC_OPERATION_INIT. 1327 * -# Call psa_mac_sign_setup() to specify the algorithm and key. 1328 * -# Call psa_mac_update() zero, one or more times, passing a fragment 1329 * of the message each time. The MAC that is calculated is the MAC 1330 * of the concatenation of these messages in order. 1331 * -# At the end of the message, call psa_mac_sign_finish() to finish 1332 * calculating the MAC value and retrieve it. 1333 * 1334 * If an error occurs at any step after a call to psa_mac_sign_setup(), the 1335 * operation will need to be reset by a call to psa_mac_abort(). The 1336 * application may call psa_mac_abort() at any time after the operation 1337 * has been initialized. 1338 * 1339 * After a successful call to psa_mac_sign_setup(), the application must 1340 * eventually terminate the operation through one of the following methods: 1341 * - A successful call to psa_mac_sign_finish(). 1342 * - A call to psa_mac_abort(). 1343 * 1344 * \param[in,out] operation The operation object to set up. It must have 1345 * been initialized as per the documentation for 1346 * #psa_mac_operation_t and not yet in use. 1347 * \param key Identifier of the key to use for the operation. It 1348 * must remain valid until the operation terminates. 1349 * It must allow the usage PSA_KEY_USAGE_SIGN_MESSAGE. 1350 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value 1351 * such that #PSA_ALG_IS_MAC(\p alg) is true). 1352 * 1353 * \retval #PSA_SUCCESS 1354 * Success. 1355 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 1356 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 1357 * \retval #PSA_ERROR_INVALID_ARGUMENT 1358 * \p key is not compatible with \p alg. 1359 * \retval #PSA_ERROR_NOT_SUPPORTED 1360 * \p alg is not supported or is not a MAC algorithm. 1361 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1362 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1363 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1364 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1365 * \retval #PSA_ERROR_STORAGE_FAILURE 1366 * The key could not be retrieved from storage. 1367 * \retval #PSA_ERROR_BAD_STATE 1368 * The operation state is not valid (it must be inactive), or 1369 * the library has not been previously initialized by psa_crypto_init(). 1370 * It is implementation-dependent whether a failure to initialize 1371 * results in this error code. 1372 */ 1373 psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation, 1374 mbedtls_svc_key_id_t key, 1375 psa_algorithm_t alg); 1376 1377 /** Set up a multipart MAC verification operation. 1378 * 1379 * This function sets up the verification of the MAC 1380 * (message authentication code) of a byte string against an expected value. 1381 * 1382 * The sequence of operations to verify a MAC is as follows: 1383 * -# Allocate an operation object which will be passed to all the functions 1384 * listed here. 1385 * -# Initialize the operation object with one of the methods described in the 1386 * documentation for #psa_mac_operation_t, e.g. #PSA_MAC_OPERATION_INIT. 1387 * -# Call psa_mac_verify_setup() to specify the algorithm and key. 1388 * -# Call psa_mac_update() zero, one or more times, passing a fragment 1389 * of the message each time. The MAC that is calculated is the MAC 1390 * of the concatenation of these messages in order. 1391 * -# At the end of the message, call psa_mac_verify_finish() to finish 1392 * calculating the actual MAC of the message and verify it against 1393 * the expected value. 1394 * 1395 * If an error occurs at any step after a call to psa_mac_verify_setup(), the 1396 * operation will need to be reset by a call to psa_mac_abort(). The 1397 * application may call psa_mac_abort() at any time after the operation 1398 * has been initialized. 1399 * 1400 * After a successful call to psa_mac_verify_setup(), the application must 1401 * eventually terminate the operation through one of the following methods: 1402 * - A successful call to psa_mac_verify_finish(). 1403 * - A call to psa_mac_abort(). 1404 * 1405 * \param[in,out] operation The operation object to set up. It must have 1406 * been initialized as per the documentation for 1407 * #psa_mac_operation_t and not yet in use. 1408 * \param key Identifier of the key to use for the operation. It 1409 * must remain valid until the operation terminates. 1410 * It must allow the usage 1411 * PSA_KEY_USAGE_VERIFY_MESSAGE. 1412 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value 1413 * such that #PSA_ALG_IS_MAC(\p alg) is true). 1414 * 1415 * \retval #PSA_SUCCESS 1416 * Success. 1417 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 1418 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 1419 * \retval #PSA_ERROR_INVALID_ARGUMENT 1420 * \c key is not compatible with \c alg. 1421 * \retval #PSA_ERROR_NOT_SUPPORTED 1422 * \c alg is not supported or is not a MAC algorithm. 1423 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1424 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1425 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1426 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1427 * \retval #PSA_ERROR_STORAGE_FAILURE 1428 * The key could not be retrieved from storage. 1429 * \retval #PSA_ERROR_BAD_STATE 1430 * The operation state is not valid (it must be inactive), or 1431 * the library has not been previously initialized by psa_crypto_init(). 1432 * It is implementation-dependent whether a failure to initialize 1433 * results in this error code. 1434 */ 1435 psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation, 1436 mbedtls_svc_key_id_t key, 1437 psa_algorithm_t alg); 1438 1439 /** Add a message fragment to a multipart MAC operation. 1440 * 1441 * The application must call psa_mac_sign_setup() or psa_mac_verify_setup() 1442 * before calling this function. 1443 * 1444 * If this function returns an error status, the operation enters an error 1445 * state and must be aborted by calling psa_mac_abort(). 1446 * 1447 * \param[in,out] operation Active MAC operation. 1448 * \param[in] input Buffer containing the message fragment to add to 1449 * the MAC calculation. 1450 * \param input_length Size of the \p input buffer in bytes. 1451 * 1452 * \retval #PSA_SUCCESS 1453 * Success. 1454 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1455 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1456 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1457 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1458 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 1459 * \retval #PSA_ERROR_BAD_STATE 1460 * The operation state is not valid (it must be active), or 1461 * the library has not been previously initialized by psa_crypto_init(). 1462 * It is implementation-dependent whether a failure to initialize 1463 * results in this error code. 1464 */ 1465 psa_status_t psa_mac_update(psa_mac_operation_t *operation, 1466 const uint8_t *input, 1467 size_t input_length); 1468 1469 /** Finish the calculation of the MAC of a message. 1470 * 1471 * The application must call psa_mac_sign_setup() before calling this function. 1472 * This function calculates the MAC of the message formed by concatenating 1473 * the inputs passed to preceding calls to psa_mac_update(). 1474 * 1475 * When this function returns successfully, the operation becomes inactive. 1476 * If this function returns an error status, the operation enters an error 1477 * state and must be aborted by calling psa_mac_abort(). 1478 * 1479 * \warning Applications should not call this function if they expect 1480 * a specific value for the MAC. Call psa_mac_verify_finish() instead. 1481 * Beware that comparing integrity or authenticity data such as 1482 * MAC values with a function such as \c memcmp is risky 1483 * because the time taken by the comparison may leak information 1484 * about the MAC value which could allow an attacker to guess 1485 * a valid MAC and thereby bypass security controls. 1486 * 1487 * \param[in,out] operation Active MAC operation. 1488 * \param[out] mac Buffer where the MAC value is to be written. 1489 * \param mac_size Size of the \p mac buffer in bytes. 1490 * \param[out] mac_length On success, the number of bytes 1491 * that make up the MAC value. This is always 1492 * #PSA_MAC_LENGTH(\c key_type, \c key_bits, \c alg) 1493 * where \c key_type and \c key_bits are the type and 1494 * bit-size respectively of the key and \c alg is the 1495 * MAC algorithm that is calculated. 1496 * 1497 * \retval #PSA_SUCCESS 1498 * Success. 1499 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 1500 * The size of the \p mac buffer is too small. You can determine a 1501 * sufficient buffer size by calling PSA_MAC_LENGTH(). 1502 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1503 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1504 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1505 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1506 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 1507 * \retval #PSA_ERROR_BAD_STATE 1508 * The operation state is not valid (it must be an active mac sign 1509 * operation), or the library has not been previously initialized 1510 * by psa_crypto_init(). 1511 * It is implementation-dependent whether a failure to initialize 1512 * results in this error code. 1513 */ 1514 psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation, 1515 uint8_t *mac, 1516 size_t mac_size, 1517 size_t *mac_length); 1518 1519 /** Finish the calculation of the MAC of a message and compare it with 1520 * an expected value. 1521 * 1522 * The application must call psa_mac_verify_setup() before calling this function. 1523 * This function calculates the MAC of the message formed by concatenating 1524 * the inputs passed to preceding calls to psa_mac_update(). It then 1525 * compares the calculated MAC with the expected MAC passed as a 1526 * parameter to this function. 1527 * 1528 * When this function returns successfully, the operation becomes inactive. 1529 * If this function returns an error status, the operation enters an error 1530 * state and must be aborted by calling psa_mac_abort(). 1531 * 1532 * \note Implementations shall make the best effort to ensure that the 1533 * comparison between the actual MAC and the expected MAC is performed 1534 * in constant time. 1535 * 1536 * \param[in,out] operation Active MAC operation. 1537 * \param[in] mac Buffer containing the expected MAC value. 1538 * \param mac_length Size of the \p mac buffer in bytes. 1539 * 1540 * \retval #PSA_SUCCESS 1541 * The expected MAC is identical to the actual MAC of the message. 1542 * \retval #PSA_ERROR_INVALID_SIGNATURE 1543 * The MAC of the message was calculated successfully, but it 1544 * differs from the expected MAC. 1545 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1546 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1547 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1548 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1549 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 1550 * \retval #PSA_ERROR_BAD_STATE 1551 * The operation state is not valid (it must be an active mac verify 1552 * operation), or the library has not been previously initialized 1553 * by psa_crypto_init(). 1554 * It is implementation-dependent whether a failure to initialize 1555 * results in this error code. 1556 */ 1557 psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation, 1558 const uint8_t *mac, 1559 size_t mac_length); 1560 1561 /** Abort a MAC operation. 1562 * 1563 * Aborting an operation frees all associated resources except for the 1564 * \p operation structure itself. Once aborted, the operation object 1565 * can be reused for another operation by calling 1566 * psa_mac_sign_setup() or psa_mac_verify_setup() again. 1567 * 1568 * You may call this function any time after the operation object has 1569 * been initialized by one of the methods described in #psa_mac_operation_t. 1570 * 1571 * In particular, calling psa_mac_abort() after the operation has been 1572 * terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or 1573 * psa_mac_verify_finish() is safe and has no effect. 1574 * 1575 * \param[in,out] operation Initialized MAC operation. 1576 * 1577 * \retval #PSA_SUCCESS \emptydescription 1578 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1579 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1580 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1581 * \retval #PSA_ERROR_BAD_STATE 1582 * The library has not been previously initialized by psa_crypto_init(). 1583 * It is implementation-dependent whether a failure to initialize 1584 * results in this error code. 1585 */ 1586 psa_status_t psa_mac_abort(psa_mac_operation_t *operation); 1587 1588 /**@}*/ 1589 1590 /** \defgroup cipher Symmetric ciphers 1591 * @{ 1592 */ 1593 1594 /** Encrypt a message using a symmetric cipher. 1595 * 1596 * This function encrypts a message with a random IV (initialization 1597 * vector). Use the multipart operation interface with a 1598 * #psa_cipher_operation_t object to provide other forms of IV. 1599 * 1600 * \param key Identifier of the key to use for the operation. 1601 * It must allow the usage #PSA_KEY_USAGE_ENCRYPT. 1602 * \param alg The cipher algorithm to compute 1603 * (\c PSA_ALG_XXX value such that 1604 * #PSA_ALG_IS_CIPHER(\p alg) is true). 1605 * \param[in] input Buffer containing the message to encrypt. 1606 * \param input_length Size of the \p input buffer in bytes. 1607 * \param[out] output Buffer where the output is to be written. 1608 * The output contains the IV followed by 1609 * the ciphertext proper. 1610 * \param output_size Size of the \p output buffer in bytes. 1611 * \param[out] output_length On success, the number of bytes 1612 * that make up the output. 1613 * 1614 * \retval #PSA_SUCCESS 1615 * Success. 1616 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 1617 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 1618 * \retval #PSA_ERROR_INVALID_ARGUMENT 1619 * \p key is not compatible with \p alg. 1620 * \retval #PSA_ERROR_NOT_SUPPORTED 1621 * \p alg is not supported or is not a cipher algorithm. 1622 * \retval #PSA_ERROR_BUFFER_TOO_SMALL \emptydescription 1623 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1624 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1625 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1626 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1627 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 1628 * \retval #PSA_ERROR_BAD_STATE 1629 * The library has not been previously initialized by psa_crypto_init(). 1630 * It is implementation-dependent whether a failure to initialize 1631 * results in this error code. 1632 */ 1633 psa_status_t psa_cipher_encrypt(mbedtls_svc_key_id_t key, 1634 psa_algorithm_t alg, 1635 const uint8_t *input, 1636 size_t input_length, 1637 uint8_t *output, 1638 size_t output_size, 1639 size_t *output_length); 1640 1641 /** Decrypt a message using a symmetric cipher. 1642 * 1643 * This function decrypts a message encrypted with a symmetric cipher. 1644 * 1645 * \param key Identifier of the key to use for the operation. 1646 * It must remain valid until the operation 1647 * terminates. It must allow the usage 1648 * #PSA_KEY_USAGE_DECRYPT. 1649 * \param alg The cipher algorithm to compute 1650 * (\c PSA_ALG_XXX value such that 1651 * #PSA_ALG_IS_CIPHER(\p alg) is true). 1652 * \param[in] input Buffer containing the message to decrypt. 1653 * This consists of the IV followed by the 1654 * ciphertext proper. 1655 * \param input_length Size of the \p input buffer in bytes. 1656 * \param[out] output Buffer where the plaintext is to be written. 1657 * \param output_size Size of the \p output buffer in bytes. 1658 * \param[out] output_length On success, the number of bytes 1659 * that make up the output. 1660 * 1661 * \retval #PSA_SUCCESS 1662 * Success. 1663 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 1664 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 1665 * \retval #PSA_ERROR_INVALID_ARGUMENT 1666 * \p key is not compatible with \p alg. 1667 * \retval #PSA_ERROR_NOT_SUPPORTED 1668 * \p alg is not supported or is not a cipher algorithm. 1669 * \retval #PSA_ERROR_BUFFER_TOO_SMALL \emptydescription 1670 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1671 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1672 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1673 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 1674 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1675 * \retval #PSA_ERROR_BAD_STATE 1676 * The library has not been previously initialized by psa_crypto_init(). 1677 * It is implementation-dependent whether a failure to initialize 1678 * results in this error code. 1679 */ 1680 psa_status_t psa_cipher_decrypt(mbedtls_svc_key_id_t key, 1681 psa_algorithm_t alg, 1682 const uint8_t *input, 1683 size_t input_length, 1684 uint8_t *output, 1685 size_t output_size, 1686 size_t *output_length); 1687 1688 /** The type of the state data structure for multipart cipher operations. 1689 * 1690 * Before calling any function on a cipher operation object, the application 1691 * must initialize it by any of the following means: 1692 * - Set the structure to all-bits-zero, for example: 1693 * \code 1694 * psa_cipher_operation_t operation; 1695 * memset(&operation, 0, sizeof(operation)); 1696 * \endcode 1697 * - Initialize the structure to logical zero values, for example: 1698 * \code 1699 * psa_cipher_operation_t operation = {0}; 1700 * \endcode 1701 * - Initialize the structure to the initializer #PSA_CIPHER_OPERATION_INIT, 1702 * for example: 1703 * \code 1704 * psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT; 1705 * \endcode 1706 * - Assign the result of the function psa_cipher_operation_init() 1707 * to the structure, for example: 1708 * \code 1709 * psa_cipher_operation_t operation; 1710 * operation = psa_cipher_operation_init(); 1711 * \endcode 1712 * 1713 * This is an implementation-defined \c struct. Applications should not 1714 * make any assumptions about the content of this structure. 1715 * Implementation details can change in future versions without notice. */ 1716 typedef struct psa_cipher_operation_s psa_cipher_operation_t; 1717 1718 /** \def PSA_CIPHER_OPERATION_INIT 1719 * 1720 * This macro returns a suitable initializer for a cipher operation object of 1721 * type #psa_cipher_operation_t. 1722 */ 1723 1724 /** Return an initial value for a cipher operation object. 1725 */ 1726 static psa_cipher_operation_t psa_cipher_operation_init(void); 1727 1728 /** Set the key for a multipart symmetric encryption operation. 1729 * 1730 * The sequence of operations to encrypt a message with a symmetric cipher 1731 * is as follows: 1732 * -# Allocate an operation object which will be passed to all the functions 1733 * listed here. 1734 * -# Initialize the operation object with one of the methods described in the 1735 * documentation for #psa_cipher_operation_t, e.g. 1736 * #PSA_CIPHER_OPERATION_INIT. 1737 * -# Call psa_cipher_encrypt_setup() to specify the algorithm and key. 1738 * -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to 1739 * generate or set the IV (initialization vector). You should use 1740 * psa_cipher_generate_iv() unless the protocol you are implementing 1741 * requires a specific IV value. 1742 * -# Call psa_cipher_update() zero, one or more times, passing a fragment 1743 * of the message each time. 1744 * -# Call psa_cipher_finish(). 1745 * 1746 * If an error occurs at any step after a call to psa_cipher_encrypt_setup(), 1747 * the operation will need to be reset by a call to psa_cipher_abort(). The 1748 * application may call psa_cipher_abort() at any time after the operation 1749 * has been initialized. 1750 * 1751 * After a successful call to psa_cipher_encrypt_setup(), the application must 1752 * eventually terminate the operation. The following events terminate an 1753 * operation: 1754 * - A successful call to psa_cipher_finish(). 1755 * - A call to psa_cipher_abort(). 1756 * 1757 * \param[in,out] operation The operation object to set up. It must have 1758 * been initialized as per the documentation for 1759 * #psa_cipher_operation_t and not yet in use. 1760 * \param key Identifier of the key to use for the operation. 1761 * It must remain valid until the operation 1762 * terminates. It must allow the usage 1763 * #PSA_KEY_USAGE_ENCRYPT. 1764 * \param alg The cipher algorithm to compute 1765 * (\c PSA_ALG_XXX value such that 1766 * #PSA_ALG_IS_CIPHER(\p alg) is true). 1767 * 1768 * \retval #PSA_SUCCESS 1769 * Success. 1770 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 1771 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 1772 * \retval #PSA_ERROR_INVALID_ARGUMENT 1773 * \p key is not compatible with \p alg. 1774 * \retval #PSA_ERROR_NOT_SUPPORTED 1775 * \p alg is not supported or is not a cipher algorithm. 1776 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1777 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1778 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1779 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1780 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 1781 * \retval #PSA_ERROR_BAD_STATE 1782 * The operation state is not valid (it must be inactive), or 1783 * the library has not been previously initialized by psa_crypto_init(). 1784 * It is implementation-dependent whether a failure to initialize 1785 * results in this error code. 1786 */ 1787 psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, 1788 mbedtls_svc_key_id_t key, 1789 psa_algorithm_t alg); 1790 1791 /** Set the key for a multipart symmetric decryption operation. 1792 * 1793 * The sequence of operations to decrypt a message with a symmetric cipher 1794 * is as follows: 1795 * -# Allocate an operation object which will be passed to all the functions 1796 * listed here. 1797 * -# Initialize the operation object with one of the methods described in the 1798 * documentation for #psa_cipher_operation_t, e.g. 1799 * #PSA_CIPHER_OPERATION_INIT. 1800 * -# Call psa_cipher_decrypt_setup() to specify the algorithm and key. 1801 * -# Call psa_cipher_set_iv() with the IV (initialization vector) for the 1802 * decryption. If the IV is prepended to the ciphertext, you can call 1803 * psa_cipher_update() on a buffer containing the IV followed by the 1804 * beginning of the message. 1805 * -# Call psa_cipher_update() zero, one or more times, passing a fragment 1806 * of the message each time. 1807 * -# Call psa_cipher_finish(). 1808 * 1809 * If an error occurs at any step after a call to psa_cipher_decrypt_setup(), 1810 * the operation will need to be reset by a call to psa_cipher_abort(). The 1811 * application may call psa_cipher_abort() at any time after the operation 1812 * has been initialized. 1813 * 1814 * After a successful call to psa_cipher_decrypt_setup(), the application must 1815 * eventually terminate the operation. The following events terminate an 1816 * operation: 1817 * - A successful call to psa_cipher_finish(). 1818 * - A call to psa_cipher_abort(). 1819 * 1820 * \param[in,out] operation The operation object to set up. It must have 1821 * been initialized as per the documentation for 1822 * #psa_cipher_operation_t and not yet in use. 1823 * \param key Identifier of the key to use for the operation. 1824 * It must remain valid until the operation 1825 * terminates. It must allow the usage 1826 * #PSA_KEY_USAGE_DECRYPT. 1827 * \param alg The cipher algorithm to compute 1828 * (\c PSA_ALG_XXX value such that 1829 * #PSA_ALG_IS_CIPHER(\p alg) is true). 1830 * 1831 * \retval #PSA_SUCCESS 1832 * Success. 1833 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 1834 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 1835 * \retval #PSA_ERROR_INVALID_ARGUMENT 1836 * \p key is not compatible with \p alg. 1837 * \retval #PSA_ERROR_NOT_SUPPORTED 1838 * \p alg is not supported or is not a cipher algorithm. 1839 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1840 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1841 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1842 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1843 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 1844 * \retval #PSA_ERROR_BAD_STATE 1845 * The operation state is not valid (it must be inactive), or 1846 * the library has not been previously initialized by psa_crypto_init(). 1847 * It is implementation-dependent whether a failure to initialize 1848 * results in this error code. 1849 */ 1850 psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation, 1851 mbedtls_svc_key_id_t key, 1852 psa_algorithm_t alg); 1853 1854 /** Generate an IV for a symmetric encryption operation. 1855 * 1856 * This function generates a random IV (initialization vector), nonce 1857 * or initial counter value for the encryption operation as appropriate 1858 * for the chosen algorithm, key type and key size. 1859 * 1860 * The application must call psa_cipher_encrypt_setup() before 1861 * calling this function. 1862 * 1863 * If this function returns an error status, the operation enters an error 1864 * state and must be aborted by calling psa_cipher_abort(). 1865 * 1866 * \param[in,out] operation Active cipher operation. 1867 * \param[out] iv Buffer where the generated IV is to be written. 1868 * \param iv_size Size of the \p iv buffer in bytes. 1869 * \param[out] iv_length On success, the number of bytes of the 1870 * generated IV. 1871 * 1872 * \retval #PSA_SUCCESS 1873 * Success. 1874 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 1875 * The size of the \p iv buffer is too small. 1876 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1877 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1878 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1879 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1880 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 1881 * \retval #PSA_ERROR_BAD_STATE 1882 * The operation state is not valid (it must be active, with no IV set), 1883 * or the library has not been previously initialized 1884 * by psa_crypto_init(). 1885 * It is implementation-dependent whether a failure to initialize 1886 * results in this error code. 1887 */ 1888 psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation, 1889 uint8_t *iv, 1890 size_t iv_size, 1891 size_t *iv_length); 1892 1893 /** Set the IV for a symmetric encryption or decryption operation. 1894 * 1895 * This function sets the IV (initialization vector), nonce 1896 * or initial counter value for the encryption or decryption operation. 1897 * 1898 * The application must call psa_cipher_encrypt_setup() before 1899 * calling this function. 1900 * 1901 * If this function returns an error status, the operation enters an error 1902 * state and must be aborted by calling psa_cipher_abort(). 1903 * 1904 * \note When encrypting, applications should use psa_cipher_generate_iv() 1905 * instead of this function, unless implementing a protocol that requires 1906 * a non-random IV. 1907 * 1908 * \param[in,out] operation Active cipher operation. 1909 * \param[in] iv Buffer containing the IV to use. 1910 * \param iv_length Size of the IV in bytes. 1911 * 1912 * \retval #PSA_SUCCESS 1913 * Success. 1914 * \retval #PSA_ERROR_INVALID_ARGUMENT 1915 * The size of \p iv is not acceptable for the chosen algorithm, 1916 * or the chosen algorithm does not use an IV. 1917 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1918 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1919 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1920 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1921 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 1922 * \retval #PSA_ERROR_BAD_STATE 1923 * The operation state is not valid (it must be an active cipher 1924 * encrypt operation, with no IV set), or the library has not been 1925 * previously initialized by psa_crypto_init(). 1926 * It is implementation-dependent whether a failure to initialize 1927 * results in this error code. 1928 */ 1929 psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation, 1930 const uint8_t *iv, 1931 size_t iv_length); 1932 1933 /** Encrypt or decrypt a message fragment in an active cipher operation. 1934 * 1935 * Before calling this function, you must: 1936 * 1. Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(). 1937 * The choice of setup function determines whether this function 1938 * encrypts or decrypts its input. 1939 * 2. If the algorithm requires an IV, call psa_cipher_generate_iv() 1940 * (recommended when encrypting) or psa_cipher_set_iv(). 1941 * 1942 * If this function returns an error status, the operation enters an error 1943 * state and must be aborted by calling psa_cipher_abort(). 1944 * 1945 * \param[in,out] operation Active cipher operation. 1946 * \param[in] input Buffer containing the message fragment to 1947 * encrypt or decrypt. 1948 * \param input_length Size of the \p input buffer in bytes. 1949 * \param[out] output Buffer where the output is to be written. 1950 * \param output_size Size of the \p output buffer in bytes. 1951 * \param[out] output_length On success, the number of bytes 1952 * that make up the returned output. 1953 * 1954 * \retval #PSA_SUCCESS 1955 * Success. 1956 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 1957 * The size of the \p output buffer is too small. 1958 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1959 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1960 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1961 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1962 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 1963 * \retval #PSA_ERROR_BAD_STATE 1964 * The operation state is not valid (it must be active, with an IV set 1965 * if required for the algorithm), or the library has not been 1966 * previously initialized by psa_crypto_init(). 1967 * It is implementation-dependent whether a failure to initialize 1968 * results in this error code. 1969 */ 1970 psa_status_t psa_cipher_update(psa_cipher_operation_t *operation, 1971 const uint8_t *input, 1972 size_t input_length, 1973 uint8_t *output, 1974 size_t output_size, 1975 size_t *output_length); 1976 1977 /** Finish encrypting or decrypting a message in a cipher operation. 1978 * 1979 * The application must call psa_cipher_encrypt_setup() or 1980 * psa_cipher_decrypt_setup() before calling this function. The choice 1981 * of setup function determines whether this function encrypts or 1982 * decrypts its input. 1983 * 1984 * This function finishes the encryption or decryption of the message 1985 * formed by concatenating the inputs passed to preceding calls to 1986 * psa_cipher_update(). 1987 * 1988 * When this function returns successfully, the operation becomes inactive. 1989 * If this function returns an error status, the operation enters an error 1990 * state and must be aborted by calling psa_cipher_abort(). 1991 * 1992 * \param[in,out] operation Active cipher operation. 1993 * \param[out] output Buffer where the output is to be written. 1994 * \param output_size Size of the \p output buffer in bytes. 1995 * \param[out] output_length On success, the number of bytes 1996 * that make up the returned output. 1997 * 1998 * \retval #PSA_SUCCESS 1999 * Success. 2000 * \retval #PSA_ERROR_INVALID_ARGUMENT 2001 * The total input size passed to this operation is not valid for 2002 * this particular algorithm. For example, the algorithm is a based 2003 * on block cipher and requires a whole number of blocks, but the 2004 * total input size is not a multiple of the block size. 2005 * \retval #PSA_ERROR_INVALID_PADDING 2006 * This is a decryption operation for an algorithm that includes 2007 * padding, and the ciphertext does not contain valid padding. 2008 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 2009 * The size of the \p output buffer is too small. 2010 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 2011 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2012 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2013 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2014 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 2015 * \retval #PSA_ERROR_BAD_STATE 2016 * The operation state is not valid (it must be active, with an IV set 2017 * if required for the algorithm), or the library has not been 2018 * previously initialized by psa_crypto_init(). 2019 * It is implementation-dependent whether a failure to initialize 2020 * results in this error code. 2021 */ 2022 psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation, 2023 uint8_t *output, 2024 size_t output_size, 2025 size_t *output_length); 2026 2027 /** Abort a cipher operation. 2028 * 2029 * Aborting an operation frees all associated resources except for the 2030 * \p operation structure itself. Once aborted, the operation object 2031 * can be reused for another operation by calling 2032 * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again. 2033 * 2034 * You may call this function any time after the operation object has 2035 * been initialized as described in #psa_cipher_operation_t. 2036 * 2037 * In particular, calling psa_cipher_abort() after the operation has been 2038 * terminated by a call to psa_cipher_abort() or psa_cipher_finish() 2039 * is safe and has no effect. 2040 * 2041 * \param[in,out] operation Initialized cipher operation. 2042 * 2043 * \retval #PSA_SUCCESS \emptydescription 2044 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2045 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2046 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2047 * \retval #PSA_ERROR_BAD_STATE 2048 * The library has not been previously initialized by psa_crypto_init(). 2049 * It is implementation-dependent whether a failure to initialize 2050 * results in this error code. 2051 */ 2052 psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation); 2053 2054 /**@}*/ 2055 2056 /** \defgroup aead Authenticated encryption with associated data (AEAD) 2057 * @{ 2058 */ 2059 2060 /** Process an authenticated encryption operation. 2061 * 2062 * \param key Identifier of the key to use for the 2063 * operation. It must allow the usage 2064 * #PSA_KEY_USAGE_ENCRYPT. 2065 * \param alg The AEAD algorithm to compute 2066 * (\c PSA_ALG_XXX value such that 2067 * #PSA_ALG_IS_AEAD(\p alg) is true). 2068 * \param[in] nonce Nonce or IV to use. 2069 * \param nonce_length Size of the \p nonce buffer in bytes. 2070 * \param[in] additional_data Additional data that will be authenticated 2071 * but not encrypted. 2072 * \param additional_data_length Size of \p additional_data in bytes. 2073 * \param[in] plaintext Data that will be authenticated and 2074 * encrypted. 2075 * \param plaintext_length Size of \p plaintext in bytes. 2076 * \param[out] ciphertext Output buffer for the authenticated and 2077 * encrypted data. The additional data is not 2078 * part of this output. For algorithms where the 2079 * encrypted data and the authentication tag 2080 * are defined as separate outputs, the 2081 * authentication tag is appended to the 2082 * encrypted data. 2083 * \param ciphertext_size Size of the \p ciphertext buffer in bytes. 2084 * This must be appropriate for the selected 2085 * algorithm and key: 2086 * - A sufficient output size is 2087 * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\c key_type, 2088 * \p alg, \p plaintext_length) where 2089 * \c key_type is the type of \p key. 2090 * - #PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(\p 2091 * plaintext_length) evaluates to the maximum 2092 * ciphertext size of any supported AEAD 2093 * encryption. 2094 * \param[out] ciphertext_length On success, the size of the output 2095 * in the \p ciphertext buffer. 2096 * 2097 * \retval #PSA_SUCCESS 2098 * Success. 2099 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 2100 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 2101 * \retval #PSA_ERROR_INVALID_ARGUMENT 2102 * \p key is not compatible with \p alg. 2103 * \retval #PSA_ERROR_NOT_SUPPORTED 2104 * \p alg is not supported or is not an AEAD algorithm. 2105 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 2106 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 2107 * \p ciphertext_size is too small. 2108 * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\c key_type, \p alg, 2109 * \p plaintext_length) or 2110 * #PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(\p plaintext_length) can be used to 2111 * determine the required buffer size. 2112 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2113 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2114 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2115 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 2116 * \retval #PSA_ERROR_BAD_STATE 2117 * The library has not been previously initialized by psa_crypto_init(). 2118 * It is implementation-dependent whether a failure to initialize 2119 * results in this error code. 2120 */ 2121 psa_status_t psa_aead_encrypt(mbedtls_svc_key_id_t key, 2122 psa_algorithm_t alg, 2123 const uint8_t *nonce, 2124 size_t nonce_length, 2125 const uint8_t *additional_data, 2126 size_t additional_data_length, 2127 const uint8_t *plaintext, 2128 size_t plaintext_length, 2129 uint8_t *ciphertext, 2130 size_t ciphertext_size, 2131 size_t *ciphertext_length); 2132 2133 /** Process an authenticated decryption operation. 2134 * 2135 * \param key Identifier of the key to use for the 2136 * operation. It must allow the usage 2137 * #PSA_KEY_USAGE_DECRYPT. 2138 * \param alg The AEAD algorithm to compute 2139 * (\c PSA_ALG_XXX value such that 2140 * #PSA_ALG_IS_AEAD(\p alg) is true). 2141 * \param[in] nonce Nonce or IV to use. 2142 * \param nonce_length Size of the \p nonce buffer in bytes. 2143 * \param[in] additional_data Additional data that has been authenticated 2144 * but not encrypted. 2145 * \param additional_data_length Size of \p additional_data in bytes. 2146 * \param[in] ciphertext Data that has been authenticated and 2147 * encrypted. For algorithms where the 2148 * encrypted data and the authentication tag 2149 * are defined as separate inputs, the buffer 2150 * must contain the encrypted data followed 2151 * by the authentication tag. 2152 * \param ciphertext_length Size of \p ciphertext in bytes. 2153 * \param[out] plaintext Output buffer for the decrypted data. 2154 * \param plaintext_size Size of the \p plaintext buffer in bytes. 2155 * This must be appropriate for the selected 2156 * algorithm and key: 2157 * - A sufficient output size is 2158 * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\c key_type, 2159 * \p alg, \p ciphertext_length) where 2160 * \c key_type is the type of \p key. 2161 * - #PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(\p 2162 * ciphertext_length) evaluates to the maximum 2163 * plaintext size of any supported AEAD 2164 * decryption. 2165 * \param[out] plaintext_length On success, the size of the output 2166 * in the \p plaintext buffer. 2167 * 2168 * \retval #PSA_SUCCESS 2169 * Success. 2170 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 2171 * \retval #PSA_ERROR_INVALID_SIGNATURE 2172 * The ciphertext is not authentic. 2173 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 2174 * \retval #PSA_ERROR_INVALID_ARGUMENT 2175 * \p key is not compatible with \p alg. 2176 * \retval #PSA_ERROR_NOT_SUPPORTED 2177 * \p alg is not supported or is not an AEAD algorithm. 2178 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 2179 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 2180 * \p plaintext_size is too small. 2181 * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\c key_type, \p alg, 2182 * \p ciphertext_length) or 2183 * #PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(\p ciphertext_length) can be used 2184 * to determine the required buffer size. 2185 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2186 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2187 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2188 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 2189 * \retval #PSA_ERROR_BAD_STATE 2190 * The library has not been previously initialized by psa_crypto_init(). 2191 * It is implementation-dependent whether a failure to initialize 2192 * results in this error code. 2193 */ 2194 psa_status_t psa_aead_decrypt(mbedtls_svc_key_id_t key, 2195 psa_algorithm_t alg, 2196 const uint8_t *nonce, 2197 size_t nonce_length, 2198 const uint8_t *additional_data, 2199 size_t additional_data_length, 2200 const uint8_t *ciphertext, 2201 size_t ciphertext_length, 2202 uint8_t *plaintext, 2203 size_t plaintext_size, 2204 size_t *plaintext_length); 2205 2206 /** The type of the state data structure for multipart AEAD operations. 2207 * 2208 * Before calling any function on an AEAD operation object, the application 2209 * must initialize it by any of the following means: 2210 * - Set the structure to all-bits-zero, for example: 2211 * \code 2212 * psa_aead_operation_t operation; 2213 * memset(&operation, 0, sizeof(operation)); 2214 * \endcode 2215 * - Initialize the structure to logical zero values, for example: 2216 * \code 2217 * psa_aead_operation_t operation = {0}; 2218 * \endcode 2219 * - Initialize the structure to the initializer #PSA_AEAD_OPERATION_INIT, 2220 * for example: 2221 * \code 2222 * psa_aead_operation_t operation = PSA_AEAD_OPERATION_INIT; 2223 * \endcode 2224 * - Assign the result of the function psa_aead_operation_init() 2225 * to the structure, for example: 2226 * \code 2227 * psa_aead_operation_t operation; 2228 * operation = psa_aead_operation_init(); 2229 * \endcode 2230 * 2231 * This is an implementation-defined \c struct. Applications should not 2232 * make any assumptions about the content of this structure. 2233 * Implementation details can change in future versions without notice. */ 2234 typedef struct psa_aead_operation_s psa_aead_operation_t; 2235 2236 /** \def PSA_AEAD_OPERATION_INIT 2237 * 2238 * This macro returns a suitable initializer for an AEAD operation object of 2239 * type #psa_aead_operation_t. 2240 */ 2241 2242 /** Return an initial value for an AEAD operation object. 2243 */ 2244 static psa_aead_operation_t psa_aead_operation_init(void); 2245 2246 /** Set the key for a multipart authenticated encryption operation. 2247 * 2248 * The sequence of operations to encrypt a message with authentication 2249 * is as follows: 2250 * -# Allocate an operation object which will be passed to all the functions 2251 * listed here. 2252 * -# Initialize the operation object with one of the methods described in the 2253 * documentation for #psa_aead_operation_t, e.g. 2254 * #PSA_AEAD_OPERATION_INIT. 2255 * -# Call psa_aead_encrypt_setup() to specify the algorithm and key. 2256 * -# If needed, call psa_aead_set_lengths() to specify the length of the 2257 * inputs to the subsequent calls to psa_aead_update_ad() and 2258 * psa_aead_update(). See the documentation of psa_aead_set_lengths() 2259 * for details. 2260 * -# Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to 2261 * generate or set the nonce. You should use 2262 * psa_aead_generate_nonce() unless the protocol you are implementing 2263 * requires a specific nonce value. 2264 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment 2265 * of the non-encrypted additional authenticated data each time. 2266 * -# Call psa_aead_update() zero, one or more times, passing a fragment 2267 * of the message to encrypt each time. 2268 * -# Call psa_aead_finish(). 2269 * 2270 * If an error occurs at any step after a call to psa_aead_encrypt_setup(), 2271 * the operation will need to be reset by a call to psa_aead_abort(). The 2272 * application may call psa_aead_abort() at any time after the operation 2273 * has been initialized. 2274 * 2275 * After a successful call to psa_aead_encrypt_setup(), the application must 2276 * eventually terminate the operation. The following events terminate an 2277 * operation: 2278 * - A successful call to psa_aead_finish(). 2279 * - A call to psa_aead_abort(). 2280 * 2281 * \param[in,out] operation The operation object to set up. It must have 2282 * been initialized as per the documentation for 2283 * #psa_aead_operation_t and not yet in use. 2284 * \param key Identifier of the key to use for the operation. 2285 * It must remain valid until the operation 2286 * terminates. It must allow the usage 2287 * #PSA_KEY_USAGE_ENCRYPT. 2288 * \param alg The AEAD algorithm to compute 2289 * (\c PSA_ALG_XXX value such that 2290 * #PSA_ALG_IS_AEAD(\p alg) is true). 2291 * 2292 * \retval #PSA_SUCCESS 2293 * Success. 2294 * \retval #PSA_ERROR_BAD_STATE 2295 * The operation state is not valid (it must be inactive), or 2296 * the library has not been previously initialized by psa_crypto_init(). 2297 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 2298 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 2299 * \retval #PSA_ERROR_INVALID_ARGUMENT 2300 * \p key is not compatible with \p alg. 2301 * \retval #PSA_ERROR_NOT_SUPPORTED 2302 * \p alg is not supported or is not an AEAD algorithm. 2303 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 2304 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2305 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2306 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2307 * \retval #PSA_ERROR_STORAGE_FAILURE 2308 * The library has not been previously initialized by psa_crypto_init(). 2309 * It is implementation-dependent whether a failure to initialize 2310 * results in this error code. 2311 */ 2312 psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation, 2313 mbedtls_svc_key_id_t key, 2314 psa_algorithm_t alg); 2315 2316 /** Set the key for a multipart authenticated decryption operation. 2317 * 2318 * The sequence of operations to decrypt a message with authentication 2319 * is as follows: 2320 * -# Allocate an operation object which will be passed to all the functions 2321 * listed here. 2322 * -# Initialize the operation object with one of the methods described in the 2323 * documentation for #psa_aead_operation_t, e.g. 2324 * #PSA_AEAD_OPERATION_INIT. 2325 * -# Call psa_aead_decrypt_setup() to specify the algorithm and key. 2326 * -# If needed, call psa_aead_set_lengths() to specify the length of the 2327 * inputs to the subsequent calls to psa_aead_update_ad() and 2328 * psa_aead_update(). See the documentation of psa_aead_set_lengths() 2329 * for details. 2330 * -# Call psa_aead_set_nonce() with the nonce for the decryption. 2331 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment 2332 * of the non-encrypted additional authenticated data each time. 2333 * -# Call psa_aead_update() zero, one or more times, passing a fragment 2334 * of the ciphertext to decrypt each time. 2335 * -# Call psa_aead_verify(). 2336 * 2337 * If an error occurs at any step after a call to psa_aead_decrypt_setup(), 2338 * the operation will need to be reset by a call to psa_aead_abort(). The 2339 * application may call psa_aead_abort() at any time after the operation 2340 * has been initialized. 2341 * 2342 * After a successful call to psa_aead_decrypt_setup(), the application must 2343 * eventually terminate the operation. The following events terminate an 2344 * operation: 2345 * - A successful call to psa_aead_verify(). 2346 * - A call to psa_aead_abort(). 2347 * 2348 * \param[in,out] operation The operation object to set up. It must have 2349 * been initialized as per the documentation for 2350 * #psa_aead_operation_t and not yet in use. 2351 * \param key Identifier of the key to use for the operation. 2352 * It must remain valid until the operation 2353 * terminates. It must allow the usage 2354 * #PSA_KEY_USAGE_DECRYPT. 2355 * \param alg The AEAD algorithm to compute 2356 * (\c PSA_ALG_XXX value such that 2357 * #PSA_ALG_IS_AEAD(\p alg) is true). 2358 * 2359 * \retval #PSA_SUCCESS 2360 * Success. 2361 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 2362 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 2363 * \retval #PSA_ERROR_INVALID_ARGUMENT 2364 * \p key is not compatible with \p alg. 2365 * \retval #PSA_ERROR_NOT_SUPPORTED 2366 * \p alg is not supported or is not an AEAD algorithm. 2367 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 2368 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2369 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2370 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2371 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 2372 * \retval #PSA_ERROR_BAD_STATE 2373 * The operation state is not valid (it must be inactive), or the 2374 * library has not been previously initialized by psa_crypto_init(). 2375 * It is implementation-dependent whether a failure to initialize 2376 * results in this error code. 2377 */ 2378 psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation, 2379 mbedtls_svc_key_id_t key, 2380 psa_algorithm_t alg); 2381 2382 /** Generate a random nonce for an authenticated encryption operation. 2383 * 2384 * This function generates a random nonce for the authenticated encryption 2385 * operation with an appropriate size for the chosen algorithm, key type 2386 * and key size. 2387 * 2388 * The application must call psa_aead_encrypt_setup() before 2389 * calling this function. 2390 * 2391 * If this function returns an error status, the operation enters an error 2392 * state and must be aborted by calling psa_aead_abort(). 2393 * 2394 * \param[in,out] operation Active AEAD operation. 2395 * \param[out] nonce Buffer where the generated nonce is to be 2396 * written. 2397 * \param nonce_size Size of the \p nonce buffer in bytes. 2398 * \param[out] nonce_length On success, the number of bytes of the 2399 * generated nonce. 2400 * 2401 * \retval #PSA_SUCCESS 2402 * Success. 2403 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 2404 * The size of the \p nonce buffer is too small. 2405 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 2406 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2407 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2408 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2409 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 2410 * \retval #PSA_ERROR_BAD_STATE 2411 * The operation state is not valid (it must be an active aead encrypt 2412 * operation, with no nonce set), or the library has not been 2413 * previously initialized by psa_crypto_init(). 2414 * It is implementation-dependent whether a failure to initialize 2415 * results in this error code. 2416 */ 2417 psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation, 2418 uint8_t *nonce, 2419 size_t nonce_size, 2420 size_t *nonce_length); 2421 2422 /** Set the nonce for an authenticated encryption or decryption operation. 2423 * 2424 * This function sets the nonce for the authenticated 2425 * encryption or decryption operation. 2426 * 2427 * The application must call psa_aead_encrypt_setup() or 2428 * psa_aead_decrypt_setup() before calling this function. 2429 * 2430 * If this function returns an error status, the operation enters an error 2431 * state and must be aborted by calling psa_aead_abort(). 2432 * 2433 * \note When encrypting, applications should use psa_aead_generate_nonce() 2434 * instead of this function, unless implementing a protocol that requires 2435 * a non-random IV. 2436 * 2437 * \param[in,out] operation Active AEAD operation. 2438 * \param[in] nonce Buffer containing the nonce to use. 2439 * \param nonce_length Size of the nonce in bytes. 2440 * 2441 * \retval #PSA_SUCCESS 2442 * Success. 2443 * \retval #PSA_ERROR_INVALID_ARGUMENT 2444 * The size of \p nonce is not acceptable for the chosen algorithm. 2445 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 2446 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2447 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2448 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2449 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 2450 * \retval #PSA_ERROR_BAD_STATE 2451 * The operation state is not valid (it must be active, with no nonce 2452 * set), or the library has not been previously initialized 2453 * by psa_crypto_init(). 2454 * It is implementation-dependent whether a failure to initialize 2455 * results in this error code. 2456 */ 2457 psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation, 2458 const uint8_t *nonce, 2459 size_t nonce_length); 2460 2461 /** Declare the lengths of the message and additional data for AEAD. 2462 * 2463 * The application must call this function before calling 2464 * psa_aead_update_ad() or psa_aead_update() if the algorithm for 2465 * the operation requires it. If the algorithm does not require it, 2466 * calling this function is optional, but if this function is called 2467 * then the implementation must enforce the lengths. 2468 * 2469 * You may call this function before or after setting the nonce with 2470 * psa_aead_set_nonce() or psa_aead_generate_nonce(). 2471 * 2472 * - For #PSA_ALG_CCM, calling this function is required. 2473 * - For the other AEAD algorithms defined in this specification, calling 2474 * this function is not required. 2475 * - For vendor-defined algorithm, refer to the vendor documentation. 2476 * 2477 * If this function returns an error status, the operation enters an error 2478 * state and must be aborted by calling psa_aead_abort(). 2479 * 2480 * \param[in,out] operation Active AEAD operation. 2481 * \param ad_length Size of the non-encrypted additional 2482 * authenticated data in bytes. 2483 * \param plaintext_length Size of the plaintext to encrypt in bytes. 2484 * 2485 * \retval #PSA_SUCCESS 2486 * Success. 2487 * \retval #PSA_ERROR_INVALID_ARGUMENT 2488 * At least one of the lengths is not acceptable for the chosen 2489 * algorithm. 2490 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 2491 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2492 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2493 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2494 * \retval #PSA_ERROR_BAD_STATE 2495 * The operation state is not valid (it must be active, and 2496 * psa_aead_update_ad() and psa_aead_update() must not have been 2497 * called yet), or the library has not been previously initialized 2498 * by psa_crypto_init(). 2499 * It is implementation-dependent whether a failure to initialize 2500 * results in this error code. 2501 */ 2502 psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation, 2503 size_t ad_length, 2504 size_t plaintext_length); 2505 2506 /** Pass additional data to an active AEAD operation. 2507 * 2508 * Additional data is authenticated, but not encrypted. 2509 * 2510 * You may call this function multiple times to pass successive fragments 2511 * of the additional data. You may not call this function after passing 2512 * data to encrypt or decrypt with psa_aead_update(). 2513 * 2514 * Before calling this function, you must: 2515 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup(). 2516 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce(). 2517 * 2518 * If this function returns an error status, the operation enters an error 2519 * state and must be aborted by calling psa_aead_abort(). 2520 * 2521 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS, 2522 * there is no guarantee that the input is valid. Therefore, until 2523 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS, 2524 * treat the input as untrusted and prepare to undo any action that 2525 * depends on the input if psa_aead_verify() returns an error status. 2526 * 2527 * \param[in,out] operation Active AEAD operation. 2528 * \param[in] input Buffer containing the fragment of 2529 * additional data. 2530 * \param input_length Size of the \p input buffer in bytes. 2531 * 2532 * \retval #PSA_SUCCESS 2533 * Success. 2534 * \retval #PSA_ERROR_INVALID_ARGUMENT 2535 * The total input length overflows the additional data length that 2536 * was previously specified with psa_aead_set_lengths(). 2537 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 2538 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2539 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2540 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2541 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 2542 * \retval #PSA_ERROR_BAD_STATE 2543 * The operation state is not valid (it must be active, have a nonce 2544 * set, have lengths set if required by the algorithm, and 2545 * psa_aead_update() must not have been called yet), or the library 2546 * has not been previously initialized by psa_crypto_init(). 2547 * It is implementation-dependent whether a failure to initialize 2548 * results in this error code. 2549 */ 2550 psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation, 2551 const uint8_t *input, 2552 size_t input_length); 2553 2554 /** Encrypt or decrypt a message fragment in an active AEAD operation. 2555 * 2556 * Before calling this function, you must: 2557 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup(). 2558 * The choice of setup function determines whether this function 2559 * encrypts or decrypts its input. 2560 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce(). 2561 * 3. Call psa_aead_update_ad() to pass all the additional data. 2562 * 2563 * If this function returns an error status, the operation enters an error 2564 * state and must be aborted by calling psa_aead_abort(). 2565 * 2566 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS, 2567 * there is no guarantee that the input is valid. Therefore, until 2568 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS: 2569 * - Do not use the output in any way other than storing it in a 2570 * confidential location. If you take any action that depends 2571 * on the tentative decrypted data, this action will need to be 2572 * undone if the input turns out not to be valid. Furthermore, 2573 * if an adversary can observe that this action took place 2574 * (for example through timing), they may be able to use this 2575 * fact as an oracle to decrypt any message encrypted with the 2576 * same key. 2577 * - In particular, do not copy the output anywhere but to a 2578 * memory or storage space that you have exclusive access to. 2579 * 2580 * This function does not require the input to be aligned to any 2581 * particular block boundary. If the implementation can only process 2582 * a whole block at a time, it must consume all the input provided, but 2583 * it may delay the end of the corresponding output until a subsequent 2584 * call to psa_aead_update(), psa_aead_finish() or psa_aead_verify() 2585 * provides sufficient input. The amount of data that can be delayed 2586 * in this way is bounded by #PSA_AEAD_UPDATE_OUTPUT_SIZE. 2587 * 2588 * \param[in,out] operation Active AEAD operation. 2589 * \param[in] input Buffer containing the message fragment to 2590 * encrypt or decrypt. 2591 * \param input_length Size of the \p input buffer in bytes. 2592 * \param[out] output Buffer where the output is to be written. 2593 * \param output_size Size of the \p output buffer in bytes. 2594 * This must be appropriate for the selected 2595 * algorithm and key: 2596 * - A sufficient output size is 2597 * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c key_type, 2598 * \c alg, \p input_length) where 2599 * \c key_type is the type of key and \c alg is 2600 * the algorithm that were used to set up the 2601 * operation. 2602 * - #PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(\p 2603 * input_length) evaluates to the maximum 2604 * output size of any supported AEAD 2605 * algorithm. 2606 * \param[out] output_length On success, the number of bytes 2607 * that make up the returned output. 2608 * 2609 * \retval #PSA_SUCCESS 2610 * Success. 2611 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 2612 * The size of the \p output buffer is too small. 2613 * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c key_type, \c alg, \p input_length) or 2614 * #PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(\p input_length) can be used to 2615 * determine the required buffer size. 2616 * \retval #PSA_ERROR_INVALID_ARGUMENT 2617 * The total length of input to psa_aead_update_ad() so far is 2618 * less than the additional data length that was previously 2619 * specified with psa_aead_set_lengths(), or 2620 * the total input length overflows the plaintext length that 2621 * was previously specified with psa_aead_set_lengths(). 2622 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 2623 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2624 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2625 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2626 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 2627 * \retval #PSA_ERROR_BAD_STATE 2628 * The operation state is not valid (it must be active, have a nonce 2629 * set, and have lengths set if required by the algorithm), or the 2630 * library has not been previously initialized by psa_crypto_init(). 2631 * It is implementation-dependent whether a failure to initialize 2632 * results in this error code. 2633 */ 2634 psa_status_t psa_aead_update(psa_aead_operation_t *operation, 2635 const uint8_t *input, 2636 size_t input_length, 2637 uint8_t *output, 2638 size_t output_size, 2639 size_t *output_length); 2640 2641 /** Finish encrypting a message in an AEAD operation. 2642 * 2643 * The operation must have been set up with psa_aead_encrypt_setup(). 2644 * 2645 * This function finishes the authentication of the additional data 2646 * formed by concatenating the inputs passed to preceding calls to 2647 * psa_aead_update_ad() with the plaintext formed by concatenating the 2648 * inputs passed to preceding calls to psa_aead_update(). 2649 * 2650 * This function has two output buffers: 2651 * - \p ciphertext contains trailing ciphertext that was buffered from 2652 * preceding calls to psa_aead_update(). 2653 * - \p tag contains the authentication tag. 2654 * 2655 * When this function returns successfully, the operation becomes inactive. 2656 * If this function returns an error status, the operation enters an error 2657 * state and must be aborted by calling psa_aead_abort(). 2658 * 2659 * \param[in,out] operation Active AEAD operation. 2660 * \param[out] ciphertext Buffer where the last part of the ciphertext 2661 * is to be written. 2662 * \param ciphertext_size Size of the \p ciphertext buffer in bytes. 2663 * This must be appropriate for the selected 2664 * algorithm and key: 2665 * - A sufficient output size is 2666 * #PSA_AEAD_FINISH_OUTPUT_SIZE(\c key_type, 2667 * \c alg) where \c key_type is the type of key 2668 * and \c alg is the algorithm that were used to 2669 * set up the operation. 2670 * - #PSA_AEAD_FINISH_OUTPUT_MAX_SIZE evaluates to 2671 * the maximum output size of any supported AEAD 2672 * algorithm. 2673 * \param[out] ciphertext_length On success, the number of bytes of 2674 * returned ciphertext. 2675 * \param[out] tag Buffer where the authentication tag is 2676 * to be written. 2677 * \param tag_size Size of the \p tag buffer in bytes. 2678 * This must be appropriate for the selected 2679 * algorithm and key: 2680 * - The exact tag size is #PSA_AEAD_TAG_LENGTH(\c 2681 * key_type, \c key_bits, \c alg) where 2682 * \c key_type and \c key_bits are the type and 2683 * bit-size of the key, and \c alg is the 2684 * algorithm that were used in the call to 2685 * psa_aead_encrypt_setup(). 2686 * - #PSA_AEAD_TAG_MAX_SIZE evaluates to the 2687 * maximum tag size of any supported AEAD 2688 * algorithm. 2689 * \param[out] tag_length On success, the number of bytes 2690 * that make up the returned tag. 2691 * 2692 * \retval #PSA_SUCCESS 2693 * Success. 2694 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 2695 * The size of the \p ciphertext or \p tag buffer is too small. 2696 * #PSA_AEAD_FINISH_OUTPUT_SIZE(\c key_type, \c alg) or 2697 * #PSA_AEAD_FINISH_OUTPUT_MAX_SIZE can be used to determine the 2698 * required \p ciphertext buffer size. #PSA_AEAD_TAG_LENGTH(\c key_type, 2699 * \c key_bits, \c alg) or #PSA_AEAD_TAG_MAX_SIZE can be used to 2700 * determine the required \p tag buffer size. 2701 * \retval #PSA_ERROR_INVALID_ARGUMENT 2702 * The total length of input to psa_aead_update_ad() so far is 2703 * less than the additional data length that was previously 2704 * specified with psa_aead_set_lengths(), or 2705 * the total length of input to psa_aead_update() so far is 2706 * less than the plaintext length that was previously 2707 * specified with psa_aead_set_lengths(). 2708 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 2709 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2710 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2711 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2712 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 2713 * \retval #PSA_ERROR_BAD_STATE 2714 * The operation state is not valid (it must be an active encryption 2715 * operation with a nonce set), or the library has not been previously 2716 * initialized by psa_crypto_init(). 2717 * It is implementation-dependent whether a failure to initialize 2718 * results in this error code. 2719 */ 2720 psa_status_t psa_aead_finish(psa_aead_operation_t *operation, 2721 uint8_t *ciphertext, 2722 size_t ciphertext_size, 2723 size_t *ciphertext_length, 2724 uint8_t *tag, 2725 size_t tag_size, 2726 size_t *tag_length); 2727 2728 /** Finish authenticating and decrypting a message in an AEAD operation. 2729 * 2730 * The operation must have been set up with psa_aead_decrypt_setup(). 2731 * 2732 * This function finishes the authenticated decryption of the message 2733 * components: 2734 * 2735 * - The additional data consisting of the concatenation of the inputs 2736 * passed to preceding calls to psa_aead_update_ad(). 2737 * - The ciphertext consisting of the concatenation of the inputs passed to 2738 * preceding calls to psa_aead_update(). 2739 * - The tag passed to this function call. 2740 * 2741 * If the authentication tag is correct, this function outputs any remaining 2742 * plaintext and reports success. If the authentication tag is not correct, 2743 * this function returns #PSA_ERROR_INVALID_SIGNATURE. 2744 * 2745 * When this function returns successfully, the operation becomes inactive. 2746 * If this function returns an error status, the operation enters an error 2747 * state and must be aborted by calling psa_aead_abort(). 2748 * 2749 * \note Implementations shall make the best effort to ensure that the 2750 * comparison between the actual tag and the expected tag is performed 2751 * in constant time. 2752 * 2753 * \param[in,out] operation Active AEAD operation. 2754 * \param[out] plaintext Buffer where the last part of the plaintext 2755 * is to be written. This is the remaining data 2756 * from previous calls to psa_aead_update() 2757 * that could not be processed until the end 2758 * of the input. 2759 * \param plaintext_size Size of the \p plaintext buffer in bytes. 2760 * This must be appropriate for the selected algorithm and key: 2761 * - A sufficient output size is 2762 * #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c key_type, 2763 * \c alg) where \c key_type is the type of key 2764 * and \c alg is the algorithm that were used to 2765 * set up the operation. 2766 * - #PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE evaluates to 2767 * the maximum output size of any supported AEAD 2768 * algorithm. 2769 * \param[out] plaintext_length On success, the number of bytes of 2770 * returned plaintext. 2771 * \param[in] tag Buffer containing the authentication tag. 2772 * \param tag_length Size of the \p tag buffer in bytes. 2773 * 2774 * \retval #PSA_SUCCESS 2775 * Success. 2776 * \retval #PSA_ERROR_INVALID_SIGNATURE 2777 * The calculations were successful, but the authentication tag is 2778 * not correct. 2779 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 2780 * The size of the \p plaintext buffer is too small. 2781 * #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c key_type, \c alg) or 2782 * #PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE can be used to determine the 2783 * required buffer size. 2784 * \retval #PSA_ERROR_INVALID_ARGUMENT 2785 * The total length of input to psa_aead_update_ad() so far is 2786 * less than the additional data length that was previously 2787 * specified with psa_aead_set_lengths(), or 2788 * the total length of input to psa_aead_update() so far is 2789 * less than the plaintext length that was previously 2790 * specified with psa_aead_set_lengths(). 2791 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 2792 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2793 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2794 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2795 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 2796 * \retval #PSA_ERROR_BAD_STATE 2797 * The operation state is not valid (it must be an active decryption 2798 * operation with a nonce set), or the library has not been previously 2799 * initialized by psa_crypto_init(). 2800 * It is implementation-dependent whether a failure to initialize 2801 * results in this error code. 2802 */ 2803 psa_status_t psa_aead_verify(psa_aead_operation_t *operation, 2804 uint8_t *plaintext, 2805 size_t plaintext_size, 2806 size_t *plaintext_length, 2807 const uint8_t *tag, 2808 size_t tag_length); 2809 2810 /** Abort an AEAD operation. 2811 * 2812 * Aborting an operation frees all associated resources except for the 2813 * \p operation structure itself. Once aborted, the operation object 2814 * can be reused for another operation by calling 2815 * psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again. 2816 * 2817 * You may call this function any time after the operation object has 2818 * been initialized as described in #psa_aead_operation_t. 2819 * 2820 * In particular, calling psa_aead_abort() after the operation has been 2821 * terminated by a call to psa_aead_abort(), psa_aead_finish() or 2822 * psa_aead_verify() is safe and has no effect. 2823 * 2824 * \param[in,out] operation Initialized AEAD operation. 2825 * 2826 * \retval #PSA_SUCCESS \emptydescription 2827 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2828 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2829 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2830 * \retval #PSA_ERROR_BAD_STATE 2831 * The library has not been previously initialized by psa_crypto_init(). 2832 * It is implementation-dependent whether a failure to initialize 2833 * results in this error code. 2834 */ 2835 psa_status_t psa_aead_abort(psa_aead_operation_t *operation); 2836 2837 /**@}*/ 2838 2839 /** \defgroup asymmetric Asymmetric cryptography 2840 * @{ 2841 */ 2842 2843 /** 2844 * \brief Sign a message with a private key. For hash-and-sign algorithms, 2845 * this includes the hashing step. 2846 * 2847 * \note To perform a multi-part hash-and-sign signature algorithm, first use 2848 * a multi-part hash operation and then pass the resulting hash to 2849 * psa_sign_hash(). PSA_ALG_GET_HASH(\p alg) can be used to determine the 2850 * hash algorithm to use. 2851 * 2852 * \param[in] key Identifier of the key to use for the operation. 2853 * It must be an asymmetric key pair. The key must 2854 * allow the usage #PSA_KEY_USAGE_SIGN_MESSAGE. 2855 * \param[in] alg An asymmetric signature algorithm (PSA_ALG_XXX 2856 * value such that #PSA_ALG_IS_SIGN_MESSAGE(\p alg) 2857 * is true), that is compatible with the type of 2858 * \p key. 2859 * \param[in] input The input message to sign. 2860 * \param[in] input_length Size of the \p input buffer in bytes. 2861 * \param[out] signature Buffer where the signature is to be written. 2862 * \param[in] signature_size Size of the \p signature buffer in bytes. This 2863 * must be appropriate for the selected 2864 * algorithm and key: 2865 * - The required signature size is 2866 * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) 2867 * where \c key_type and \c key_bits are the type and 2868 * bit-size respectively of key. 2869 * - #PSA_SIGNATURE_MAX_SIZE evaluates to the 2870 * maximum signature size of any supported 2871 * signature algorithm. 2872 * \param[out] signature_length On success, the number of bytes that make up 2873 * the returned signature value. 2874 * 2875 * \retval #PSA_SUCCESS \emptydescription 2876 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 2877 * \retval #PSA_ERROR_NOT_PERMITTED 2878 * The key does not have the #PSA_KEY_USAGE_SIGN_MESSAGE flag, 2879 * or it does not permit the requested algorithm. 2880 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 2881 * The size of the \p signature buffer is too small. You can 2882 * determine a sufficient buffer size by calling 2883 * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) 2884 * where \c key_type and \c key_bits are the type and bit-size 2885 * respectively of \p key. 2886 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 2887 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 2888 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 2889 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2890 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2891 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2892 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 2893 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 2894 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 2895 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 2896 * \retval #PSA_ERROR_BAD_STATE 2897 * The library has not been previously initialized by psa_crypto_init(). 2898 * It is implementation-dependent whether a failure to initialize 2899 * results in this error code. 2900 */ 2901 psa_status_t psa_sign_message(mbedtls_svc_key_id_t key, 2902 psa_algorithm_t alg, 2903 const uint8_t *input, 2904 size_t input_length, 2905 uint8_t *signature, 2906 size_t signature_size, 2907 size_t *signature_length); 2908 2909 /** \brief Verify the signature of a message with a public key, using 2910 * a hash-and-sign verification algorithm. 2911 * 2912 * \note To perform a multi-part hash-and-sign signature verification 2913 * algorithm, first use a multi-part hash operation to hash the message 2914 * and then pass the resulting hash to psa_verify_hash(). 2915 * PSA_ALG_GET_HASH(\p alg) can be used to determine the hash algorithm 2916 * to use. 2917 * 2918 * \param[in] key Identifier of the key to use for the operation. 2919 * It must be a public key or an asymmetric key 2920 * pair. The key must allow the usage 2921 * #PSA_KEY_USAGE_VERIFY_MESSAGE. 2922 * \param[in] alg An asymmetric signature algorithm (PSA_ALG_XXX 2923 * value such that #PSA_ALG_IS_SIGN_MESSAGE(\p alg) 2924 * is true), that is compatible with the type of 2925 * \p key. 2926 * \param[in] input The message whose signature is to be verified. 2927 * \param[in] input_length Size of the \p input buffer in bytes. 2928 * \param[in] signature Buffer containing the signature to verify. 2929 * \param[in] signature_length Size of the \p signature buffer in bytes. 2930 * 2931 * \retval #PSA_SUCCESS \emptydescription 2932 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 2933 * \retval #PSA_ERROR_NOT_PERMITTED 2934 * The key does not have the #PSA_KEY_USAGE_SIGN_MESSAGE flag, 2935 * or it does not permit the requested algorithm. 2936 * \retval #PSA_ERROR_INVALID_SIGNATURE 2937 * The calculation was performed successfully, but the passed signature 2938 * is not a valid signature. 2939 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 2940 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 2941 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 2942 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2943 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2944 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2945 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 2946 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 2947 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 2948 * \retval #PSA_ERROR_BAD_STATE 2949 * The library has not been previously initialized by psa_crypto_init(). 2950 * It is implementation-dependent whether a failure to initialize 2951 * results in this error code. 2952 */ 2953 psa_status_t psa_verify_message(mbedtls_svc_key_id_t key, 2954 psa_algorithm_t alg, 2955 const uint8_t *input, 2956 size_t input_length, 2957 const uint8_t *signature, 2958 size_t signature_length); 2959 2960 /** 2961 * \brief Sign a hash or short message with a private key. 2962 * 2963 * Note that to perform a hash-and-sign signature algorithm, you must 2964 * first calculate the hash by calling psa_hash_setup(), psa_hash_update() 2965 * and psa_hash_finish(), or alternatively by calling psa_hash_compute(). 2966 * Then pass the resulting hash as the \p hash 2967 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg) 2968 * to determine the hash algorithm to use. 2969 * 2970 * \param key Identifier of the key to use for the operation. 2971 * It must be an asymmetric key pair. The key must 2972 * allow the usage #PSA_KEY_USAGE_SIGN_HASH. 2973 * \param alg A signature algorithm (PSA_ALG_XXX 2974 * value such that #PSA_ALG_IS_SIGN_HASH(\p alg) 2975 * is true), that is compatible with 2976 * the type of \p key. 2977 * \param[in] hash The hash or message to sign. 2978 * \param hash_length Size of the \p hash buffer in bytes. 2979 * \param[out] signature Buffer where the signature is to be written. 2980 * \param signature_size Size of the \p signature buffer in bytes. 2981 * \param[out] signature_length On success, the number of bytes 2982 * that make up the returned signature value. 2983 * 2984 * \retval #PSA_SUCCESS \emptydescription 2985 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 2986 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 2987 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 2988 * The size of the \p signature buffer is too small. You can 2989 * determine a sufficient buffer size by calling 2990 * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) 2991 * where \c key_type and \c key_bits are the type and bit-size 2992 * respectively of \p key. 2993 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 2994 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 2995 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 2996 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 2997 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 2998 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 2999 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 3000 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 3001 * \retval #PSA_ERROR_BAD_STATE 3002 * The library has not been previously initialized by psa_crypto_init(). 3003 * It is implementation-dependent whether a failure to initialize 3004 * results in this error code. 3005 */ 3006 psa_status_t psa_sign_hash(mbedtls_svc_key_id_t key, 3007 psa_algorithm_t alg, 3008 const uint8_t *hash, 3009 size_t hash_length, 3010 uint8_t *signature, 3011 size_t signature_size, 3012 size_t *signature_length); 3013 3014 /** 3015 * \brief Verify the signature of a hash or short message using a public key. 3016 * 3017 * Note that to perform a hash-and-sign signature algorithm, you must 3018 * first calculate the hash by calling psa_hash_setup(), psa_hash_update() 3019 * and psa_hash_finish(), or alternatively by calling psa_hash_compute(). 3020 * Then pass the resulting hash as the \p hash 3021 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg) 3022 * to determine the hash algorithm to use. 3023 * 3024 * \param key Identifier of the key to use for the operation. It 3025 * must be a public key or an asymmetric key pair. The 3026 * key must allow the usage 3027 * #PSA_KEY_USAGE_VERIFY_HASH. 3028 * \param alg A signature algorithm (PSA_ALG_XXX 3029 * value such that #PSA_ALG_IS_SIGN_HASH(\p alg) 3030 * is true), that is compatible with 3031 * the type of \p key. 3032 * \param[in] hash The hash or message whose signature is to be 3033 * verified. 3034 * \param hash_length Size of the \p hash buffer in bytes. 3035 * \param[in] signature Buffer containing the signature to verify. 3036 * \param signature_length Size of the \p signature buffer in bytes. 3037 * 3038 * \retval #PSA_SUCCESS 3039 * The signature is valid. 3040 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 3041 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 3042 * \retval #PSA_ERROR_INVALID_SIGNATURE 3043 * The calculation was performed successfully, but the passed 3044 * signature is not a valid signature. 3045 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 3046 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 3047 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 3048 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 3049 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 3050 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 3051 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 3052 * \retval #PSA_ERROR_BAD_STATE 3053 * The library has not been previously initialized by psa_crypto_init(). 3054 * It is implementation-dependent whether a failure to initialize 3055 * results in this error code. 3056 */ 3057 psa_status_t psa_verify_hash(mbedtls_svc_key_id_t key, 3058 psa_algorithm_t alg, 3059 const uint8_t *hash, 3060 size_t hash_length, 3061 const uint8_t *signature, 3062 size_t signature_length); 3063 3064 /** 3065 * \brief Encrypt a short message with a public key. 3066 * 3067 * \param key Identifier of the key to use for the operation. 3068 * It must be a public key or an asymmetric key 3069 * pair. It must allow the usage 3070 * #PSA_KEY_USAGE_ENCRYPT. 3071 * \param alg An asymmetric encryption algorithm that is 3072 * compatible with the type of \p key. 3073 * \param[in] input The message to encrypt. 3074 * \param input_length Size of the \p input buffer in bytes. 3075 * \param[in] salt A salt or label, if supported by the 3076 * encryption algorithm. 3077 * If the algorithm does not support a 3078 * salt, pass \c NULL. 3079 * If the algorithm supports an optional 3080 * salt and you do not want to pass a salt, 3081 * pass \c NULL. 3082 * 3083 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is 3084 * supported. 3085 * \param salt_length Size of the \p salt buffer in bytes. 3086 * If \p salt is \c NULL, pass 0. 3087 * \param[out] output Buffer where the encrypted message is to 3088 * be written. 3089 * \param output_size Size of the \p output buffer in bytes. 3090 * \param[out] output_length On success, the number of bytes 3091 * that make up the returned output. 3092 * 3093 * \retval #PSA_SUCCESS \emptydescription 3094 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 3095 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 3096 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 3097 * The size of the \p output buffer is too small. You can 3098 * determine a sufficient buffer size by calling 3099 * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) 3100 * where \c key_type and \c key_bits are the type and bit-size 3101 * respectively of \p key. 3102 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 3103 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 3104 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 3105 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 3106 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 3107 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 3108 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 3109 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 3110 * \retval #PSA_ERROR_BAD_STATE 3111 * The library has not been previously initialized by psa_crypto_init(). 3112 * It is implementation-dependent whether a failure to initialize 3113 * results in this error code. 3114 */ 3115 psa_status_t psa_asymmetric_encrypt(mbedtls_svc_key_id_t key, 3116 psa_algorithm_t alg, 3117 const uint8_t *input, 3118 size_t input_length, 3119 const uint8_t *salt, 3120 size_t salt_length, 3121 uint8_t *output, 3122 size_t output_size, 3123 size_t *output_length); 3124 3125 /** 3126 * \brief Decrypt a short message with a private key. 3127 * 3128 * \param key Identifier of the key to use for the operation. 3129 * It must be an asymmetric key pair. It must 3130 * allow the usage #PSA_KEY_USAGE_DECRYPT. 3131 * \param alg An asymmetric encryption algorithm that is 3132 * compatible with the type of \p key. 3133 * \param[in] input The message to decrypt. 3134 * \param input_length Size of the \p input buffer in bytes. 3135 * \param[in] salt A salt or label, if supported by the 3136 * encryption algorithm. 3137 * If the algorithm does not support a 3138 * salt, pass \c NULL. 3139 * If the algorithm supports an optional 3140 * salt and you do not want to pass a salt, 3141 * pass \c NULL. 3142 * 3143 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is 3144 * supported. 3145 * \param salt_length Size of the \p salt buffer in bytes. 3146 * If \p salt is \c NULL, pass 0. 3147 * \param[out] output Buffer where the decrypted message is to 3148 * be written. 3149 * \param output_size Size of the \c output buffer in bytes. 3150 * \param[out] output_length On success, the number of bytes 3151 * that make up the returned output. 3152 * 3153 * \retval #PSA_SUCCESS \emptydescription 3154 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 3155 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 3156 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 3157 * The size of the \p output buffer is too small. You can 3158 * determine a sufficient buffer size by calling 3159 * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) 3160 * where \c key_type and \c key_bits are the type and bit-size 3161 * respectively of \p key. 3162 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 3163 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 3164 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 3165 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 3166 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 3167 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 3168 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 3169 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 3170 * \retval #PSA_ERROR_INVALID_PADDING \emptydescription 3171 * \retval #PSA_ERROR_BAD_STATE 3172 * The library has not been previously initialized by psa_crypto_init(). 3173 * It is implementation-dependent whether a failure to initialize 3174 * results in this error code. 3175 */ 3176 psa_status_t psa_asymmetric_decrypt(mbedtls_svc_key_id_t key, 3177 psa_algorithm_t alg, 3178 const uint8_t *input, 3179 size_t input_length, 3180 const uint8_t *salt, 3181 size_t salt_length, 3182 uint8_t *output, 3183 size_t output_size, 3184 size_t *output_length); 3185 3186 /**@}*/ 3187 3188 /** \defgroup key_derivation Key derivation and pseudorandom generation 3189 * @{ 3190 */ 3191 3192 /** The type of the state data structure for key derivation operations. 3193 * 3194 * Before calling any function on a key derivation operation object, the 3195 * application must initialize it by any of the following means: 3196 * - Set the structure to all-bits-zero, for example: 3197 * \code 3198 * psa_key_derivation_operation_t operation; 3199 * memset(&operation, 0, sizeof(operation)); 3200 * \endcode 3201 * - Initialize the structure to logical zero values, for example: 3202 * \code 3203 * psa_key_derivation_operation_t operation = {0}; 3204 * \endcode 3205 * - Initialize the structure to the initializer #PSA_KEY_DERIVATION_OPERATION_INIT, 3206 * for example: 3207 * \code 3208 * psa_key_derivation_operation_t operation = PSA_KEY_DERIVATION_OPERATION_INIT; 3209 * \endcode 3210 * - Assign the result of the function psa_key_derivation_operation_init() 3211 * to the structure, for example: 3212 * \code 3213 * psa_key_derivation_operation_t operation; 3214 * operation = psa_key_derivation_operation_init(); 3215 * \endcode 3216 * 3217 * This is an implementation-defined \c struct. Applications should not 3218 * make any assumptions about the content of this structure. 3219 * Implementation details can change in future versions without notice. 3220 */ 3221 typedef struct psa_key_derivation_s psa_key_derivation_operation_t; 3222 3223 /** \def PSA_KEY_DERIVATION_OPERATION_INIT 3224 * 3225 * This macro returns a suitable initializer for a key derivation operation 3226 * object of type #psa_key_derivation_operation_t. 3227 */ 3228 3229 /** Return an initial value for a key derivation operation object. 3230 */ 3231 static psa_key_derivation_operation_t psa_key_derivation_operation_init(void); 3232 3233 /** Set up a key derivation operation. 3234 * 3235 * A key derivation algorithm takes some inputs and uses them to generate 3236 * a byte stream in a deterministic way. 3237 * This byte stream can be used to produce keys and other 3238 * cryptographic material. 3239 * 3240 * To derive a key: 3241 * -# Start with an initialized object of type #psa_key_derivation_operation_t. 3242 * -# Call psa_key_derivation_setup() to select the algorithm. 3243 * -# Provide the inputs for the key derivation by calling 3244 * psa_key_derivation_input_bytes() or psa_key_derivation_input_key() 3245 * as appropriate. Which inputs are needed, in what order, and whether 3246 * they may be keys and if so of what type depends on the algorithm. 3247 * -# Optionally set the operation's maximum capacity with 3248 * psa_key_derivation_set_capacity(). You may do this before, in the middle 3249 * of or after providing inputs. For some algorithms, this step is mandatory 3250 * because the output depends on the maximum capacity. 3251 * -# To derive a key, call psa_key_derivation_output_key() or 3252 * psa_key_derivation_output_key_custom(). 3253 * To derive a byte string for a different purpose, call 3254 * psa_key_derivation_output_bytes(). 3255 * Successive calls to these functions use successive output bytes 3256 * calculated by the key derivation algorithm. 3257 * -# Clean up the key derivation operation object with 3258 * psa_key_derivation_abort(). 3259 * 3260 * If this function returns an error, the key derivation operation object is 3261 * not changed. 3262 * 3263 * If an error occurs at any step after a call to psa_key_derivation_setup(), 3264 * the operation will need to be reset by a call to psa_key_derivation_abort(). 3265 * 3266 * Implementations must reject an attempt to derive a key of size 0. 3267 * 3268 * \param[in,out] operation The key derivation operation object 3269 * to set up. It must 3270 * have been initialized but not set up yet. 3271 * \param alg The key derivation algorithm to compute 3272 * (\c PSA_ALG_XXX value such that 3273 * #PSA_ALG_IS_KEY_DERIVATION(\p alg) is true). 3274 * 3275 * \retval #PSA_SUCCESS 3276 * Success. 3277 * \retval #PSA_ERROR_INVALID_ARGUMENT 3278 * \c alg is not a key derivation algorithm. 3279 * \retval #PSA_ERROR_NOT_SUPPORTED 3280 * \c alg is not supported or is not a key derivation algorithm. 3281 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 3282 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 3283 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 3284 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 3285 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 3286 * \retval #PSA_ERROR_BAD_STATE 3287 * The operation state is not valid (it must be inactive), or 3288 * the library has not been previously initialized by psa_crypto_init(). 3289 * It is implementation-dependent whether a failure to initialize 3290 * results in this error code. 3291 */ 3292 psa_status_t psa_key_derivation_setup( 3293 psa_key_derivation_operation_t *operation, 3294 psa_algorithm_t alg); 3295 3296 /** Retrieve the current capacity of a key derivation operation. 3297 * 3298 * The capacity of a key derivation is the maximum number of bytes that it can 3299 * return. When you get *N* bytes of output from a key derivation operation, 3300 * this reduces its capacity by *N*. 3301 * 3302 * \param[in] operation The operation to query. 3303 * \param[out] capacity On success, the capacity of the operation. 3304 * 3305 * \retval #PSA_SUCCESS \emptydescription 3306 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 3307 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 3308 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 3309 * \retval #PSA_ERROR_BAD_STATE 3310 * The operation state is not valid (it must be active), or 3311 * the library has not been previously initialized by psa_crypto_init(). 3312 * It is implementation-dependent whether a failure to initialize 3313 * results in this error code. 3314 */ 3315 psa_status_t psa_key_derivation_get_capacity( 3316 const psa_key_derivation_operation_t *operation, 3317 size_t *capacity); 3318 3319 /** Set the maximum capacity of a key derivation operation. 3320 * 3321 * The capacity of a key derivation operation is the maximum number of bytes 3322 * that the key derivation operation can return from this point onwards. 3323 * 3324 * \param[in,out] operation The key derivation operation object to modify. 3325 * \param capacity The new capacity of the operation. 3326 * It must be less or equal to the operation's 3327 * current capacity. 3328 * 3329 * \retval #PSA_SUCCESS \emptydescription 3330 * \retval #PSA_ERROR_INVALID_ARGUMENT 3331 * \p capacity is larger than the operation's current capacity. 3332 * In this case, the operation object remains valid and its capacity 3333 * remains unchanged. 3334 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 3335 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 3336 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 3337 * \retval #PSA_ERROR_BAD_STATE 3338 * The operation state is not valid (it must be active), or the 3339 * library has not been previously initialized by psa_crypto_init(). 3340 * It is implementation-dependent whether a failure to initialize 3341 * results in this error code. 3342 */ 3343 psa_status_t psa_key_derivation_set_capacity( 3344 psa_key_derivation_operation_t *operation, 3345 size_t capacity); 3346 3347 /** Use the maximum possible capacity for a key derivation operation. 3348 * 3349 * Use this value as the capacity argument when setting up a key derivation 3350 * to indicate that the operation should have the maximum possible capacity. 3351 * The value of the maximum possible capacity depends on the key derivation 3352 * algorithm. 3353 */ 3354 #define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY ((size_t) (-1)) 3355 3356 /** Provide an input for key derivation or key agreement. 3357 * 3358 * Which inputs are required and in what order depends on the algorithm. 3359 * Refer to the documentation of each key derivation or key agreement 3360 * algorithm for information. 3361 * 3362 * This function passes direct inputs, which is usually correct for 3363 * non-secret inputs. To pass a secret input, which should be in a key 3364 * object, call psa_key_derivation_input_key() instead of this function. 3365 * Refer to the documentation of individual step types 3366 * (`PSA_KEY_DERIVATION_INPUT_xxx` values of type ::psa_key_derivation_step_t) 3367 * for more information. 3368 * 3369 * If this function returns an error status, the operation enters an error 3370 * state and must be aborted by calling psa_key_derivation_abort(). 3371 * 3372 * \param[in,out] operation The key derivation operation object to use. 3373 * It must have been set up with 3374 * psa_key_derivation_setup() and must not 3375 * have produced any output yet. 3376 * \param step Which step the input data is for. 3377 * \param[in] data Input data to use. 3378 * \param data_length Size of the \p data buffer in bytes. 3379 * 3380 * \retval #PSA_SUCCESS 3381 * Success. 3382 * \retval #PSA_ERROR_INVALID_ARGUMENT 3383 * \c step is not compatible with the operation's algorithm, or 3384 * \c step does not allow direct inputs. 3385 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 3386 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 3387 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 3388 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 3389 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 3390 * \retval #PSA_ERROR_BAD_STATE 3391 * The operation state is not valid for this input \p step, or 3392 * the library has not been previously initialized by psa_crypto_init(). 3393 * It is implementation-dependent whether a failure to initialize 3394 * results in this error code. 3395 */ 3396 psa_status_t psa_key_derivation_input_bytes( 3397 psa_key_derivation_operation_t *operation, 3398 psa_key_derivation_step_t step, 3399 const uint8_t *data, 3400 size_t data_length); 3401 3402 /** Provide a numeric input for key derivation or key agreement. 3403 * 3404 * Which inputs are required and in what order depends on the algorithm. 3405 * However, when an algorithm requires a particular order, numeric inputs 3406 * usually come first as they tend to be configuration parameters. 3407 * Refer to the documentation of each key derivation or key agreement 3408 * algorithm for information. 3409 * 3410 * This function is used for inputs which are fixed-size non-negative 3411 * integers. 3412 * 3413 * If this function returns an error status, the operation enters an error 3414 * state and must be aborted by calling psa_key_derivation_abort(). 3415 * 3416 * \param[in,out] operation The key derivation operation object to use. 3417 * It must have been set up with 3418 * psa_key_derivation_setup() and must not 3419 * have produced any output yet. 3420 * \param step Which step the input data is for. 3421 * \param[in] value The value of the numeric input. 3422 * 3423 * \retval #PSA_SUCCESS 3424 * Success. 3425 * \retval #PSA_ERROR_INVALID_ARGUMENT 3426 * \c step is not compatible with the operation's algorithm, or 3427 * \c step does not allow numeric inputs. 3428 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 3429 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 3430 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 3431 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 3432 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 3433 * \retval #PSA_ERROR_BAD_STATE 3434 * The operation state is not valid for this input \p step, or 3435 * the library has not been previously initialized by psa_crypto_init(). 3436 * It is implementation-dependent whether a failure to initialize 3437 * results in this error code. 3438 */ 3439 psa_status_t psa_key_derivation_input_integer( 3440 psa_key_derivation_operation_t *operation, 3441 psa_key_derivation_step_t step, 3442 uint64_t value); 3443 3444 /** Provide an input for key derivation in the form of a key. 3445 * 3446 * Which inputs are required and in what order depends on the algorithm. 3447 * Refer to the documentation of each key derivation or key agreement 3448 * algorithm for information. 3449 * 3450 * This function obtains input from a key object, which is usually correct for 3451 * secret inputs or for non-secret personalization strings kept in the key 3452 * store. To pass a non-secret parameter which is not in the key store, 3453 * call psa_key_derivation_input_bytes() instead of this function. 3454 * Refer to the documentation of individual step types 3455 * (`PSA_KEY_DERIVATION_INPUT_xxx` values of type ::psa_key_derivation_step_t) 3456 * for more information. 3457 * 3458 * If this function returns an error status, the operation enters an error 3459 * state and must be aborted by calling psa_key_derivation_abort(). 3460 * 3461 * \param[in,out] operation The key derivation operation object to use. 3462 * It must have been set up with 3463 * psa_key_derivation_setup() and must not 3464 * have produced any output yet. 3465 * \param step Which step the input data is for. 3466 * \param key Identifier of the key. It must have an 3467 * appropriate type for step and must allow the 3468 * usage #PSA_KEY_USAGE_DERIVE or 3469 * #PSA_KEY_USAGE_VERIFY_DERIVATION (see note) 3470 * and the algorithm used by the operation. 3471 * 3472 * \note Once all inputs steps are completed, the operations will allow: 3473 * - psa_key_derivation_output_bytes() if each input was either a direct input 3474 * or a key with #PSA_KEY_USAGE_DERIVE set; 3475 * - psa_key_derivation_output_key() or psa_key_derivation_output_key_custom() 3476 * if the input for step 3477 * #PSA_KEY_DERIVATION_INPUT_SECRET or #PSA_KEY_DERIVATION_INPUT_PASSWORD 3478 * was from a key slot with #PSA_KEY_USAGE_DERIVE and each other input was 3479 * either a direct input or a key with #PSA_KEY_USAGE_DERIVE set; 3480 * - psa_key_derivation_verify_bytes() if each input was either a direct input 3481 * or a key with #PSA_KEY_USAGE_VERIFY_DERIVATION set; 3482 * - psa_key_derivation_verify_key() under the same conditions as 3483 * psa_key_derivation_verify_bytes(). 3484 * 3485 * \retval #PSA_SUCCESS 3486 * Success. 3487 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 3488 * \retval #PSA_ERROR_NOT_PERMITTED 3489 * The key allows neither #PSA_KEY_USAGE_DERIVE nor 3490 * #PSA_KEY_USAGE_VERIFY_DERIVATION, or it doesn't allow this 3491 * algorithm. 3492 * \retval #PSA_ERROR_INVALID_ARGUMENT 3493 * \c step is not compatible with the operation's algorithm, or 3494 * \c step does not allow key inputs of the given type 3495 * or does not allow key inputs at all. 3496 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 3497 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 3498 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 3499 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 3500 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 3501 * \retval #PSA_ERROR_BAD_STATE 3502 * The operation state is not valid for this input \p step, or 3503 * the library has not been previously initialized by psa_crypto_init(). 3504 * It is implementation-dependent whether a failure to initialize 3505 * results in this error code. 3506 */ 3507 psa_status_t psa_key_derivation_input_key( 3508 psa_key_derivation_operation_t *operation, 3509 psa_key_derivation_step_t step, 3510 mbedtls_svc_key_id_t key); 3511 3512 /** Perform a key agreement and use the shared secret as input to a key 3513 * derivation. 3514 * 3515 * A key agreement algorithm takes two inputs: a private key \p private_key 3516 * a public key \p peer_key. 3517 * The result of this function is passed as input to a key derivation. 3518 * The output of this key derivation can be extracted by reading from the 3519 * resulting operation to produce keys and other cryptographic material. 3520 * 3521 * If this function returns an error status, the operation enters an error 3522 * state and must be aborted by calling psa_key_derivation_abort(). 3523 * 3524 * \param[in,out] operation The key derivation operation object to use. 3525 * It must have been set up with 3526 * psa_key_derivation_setup() with a 3527 * key agreement and derivation algorithm 3528 * \c alg (\c PSA_ALG_XXX value such that 3529 * #PSA_ALG_IS_KEY_AGREEMENT(\c alg) is true 3530 * and #PSA_ALG_IS_RAW_KEY_AGREEMENT(\c alg) 3531 * is false). 3532 * The operation must be ready for an 3533 * input of the type given by \p step. 3534 * \param step Which step the input data is for. 3535 * \param private_key Identifier of the private key to use. It must 3536 * allow the usage #PSA_KEY_USAGE_DERIVE. 3537 * \param[in] peer_key Public key of the peer. The peer key must be in the 3538 * same format that psa_import_key() accepts for the 3539 * public key type corresponding to the type of 3540 * private_key. That is, this function performs the 3541 * equivalent of 3542 * #psa_import_key(..., 3543 * `peer_key`, `peer_key_length`) where 3544 * with key attributes indicating the public key 3545 * type corresponding to the type of `private_key`. 3546 * For example, for EC keys, this means that peer_key 3547 * is interpreted as a point on the curve that the 3548 * private key is on. The standard formats for public 3549 * keys are documented in the documentation of 3550 * psa_export_public_key(). 3551 * \param peer_key_length Size of \p peer_key in bytes. 3552 * 3553 * \retval #PSA_SUCCESS 3554 * Success. 3555 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 3556 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 3557 * \retval #PSA_ERROR_INVALID_ARGUMENT 3558 * \c private_key is not compatible with \c alg, 3559 * or \p peer_key is not valid for \c alg or not compatible with 3560 * \c private_key, or \c step does not allow an input resulting 3561 * from a key agreement. 3562 * \retval #PSA_ERROR_NOT_SUPPORTED 3563 * \c alg is not supported or is not a key derivation algorithm. 3564 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 3565 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 3566 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 3567 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 3568 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 3569 * \retval #PSA_ERROR_BAD_STATE 3570 * The operation state is not valid for this key agreement \p step, 3571 * or the library has not been previously initialized by psa_crypto_init(). 3572 * It is implementation-dependent whether a failure to initialize 3573 * results in this error code. 3574 */ 3575 psa_status_t psa_key_derivation_key_agreement( 3576 psa_key_derivation_operation_t *operation, 3577 psa_key_derivation_step_t step, 3578 mbedtls_svc_key_id_t private_key, 3579 const uint8_t *peer_key, 3580 size_t peer_key_length); 3581 3582 /** Read some data from a key derivation operation. 3583 * 3584 * This function calculates output bytes from a key derivation algorithm and 3585 * return those bytes. 3586 * If you view the key derivation's output as a stream of bytes, this 3587 * function destructively reads the requested number of bytes from the 3588 * stream. 3589 * The operation's capacity decreases by the number of bytes read. 3590 * 3591 * If this function returns an error status other than 3592 * #PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error 3593 * state and must be aborted by calling psa_key_derivation_abort(). 3594 * 3595 * \param[in,out] operation The key derivation operation object to read from. 3596 * \param[out] output Buffer where the output will be written. 3597 * \param output_length Number of bytes to output. 3598 * 3599 * \retval #PSA_SUCCESS \emptydescription 3600 * \retval #PSA_ERROR_NOT_PERMITTED 3601 * One of the inputs was a key whose policy didn't allow 3602 * #PSA_KEY_USAGE_DERIVE. 3603 * \retval #PSA_ERROR_INSUFFICIENT_DATA 3604 * The operation's capacity was less than 3605 * \p output_length bytes. Note that in this case, 3606 * no output is written to the output buffer. 3607 * The operation's capacity is set to 0, thus 3608 * subsequent calls to this function will not 3609 * succeed, even with a smaller output buffer. 3610 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 3611 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 3612 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 3613 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 3614 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 3615 * \retval #PSA_ERROR_BAD_STATE 3616 * The operation state is not valid (it must be active and completed 3617 * all required input steps), or the library has not been previously 3618 * initialized by psa_crypto_init(). 3619 * It is implementation-dependent whether a failure to initialize 3620 * results in this error code. 3621 */ 3622 psa_status_t psa_key_derivation_output_bytes( 3623 psa_key_derivation_operation_t *operation, 3624 uint8_t *output, 3625 size_t output_length); 3626 3627 /** Derive a key from an ongoing key derivation operation. 3628 * 3629 * This function calculates output bytes from a key derivation algorithm 3630 * and uses those bytes to generate a key deterministically. 3631 * The key's location, usage policy, type and size are taken from 3632 * \p attributes. 3633 * 3634 * If you view the key derivation's output as a stream of bytes, this 3635 * function destructively reads as many bytes as required from the 3636 * stream. 3637 * The operation's capacity decreases by the number of bytes read. 3638 * 3639 * If this function returns an error status other than 3640 * #PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error 3641 * state and must be aborted by calling psa_key_derivation_abort(). 3642 * 3643 * How much output is produced and consumed from the operation, and how 3644 * the key is derived, depends on the key type and on the key size 3645 * (denoted \c bits below): 3646 * 3647 * - For key types for which the key is an arbitrary sequence of bytes 3648 * of a given size, this function is functionally equivalent to 3649 * calling #psa_key_derivation_output_bytes 3650 * and passing the resulting output to #psa_import_key. 3651 * However, this function has a security benefit: 3652 * if the implementation provides an isolation boundary then 3653 * the key material is not exposed outside the isolation boundary. 3654 * As a consequence, for these key types, this function always consumes 3655 * exactly (\c bits / 8) bytes from the operation. 3656 * The following key types defined in this specification follow this scheme: 3657 * 3658 * - #PSA_KEY_TYPE_AES; 3659 * - #PSA_KEY_TYPE_ARIA; 3660 * - #PSA_KEY_TYPE_CAMELLIA; 3661 * - #PSA_KEY_TYPE_DERIVE; 3662 * - #PSA_KEY_TYPE_HMAC; 3663 * - #PSA_KEY_TYPE_PASSWORD_HASH. 3664 * 3665 * - For ECC keys on a Montgomery elliptic curve 3666 * (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a 3667 * Montgomery curve), this function always draws a byte string whose 3668 * length is determined by the curve, and sets the mandatory bits 3669 * accordingly. That is: 3670 * 3671 * - Curve25519 (#PSA_ECC_FAMILY_MONTGOMERY, 255 bits): draw a 32-byte 3672 * string and process it as specified in RFC 7748 §5. 3673 * - Curve448 (#PSA_ECC_FAMILY_MONTGOMERY, 448 bits): draw a 56-byte 3674 * string and process it as specified in RFC 7748 §5. 3675 * 3676 * - For key types for which the key is represented by a single sequence of 3677 * \c bits bits with constraints as to which bit sequences are acceptable, 3678 * this function draws a byte string of length (\c bits / 8) bytes rounded 3679 * up to the nearest whole number of bytes. If the resulting byte string 3680 * is acceptable, it becomes the key, otherwise the drawn bytes are discarded. 3681 * This process is repeated until an acceptable byte string is drawn. 3682 * The byte string drawn from the operation is interpreted as specified 3683 * for the output produced by psa_export_key(). 3684 * The following key types defined in this specification follow this scheme: 3685 * 3686 * - #PSA_KEY_TYPE_DES. 3687 * Force-set the parity bits, but discard forbidden weak keys. 3688 * For 2-key and 3-key triple-DES, the three keys are generated 3689 * successively (for example, for 3-key triple-DES, 3690 * if the first 8 bytes specify a weak key and the next 8 bytes do not, 3691 * discard the first 8 bytes, use the next 8 bytes as the first key, 3692 * and continue reading output from the operation to derive the other 3693 * two keys). 3694 * - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEY_PAIR(\c group) 3695 * where \c group designates any Diffie-Hellman group) and 3696 * ECC keys on a Weierstrass elliptic curve 3697 * (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a 3698 * Weierstrass curve). 3699 * For these key types, interpret the byte string as integer 3700 * in big-endian order. Discard it if it is not in the range 3701 * [0, *N* - 2] where *N* is the boundary of the private key domain 3702 * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA, 3703 * or the order of the curve's base point for ECC). 3704 * Add 1 to the resulting integer and use this as the private key *x*. 3705 * This method allows compliance to NIST standards, specifically 3706 * the methods titled "key-pair generation by testing candidates" 3707 * in NIST SP 800-56A §5.6.1.1.4 for Diffie-Hellman, 3708 * in FIPS 186-4 §B.1.2 for DSA, and 3709 * in NIST SP 800-56A §5.6.1.2.2 or 3710 * FIPS 186-4 §B.4.2 for elliptic curve keys. 3711 * 3712 * - For other key types, including #PSA_KEY_TYPE_RSA_KEY_PAIR, 3713 * the way in which the operation output is consumed is 3714 * implementation-defined. 3715 * 3716 * In all cases, the data that is read is discarded from the operation. 3717 * The operation's capacity is decreased by the number of bytes read. 3718 * 3719 * For algorithms that take an input step #PSA_KEY_DERIVATION_INPUT_SECRET, 3720 * the input to that step must be provided with psa_key_derivation_input_key(). 3721 * Future versions of this specification may include additional restrictions 3722 * on the derived key based on the attributes and strength of the secret key. 3723 * 3724 * \note This function is equivalent to calling 3725 * psa_key_derivation_output_key_custom() 3726 * with the custom production parameters #PSA_CUSTOM_KEY_PARAMETERS_INIT 3727 * and `custom_data_length == 0` (i.e. `custom_data` is empty). 3728 * 3729 * \param[in] attributes The attributes for the new key. 3730 * If the key type to be created is 3731 * #PSA_KEY_TYPE_PASSWORD_HASH then the algorithm in 3732 * the policy must be the same as in the current 3733 * operation. 3734 * \param[in,out] operation The key derivation operation object to read from. 3735 * \param[out] key On success, an identifier for the newly created 3736 * key. For persistent keys, this is the key 3737 * identifier defined in \p attributes. 3738 * \c 0 on failure. 3739 * 3740 * \retval #PSA_SUCCESS 3741 * Success. 3742 * If the key is persistent, the key material and the key's metadata 3743 * have been saved to persistent storage. 3744 * \retval #PSA_ERROR_ALREADY_EXISTS 3745 * This is an attempt to create a persistent key, and there is 3746 * already a persistent key with the given identifier. 3747 * \retval #PSA_ERROR_INSUFFICIENT_DATA 3748 * There was not enough data to create the desired key. 3749 * Note that in this case, no output is written to the output buffer. 3750 * The operation's capacity is set to 0, thus subsequent calls to 3751 * this function will not succeed, even with a smaller output buffer. 3752 * \retval #PSA_ERROR_NOT_SUPPORTED 3753 * The key type or key size is not supported, either by the 3754 * implementation in general or in this particular location. 3755 * \retval #PSA_ERROR_INVALID_ARGUMENT 3756 * The provided key attributes are not valid for the operation. 3757 * \retval #PSA_ERROR_NOT_PERMITTED 3758 * The #PSA_KEY_DERIVATION_INPUT_SECRET or 3759 * #PSA_KEY_DERIVATION_INPUT_PASSWORD input was not provided through a 3760 * key; or one of the inputs was a key whose policy didn't allow 3761 * #PSA_KEY_USAGE_DERIVE. 3762 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 3763 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription 3764 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 3765 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 3766 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 3767 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 3768 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 3769 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 3770 * \retval #PSA_ERROR_BAD_STATE 3771 * The operation state is not valid (it must be active and completed 3772 * all required input steps), or the library has not been previously 3773 * initialized by psa_crypto_init(). 3774 * It is implementation-dependent whether a failure to initialize 3775 * results in this error code. 3776 */ 3777 psa_status_t psa_key_derivation_output_key( 3778 const psa_key_attributes_t *attributes, 3779 psa_key_derivation_operation_t *operation, 3780 mbedtls_svc_key_id_t *key); 3781 3782 /** Derive a key from an ongoing key derivation operation with custom 3783 * production parameters. 3784 * 3785 * See the description of psa_key_derivation_out_key() for the operation of 3786 * this function with the default production parameters. 3787 * Mbed TLS currently does not currently support any non-default production 3788 * parameters. 3789 * 3790 * \note This function is experimental and may change in future minor 3791 * versions of Mbed TLS. 3792 * 3793 * \param[in] attributes The attributes for the new key. 3794 * If the key type to be created is 3795 * #PSA_KEY_TYPE_PASSWORD_HASH then the algorithm in 3796 * the policy must be the same as in the current 3797 * operation. 3798 * \param[in,out] operation The key derivation operation object to read from. 3799 * \param[in] custom Customization parameters for the key generation. 3800 * When this is #PSA_CUSTOM_KEY_PARAMETERS_INIT 3801 * with \p custom_data_length = 0, 3802 * this function is equivalent to 3803 * psa_key_derivation_output_key(). 3804 * \param[in] custom_data Variable-length data associated with \c custom. 3805 * \param custom_data_length 3806 * Length of `custom_data` in bytes. 3807 * \param[out] key On success, an identifier for the newly created 3808 * key. For persistent keys, this is the key 3809 * identifier defined in \p attributes. 3810 * \c 0 on failure. 3811 * 3812 * \retval #PSA_SUCCESS 3813 * Success. 3814 * If the key is persistent, the key material and the key's metadata 3815 * have been saved to persistent storage. 3816 * \retval #PSA_ERROR_ALREADY_EXISTS 3817 * This is an attempt to create a persistent key, and there is 3818 * already a persistent key with the given identifier. 3819 * \retval #PSA_ERROR_INSUFFICIENT_DATA 3820 * There was not enough data to create the desired key. 3821 * Note that in this case, no output is written to the output buffer. 3822 * The operation's capacity is set to 0, thus subsequent calls to 3823 * this function will not succeed, even with a smaller output buffer. 3824 * \retval #PSA_ERROR_NOT_SUPPORTED 3825 * The key type or key size is not supported, either by the 3826 * implementation in general or in this particular location. 3827 * \retval #PSA_ERROR_INVALID_ARGUMENT 3828 * The provided key attributes are not valid for the operation. 3829 * \retval #PSA_ERROR_NOT_PERMITTED 3830 * The #PSA_KEY_DERIVATION_INPUT_SECRET or 3831 * #PSA_KEY_DERIVATION_INPUT_PASSWORD input was not provided through a 3832 * key; or one of the inputs was a key whose policy didn't allow 3833 * #PSA_KEY_USAGE_DERIVE. 3834 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 3835 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription 3836 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 3837 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 3838 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 3839 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 3840 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 3841 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 3842 * \retval #PSA_ERROR_BAD_STATE 3843 * The operation state is not valid (it must be active and completed 3844 * all required input steps), or the library has not been previously 3845 * initialized by psa_crypto_init(). 3846 * It is implementation-dependent whether a failure to initialize 3847 * results in this error code. 3848 */ 3849 psa_status_t psa_key_derivation_output_key_custom( 3850 const psa_key_attributes_t *attributes, 3851 psa_key_derivation_operation_t *operation, 3852 const psa_custom_key_parameters_t *custom, 3853 const uint8_t *custom_data, 3854 size_t custom_data_length, 3855 mbedtls_svc_key_id_t *key); 3856 3857 #ifndef __cplusplus 3858 /* Omitted when compiling in C++, because one of the parameters is a 3859 * pointer to a struct with a flexible array member, and that is not 3860 * standard C++. 3861 * https://github.com/Mbed-TLS/mbedtls/issues/9020 3862 */ 3863 /** Derive a key from an ongoing key derivation operation with custom 3864 * production parameters. 3865 * 3866 * \note 3867 * This is a deprecated variant of psa_key_derivation_output_key_custom(). 3868 * It is equivalent except that the associated variable-length data 3869 * is passed in `params->data` instead of a separate parameter. 3870 * This function will be removed in a future version of Mbed TLS. 3871 * 3872 * \param[in] attributes The attributes for the new key. 3873 * If the key type to be created is 3874 * #PSA_KEY_TYPE_PASSWORD_HASH then the algorithm in 3875 * the policy must be the same as in the current 3876 * operation. 3877 * \param[in,out] operation The key derivation operation object to read from. 3878 * \param[in] params Customization parameters for the key derivation. 3879 * When this is #PSA_KEY_PRODUCTION_PARAMETERS_INIT 3880 * with \p params_data_length = 0, 3881 * this function is equivalent to 3882 * psa_key_derivation_output_key(). 3883 * Mbed TLS currently only supports the default 3884 * production parameters, i.e. 3885 * #PSA_KEY_PRODUCTION_PARAMETERS_INIT, 3886 * for all key types. 3887 * \param params_data_length 3888 * Length of `params->data` in bytes. 3889 * \param[out] key On success, an identifier for the newly created 3890 * key. For persistent keys, this is the key 3891 * identifier defined in \p attributes. 3892 * \c 0 on failure. 3893 * 3894 * \retval #PSA_SUCCESS 3895 * Success. 3896 * If the key is persistent, the key material and the key's metadata 3897 * have been saved to persistent storage. 3898 * \retval #PSA_ERROR_ALREADY_EXISTS 3899 * This is an attempt to create a persistent key, and there is 3900 * already a persistent key with the given identifier. 3901 * \retval #PSA_ERROR_INSUFFICIENT_DATA 3902 * There was not enough data to create the desired key. 3903 * Note that in this case, no output is written to the output buffer. 3904 * The operation's capacity is set to 0, thus subsequent calls to 3905 * this function will not succeed, even with a smaller output buffer. 3906 * \retval #PSA_ERROR_NOT_SUPPORTED 3907 * The key type or key size is not supported, either by the 3908 * implementation in general or in this particular location. 3909 * \retval #PSA_ERROR_INVALID_ARGUMENT 3910 * The provided key attributes are not valid for the operation. 3911 * \retval #PSA_ERROR_NOT_PERMITTED 3912 * The #PSA_KEY_DERIVATION_INPUT_SECRET or 3913 * #PSA_KEY_DERIVATION_INPUT_PASSWORD input was not provided through a 3914 * key; or one of the inputs was a key whose policy didn't allow 3915 * #PSA_KEY_USAGE_DERIVE. 3916 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 3917 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription 3918 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 3919 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 3920 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 3921 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 3922 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 3923 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 3924 * \retval #PSA_ERROR_BAD_STATE 3925 * The operation state is not valid (it must be active and completed 3926 * all required input steps), or the library has not been previously 3927 * initialized by psa_crypto_init(). 3928 * It is implementation-dependent whether a failure to initialize 3929 * results in this error code. 3930 */ 3931 psa_status_t psa_key_derivation_output_key_ext( 3932 const psa_key_attributes_t *attributes, 3933 psa_key_derivation_operation_t *operation, 3934 const psa_key_production_parameters_t *params, 3935 size_t params_data_length, 3936 mbedtls_svc_key_id_t *key); 3937 #endif /* !__cplusplus */ 3938 3939 /** Compare output data from a key derivation operation to an expected value. 3940 * 3941 * This function calculates output bytes from a key derivation algorithm and 3942 * compares those bytes to an expected value in constant time. 3943 * If you view the key derivation's output as a stream of bytes, this 3944 * function destructively reads the expected number of bytes from the 3945 * stream before comparing them. 3946 * The operation's capacity decreases by the number of bytes read. 3947 * 3948 * This is functionally equivalent to the following code: 3949 * \code 3950 * psa_key_derivation_output_bytes(operation, tmp, output_length); 3951 * if (memcmp(output, tmp, output_length) != 0) 3952 * return PSA_ERROR_INVALID_SIGNATURE; 3953 * \endcode 3954 * except (1) it works even if the key's policy does not allow outputting the 3955 * bytes, and (2) the comparison will be done in constant time. 3956 * 3957 * If this function returns an error status other than 3958 * #PSA_ERROR_INSUFFICIENT_DATA or #PSA_ERROR_INVALID_SIGNATURE, 3959 * the operation enters an error state and must be aborted by calling 3960 * psa_key_derivation_abort(). 3961 * 3962 * \param[in,out] operation The key derivation operation object to read from. 3963 * \param[in] expected Buffer containing the expected derivation output. 3964 * \param expected_length Length of the expected output; this is also the 3965 * number of bytes that will be read. 3966 * 3967 * \retval #PSA_SUCCESS \emptydescription 3968 * \retval #PSA_ERROR_INVALID_SIGNATURE 3969 * The output was read successfully, but it differs from the expected 3970 * output. 3971 * \retval #PSA_ERROR_NOT_PERMITTED 3972 * One of the inputs was a key whose policy didn't allow 3973 * #PSA_KEY_USAGE_VERIFY_DERIVATION. 3974 * \retval #PSA_ERROR_INSUFFICIENT_DATA 3975 * The operation's capacity was less than 3976 * \p output_length bytes. Note that in this case, 3977 * the operation's capacity is set to 0, thus 3978 * subsequent calls to this function will not 3979 * succeed, even with a smaller expected output. 3980 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 3981 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 3982 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 3983 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 3984 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 3985 * \retval #PSA_ERROR_BAD_STATE 3986 * The operation state is not valid (it must be active and completed 3987 * all required input steps), or the library has not been previously 3988 * initialized by psa_crypto_init(). 3989 * It is implementation-dependent whether a failure to initialize 3990 * results in this error code. 3991 */ 3992 psa_status_t psa_key_derivation_verify_bytes( 3993 psa_key_derivation_operation_t *operation, 3994 const uint8_t *expected, 3995 size_t expected_length); 3996 3997 /** Compare output data from a key derivation operation to an expected value 3998 * stored in a key object. 3999 * 4000 * This function calculates output bytes from a key derivation algorithm and 4001 * compares those bytes to an expected value, provided as key of type 4002 * #PSA_KEY_TYPE_PASSWORD_HASH. 4003 * If you view the key derivation's output as a stream of bytes, this 4004 * function destructively reads the number of bytes corresponding to the 4005 * length of the expected value from the stream before comparing them. 4006 * The operation's capacity decreases by the number of bytes read. 4007 * 4008 * This is functionally equivalent to exporting the key and calling 4009 * psa_key_derivation_verify_bytes() on the result, except that it 4010 * works even if the key cannot be exported. 4011 * 4012 * If this function returns an error status other than 4013 * #PSA_ERROR_INSUFFICIENT_DATA or #PSA_ERROR_INVALID_SIGNATURE, 4014 * the operation enters an error state and must be aborted by calling 4015 * psa_key_derivation_abort(). 4016 * 4017 * \param[in,out] operation The key derivation operation object to read from. 4018 * \param[in] expected A key of type #PSA_KEY_TYPE_PASSWORD_HASH 4019 * containing the expected output. Its policy must 4020 * include the #PSA_KEY_USAGE_VERIFY_DERIVATION flag 4021 * and the permitted algorithm must match the 4022 * operation. The value of this key was likely 4023 * computed by a previous call to 4024 * psa_key_derivation_output_key() or 4025 * psa_key_derivation_output_key_custom(). 4026 * 4027 * \retval #PSA_SUCCESS \emptydescription 4028 * \retval #PSA_ERROR_INVALID_SIGNATURE 4029 * The output was read successfully, but if differs from the expected 4030 * output. 4031 * \retval #PSA_ERROR_INVALID_HANDLE 4032 * The key passed as the expected value does not exist. 4033 * \retval #PSA_ERROR_INVALID_ARGUMENT 4034 * The key passed as the expected value has an invalid type. 4035 * \retval #PSA_ERROR_NOT_PERMITTED 4036 * The key passed as the expected value does not allow this usage or 4037 * this algorithm; or one of the inputs was a key whose policy didn't 4038 * allow #PSA_KEY_USAGE_VERIFY_DERIVATION. 4039 * \retval #PSA_ERROR_INSUFFICIENT_DATA 4040 * The operation's capacity was less than 4041 * the length of the expected value. In this case, 4042 * the operation's capacity is set to 0, thus 4043 * subsequent calls to this function will not 4044 * succeed, even with a smaller expected output. 4045 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 4046 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 4047 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 4048 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 4049 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 4050 * \retval #PSA_ERROR_BAD_STATE 4051 * The operation state is not valid (it must be active and completed 4052 * all required input steps), or the library has not been previously 4053 * initialized by psa_crypto_init(). 4054 * It is implementation-dependent whether a failure to initialize 4055 * results in this error code. 4056 */ 4057 psa_status_t psa_key_derivation_verify_key( 4058 psa_key_derivation_operation_t *operation, 4059 psa_key_id_t expected); 4060 4061 /** Abort a key derivation operation. 4062 * 4063 * Aborting an operation frees all associated resources except for the \c 4064 * operation structure itself. Once aborted, the operation object can be reused 4065 * for another operation by calling psa_key_derivation_setup() again. 4066 * 4067 * This function may be called at any time after the operation 4068 * object has been initialized as described in #psa_key_derivation_operation_t. 4069 * 4070 * In particular, it is valid to call psa_key_derivation_abort() twice, or to 4071 * call psa_key_derivation_abort() on an operation that has not been set up. 4072 * 4073 * \param[in,out] operation The operation to abort. 4074 * 4075 * \retval #PSA_SUCCESS \emptydescription 4076 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 4077 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 4078 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 4079 * \retval #PSA_ERROR_BAD_STATE 4080 * The library has not been previously initialized by psa_crypto_init(). 4081 * It is implementation-dependent whether a failure to initialize 4082 * results in this error code. 4083 */ 4084 psa_status_t psa_key_derivation_abort( 4085 psa_key_derivation_operation_t *operation); 4086 4087 /** Perform a key agreement and return the raw shared secret. 4088 * 4089 * \warning The raw result of a key agreement algorithm such as finite-field 4090 * Diffie-Hellman or elliptic curve Diffie-Hellman has biases and should 4091 * not be used directly as key material. It should instead be passed as 4092 * input to a key derivation algorithm. To chain a key agreement with 4093 * a key derivation, use psa_key_derivation_key_agreement() and other 4094 * functions from the key derivation interface. 4095 * 4096 * \param alg The key agreement algorithm to compute 4097 * (\c PSA_ALG_XXX value such that 4098 * #PSA_ALG_IS_RAW_KEY_AGREEMENT(\p alg) 4099 * is true). 4100 * \param private_key Identifier of the private key to use. It must 4101 * allow the usage #PSA_KEY_USAGE_DERIVE. 4102 * \param[in] peer_key Public key of the peer. It must be 4103 * in the same format that psa_import_key() 4104 * accepts. The standard formats for public 4105 * keys are documented in the documentation 4106 * of psa_export_public_key(). 4107 * \param peer_key_length Size of \p peer_key in bytes. 4108 * \param[out] output Buffer where the decrypted message is to 4109 * be written. 4110 * \param output_size Size of the \c output buffer in bytes. 4111 * \param[out] output_length On success, the number of bytes 4112 * that make up the returned output. 4113 * 4114 * \retval #PSA_SUCCESS 4115 * Success. 4116 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 4117 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 4118 * \retval #PSA_ERROR_INVALID_ARGUMENT 4119 * \p alg is not a key agreement algorithm, or 4120 * \p private_key is not compatible with \p alg, 4121 * or \p peer_key is not valid for \p alg or not compatible with 4122 * \p private_key. 4123 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 4124 * \p output_size is too small 4125 * \retval #PSA_ERROR_NOT_SUPPORTED 4126 * \p alg is not a supported key agreement algorithm. 4127 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 4128 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 4129 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 4130 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 4131 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 4132 * \retval #PSA_ERROR_BAD_STATE 4133 * The library has not been previously initialized by psa_crypto_init(). 4134 * It is implementation-dependent whether a failure to initialize 4135 * results in this error code. 4136 */ 4137 psa_status_t psa_raw_key_agreement(psa_algorithm_t alg, 4138 mbedtls_svc_key_id_t private_key, 4139 const uint8_t *peer_key, 4140 size_t peer_key_length, 4141 uint8_t *output, 4142 size_t output_size, 4143 size_t *output_length); 4144 4145 /**@}*/ 4146 4147 /** \defgroup random Random generation 4148 * @{ 4149 */ 4150 4151 /** 4152 * \brief Generate random bytes. 4153 * 4154 * \warning This function **can** fail! Callers MUST check the return status 4155 * and MUST NOT use the content of the output buffer if the return 4156 * status is not #PSA_SUCCESS. 4157 * 4158 * \note To generate a key, use psa_generate_key() instead. 4159 * 4160 * \param[out] output Output buffer for the generated data. 4161 * \param output_size Number of bytes to generate and output. 4162 * 4163 * \retval #PSA_SUCCESS \emptydescription 4164 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 4165 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 4166 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 4167 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 4168 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 4169 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 4170 * \retval #PSA_ERROR_BAD_STATE 4171 * The library has not been previously initialized by psa_crypto_init(). 4172 * It is implementation-dependent whether a failure to initialize 4173 * results in this error code. 4174 */ 4175 psa_status_t psa_generate_random(uint8_t *output, 4176 size_t output_size); 4177 4178 /** 4179 * \brief Generate a key or key pair. 4180 * 4181 * The key is generated randomly. 4182 * Its location, usage policy, type and size are taken from \p attributes. 4183 * 4184 * Implementations must reject an attempt to generate a key of size 0. 4185 * 4186 * The following type-specific considerations apply: 4187 * - For RSA keys (#PSA_KEY_TYPE_RSA_KEY_PAIR), 4188 * the public exponent is 65537. 4189 * The modulus is a product of two probabilistic primes 4190 * between 2^{n-1} and 2^n where n is the bit size specified in the 4191 * attributes. 4192 * 4193 * \note This function is equivalent to calling psa_generate_key_custom() 4194 * with the custom production parameters #PSA_CUSTOM_KEY_PARAMETERS_INIT 4195 * and `custom_data_length == 0` (i.e. `custom_data` is empty). 4196 * 4197 * \param[in] attributes The attributes for the new key. 4198 * \param[out] key On success, an identifier for the newly created 4199 * key. For persistent keys, this is the key 4200 * identifier defined in \p attributes. 4201 * \c 0 on failure. 4202 * 4203 * \retval #PSA_SUCCESS 4204 * Success. 4205 * If the key is persistent, the key material and the key's metadata 4206 * have been saved to persistent storage. 4207 * \retval #PSA_ERROR_ALREADY_EXISTS 4208 * This is an attempt to create a persistent key, and there is 4209 * already a persistent key with the given identifier. 4210 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 4211 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 4212 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 4213 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 4214 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 4215 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 4216 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 4217 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription 4218 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 4219 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 4220 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 4221 * \retval #PSA_ERROR_BAD_STATE 4222 * The library has not been previously initialized by psa_crypto_init(). 4223 * It is implementation-dependent whether a failure to initialize 4224 * results in this error code. 4225 */ 4226 psa_status_t psa_generate_key(const psa_key_attributes_t *attributes, 4227 mbedtls_svc_key_id_t *key); 4228 4229 /** 4230 * \brief Generate a key or key pair using custom production parameters. 4231 * 4232 * See the description of psa_generate_key() for the operation of this 4233 * function with the default production parameters. In addition, this function 4234 * supports the following production customizations, described in more detail 4235 * in the documentation of ::psa_custom_key_parameters_t: 4236 * 4237 * - RSA keys: generation with a custom public exponent. 4238 * 4239 * \note This function is experimental and may change in future minor 4240 * versions of Mbed TLS. 4241 * 4242 * \param[in] attributes The attributes for the new key. 4243 * \param[in] custom Customization parameters for the key generation. 4244 * When this is #PSA_CUSTOM_KEY_PARAMETERS_INIT 4245 * with \p custom_data_length = 0, 4246 * this function is equivalent to 4247 * psa_generate_key(). 4248 * \param[in] custom_data Variable-length data associated with \c custom. 4249 * \param custom_data_length 4250 * Length of `custom_data` in bytes. 4251 * \param[out] key On success, an identifier for the newly created 4252 * key. For persistent keys, this is the key 4253 * identifier defined in \p attributes. 4254 * \c 0 on failure. 4255 * 4256 * \retval #PSA_SUCCESS 4257 * Success. 4258 * If the key is persistent, the key material and the key's metadata 4259 * have been saved to persistent storage. 4260 * \retval #PSA_ERROR_ALREADY_EXISTS 4261 * This is an attempt to create a persistent key, and there is 4262 * already a persistent key with the given identifier. 4263 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 4264 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 4265 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 4266 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 4267 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 4268 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 4269 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 4270 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription 4271 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 4272 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 4273 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 4274 * \retval #PSA_ERROR_BAD_STATE 4275 * The library has not been previously initialized by psa_crypto_init(). 4276 * It is implementation-dependent whether a failure to initialize 4277 * results in this error code. 4278 */ 4279 psa_status_t psa_generate_key_custom(const psa_key_attributes_t *attributes, 4280 const psa_custom_key_parameters_t *custom, 4281 const uint8_t *custom_data, 4282 size_t custom_data_length, 4283 mbedtls_svc_key_id_t *key); 4284 4285 #ifndef __cplusplus 4286 /* Omitted when compiling in C++, because one of the parameters is a 4287 * pointer to a struct with a flexible array member, and that is not 4288 * standard C++. 4289 * https://github.com/Mbed-TLS/mbedtls/issues/9020 4290 */ 4291 /** 4292 * \brief Generate a key or key pair using custom production parameters. 4293 * 4294 * \note 4295 * This is a deprecated variant of psa_key_derivation_output_key_custom(). 4296 * It is equivalent except that the associated variable-length data 4297 * is passed in `params->data` instead of a separate parameter. 4298 * This function will be removed in a future version of Mbed TLS. 4299 * 4300 * \param[in] attributes The attributes for the new key. 4301 * \param[in] params Customization parameters for the key generation. 4302 * When this is #PSA_KEY_PRODUCTION_PARAMETERS_INIT 4303 * with \p params_data_length = 0, 4304 * this function is equivalent to 4305 * psa_generate_key(). 4306 * \param params_data_length 4307 * Length of `params->data` in bytes. 4308 * \param[out] key On success, an identifier for the newly created 4309 * key. For persistent keys, this is the key 4310 * identifier defined in \p attributes. 4311 * \c 0 on failure. 4312 * 4313 * \retval #PSA_SUCCESS 4314 * Success. 4315 * If the key is persistent, the key material and the key's metadata 4316 * have been saved to persistent storage. 4317 * \retval #PSA_ERROR_ALREADY_EXISTS 4318 * This is an attempt to create a persistent key, and there is 4319 * already a persistent key with the given identifier. 4320 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 4321 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 4322 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 4323 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 4324 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 4325 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 4326 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 4327 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription 4328 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 4329 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 4330 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 4331 * \retval #PSA_ERROR_BAD_STATE 4332 * The library has not been previously initialized by psa_crypto_init(). 4333 * It is implementation-dependent whether a failure to initialize 4334 * results in this error code. 4335 */ 4336 psa_status_t psa_generate_key_ext(const psa_key_attributes_t *attributes, 4337 const psa_key_production_parameters_t *params, 4338 size_t params_data_length, 4339 mbedtls_svc_key_id_t *key); 4340 #endif /* !__cplusplus */ 4341 4342 /**@}*/ 4343 4344 /** \defgroup interruptible_hash Interruptible sign/verify hash 4345 * @{ 4346 */ 4347 4348 /** The type of the state data structure for interruptible hash 4349 * signing operations. 4350 * 4351 * Before calling any function on a sign hash operation object, the 4352 * application must initialize it by any of the following means: 4353 * - Set the structure to all-bits-zero, for example: 4354 * \code 4355 * psa_sign_hash_interruptible_operation_t operation; 4356 * memset(&operation, 0, sizeof(operation)); 4357 * \endcode 4358 * - Initialize the structure to logical zero values, for example: 4359 * \code 4360 * psa_sign_hash_interruptible_operation_t operation = {0}; 4361 * \endcode 4362 * - Initialize the structure to the initializer 4363 * #PSA_SIGN_HASH_INTERRUPTIBLE_OPERATION_INIT, for example: 4364 * \code 4365 * psa_sign_hash_interruptible_operation_t operation = 4366 * PSA_SIGN_HASH_INTERRUPTIBLE_OPERATION_INIT; 4367 * \endcode 4368 * - Assign the result of the function 4369 * psa_sign_hash_interruptible_operation_init() to the structure, for 4370 * example: 4371 * \code 4372 * psa_sign_hash_interruptible_operation_t operation; 4373 * operation = psa_sign_hash_interruptible_operation_init(); 4374 * \endcode 4375 * 4376 * This is an implementation-defined \c struct. Applications should not 4377 * make any assumptions about the content of this structure. 4378 * Implementation details can change in future versions without notice. */ 4379 typedef struct psa_sign_hash_interruptible_operation_s psa_sign_hash_interruptible_operation_t; 4380 4381 /** The type of the state data structure for interruptible hash 4382 * verification operations. 4383 * 4384 * Before calling any function on a sign hash operation object, the 4385 * application must initialize it by any of the following means: 4386 * - Set the structure to all-bits-zero, for example: 4387 * \code 4388 * psa_verify_hash_interruptible_operation_t operation; 4389 * memset(&operation, 0, sizeof(operation)); 4390 * \endcode 4391 * - Initialize the structure to logical zero values, for example: 4392 * \code 4393 * psa_verify_hash_interruptible_operation_t operation = {0}; 4394 * \endcode 4395 * - Initialize the structure to the initializer 4396 * #PSA_VERIFY_HASH_INTERRUPTIBLE_OPERATION_INIT, for example: 4397 * \code 4398 * psa_verify_hash_interruptible_operation_t operation = 4399 * PSA_VERIFY_HASH_INTERRUPTIBLE_OPERATION_INIT; 4400 * \endcode 4401 * - Assign the result of the function 4402 * psa_verify_hash_interruptible_operation_init() to the structure, for 4403 * example: 4404 * \code 4405 * psa_verify_hash_interruptible_operation_t operation; 4406 * operation = psa_verify_hash_interruptible_operation_init(); 4407 * \endcode 4408 * 4409 * This is an implementation-defined \c struct. Applications should not 4410 * make any assumptions about the content of this structure. 4411 * Implementation details can change in future versions without notice. */ 4412 typedef struct psa_verify_hash_interruptible_operation_s psa_verify_hash_interruptible_operation_t; 4413 4414 /** 4415 * \brief Set the maximum number of ops allowed to be 4416 * executed by an interruptible function in a 4417 * single call. 4418 * 4419 * \warning This is a beta API, and thus subject to change 4420 * at any point. It is not bound by the usual 4421 * interface stability promises. 4422 * 4423 * \note The time taken to execute a single op is 4424 * implementation specific and depends on 4425 * software, hardware, the algorithm, key type and 4426 * curve chosen. Even within a single operation, 4427 * successive ops can take differing amounts of 4428 * time. The only guarantee is that lower values 4429 * for \p max_ops means functions will block for a 4430 * lesser maximum amount of time. The functions 4431 * \c psa_sign_interruptible_get_num_ops() and 4432 * \c psa_verify_interruptible_get_num_ops() are 4433 * provided to help with tuning this value. 4434 * 4435 * \note This value defaults to 4436 * #PSA_INTERRUPTIBLE_MAX_OPS_UNLIMITED, which 4437 * means the whole operation will be done in one 4438 * go, regardless of the number of ops required. 4439 * 4440 * \note If more ops are needed to complete a 4441 * computation, #PSA_OPERATION_INCOMPLETE will be 4442 * returned by the function performing the 4443 * computation. It is then the caller's 4444 * responsibility to either call again with the 4445 * same operation context until it returns 0 or an 4446 * error code; or to call the relevant abort 4447 * function if the answer is no longer required. 4448 * 4449 * \note The interpretation of \p max_ops is also 4450 * implementation defined. On a hard real time 4451 * system, this can indicate a hard deadline, as a 4452 * real-time system needs a guarantee of not 4453 * spending more than X time, however care must be 4454 * taken in such an implementation to avoid the 4455 * situation whereby calls just return, not being 4456 * able to do any actual work within the allotted 4457 * time. On a non-real-time system, the 4458 * implementation can be more relaxed, but again 4459 * whether this number should be interpreted as as 4460 * hard or soft limit or even whether a less than 4461 * or equals as regards to ops executed in a 4462 * single call is implementation defined. 4463 * 4464 * \note For keys in local storage when no accelerator 4465 * driver applies, please see also the 4466 * documentation for \c mbedtls_ecp_set_max_ops(), 4467 * which is the internal implementation in these 4468 * cases. 4469 * 4470 * \warning With implementations that interpret this number 4471 * as a hard limit, setting this number too small 4472 * may result in an infinite loop, whereby each 4473 * call results in immediate return with no ops 4474 * done (as there is not enough time to execute 4475 * any), and thus no result will ever be achieved. 4476 * 4477 * \note This only applies to functions whose 4478 * documentation mentions they may return 4479 * #PSA_OPERATION_INCOMPLETE. 4480 * 4481 * \param max_ops The maximum number of ops to be executed in a 4482 * single call. This can be a number from 0 to 4483 * #PSA_INTERRUPTIBLE_MAX_OPS_UNLIMITED, where 0 4484 * is the least amount of work done per call. 4485 */ 4486 void psa_interruptible_set_max_ops(uint32_t max_ops); 4487 4488 /** 4489 * \brief Get the maximum number of ops allowed to be 4490 * executed by an interruptible function in a 4491 * single call. This will return the last 4492 * value set by 4493 * \c psa_interruptible_set_max_ops() or 4494 * #PSA_INTERRUPTIBLE_MAX_OPS_UNLIMITED if 4495 * that function has never been called. 4496 * 4497 * \warning This is a beta API, and thus subject to change 4498 * at any point. It is not bound by the usual 4499 * interface stability promises. 4500 * 4501 * \return Maximum number of ops allowed to be 4502 * executed by an interruptible function in a 4503 * single call. 4504 */ 4505 uint32_t psa_interruptible_get_max_ops(void); 4506 4507 /** 4508 * \brief Get the number of ops that a hash signing 4509 * operation has taken so far. If the operation 4510 * has completed, then this will represent the 4511 * number of ops required for the entire 4512 * operation. After initialization or calling 4513 * \c psa_sign_hash_interruptible_abort() on 4514 * the operation, a value of 0 will be returned. 4515 * 4516 * \note This interface is guaranteed re-entrant and 4517 * thus may be called from driver code. 4518 * 4519 * \warning This is a beta API, and thus subject to change 4520 * at any point. It is not bound by the usual 4521 * interface stability promises. 4522 * 4523 * This is a helper provided to help you tune the 4524 * value passed to \c 4525 * psa_interruptible_set_max_ops(). 4526 * 4527 * \param operation The \c psa_sign_hash_interruptible_operation_t 4528 * to use. This must be initialized first. 4529 * 4530 * \return Number of ops that the operation has taken so 4531 * far. 4532 */ 4533 uint32_t psa_sign_hash_get_num_ops( 4534 const psa_sign_hash_interruptible_operation_t *operation); 4535 4536 /** 4537 * \brief Get the number of ops that a hash verification 4538 * operation has taken so far. If the operation 4539 * has completed, then this will represent the 4540 * number of ops required for the entire 4541 * operation. After initialization or calling \c 4542 * psa_verify_hash_interruptible_abort() on the 4543 * operation, a value of 0 will be returned. 4544 * 4545 * \warning This is a beta API, and thus subject to change 4546 * at any point. It is not bound by the usual 4547 * interface stability promises. 4548 * 4549 * This is a helper provided to help you tune the 4550 * value passed to \c 4551 * psa_interruptible_set_max_ops(). 4552 * 4553 * \param operation The \c 4554 * psa_verify_hash_interruptible_operation_t to 4555 * use. This must be initialized first. 4556 * 4557 * \return Number of ops that the operation has taken so 4558 * far. 4559 */ 4560 uint32_t psa_verify_hash_get_num_ops( 4561 const psa_verify_hash_interruptible_operation_t *operation); 4562 4563 /** 4564 * \brief Start signing a hash or short message with a 4565 * private key, in an interruptible manner. 4566 * 4567 * \see \c psa_sign_hash_complete() 4568 * 4569 * \warning This is a beta API, and thus subject to change 4570 * at any point. It is not bound by the usual 4571 * interface stability promises. 4572 * 4573 * \note This function combined with \c 4574 * psa_sign_hash_complete() is equivalent to 4575 * \c psa_sign_hash() but 4576 * \c psa_sign_hash_complete() can return early and 4577 * resume according to the limit set with \c 4578 * psa_interruptible_set_max_ops() to reduce the 4579 * maximum time spent in a function call. 4580 * 4581 * \note Users should call \c psa_sign_hash_complete() 4582 * repeatedly on the same context after a 4583 * successful call to this function until \c 4584 * psa_sign_hash_complete() either returns 0 or an 4585 * error. \c psa_sign_hash_complete() will return 4586 * #PSA_OPERATION_INCOMPLETE if there is more work 4587 * to do. Alternatively users can call 4588 * \c psa_sign_hash_abort() at any point if they no 4589 * longer want the result. 4590 * 4591 * \note If this function returns an error status, the 4592 * operation enters an error state and must be 4593 * aborted by calling \c psa_sign_hash_abort(). 4594 * 4595 * \param[in, out] operation The \c psa_sign_hash_interruptible_operation_t 4596 * to use. This must be initialized first. 4597 * 4598 * \param key Identifier of the key to use for the operation. 4599 * It must be an asymmetric key pair. The key must 4600 * allow the usage #PSA_KEY_USAGE_SIGN_HASH. 4601 * \param alg A signature algorithm (\c PSA_ALG_XXX 4602 * value such that #PSA_ALG_IS_SIGN_HASH(\p alg) 4603 * is true), that is compatible with 4604 * the type of \p key. 4605 * \param[in] hash The hash or message to sign. 4606 * \param hash_length Size of the \p hash buffer in bytes. 4607 * 4608 * \retval #PSA_SUCCESS 4609 * The operation started successfully - call \c psa_sign_hash_complete() 4610 * with the same context to complete the operation 4611 * 4612 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 4613 * \retval #PSA_ERROR_NOT_PERMITTED 4614 * The key does not have the #PSA_KEY_USAGE_SIGN_HASH flag, or it does 4615 * not permit the requested algorithm. 4616 * \retval #PSA_ERROR_BAD_STATE 4617 * An operation has previously been started on this context, and is 4618 * still in progress. 4619 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 4620 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 4621 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 4622 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 4623 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 4624 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 4625 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 4626 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 4627 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 4628 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 4629 * \retval #PSA_ERROR_BAD_STATE 4630 * The library has not been previously initialized by psa_crypto_init(). 4631 * It is implementation-dependent whether a failure to initialize 4632 * results in this error code. 4633 */ 4634 psa_status_t psa_sign_hash_start( 4635 psa_sign_hash_interruptible_operation_t *operation, 4636 mbedtls_svc_key_id_t key, psa_algorithm_t alg, 4637 const uint8_t *hash, size_t hash_length); 4638 4639 /** 4640 * \brief Continue and eventually complete the action of 4641 * signing a hash or short message with a private 4642 * key, in an interruptible manner. 4643 * 4644 * \see \c psa_sign_hash_start() 4645 * 4646 * \warning This is a beta API, and thus subject to change 4647 * at any point. It is not bound by the usual 4648 * interface stability promises. 4649 * 4650 * \note This function combined with \c 4651 * psa_sign_hash_start() is equivalent to 4652 * \c psa_sign_hash() but this function can return 4653 * early and resume according to the limit set with 4654 * \c psa_interruptible_set_max_ops() to reduce the 4655 * maximum time spent in a function call. 4656 * 4657 * \note Users should call this function on the same 4658 * operation object repeatedly until it either 4659 * returns 0 or an error. This function will return 4660 * #PSA_OPERATION_INCOMPLETE if there is more work 4661 * to do. Alternatively users can call 4662 * \c psa_sign_hash_abort() at any point if they no 4663 * longer want the result. 4664 * 4665 * \note When this function returns successfully, the 4666 * operation becomes inactive. If this function 4667 * returns an error status, the operation enters an 4668 * error state and must be aborted by calling 4669 * \c psa_sign_hash_abort(). 4670 * 4671 * \param[in, out] operation The \c psa_sign_hash_interruptible_operation_t 4672 * to use. This must be initialized first, and have 4673 * had \c psa_sign_hash_start() called with it 4674 * first. 4675 * 4676 * \param[out] signature Buffer where the signature is to be written. 4677 * \param signature_size Size of the \p signature buffer in bytes. This 4678 * must be appropriate for the selected 4679 * algorithm and key: 4680 * - The required signature size is 4681 * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c 4682 * key_bits, \c alg) where \c key_type and \c 4683 * key_bits are the type and bit-size 4684 * respectively of key. 4685 * - #PSA_SIGNATURE_MAX_SIZE evaluates to the 4686 * maximum signature size of any supported 4687 * signature algorithm. 4688 * \param[out] signature_length On success, the number of bytes that make up 4689 * the returned signature value. 4690 * 4691 * \retval #PSA_SUCCESS 4692 * Operation completed successfully 4693 * 4694 * \retval #PSA_OPERATION_INCOMPLETE 4695 * Operation was interrupted due to the setting of \c 4696 * psa_interruptible_set_max_ops(). There is still work to be done. 4697 * Call this function again with the same operation object. 4698 * 4699 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 4700 * The size of the \p signature buffer is too small. You can 4701 * determine a sufficient buffer size by calling 4702 * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \c alg) 4703 * where \c key_type and \c key_bits are the type and bit-size 4704 * respectively of \c key. 4705 * 4706 * \retval #PSA_ERROR_BAD_STATE 4707 * An operation was not previously started on this context via 4708 * \c psa_sign_hash_start(). 4709 * 4710 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 4711 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 4712 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 4713 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 4714 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 4715 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 4716 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 4717 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 4718 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 4719 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 4720 * \retval #PSA_ERROR_BAD_STATE 4721 * The library has either not been previously initialized by 4722 * psa_crypto_init() or you did not previously call 4723 * psa_sign_hash_start() with this operation object. It is 4724 * implementation-dependent whether a failure to initialize results in 4725 * this error code. 4726 */ 4727 psa_status_t psa_sign_hash_complete( 4728 psa_sign_hash_interruptible_operation_t *operation, 4729 uint8_t *signature, size_t signature_size, 4730 size_t *signature_length); 4731 4732 /** 4733 * \brief Abort a sign hash operation. 4734 * 4735 * \warning This is a beta API, and thus subject to change 4736 * at any point. It is not bound by the usual 4737 * interface stability promises. 4738 * 4739 * \note This function is the only function that clears 4740 * the number of ops completed as part of the 4741 * operation. Please ensure you copy this value via 4742 * \c psa_sign_hash_get_num_ops() if required 4743 * before calling. 4744 * 4745 * \note Aborting an operation frees all associated 4746 * resources except for the \p operation structure 4747 * itself. Once aborted, the operation object can 4748 * be reused for another operation by calling \c 4749 * psa_sign_hash_start() again. 4750 * 4751 * \note You may call this function any time after the 4752 * operation object has been initialized. In 4753 * particular, calling \c psa_sign_hash_abort() 4754 * after the operation has already been terminated 4755 * by a call to \c psa_sign_hash_abort() or 4756 * psa_sign_hash_complete() is safe. 4757 * 4758 * \param[in,out] operation Initialized sign hash operation. 4759 * 4760 * \retval #PSA_SUCCESS 4761 * The operation was aborted successfully. 4762 * 4763 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 4764 * \retval #PSA_ERROR_BAD_STATE 4765 * The library has not been previously initialized by psa_crypto_init(). 4766 * It is implementation-dependent whether a failure to initialize 4767 * results in this error code. 4768 */ 4769 psa_status_t psa_sign_hash_abort( 4770 psa_sign_hash_interruptible_operation_t *operation); 4771 4772 /** 4773 * \brief Start reading and verifying a hash or short 4774 * message, in an interruptible manner. 4775 * 4776 * \see \c psa_verify_hash_complete() 4777 * 4778 * \warning This is a beta API, and thus subject to change 4779 * at any point. It is not bound by the usual 4780 * interface stability promises. 4781 * 4782 * \note This function combined with \c 4783 * psa_verify_hash_complete() is equivalent to 4784 * \c psa_verify_hash() but \c 4785 * psa_verify_hash_complete() can return early and 4786 * resume according to the limit set with \c 4787 * psa_interruptible_set_max_ops() to reduce the 4788 * maximum time spent in a function. 4789 * 4790 * \note Users should call \c psa_verify_hash_complete() 4791 * repeatedly on the same operation object after a 4792 * successful call to this function until \c 4793 * psa_verify_hash_complete() either returns 0 or 4794 * an error. \c psa_verify_hash_complete() will 4795 * return #PSA_OPERATION_INCOMPLETE if there is 4796 * more work to do. Alternatively users can call 4797 * \c psa_verify_hash_abort() at any point if they 4798 * no longer want the result. 4799 * 4800 * \note If this function returns an error status, the 4801 * operation enters an error state and must be 4802 * aborted by calling \c psa_verify_hash_abort(). 4803 * 4804 * \param[in, out] operation The \c psa_verify_hash_interruptible_operation_t 4805 * to use. This must be initialized first. 4806 * 4807 * \param key Identifier of the key to use for the operation. 4808 * The key must allow the usage 4809 * #PSA_KEY_USAGE_VERIFY_HASH. 4810 * \param alg A signature algorithm (\c PSA_ALG_XXX 4811 * value such that #PSA_ALG_IS_SIGN_HASH(\p alg) 4812 * is true), that is compatible with 4813 * the type of \p key. 4814 * \param[in] hash The hash whose signature is to be verified. 4815 * \param hash_length Size of the \p hash buffer in bytes. 4816 * \param[in] signature Buffer containing the signature to verify. 4817 * \param signature_length Size of the \p signature buffer in bytes. 4818 * 4819 * \retval #PSA_SUCCESS 4820 * The operation started successfully - please call \c 4821 * psa_verify_hash_complete() with the same context to complete the 4822 * operation. 4823 * 4824 * \retval #PSA_ERROR_BAD_STATE 4825 * Another operation has already been started on this context, and is 4826 * still in progress. 4827 * 4828 * \retval #PSA_ERROR_NOT_PERMITTED 4829 * The key does not have the #PSA_KEY_USAGE_VERIFY_HASH flag, or it does 4830 * not permit the requested algorithm. 4831 * 4832 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 4833 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 4834 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 4835 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 4836 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 4837 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 4838 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 4839 * \retval PSA_ERROR_DATA_CORRUPT \emptydescription 4840 * \retval PSA_ERROR_DATA_INVALID \emptydescription 4841 * \retval #PSA_ERROR_BAD_STATE 4842 * The library has not been previously initialized by psa_crypto_init(). 4843 * It is implementation-dependent whether a failure to initialize 4844 * results in this error code. 4845 */ 4846 psa_status_t psa_verify_hash_start( 4847 psa_verify_hash_interruptible_operation_t *operation, 4848 mbedtls_svc_key_id_t key, psa_algorithm_t alg, 4849 const uint8_t *hash, size_t hash_length, 4850 const uint8_t *signature, size_t signature_length); 4851 4852 /** 4853 * \brief Continue and eventually complete the action of 4854 * reading and verifying a hash or short message 4855 * signed with a private key, in an interruptible 4856 * manner. 4857 * 4858 * \see \c psa_verify_hash_start() 4859 * 4860 * \warning This is a beta API, and thus subject to change 4861 * at any point. It is not bound by the usual 4862 * interface stability promises. 4863 * 4864 * \note This function combined with \c 4865 * psa_verify_hash_start() is equivalent to 4866 * \c psa_verify_hash() but this function can 4867 * return early and resume according to the limit 4868 * set with \c psa_interruptible_set_max_ops() to 4869 * reduce the maximum time spent in a function 4870 * call. 4871 * 4872 * \note Users should call this function on the same 4873 * operation object repeatedly until it either 4874 * returns 0 or an error. This function will return 4875 * #PSA_OPERATION_INCOMPLETE if there is more work 4876 * to do. Alternatively users can call 4877 * \c psa_verify_hash_abort() at any point if they 4878 * no longer want the result. 4879 * 4880 * \note When this function returns successfully, the 4881 * operation becomes inactive. If this function 4882 * returns an error status, the operation enters an 4883 * error state and must be aborted by calling 4884 * \c psa_verify_hash_abort(). 4885 * 4886 * \param[in, out] operation The \c psa_verify_hash_interruptible_operation_t 4887 * to use. This must be initialized first, and have 4888 * had \c psa_verify_hash_start() called with it 4889 * first. 4890 * 4891 * \retval #PSA_SUCCESS 4892 * Operation completed successfully, and the passed signature is valid. 4893 * 4894 * \retval #PSA_OPERATION_INCOMPLETE 4895 * Operation was interrupted due to the setting of \c 4896 * psa_interruptible_set_max_ops(). There is still work to be done. 4897 * Call this function again with the same operation object. 4898 * 4899 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 4900 * \retval #PSA_ERROR_INVALID_SIGNATURE 4901 * The calculation was performed successfully, but the passed 4902 * signature is not a valid signature. 4903 * \retval #PSA_ERROR_BAD_STATE 4904 * An operation was not previously started on this context via 4905 * \c psa_verify_hash_start(). 4906 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 4907 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 4908 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 4909 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 4910 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 4911 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 4912 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 4913 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 4914 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 4915 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 4916 * \retval #PSA_ERROR_BAD_STATE 4917 * The library has either not been previously initialized by 4918 * psa_crypto_init() or you did not previously call 4919 * psa_verify_hash_start() on this object. It is 4920 * implementation-dependent whether a failure to initialize results in 4921 * this error code. 4922 */ 4923 psa_status_t psa_verify_hash_complete( 4924 psa_verify_hash_interruptible_operation_t *operation); 4925 4926 /** 4927 * \brief Abort a verify hash operation. 4928 * 4929 * \warning This is a beta API, and thus subject to change at 4930 * any point. It is not bound by the usual interface 4931 * stability promises. 4932 * 4933 * \note This function is the only function that clears the 4934 * number of ops completed as part of the operation. 4935 * Please ensure you copy this value via 4936 * \c psa_verify_hash_get_num_ops() if required 4937 * before calling. 4938 * 4939 * \note Aborting an operation frees all associated 4940 * resources except for the operation structure 4941 * itself. Once aborted, the operation object can be 4942 * reused for another operation by calling \c 4943 * psa_verify_hash_start() again. 4944 * 4945 * \note You may call this function any time after the 4946 * operation object has been initialized. 4947 * In particular, calling \c psa_verify_hash_abort() 4948 * after the operation has already been terminated by 4949 * a call to \c psa_verify_hash_abort() or 4950 * psa_verify_hash_complete() is safe. 4951 * 4952 * \param[in,out] operation Initialized verify hash operation. 4953 * 4954 * \retval #PSA_SUCCESS 4955 * The operation was aborted successfully. 4956 * 4957 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 4958 * \retval #PSA_ERROR_BAD_STATE 4959 * The library has not been previously initialized by psa_crypto_init(). 4960 * It is implementation-dependent whether a failure to initialize 4961 * results in this error code. 4962 */ 4963 psa_status_t psa_verify_hash_abort( 4964 psa_verify_hash_interruptible_operation_t *operation); 4965 4966 4967 /**@}*/ 4968 4969 #ifdef __cplusplus 4970 } 4971 #endif 4972 4973 /* The file "crypto_extra.h" contains vendor-specific definitions. This 4974 * can include vendor-defined algorithms, extra functions, etc. */ 4975 #include "crypto_extra.h" 4976 4977 #endif /* PSA_CRYPTO_H */ 4978