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