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