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