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