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