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