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