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