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