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