1/* 2 * PSA crypto core internal interfaces 3 */ 4/* 5 * Copyright The Mbed TLS Contributors 6 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 7 */ 8 9#ifndef PSA_CRYPTO_CORE_H 10#define PSA_CRYPTO_CORE_H 11 12/* 13 * Include the build-time configuration information header. Here, we do not 14 * include `"mbedtls/build_info.h"` directly but `"psa/build_info.h"`, which 15 * is basically just an alias to it. This is to ease the maintenance of the 16 * TF-PSA-Crypto repository which has a different build system and 17 * configuration. 18 */ 19#include "psa/build_info.h" 20 21#include "psa/crypto.h" 22#include "psa/crypto_se_driver.h" 23#if defined(MBEDTLS_THREADING_C) 24#include "mbedtls/threading.h" 25#endif 26 27/** 28 * Tell if PSA is ready for this hash. 29 * 30 * \note For now, only checks the state of the driver subsystem, 31 * not the algorithm. Might do more in the future. 32 * 33 * \param hash_alg The hash algorithm (ignored for now). 34 * 35 * \return 1 if the driver subsytem is ready, 0 otherwise. 36 */ 37int psa_can_do_hash(psa_algorithm_t hash_alg); 38 39/** 40 * Tell if PSA is ready for this cipher. 41 * 42 * \note For now, only checks the state of the driver subsystem, 43 * not the algorithm. Might do more in the future. 44 * 45 * \param cipher_alg The cipher algorithm (ignored for now). 46 * 47 * \return 1 if the driver subsytem is ready, 0 otherwise. 48 */ 49int psa_can_do_cipher(psa_key_type_t key_type, psa_algorithm_t cipher_alg); 50 51typedef enum { 52 PSA_SLOT_EMPTY = 0, 53 PSA_SLOT_FILLING, 54 PSA_SLOT_FULL, 55 PSA_SLOT_PENDING_DELETION, 56} psa_key_slot_state_t; 57 58/** The data structure representing a key slot, containing key material 59 * and metadata for one key. 60 */ 61typedef struct { 62 psa_key_attributes_t attr; 63 64 /* 65 * The current state of the key slot, as described in 66 * docs/architecture/psa-thread-safety/psa-thread-safety.md. 67 * 68 * Library functions can modify the state of a key slot by calling 69 * psa_key_slot_state_transition. 70 * 71 * The state variable is used to help determine whether library functions 72 * which operate on the slot succeed. For example, psa_finish_key_creation, 73 * which transfers the state of a slot from PSA_SLOT_FILLING to 74 * PSA_SLOT_FULL, must fail with error code PSA_ERROR_CORRUPTION_DETECTED 75 * if the state of the slot is not PSA_SLOT_FILLING. 76 * 77 * Library functions which traverse the array of key slots only consider 78 * slots that are in a suitable state for the function. 79 * For example, psa_get_and_lock_key_slot_in_memory, which finds a slot 80 * containing a given key ID, will only check slots whose state variable is 81 * PSA_SLOT_FULL. */ 82 psa_key_slot_state_t state; 83 84 /* 85 * Number of functions registered as reading the material in the key slot. 86 * 87 * Library functions must not write directly to registered_readers 88 * 89 * A function must call psa_register_read(slot) before reading the current 90 * contents of the slot for an operation. 91 * They then must call psa_unregister_read(slot) once they have finished 92 * reading the current contents of the slot. If the key slot mutex is not 93 * held (when mutexes are enabled), this call must be done via a call to 94 * psa_unregister_read_under_mutex(slot). 95 * A function must call psa_key_slot_has_readers(slot) to check if 96 * the slot is in use for reading. 97 * 98 * This counter is used to prevent resetting the key slot while the library 99 * may access it. For example, such control is needed in the following 100 * scenarios: 101 * . In case of key slot starvation, all key slots contain the description 102 * of a key, and the library asks for the description of a persistent 103 * key not present in the key slots, the key slots currently accessed by 104 * the library cannot be reclaimed to free a key slot to load the 105 * persistent key. 106 * . In case of a multi-threaded application where one thread asks to close 107 * or purge or destroy a key while it is in use by the library through 108 * another thread. */ 109 size_t registered_readers; 110 111 /* Dynamically allocated key data buffer. 112 * Format as specified in psa_export_key(). */ 113 struct key_data { 114 uint8_t *data; 115 size_t bytes; 116 } key; 117} psa_key_slot_t; 118 119#if defined(MBEDTLS_THREADING_C) 120 121/** Perform a mutex operation and return immediately upon failure. 122 * 123 * Returns PSA_ERROR_SERVICE_FAILURE if the operation fails 124 * and status was PSA_SUCCESS. 125 * 126 * Assumptions: 127 * psa_status_t status exists. 128 * f is a mutex operation which returns 0 upon success. 129 */ 130#define PSA_THREADING_CHK_RET(f) \ 131 do \ 132 { \ 133 if ((f) != 0) { \ 134 if (status == PSA_SUCCESS) { \ 135 return PSA_ERROR_SERVICE_FAILURE; \ 136 } \ 137 return status; \ 138 } \ 139 } while (0); 140 141/** Perform a mutex operation and goto exit on failure. 142 * 143 * Sets status to PSA_ERROR_SERVICE_FAILURE if status was PSA_SUCCESS. 144 * 145 * Assumptions: 146 * psa_status_t status exists. 147 * Label exit: exists. 148 * f is a mutex operation which returns 0 upon success. 149 */ 150#define PSA_THREADING_CHK_GOTO_EXIT(f) \ 151 do \ 152 { \ 153 if ((f) != 0) { \ 154 if (status == PSA_SUCCESS) { \ 155 status = PSA_ERROR_SERVICE_FAILURE; \ 156 } \ 157 goto exit; \ 158 } \ 159 } while (0); 160#endif 161 162/** Test whether a key slot has any registered readers. 163 * If multi-threading is enabled, the caller must hold the 164 * global key slot mutex. 165 * 166 * \param[in] slot The key slot to test. 167 * 168 * \return 1 if the slot has any registered readers, 0 otherwise. 169 */ 170static inline int psa_key_slot_has_readers(const psa_key_slot_t *slot) 171{ 172 return slot->registered_readers > 0; 173} 174 175#if defined(MBEDTLS_PSA_CRYPTO_SE_C) 176/** Get the SE slot number of a key from the key slot storing its description. 177 * 178 * \param[in] slot The key slot to query. This must be a key slot storing 179 * the description of a key of a dynamically registered 180 * secure element, otherwise the behaviour is undefined. 181 */ 182static inline psa_key_slot_number_t psa_key_slot_get_slot_number( 183 const psa_key_slot_t *slot) 184{ 185 return *((psa_key_slot_number_t *) (slot->key.data)); 186} 187#endif 188 189/** Completely wipe a slot in memory, including its policy. 190 * 191 * Persistent storage is not affected. 192 * Sets the slot's state to PSA_SLOT_EMPTY. 193 * If multi-threading is enabled, the caller must hold the 194 * global key slot mutex. 195 * 196 * \param[in,out] slot The key slot to wipe. 197 * 198 * \retval #PSA_SUCCESS 199 * The slot has been successfully wiped. 200 * \retval #PSA_ERROR_CORRUPTION_DETECTED 201 * The slot's state was PSA_SLOT_FULL or PSA_SLOT_PENDING_DELETION, and 202 * the amount of registered readers was not equal to 1. Or, 203 * the slot's state was PSA_SLOT_EMPTY. Or, 204 * the slot's state was PSA_SLOT_FILLING, and the amount 205 * of registered readers was not equal to 0. 206 */ 207psa_status_t psa_wipe_key_slot(psa_key_slot_t *slot); 208 209/** Try to allocate a buffer to an empty key slot. 210 * 211 * \param[in,out] slot Key slot to attach buffer to. 212 * \param[in] buffer_length Requested size of the buffer. 213 * 214 * \retval #PSA_SUCCESS 215 * The buffer has been successfully allocated. 216 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 217 * Not enough memory was available for allocation. 218 * \retval #PSA_ERROR_ALREADY_EXISTS 219 * Trying to allocate a buffer to a non-empty key slot. 220 */ 221psa_status_t psa_allocate_buffer_to_slot(psa_key_slot_t *slot, 222 size_t buffer_length); 223 224/** Wipe key data from a slot. Preserves metadata such as the policy. */ 225psa_status_t psa_remove_key_data_from_memory(psa_key_slot_t *slot); 226 227/** Copy key data (in export format) into an empty key slot. 228 * 229 * This function assumes that the slot does not contain 230 * any key material yet. On failure, the slot content is unchanged. 231 * 232 * \param[in,out] slot Key slot to copy the key into. 233 * \param[in] data Buffer containing the key material. 234 * \param data_length Size of the key buffer. 235 * 236 * \retval #PSA_SUCCESS 237 * The key has been copied successfully. 238 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 239 * Not enough memory was available for allocation of the 240 * copy buffer. 241 * \retval #PSA_ERROR_ALREADY_EXISTS 242 * There was other key material already present in the slot. 243 */ 244psa_status_t psa_copy_key_material_into_slot(psa_key_slot_t *slot, 245 const uint8_t *data, 246 size_t data_length); 247 248/** Convert an Mbed TLS error code to a PSA error code 249 * 250 * \note This function is provided solely for the convenience of 251 * Mbed TLS and may be removed at any time without notice. 252 * 253 * \param ret An Mbed TLS-thrown error code 254 * 255 * \return The corresponding PSA error code 256 */ 257psa_status_t mbedtls_to_psa_error(int ret); 258 259/** Import a key in binary format. 260 * 261 * \note The signature of this function is that of a PSA driver 262 * import_key entry point. This function behaves as an import_key 263 * entry point as defined in the PSA driver interface specification for 264 * transparent drivers. 265 * 266 * \param[in] attributes The attributes for the key to import. 267 * \param[in] data The buffer containing the key data in import 268 * format. 269 * \param[in] data_length Size of the \p data buffer in bytes. 270 * \param[out] key_buffer The buffer to contain the key data in output 271 * format upon successful return. 272 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. This 273 * size is greater or equal to \p data_length. 274 * \param[out] key_buffer_length The length of the data written in \p 275 * key_buffer in bytes. 276 * \param[out] bits The key size in number of bits. 277 * 278 * \retval #PSA_SUCCESS The key was imported successfully. 279 * \retval #PSA_ERROR_INVALID_ARGUMENT 280 * The key data is not correctly formatted. 281 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 282 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 283 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 284 */ 285psa_status_t psa_import_key_into_slot( 286 const psa_key_attributes_t *attributes, 287 const uint8_t *data, size_t data_length, 288 uint8_t *key_buffer, size_t key_buffer_size, 289 size_t *key_buffer_length, size_t *bits); 290 291/** Export a key in binary format 292 * 293 * \note The signature of this function is that of a PSA driver export_key 294 * entry point. This function behaves as an export_key entry point as 295 * defined in the PSA driver interface specification. 296 * 297 * \param[in] attributes The attributes for the key to export. 298 * \param[in] key_buffer Material or context of the key to export. 299 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 300 * \param[out] data Buffer where the key data is to be written. 301 * \param[in] data_size Size of the \p data buffer in bytes. 302 * \param[out] data_length On success, the number of bytes written in 303 * \p data 304 * 305 * \retval #PSA_SUCCESS The key was exported successfully. 306 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 307 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 308 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 309 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 310 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 311 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 312 */ 313psa_status_t psa_export_key_internal( 314 const psa_key_attributes_t *attributes, 315 const uint8_t *key_buffer, size_t key_buffer_size, 316 uint8_t *data, size_t data_size, size_t *data_length); 317 318/** Export a public key or the public part of a key pair in binary format. 319 * 320 * \note The signature of this function is that of a PSA driver 321 * export_public_key entry point. This function behaves as an 322 * export_public_key entry point as defined in the PSA driver interface 323 * specification. 324 * 325 * \param[in] attributes The attributes for the key to export. 326 * \param[in] key_buffer Material or context of the key to export. 327 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 328 * \param[out] data Buffer where the key data is to be written. 329 * \param[in] data_size Size of the \p data buffer in bytes. 330 * \param[out] data_length On success, the number of bytes written in 331 * \p data 332 * 333 * \retval #PSA_SUCCESS The public key was exported successfully. 334 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 335 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 336 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 337 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 338 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 339 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 340 */ 341psa_status_t psa_export_public_key_internal( 342 const psa_key_attributes_t *attributes, 343 const uint8_t *key_buffer, size_t key_buffer_size, 344 uint8_t *data, size_t data_size, size_t *data_length); 345 346/** Whether a key production parameters structure is the default. 347 * 348 * Calls to a key generation driver with non-default production parameters 349 * require a driver supporting custom production parameters. 350 * 351 * \param[in] params The key production parameters to check. 352 * \param params_data_length Size of `params->data` in bytes. 353 */ 354int psa_key_production_parameters_are_default( 355 const psa_key_production_parameters_t *params, 356 size_t params_data_length); 357 358/** 359 * \brief Generate a key. 360 * 361 * \note The signature of the function is that of a PSA driver generate_key 362 * entry point. 363 * 364 * \param[in] attributes The attributes for the key to generate. 365 * \param[in] params The production parameters from 366 * psa_generate_key_ext(). 367 * \param params_data_length The size of `params->data` in bytes. 368 * \param[out] key_buffer Buffer where the key data is to be written. 369 * \param[in] key_buffer_size Size of \p key_buffer in bytes. 370 * \param[out] key_buffer_length On success, the number of bytes written in 371 * \p key_buffer. 372 * 373 * \retval #PSA_SUCCESS 374 * The key was generated successfully. 375 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 376 * \retval #PSA_ERROR_NOT_SUPPORTED 377 * Key size in bits or type not supported. 378 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 379 * The size of \p key_buffer is too small. 380 */ 381psa_status_t psa_generate_key_internal(const psa_key_attributes_t *attributes, 382 const psa_key_production_parameters_t *params, 383 size_t params_data_length, 384 uint8_t *key_buffer, 385 size_t key_buffer_size, 386 size_t *key_buffer_length); 387 388/** Sign a message with a private key. For hash-and-sign algorithms, 389 * this includes the hashing step. 390 * 391 * \note The signature of this function is that of a PSA driver 392 * sign_message entry point. This function behaves as a sign_message 393 * entry point as defined in the PSA driver interface specification for 394 * transparent drivers. 395 * 396 * \note This function will call the driver for psa_sign_hash 397 * and go through driver dispatch again. 398 * 399 * \param[in] attributes The attributes of the key to use for the 400 * operation. 401 * \param[in] key_buffer The buffer containing the key context. 402 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 403 * \param[in] alg A signature algorithm that is compatible with 404 * the type of the key. 405 * \param[in] input The input message to sign. 406 * \param[in] input_length Size of the \p input buffer in bytes. 407 * \param[out] signature Buffer where the signature is to be written. 408 * \param[in] signature_size Size of the \p signature buffer in bytes. 409 * \param[out] signature_length On success, the number of bytes 410 * that make up the returned signature value. 411 * 412 * \retval #PSA_SUCCESS \emptydescription 413 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 414 * The size of the \p signature buffer is too small. You can 415 * determine a sufficient buffer size by calling 416 * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) 417 * where \c key_type and \c key_bits are the type and bit-size 418 * respectively of the key. 419 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 420 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 421 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 422 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 423 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 424 */ 425psa_status_t psa_sign_message_builtin( 426 const psa_key_attributes_t *attributes, 427 const uint8_t *key_buffer, size_t key_buffer_size, 428 psa_algorithm_t alg, const uint8_t *input, size_t input_length, 429 uint8_t *signature, size_t signature_size, size_t *signature_length); 430 431/** Verify the signature of a message with a public key, using 432 * a hash-and-sign verification algorithm. 433 * 434 * \note The signature of this function is that of a PSA driver 435 * verify_message entry point. This function behaves as a verify_message 436 * entry point as defined in the PSA driver interface specification for 437 * transparent drivers. 438 * 439 * \note This function will call the driver for psa_verify_hash 440 * and go through driver dispatch again. 441 * 442 * \param[in] attributes The attributes of the key to use for the 443 * operation. 444 * \param[in] key_buffer The buffer containing the key context. 445 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 446 * \param[in] alg A signature algorithm that is compatible with 447 * the type of the key. 448 * \param[in] input The message whose signature is to be verified. 449 * \param[in] input_length Size of the \p input buffer in bytes. 450 * \param[in] signature Buffer containing the signature to verify. 451 * \param[in] signature_length Size of the \p signature buffer in bytes. 452 * 453 * \retval #PSA_SUCCESS 454 * The signature is valid. 455 * \retval #PSA_ERROR_INVALID_SIGNATURE 456 * The calculation was performed successfully, but the passed 457 * signature is not a valid signature. 458 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 459 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 460 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 461 */ 462psa_status_t psa_verify_message_builtin( 463 const psa_key_attributes_t *attributes, 464 const uint8_t *key_buffer, size_t key_buffer_size, 465 psa_algorithm_t alg, const uint8_t *input, size_t input_length, 466 const uint8_t *signature, size_t signature_length); 467 468/** Sign an already-calculated hash with a private key. 469 * 470 * \note The signature of this function is that of a PSA driver 471 * sign_hash entry point. This function behaves as a sign_hash 472 * entry point as defined in the PSA driver interface specification for 473 * transparent drivers. 474 * 475 * \param[in] attributes The attributes of the key to use for the 476 * operation. 477 * \param[in] key_buffer The buffer containing the key context. 478 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 479 * \param[in] alg A signature algorithm that is compatible with 480 * the type of the key. 481 * \param[in] hash The hash or message to sign. 482 * \param[in] hash_length Size of the \p hash buffer in bytes. 483 * \param[out] signature Buffer where the signature is to be written. 484 * \param[in] signature_size Size of the \p signature buffer in bytes. 485 * \param[out] signature_length On success, the number of bytes 486 * that make up the returned signature value. 487 * 488 * \retval #PSA_SUCCESS \emptydescription 489 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 490 * The size of the \p signature buffer is too small. You can 491 * determine a sufficient buffer size by calling 492 * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) 493 * where \c key_type and \c key_bits are the type and bit-size 494 * respectively of the key. 495 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 496 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 497 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 498 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 499 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 500 */ 501psa_status_t psa_sign_hash_builtin( 502 const psa_key_attributes_t *attributes, 503 const uint8_t *key_buffer, size_t key_buffer_size, 504 psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, 505 uint8_t *signature, size_t signature_size, size_t *signature_length); 506 507/** 508 * \brief Verify the signature a hash or short message using a public key. 509 * 510 * \note The signature of this function is that of a PSA driver 511 * verify_hash entry point. This function behaves as a verify_hash 512 * entry point as defined in the PSA driver interface specification for 513 * transparent drivers. 514 * 515 * \param[in] attributes The attributes of the key to use for the 516 * operation. 517 * \param[in] key_buffer The buffer containing the key context. 518 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 519 * \param[in] alg A signature algorithm that is compatible with 520 * the type of the key. 521 * \param[in] hash The hash or message whose signature is to be 522 * verified. 523 * \param[in] hash_length Size of the \p hash buffer in bytes. 524 * \param[in] signature Buffer containing the signature to verify. 525 * \param[in] signature_length Size of the \p signature buffer in bytes. 526 * 527 * \retval #PSA_SUCCESS 528 * The signature is valid. 529 * \retval #PSA_ERROR_INVALID_SIGNATURE 530 * The calculation was performed successfully, but the passed 531 * signature is not a valid signature. 532 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 533 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 534 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 535 */ 536psa_status_t psa_verify_hash_builtin( 537 const psa_key_attributes_t *attributes, 538 const uint8_t *key_buffer, size_t key_buffer_size, 539 psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, 540 const uint8_t *signature, size_t signature_length); 541 542/** 543 * \brief Validate the key bit size for unstructured keys. 544 * 545 * \note Check that the bit size is acceptable for a given key type for 546 * unstructured keys. 547 * 548 * \param[in] type The key type 549 * \param[in] bits The number of bits of the key 550 * 551 * \retval #PSA_SUCCESS 552 * The key type and size are valid. 553 * \retval #PSA_ERROR_INVALID_ARGUMENT 554 * The size in bits of the key is not valid. 555 * \retval #PSA_ERROR_NOT_SUPPORTED 556 * The type and/or the size in bits of the key or the combination of 557 * the two is not supported. 558 */ 559psa_status_t psa_validate_unstructured_key_bit_size(psa_key_type_t type, 560 size_t bits); 561 562/** Perform a key agreement and return the raw shared secret, using 563 built-in raw key agreement functions. 564 * 565 * \note The signature of this function is that of a PSA driver 566 * key_agreement entry point. This function behaves as a key_agreement 567 * entry point as defined in the PSA driver interface specification for 568 * transparent drivers. 569 * 570 * \param[in] attributes The attributes of the key to use for the 571 * operation. 572 * \param[in] key_buffer The buffer containing the private key 573 * context. 574 * \param[in] key_buffer_size Size of the \p key_buffer buffer in 575 * bytes. 576 * \param[in] alg A key agreement algorithm that is 577 * compatible with the type of the key. 578 * \param[in] peer_key The buffer containing the key context 579 * of the peer's public key. 580 * \param[in] peer_key_length Size of the \p peer_key buffer in 581 * bytes. 582 * \param[out] shared_secret The buffer to which the shared secret 583 * is to be written. 584 * \param[in] shared_secret_size Size of the \p shared_secret buffer in 585 * bytes. 586 * \param[out] shared_secret_length On success, the number of bytes that make 587 * up the returned shared secret. 588 * \retval #PSA_SUCCESS 589 * Success. Shared secret successfully calculated. 590 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 591 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 592 * \retval #PSA_ERROR_INVALID_ARGUMENT 593 * \p alg is not a key agreement algorithm, or 594 * \p private_key is not compatible with \p alg, 595 * or \p peer_key is not valid for \p alg or not compatible with 596 * \p private_key. 597 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 598 * \p shared_secret_size is too small 599 * \retval #PSA_ERROR_NOT_SUPPORTED 600 * \p alg is not a supported key agreement algorithm. 601 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 602 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 603 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 604 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 605 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 606 * \retval #PSA_ERROR_BAD_STATE \emptydescription 607 */ 608psa_status_t psa_key_agreement_raw_builtin( 609 const psa_key_attributes_t *attributes, 610 const uint8_t *key_buffer, 611 size_t key_buffer_size, 612 psa_algorithm_t alg, 613 const uint8_t *peer_key, 614 size_t peer_key_length, 615 uint8_t *shared_secret, 616 size_t shared_secret_size, 617 size_t *shared_secret_length); 618 619/** 620 * \brief Set the maximum number of ops allowed to be executed by an 621 * interruptible function in a single call. 622 * 623 * \note The signature of this function is that of a PSA driver 624 * interruptible_set_max_ops entry point. This function behaves as an 625 * interruptible_set_max_ops entry point as defined in the PSA driver 626 * interface specification for transparent drivers. 627 * 628 * \param[in] max_ops The maximum number of ops to be executed in a 629 * single call, this can be a number from 0 to 630 * #PSA_INTERRUPTIBLE_MAX_OPS_UNLIMITED, where 0 631 * is obviously the least amount of work done per 632 * call. 633 */ 634void mbedtls_psa_interruptible_set_max_ops(uint32_t max_ops); 635 636/** 637 * \brief Get the maximum number of ops allowed to be executed by an 638 * interruptible function in a single call. 639 * 640 * \note The signature of this function is that of a PSA driver 641 * interruptible_get_max_ops entry point. This function behaves as an 642 * interruptible_get_max_ops entry point as defined in the PSA driver 643 * interface specification for transparent drivers. 644 * 645 * \return Maximum number of ops allowed to be executed 646 * by an interruptible function in a single call. 647 */ 648uint32_t mbedtls_psa_interruptible_get_max_ops(void); 649 650/** 651 * \brief Get the number of ops that a hash signing operation has taken for the 652 * previous call. If no call or work has taken place, this will return 653 * zero. 654 * 655 * \note The signature of this function is that of a PSA driver 656 * sign_hash_get_num_ops entry point. This function behaves as an 657 * sign_hash_get_num_ops entry point as defined in the PSA driver 658 * interface specification for transparent drivers. 659 * 660 * \param operation The \c 661 * mbedtls_psa_sign_hash_interruptible_operation_t 662 * to use. This must be initialized first. 663 * 664 * \return Number of ops that were completed 665 * in the last call to \c 666 * mbedtls_psa_sign_hash_complete(). 667 */ 668uint32_t mbedtls_psa_sign_hash_get_num_ops( 669 const mbedtls_psa_sign_hash_interruptible_operation_t *operation); 670 671/** 672 * \brief Get the number of ops that a hash verification operation has taken for 673 * the previous call. If no call or work has taken place, this will 674 * return zero. 675 * 676 * \note The signature of this function is that of a PSA driver 677 * verify_hash_get_num_ops entry point. This function behaves as an 678 * verify_hash_get_num_ops entry point as defined in the PSA driver 679 * interface specification for transparent drivers. 680 * 681 * \param operation The \c 682 * mbedtls_psa_verify_hash_interruptible_operation_t 683 * to use. This must be initialized first. 684 * 685 * \return Number of ops that were completed 686 * in the last call to \c 687 * mbedtls_psa_verify_hash_complete(). 688 */ 689uint32_t mbedtls_psa_verify_hash_get_num_ops( 690 const mbedtls_psa_verify_hash_interruptible_operation_t *operation); 691 692/** 693 * \brief Start signing a hash or short message with a private key, in an 694 * interruptible manner. 695 * 696 * \note The signature of this function is that of a PSA driver 697 * sign_hash_start entry point. This function behaves as a 698 * sign_hash_start entry point as defined in the PSA driver interface 699 * specification for transparent drivers. 700 * 701 * \param[in] operation The \c 702 * mbedtls_psa_sign_hash_interruptible_operation_t 703 * to use. This must be initialized first. 704 * \param[in] attributes The attributes of the key to use for the 705 * operation. 706 * \param[in] key_buffer The buffer containing the key context. 707 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 708 * \param[in] alg A signature algorithm that is compatible with 709 * the type of the key. 710 * \param[in] hash The hash or message to sign. 711 * \param hash_length Size of the \p hash buffer in bytes. 712 * 713 * \retval #PSA_SUCCESS 714 * The operation started successfully - call \c psa_sign_hash_complete() 715 * with the same context to complete the operation 716 * \retval #PSA_ERROR_INVALID_ARGUMENT 717 * An unsupported, incorrectly formatted or incorrect type of key was 718 * used. 719 * \retval #PSA_ERROR_NOT_SUPPORTED Either no internal interruptible operations 720 * are currently supported, or the key type is currently unsupported. 721 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 722 * There was insufficient memory to load the key representation. 723 */ 724psa_status_t mbedtls_psa_sign_hash_start( 725 mbedtls_psa_sign_hash_interruptible_operation_t *operation, 726 const psa_key_attributes_t *attributes, const uint8_t *key_buffer, 727 size_t key_buffer_size, psa_algorithm_t alg, 728 const uint8_t *hash, size_t hash_length); 729 730/** 731 * \brief Continue and eventually complete the action of signing a hash or 732 * short message with a private key, in an interruptible manner. 733 * 734 * \note The signature of this function is that of a PSA driver 735 * sign_hash_complete entry point. This function behaves as a 736 * sign_hash_complete entry point as defined in the PSA driver interface 737 * specification for transparent drivers. 738 * 739 * \param[in] operation The \c 740 * mbedtls_psa_sign_hash_interruptible_operation_t 741 * to use. This must be initialized first. 742 * 743 * \param[out] signature Buffer where the signature is to be written. 744 * \param signature_size Size of the \p signature buffer in bytes. This 745 * must be appropriate for the selected 746 * algorithm and key. 747 * \param[out] signature_length On success, the number of bytes that make up 748 * the returned signature value. 749 * 750 * \retval #PSA_SUCCESS 751 * Operation completed successfully 752 * 753 * \retval #PSA_OPERATION_INCOMPLETE 754 * Operation was interrupted due to the setting of \c 755 * psa_interruptible_set_max_ops(), there is still work to be done, 756 * please call this function again with the same operation object. 757 * 758 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 759 * The size of the \p signature buffer is too small. You can 760 * determine a sufficient buffer size by calling 761 * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) 762 * where \c key_type and \c key_bits are the type and bit-size 763 * respectively of \p key. 764 * 765 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 766 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 767 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 768 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 769 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 770 */ 771psa_status_t mbedtls_psa_sign_hash_complete( 772 mbedtls_psa_sign_hash_interruptible_operation_t *operation, 773 uint8_t *signature, size_t signature_size, 774 size_t *signature_length); 775 776/** 777 * \brief Abort a sign hash operation. 778 * 779 * \note The signature of this function is that of a PSA driver sign_hash_abort 780 * entry point. This function behaves as a sign_hash_abort entry point as 781 * defined in the PSA driver interface specification for transparent 782 * drivers. 783 * 784 * \param[in] operation The \c 785 * mbedtls_psa_sign_hash_interruptible_operation_t 786 * to abort. 787 * 788 * \retval #PSA_SUCCESS 789 * The operation was aborted successfully. 790 */ 791psa_status_t mbedtls_psa_sign_hash_abort( 792 mbedtls_psa_sign_hash_interruptible_operation_t *operation); 793 794/** 795 * \brief Start reading and verifying a hash or short message, in an 796 * interruptible manner. 797 * 798 * \note The signature of this function is that of a PSA driver 799 * verify_hash_start entry point. This function behaves as a 800 * verify_hash_start entry point as defined in the PSA driver interface 801 * specification for transparent drivers. 802 * 803 * \param[in] operation The \c 804 * mbedtls_psa_verify_hash_interruptible_operation_t 805 * to use. This must be initialized first. 806 * \param[in] attributes The attributes of the key to use for the 807 * operation. 808 * \param[in] key_buffer The buffer containing the key context. 809 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 810 * \param[in] alg A signature algorithm that is compatible with 811 * the type of the key. 812 * \param[in] hash The hash whose signature is to be verified. 813 * \param hash_length Size of the \p hash buffer in bytes. 814 * \param[in] signature Buffer containing the signature to verify. 815 * \param signature_length Size of the \p signature buffer in bytes. 816 * 817 * \retval #PSA_SUCCESS 818 * The operation started successfully - call \c psa_sign_hash_complete() 819 * with the same context to complete the operation 820 * \retval #PSA_ERROR_INVALID_ARGUMENT 821 * An unsupported or incorrect type of key was used. 822 * \retval #PSA_ERROR_NOT_SUPPORTED 823 * Either no internal interruptible operations are currently supported, 824 * or the key type is currently unsupported. 825 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 826 * There was insufficient memory either to load the key representation, 827 * or to prepare the operation. 828 */ 829psa_status_t mbedtls_psa_verify_hash_start( 830 mbedtls_psa_verify_hash_interruptible_operation_t *operation, 831 const psa_key_attributes_t *attributes, 832 const uint8_t *key_buffer, size_t key_buffer_size, 833 psa_algorithm_t alg, 834 const uint8_t *hash, size_t hash_length, 835 const uint8_t *signature, size_t signature_length); 836 837/** 838 * \brief Continue and eventually complete the action of signing a hash or 839 * short message with a private key, in an interruptible manner. 840 * 841 * \note The signature of this function is that of a PSA driver 842 * sign_hash_complete entry point. This function behaves as a 843 * sign_hash_complete entry point as defined in the PSA driver interface 844 * specification for transparent drivers. 845 * 846 * \param[in] operation The \c 847 * mbedtls_psa_sign_hash_interruptible_operation_t 848 * to use. This must be initialized first. 849 * 850 * \retval #PSA_SUCCESS 851 * Operation completed successfully, and the passed signature is valid. 852 * 853 * \retval #PSA_OPERATION_INCOMPLETE 854 * Operation was interrupted due to the setting of \c 855 * psa_interruptible_set_max_ops(), there is still work to be done, 856 * please call this function again with the same operation object. 857 * 858 * \retval #PSA_ERROR_INVALID_SIGNATURE 859 * The calculation was performed successfully, but the passed 860 * signature is not a valid signature. 861 * 862 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 863 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 864 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 865 */ 866psa_status_t mbedtls_psa_verify_hash_complete( 867 mbedtls_psa_verify_hash_interruptible_operation_t *operation); 868 869/** 870 * \brief Abort a verify signed hash operation. 871 * 872 * \note The signature of this function is that of a PSA driver 873 * verify_hash_abort entry point. This function behaves as a 874 * verify_hash_abort entry point as defined in the PSA driver interface 875 * specification for transparent drivers. 876 * 877 * \param[in] operation The \c 878 * mbedtls_psa_verify_hash_interruptible_operation_t 879 * to abort. 880 * 881 * \retval #PSA_SUCCESS 882 * The operation was aborted successfully. 883 */ 884psa_status_t mbedtls_psa_verify_hash_abort( 885 mbedtls_psa_verify_hash_interruptible_operation_t *operation); 886 887typedef struct psa_crypto_local_input_s { 888 uint8_t *buffer; 889 size_t length; 890} psa_crypto_local_input_t; 891 892#define PSA_CRYPTO_LOCAL_INPUT_INIT ((psa_crypto_local_input_t) { NULL, 0 }) 893 894/** Allocate a local copy of an input buffer and copy the contents into it. 895 * 896 * \param[in] input Pointer to input buffer. 897 * \param[in] input_len Length of the input buffer. 898 * \param[out] local_input Pointer to a psa_crypto_local_input_t struct 899 * containing a local input copy. 900 * \return #PSA_SUCCESS, if the buffer was successfully 901 * copied. 902 * \return #PSA_ERROR_INSUFFICIENT_MEMORY, if a copy of 903 * the buffer cannot be allocated. 904 */ 905psa_status_t psa_crypto_local_input_alloc(const uint8_t *input, size_t input_len, 906 psa_crypto_local_input_t *local_input); 907 908/** Free a local copy of an input buffer. 909 * 910 * \param[in] local_input Pointer to a psa_crypto_local_input_t struct 911 * populated by a previous call to 912 * psa_crypto_local_input_alloc(). 913 */ 914void psa_crypto_local_input_free(psa_crypto_local_input_t *local_input); 915 916typedef struct psa_crypto_local_output_s { 917 uint8_t *original; 918 uint8_t *buffer; 919 size_t length; 920} psa_crypto_local_output_t; 921 922#define PSA_CRYPTO_LOCAL_OUTPUT_INIT ((psa_crypto_local_output_t) { NULL, NULL, 0 }) 923 924/** Allocate a local copy of an output buffer. 925 * 926 * \note This does not copy any data from the original 927 * output buffer but only allocates a buffer 928 * whose contents will be copied back to the 929 * original in a future call to 930 * psa_crypto_local_output_free(). 931 * 932 * \param[in] output Pointer to output buffer. 933 * \param[in] output_len Length of the output buffer. 934 * \param[out] local_output Pointer to a psa_crypto_local_output_t struct to 935 * populate with the local output copy. 936 * \return #PSA_SUCCESS, if the buffer was successfully 937 * copied. 938 * \return #PSA_ERROR_INSUFFICIENT_MEMORY, if a copy of 939 * the buffer cannot be allocated. 940 */ 941psa_status_t psa_crypto_local_output_alloc(uint8_t *output, size_t output_len, 942 psa_crypto_local_output_t *local_output); 943 944/** Copy from a local copy of an output buffer back to the original, then 945 * free the local copy. 946 * 947 * \param[in] local_output Pointer to a psa_crypto_local_output_t struct 948 * populated by a previous call to 949 * psa_crypto_local_output_alloc(). 950 * \return #PSA_SUCCESS, if the local output was 951 * successfully copied back to the original. 952 * \return #PSA_ERROR_CORRUPTION_DETECTED, if the output 953 * could not be copied back to the original. 954 */ 955psa_status_t psa_crypto_local_output_free(psa_crypto_local_output_t *local_output); 956 957#endif /* PSA_CRYPTO_CORE_H */ 958