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