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