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