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 */
psa_key_slot_has_readers(const psa_key_slot_t * slot)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 */
psa_key_slot_get_slot_number(const psa_key_slot_t * slot)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 */
996