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 #include "mbedtls/build_info.h"
13
14 #include "psa/crypto.h"
15 #include "psa/crypto_se_driver.h"
16
17 /**
18 * Tell if PSA is ready for this hash.
19 *
20 * \note For now, only checks the state of the driver subsystem,
21 * not the algorithm. Might do more in the future.
22 *
23 * \param hash_alg The hash algorithm (ignored for now).
24 *
25 * \return 1 if the driver subsytem is ready, 0 otherwise.
26 */
27 int psa_can_do_hash(psa_algorithm_t hash_alg);
28
29 /** The data structure representing a key slot, containing key material
30 * and metadata for one key.
31 */
32 typedef struct {
33 psa_core_key_attributes_t attr;
34
35 /*
36 * Number of locks on the key slot held by the library.
37 *
38 * This counter is incremented by one each time a library function
39 * retrieves through one of the dedicated internal API a pointer to the
40 * key slot.
41 *
42 * This counter is decremented by one each time a library function stops
43 * accessing the key slot and states it by calling the
44 * psa_unlock_key_slot() API.
45 *
46 * This counter is used to prevent resetting the key slot while the library
47 * may access it. For example, such control is needed in the following
48 * scenarios:
49 * . In case of key slot starvation, all key slots contain the description
50 * of a key, and the library asks for the description of a persistent
51 * key not present in the key slots, the key slots currently accessed by
52 * the library cannot be reclaimed to free a key slot to load the
53 * persistent key.
54 * . In case of a multi-threaded application where one thread asks to close
55 * or purge or destroy a key while it is in used by the library through
56 * another thread.
57 */
58 size_t lock_count;
59
60 /* Dynamically allocated key data buffer.
61 * Format as specified in psa_export_key(). */
62 struct key_data {
63 uint8_t *data;
64 size_t bytes;
65 } key;
66 } psa_key_slot_t;
67
68 /* A mask of key attribute flags used only internally.
69 * Currently there aren't any. */
70 #define PSA_KA_MASK_INTERNAL_ONLY ( \
71 0)
72
73 /** Test whether a key slot is occupied.
74 *
75 * A key slot is occupied iff the key type is nonzero. This works because
76 * no valid key can have 0 as its key type.
77 *
78 * \param[in] slot The key slot to test.
79 *
80 * \return 1 if the slot is occupied, 0 otherwise.
81 */
psa_is_key_slot_occupied(const psa_key_slot_t * slot)82 static inline int psa_is_key_slot_occupied(const psa_key_slot_t *slot)
83 {
84 return slot->attr.type != 0;
85 }
86
87 /** Test whether a key slot is locked.
88 *
89 * A key slot is locked iff its lock counter is strictly greater than 0.
90 *
91 * \param[in] slot The key slot to test.
92 *
93 * \return 1 if the slot is locked, 0 otherwise.
94 */
psa_is_key_slot_locked(const psa_key_slot_t * slot)95 static inline int psa_is_key_slot_locked(const psa_key_slot_t *slot)
96 {
97 return slot->lock_count > 0;
98 }
99
100 /** Retrieve flags from psa_key_slot_t::attr::core::flags.
101 *
102 * \param[in] slot The key slot to query.
103 * \param mask The mask of bits to extract.
104 *
105 * \return The key attribute flags in the given slot,
106 * bitwise-anded with \p mask.
107 */
psa_key_slot_get_flags(const psa_key_slot_t * slot,uint16_t mask)108 static inline uint16_t psa_key_slot_get_flags(const psa_key_slot_t *slot,
109 uint16_t mask)
110 {
111 return slot->attr.flags & mask;
112 }
113
114 /** Set flags in psa_key_slot_t::attr::core::flags.
115 *
116 * \param[in,out] slot The key slot to modify.
117 * \param mask The mask of bits to modify.
118 * \param value The new value of the selected bits.
119 */
psa_key_slot_set_flags(psa_key_slot_t * slot,uint16_t mask,uint16_t value)120 static inline void psa_key_slot_set_flags(psa_key_slot_t *slot,
121 uint16_t mask,
122 uint16_t value)
123 {
124 slot->attr.flags = ((~mask & slot->attr.flags) |
125 (mask & value));
126 }
127
128 /** Turn on flags in psa_key_slot_t::attr::core::flags.
129 *
130 * \param[in,out] slot The key slot to modify.
131 * \param mask The mask of bits to set.
132 */
psa_key_slot_set_bits_in_flags(psa_key_slot_t * slot,uint16_t mask)133 static inline void psa_key_slot_set_bits_in_flags(psa_key_slot_t *slot,
134 uint16_t mask)
135 {
136 slot->attr.flags |= mask;
137 }
138
139 /** Turn off flags in psa_key_slot_t::attr::core::flags.
140 *
141 * \param[in,out] slot The key slot to modify.
142 * \param mask The mask of bits to clear.
143 */
psa_key_slot_clear_bits(psa_key_slot_t * slot,uint16_t mask)144 static inline void psa_key_slot_clear_bits(psa_key_slot_t *slot,
145 uint16_t mask)
146 {
147 slot->attr.flags &= ~mask;
148 }
149
150 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
151 /** Get the SE slot number of a key from the key slot storing its description.
152 *
153 * \param[in] slot The key slot to query. This must be a key slot storing
154 * the description of a key of a dynamically registered
155 * secure element, otherwise the behaviour is undefined.
156 */
psa_key_slot_get_slot_number(const psa_key_slot_t * slot)157 static inline psa_key_slot_number_t psa_key_slot_get_slot_number(
158 const psa_key_slot_t *slot)
159 {
160 return *((psa_key_slot_number_t *) (slot->key.data));
161 }
162 #endif
163
164 /** Completely wipe a slot in memory, including its policy.
165 *
166 * Persistent storage is not affected.
167 *
168 * \param[in,out] slot The key slot to wipe.
169 *
170 * \retval #PSA_SUCCESS
171 * Success. This includes the case of a key slot that was
172 * already fully wiped.
173 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
174 */
175 psa_status_t psa_wipe_key_slot(psa_key_slot_t *slot);
176
177 /** Try to allocate a buffer to an empty key slot.
178 *
179 * \param[in,out] slot Key slot to attach buffer to.
180 * \param[in] buffer_length Requested size of the buffer.
181 *
182 * \retval #PSA_SUCCESS
183 * The buffer has been successfully allocated.
184 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
185 * Not enough memory was available for allocation.
186 * \retval #PSA_ERROR_ALREADY_EXISTS
187 * Trying to allocate a buffer to a non-empty key slot.
188 */
189 psa_status_t psa_allocate_buffer_to_slot(psa_key_slot_t *slot,
190 size_t buffer_length);
191
192 /** Wipe key data from a slot. Preserves metadata such as the policy. */
193 psa_status_t psa_remove_key_data_from_memory(psa_key_slot_t *slot);
194
195 /** Copy key data (in export format) into an empty key slot.
196 *
197 * This function assumes that the slot does not contain
198 * any key material yet. On failure, the slot content is unchanged.
199 *
200 * \param[in,out] slot Key slot to copy the key into.
201 * \param[in] data Buffer containing the key material.
202 * \param data_length Size of the key buffer.
203 *
204 * \retval #PSA_SUCCESS
205 * The key has been copied successfully.
206 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
207 * Not enough memory was available for allocation of the
208 * copy buffer.
209 * \retval #PSA_ERROR_ALREADY_EXISTS
210 * There was other key material already present in the slot.
211 */
212 psa_status_t psa_copy_key_material_into_slot(psa_key_slot_t *slot,
213 const uint8_t *data,
214 size_t data_length);
215
216 /** Convert an Mbed TLS error code to a PSA error code
217 *
218 * \note This function is provided solely for the convenience of
219 * Mbed TLS and may be removed at any time without notice.
220 *
221 * \param ret An Mbed TLS-thrown error code
222 *
223 * \return The corresponding PSA error code
224 */
225 psa_status_t mbedtls_to_psa_error(int ret);
226
227 /** Import a key in binary format.
228 *
229 * \note The signature of this function is that of a PSA driver
230 * import_key entry point. This function behaves as an import_key
231 * entry point as defined in the PSA driver interface specification for
232 * transparent drivers.
233 *
234 * \param[in] attributes The attributes for the key to import.
235 * \param[in] data The buffer containing the key data in import
236 * format.
237 * \param[in] data_length Size of the \p data buffer in bytes.
238 * \param[out] key_buffer The buffer to contain the key data in output
239 * format upon successful return.
240 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. This
241 * size is greater or equal to \p data_length.
242 * \param[out] key_buffer_length The length of the data written in \p
243 * key_buffer in bytes.
244 * \param[out] bits The key size in number of bits.
245 *
246 * \retval #PSA_SUCCESS The key was imported successfully.
247 * \retval #PSA_ERROR_INVALID_ARGUMENT
248 * The key data is not correctly formatted.
249 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
250 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
251 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
252 */
253 psa_status_t psa_import_key_into_slot(
254 const psa_key_attributes_t *attributes,
255 const uint8_t *data, size_t data_length,
256 uint8_t *key_buffer, size_t key_buffer_size,
257 size_t *key_buffer_length, size_t *bits);
258
259 /** Export a key in binary format
260 *
261 * \note The signature of this function is that of a PSA driver export_key
262 * entry point. This function behaves as an export_key entry point as
263 * defined in the PSA driver interface specification.
264 *
265 * \param[in] attributes The attributes for the key to export.
266 * \param[in] key_buffer Material or context of the key to export.
267 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
268 * \param[out] data Buffer where the key data is to be written.
269 * \param[in] data_size Size of the \p data buffer in bytes.
270 * \param[out] data_length On success, the number of bytes written in
271 * \p data
272 *
273 * \retval #PSA_SUCCESS The key was exported successfully.
274 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
275 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
276 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription
277 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
278 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
279 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
280 */
281 psa_status_t psa_export_key_internal(
282 const psa_key_attributes_t *attributes,
283 const uint8_t *key_buffer, size_t key_buffer_size,
284 uint8_t *data, size_t data_size, size_t *data_length);
285
286 /** Export a public key or the public part of a key pair in binary format.
287 *
288 * \note The signature of this function is that of a PSA driver
289 * export_public_key entry point. This function behaves as an
290 * export_public_key entry point as defined in the PSA driver interface
291 * specification.
292 *
293 * \param[in] attributes The attributes for the key to export.
294 * \param[in] key_buffer Material or context of the key to export.
295 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
296 * \param[out] data Buffer where the key data is to be written.
297 * \param[in] data_size Size of the \p data buffer in bytes.
298 * \param[out] data_length On success, the number of bytes written in
299 * \p data
300 *
301 * \retval #PSA_SUCCESS The public key was exported successfully.
302 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
303 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
304 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription
305 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
306 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
307 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
308 */
309 psa_status_t psa_export_public_key_internal(
310 const psa_key_attributes_t *attributes,
311 const uint8_t *key_buffer, size_t key_buffer_size,
312 uint8_t *data, size_t data_size, size_t *data_length);
313
314 /**
315 * \brief Generate a key.
316 *
317 * \note The signature of the function is that of a PSA driver generate_key
318 * entry point.
319 *
320 * \param[in] attributes The attributes for the key to generate.
321 * \param[out] key_buffer Buffer where the key data is to be written.
322 * \param[in] key_buffer_size Size of \p key_buffer in bytes.
323 * \param[out] key_buffer_length On success, the number of bytes written in
324 * \p key_buffer.
325 *
326 * \retval #PSA_SUCCESS
327 * The key was generated successfully.
328 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
329 * \retval #PSA_ERROR_NOT_SUPPORTED
330 * Key size in bits or type not supported.
331 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
332 * The size of \p key_buffer is too small.
333 */
334 psa_status_t psa_generate_key_internal(const psa_key_attributes_t *attributes,
335 uint8_t *key_buffer,
336 size_t key_buffer_size,
337 size_t *key_buffer_length);
338
339 /** Sign a message with a private key. For hash-and-sign algorithms,
340 * this includes the hashing step.
341 *
342 * \note The signature of this function is that of a PSA driver
343 * sign_message entry point. This function behaves as a sign_message
344 * entry point as defined in the PSA driver interface specification for
345 * transparent drivers.
346 *
347 * \note This function will call the driver for psa_sign_hash
348 * and go through driver dispatch again.
349 *
350 * \param[in] attributes The attributes of the key to use for the
351 * operation.
352 * \param[in] key_buffer The buffer containing the key context.
353 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
354 * \param[in] alg A signature algorithm that is compatible with
355 * the type of the key.
356 * \param[in] input The input message to sign.
357 * \param[in] input_length Size of the \p input buffer in bytes.
358 * \param[out] signature Buffer where the signature is to be written.
359 * \param[in] signature_size Size of the \p signature buffer in bytes.
360 * \param[out] signature_length On success, the number of bytes
361 * that make up the returned signature value.
362 *
363 * \retval #PSA_SUCCESS \emptydescription
364 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
365 * The size of the \p signature buffer is too small. You can
366 * determine a sufficient buffer size by calling
367 * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
368 * where \c key_type and \c key_bits are the type and bit-size
369 * respectively of the key.
370 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
371 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
372 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
373 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
374 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription
375 */
376 psa_status_t psa_sign_message_builtin(
377 const psa_key_attributes_t *attributes,
378 const uint8_t *key_buffer, size_t key_buffer_size,
379 psa_algorithm_t alg, const uint8_t *input, size_t input_length,
380 uint8_t *signature, size_t signature_size, size_t *signature_length);
381
382 /** Verify the signature of a message with a public key, using
383 * a hash-and-sign verification algorithm.
384 *
385 * \note The signature of this function is that of a PSA driver
386 * verify_message entry point. This function behaves as a verify_message
387 * entry point as defined in the PSA driver interface specification for
388 * transparent drivers.
389 *
390 * \note This function will call the driver for psa_verify_hash
391 * and go through driver dispatch again.
392 *
393 * \param[in] attributes The attributes of the key to use for the
394 * operation.
395 * \param[in] key_buffer The buffer containing the key context.
396 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
397 * \param[in] alg A signature algorithm that is compatible with
398 * the type of the key.
399 * \param[in] input The message whose signature is to be verified.
400 * \param[in] input_length Size of the \p input buffer in bytes.
401 * \param[in] signature Buffer containing the signature to verify.
402 * \param[in] signature_length Size of the \p signature buffer in bytes.
403 *
404 * \retval #PSA_SUCCESS
405 * The signature is valid.
406 * \retval #PSA_ERROR_INVALID_SIGNATURE
407 * The calculation was performed successfully, but the passed
408 * signature is not a valid signature.
409 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
410 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
411 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
412 */
413 psa_status_t psa_verify_message_builtin(
414 const psa_key_attributes_t *attributes,
415 const uint8_t *key_buffer, size_t key_buffer_size,
416 psa_algorithm_t alg, const uint8_t *input, size_t input_length,
417 const uint8_t *signature, size_t signature_length);
418
419 /** Sign an already-calculated hash with a private key.
420 *
421 * \note The signature of this function is that of a PSA driver
422 * sign_hash entry point. This function behaves as a sign_hash
423 * entry point as defined in the PSA driver interface specification for
424 * transparent drivers.
425 *
426 * \param[in] attributes The attributes of the key to use for the
427 * operation.
428 * \param[in] key_buffer The buffer containing the key context.
429 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
430 * \param[in] alg A signature algorithm that is compatible with
431 * the type of the key.
432 * \param[in] hash The hash or message to sign.
433 * \param[in] hash_length Size of the \p hash buffer in bytes.
434 * \param[out] signature Buffer where the signature is to be written.
435 * \param[in] signature_size Size of the \p signature buffer in bytes.
436 * \param[out] signature_length On success, the number of bytes
437 * that make up the returned signature value.
438 *
439 * \retval #PSA_SUCCESS \emptydescription
440 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
441 * The size of the \p signature buffer is too small. You can
442 * determine a sufficient buffer size by calling
443 * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
444 * where \c key_type and \c key_bits are the type and bit-size
445 * respectively of the key.
446 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
447 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
448 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
449 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
450 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription
451 */
452 psa_status_t psa_sign_hash_builtin(
453 const psa_key_attributes_t *attributes,
454 const uint8_t *key_buffer, size_t key_buffer_size,
455 psa_algorithm_t alg, const uint8_t *hash, size_t hash_length,
456 uint8_t *signature, size_t signature_size, size_t *signature_length);
457
458 /**
459 * \brief Verify the signature a hash or short message using a public key.
460 *
461 * \note The signature of this function is that of a PSA driver
462 * verify_hash entry point. This function behaves as a verify_hash
463 * entry point as defined in the PSA driver interface specification for
464 * transparent drivers.
465 *
466 * \param[in] attributes The attributes of the key to use for the
467 * operation.
468 * \param[in] key_buffer The buffer containing the key context.
469 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
470 * \param[in] alg A signature algorithm that is compatible with
471 * the type of the key.
472 * \param[in] hash The hash or message whose signature is to be
473 * verified.
474 * \param[in] hash_length Size of the \p hash buffer in bytes.
475 * \param[in] signature Buffer containing the signature to verify.
476 * \param[in] signature_length Size of the \p signature buffer in bytes.
477 *
478 * \retval #PSA_SUCCESS
479 * The signature is valid.
480 * \retval #PSA_ERROR_INVALID_SIGNATURE
481 * The calculation was performed successfully, but the passed
482 * signature is not a valid signature.
483 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
484 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
485 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
486 */
487 psa_status_t psa_verify_hash_builtin(
488 const psa_key_attributes_t *attributes,
489 const uint8_t *key_buffer, size_t key_buffer_size,
490 psa_algorithm_t alg, const uint8_t *hash, size_t hash_length,
491 const uint8_t *signature, size_t signature_length);
492
493 /**
494 * \brief Validate the key bit size for unstructured keys.
495 *
496 * \note Check that the bit size is acceptable for a given key type for
497 * unstructured keys.
498 *
499 * \param[in] type The key type
500 * \param[in] bits The number of bits of the key
501 *
502 * \retval #PSA_SUCCESS
503 * The key type and size are valid.
504 * \retval #PSA_ERROR_INVALID_ARGUMENT
505 * The size in bits of the key is not valid.
506 * \retval #PSA_ERROR_NOT_SUPPORTED
507 * The type and/or the size in bits of the key or the combination of
508 * the two is not supported.
509 */
510 psa_status_t psa_validate_unstructured_key_bit_size(psa_key_type_t type,
511 size_t bits);
512
513 /** Perform a key agreement and return the raw shared secret, using
514 built-in raw key agreement functions.
515 *
516 * \note The signature of this function is that of a PSA driver
517 * key_agreement entry point. This function behaves as a key_agreement
518 * entry point as defined in the PSA driver interface specification for
519 * transparent drivers.
520 *
521 * \param[in] attributes The attributes of the key to use for the
522 * operation.
523 * \param[in] key_buffer The buffer containing the private key
524 * context.
525 * \param[in] key_buffer_size Size of the \p key_buffer buffer in
526 * bytes.
527 * \param[in] alg A key agreement algorithm that is
528 * compatible with the type of the key.
529 * \param[in] peer_key The buffer containing the key context
530 * of the peer's public key.
531 * \param[in] peer_key_length Size of the \p peer_key buffer in
532 * bytes.
533 * \param[out] shared_secret The buffer to which the shared secret
534 * is to be written.
535 * \param[in] shared_secret_size Size of the \p shared_secret buffer in
536 * bytes.
537 * \param[out] shared_secret_length On success, the number of bytes that make
538 * up the returned shared secret.
539 * \retval #PSA_SUCCESS
540 * Success. Shared secret successfully calculated.
541 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription
542 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription
543 * \retval #PSA_ERROR_INVALID_ARGUMENT
544 * \p alg is not a key agreement algorithm, or
545 * \p private_key is not compatible with \p alg,
546 * or \p peer_key is not valid for \p alg or not compatible with
547 * \p private_key.
548 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
549 * \p shared_secret_size is too small
550 * \retval #PSA_ERROR_NOT_SUPPORTED
551 * \p alg is not a supported key agreement algorithm.
552 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
553 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
554 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription
555 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
556 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
557 * \retval #PSA_ERROR_BAD_STATE \emptydescription
558 */
559 psa_status_t psa_key_agreement_raw_builtin(
560 const psa_key_attributes_t *attributes,
561 const uint8_t *key_buffer,
562 size_t key_buffer_size,
563 psa_algorithm_t alg,
564 const uint8_t *peer_key,
565 size_t peer_key_length,
566 uint8_t *shared_secret,
567 size_t shared_secret_size,
568 size_t *shared_secret_length);
569
570 /**
571 * \brief Set the maximum number of ops allowed to be executed by an
572 * interruptible function in a single call.
573 *
574 * \note The signature of this function is that of a PSA driver
575 * interruptible_set_max_ops entry point. This function behaves as an
576 * interruptible_set_max_ops entry point as defined in the PSA driver
577 * interface specification for transparent drivers.
578 *
579 * \param[in] max_ops The maximum number of ops to be executed in a
580 * single call, this can be a number from 0 to
581 * #PSA_INTERRUPTIBLE_MAX_OPS_UNLIMITED, where 0
582 * is obviously the least amount of work done per
583 * call.
584 */
585 void mbedtls_psa_interruptible_set_max_ops(uint32_t max_ops);
586
587 /**
588 * \brief Get the maximum number of ops allowed to be executed by an
589 * interruptible function in a single call.
590 *
591 * \note The signature of this function is that of a PSA driver
592 * interruptible_get_max_ops entry point. This function behaves as an
593 * interruptible_get_max_ops entry point as defined in the PSA driver
594 * interface specification for transparent drivers.
595 *
596 * \return Maximum number of ops allowed to be executed
597 * by an interruptible function in a single call.
598 */
599 uint32_t mbedtls_psa_interruptible_get_max_ops(void);
600
601 /**
602 * \brief Get the number of ops that a hash signing operation has taken for the
603 * previous call. If no call or work has taken place, this will return
604 * zero.
605 *
606 * \note The signature of this function is that of a PSA driver
607 * sign_hash_get_num_ops entry point. This function behaves as an
608 * sign_hash_get_num_ops entry point as defined in the PSA driver
609 * interface specification for transparent drivers.
610 *
611 * \param operation The \c
612 * mbedtls_psa_sign_hash_interruptible_operation_t
613 * to use. This must be initialized first.
614 *
615 * \return Number of ops that were completed
616 * in the last call to \c
617 * mbedtls_psa_sign_hash_complete().
618 */
619 uint32_t mbedtls_psa_sign_hash_get_num_ops(
620 const mbedtls_psa_sign_hash_interruptible_operation_t *operation);
621
622 /**
623 * \brief Get the number of ops that a hash verification operation has taken for
624 * the previous call. If no call or work has taken place, this will
625 * return zero.
626 *
627 * \note The signature of this function is that of a PSA driver
628 * verify_hash_get_num_ops entry point. This function behaves as an
629 * verify_hash_get_num_ops entry point as defined in the PSA driver
630 * interface specification for transparent drivers.
631 *
632 * \param operation The \c
633 * mbedtls_psa_verify_hash_interruptible_operation_t
634 * to use. This must be initialized first.
635 *
636 * \return Number of ops that were completed
637 * in the last call to \c
638 * mbedtls_psa_verify_hash_complete().
639 */
640 uint32_t mbedtls_psa_verify_hash_get_num_ops(
641 const mbedtls_psa_verify_hash_interruptible_operation_t *operation);
642
643 /**
644 * \brief Start signing a hash or short message with a private key, in an
645 * interruptible manner.
646 *
647 * \note The signature of this function is that of a PSA driver
648 * sign_hash_start entry point. This function behaves as a
649 * sign_hash_start entry point as defined in the PSA driver interface
650 * specification for transparent drivers.
651 *
652 * \param[in] operation The \c
653 * mbedtls_psa_sign_hash_interruptible_operation_t
654 * to use. This must be initialized first.
655 * \param[in] attributes The attributes of the key to use for the
656 * operation.
657 * \param[in] key_buffer The buffer containing the key context.
658 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
659 * \param[in] alg A signature algorithm that is compatible with
660 * the type of the key.
661 * \param[in] hash The hash or message to sign.
662 * \param hash_length Size of the \p hash buffer in bytes.
663 *
664 * \retval #PSA_SUCCESS
665 * The operation started successfully - call \c psa_sign_hash_complete()
666 * with the same context to complete the operation
667 * \retval #PSA_ERROR_INVALID_ARGUMENT
668 * An unsupported, incorrectly formatted or incorrect type of key was
669 * used.
670 * \retval #PSA_ERROR_NOT_SUPPORTED Either no internal interruptible operations
671 * are currently supported, or the key type is currently unsupported.
672 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
673 * There was insufficient memory to load the key representation.
674 */
675 psa_status_t mbedtls_psa_sign_hash_start(
676 mbedtls_psa_sign_hash_interruptible_operation_t *operation,
677 const psa_key_attributes_t *attributes, const uint8_t *key_buffer,
678 size_t key_buffer_size, psa_algorithm_t alg,
679 const uint8_t *hash, size_t hash_length);
680
681 /**
682 * \brief Continue and eventually complete the action of signing a hash or
683 * short message with a private key, in an interruptible manner.
684 *
685 * \note The signature of this function is that of a PSA driver
686 * sign_hash_complete entry point. This function behaves as a
687 * sign_hash_complete entry point as defined in the PSA driver interface
688 * specification for transparent drivers.
689 *
690 * \param[in] operation The \c
691 * mbedtls_psa_sign_hash_interruptible_operation_t
692 * to use. This must be initialized first.
693 *
694 * \param[out] signature Buffer where the signature is to be written.
695 * \param signature_size Size of the \p signature buffer in bytes. This
696 * must be appropriate for the selected
697 * algorithm and key.
698 * \param[out] signature_length On success, the number of bytes that make up
699 * the returned signature value.
700 *
701 * \retval #PSA_SUCCESS
702 * Operation completed successfully
703 *
704 * \retval #PSA_OPERATION_INCOMPLETE
705 * Operation was interrupted due to the setting of \c
706 * psa_interruptible_set_max_ops(), there is still work to be done,
707 * please call this function again with the same operation object.
708 *
709 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
710 * The size of the \p signature buffer is too small. You can
711 * determine a sufficient buffer size by calling
712 * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
713 * where \c key_type and \c key_bits are the type and bit-size
714 * respectively of \p key.
715 *
716 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
717 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
718 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
719 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
720 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription
721 */
722 psa_status_t mbedtls_psa_sign_hash_complete(
723 mbedtls_psa_sign_hash_interruptible_operation_t *operation,
724 uint8_t *signature, size_t signature_size,
725 size_t *signature_length);
726
727 /**
728 * \brief Abort a sign hash operation.
729 *
730 * \note The signature of this function is that of a PSA driver sign_hash_abort
731 * entry point. This function behaves as a sign_hash_abort entry point as
732 * defined in the PSA driver interface specification for transparent
733 * drivers.
734 *
735 * \param[in] operation The \c
736 * mbedtls_psa_sign_hash_interruptible_operation_t
737 * to abort.
738 *
739 * \retval #PSA_SUCCESS
740 * The operation was aborted successfully.
741 */
742 psa_status_t mbedtls_psa_sign_hash_abort(
743 mbedtls_psa_sign_hash_interruptible_operation_t *operation);
744
745 /**
746 * \brief Start reading and verifying a hash or short message, in an
747 * interruptible manner.
748 *
749 * \note The signature of this function is that of a PSA driver
750 * verify_hash_start entry point. This function behaves as a
751 * verify_hash_start entry point as defined in the PSA driver interface
752 * specification for transparent drivers.
753 *
754 * \param[in] operation The \c
755 * mbedtls_psa_verify_hash_interruptible_operation_t
756 * to use. This must be initialized first.
757 * \param[in] attributes The attributes of the key to use for the
758 * operation.
759 * \param[in] key_buffer The buffer containing the key context.
760 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
761 * \param[in] alg A signature algorithm that is compatible with
762 * the type of the key.
763 * \param[in] hash The hash whose signature is to be verified.
764 * \param hash_length Size of the \p hash buffer in bytes.
765 * \param[in] signature Buffer containing the signature to verify.
766 * \param signature_length Size of the \p signature buffer in bytes.
767 *
768 * \retval #PSA_SUCCESS
769 * The operation started successfully - call \c psa_sign_hash_complete()
770 * with the same context to complete the operation
771 * \retval #PSA_ERROR_INVALID_ARGUMENT
772 * An unsupported or incorrect type of key was used.
773 * \retval #PSA_ERROR_NOT_SUPPORTED
774 * Either no internal interruptible operations are currently supported,
775 * or the key type is currently unsupported.
776 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
777 * There was insufficient memory either to load the key representation,
778 * or to prepare the operation.
779 */
780 psa_status_t mbedtls_psa_verify_hash_start(
781 mbedtls_psa_verify_hash_interruptible_operation_t *operation,
782 const psa_key_attributes_t *attributes,
783 const uint8_t *key_buffer, size_t key_buffer_size,
784 psa_algorithm_t alg,
785 const uint8_t *hash, size_t hash_length,
786 const uint8_t *signature, size_t signature_length);
787
788 /**
789 * \brief Continue and eventually complete the action of signing a hash or
790 * short message with a private key, in an interruptible manner.
791 *
792 * \note The signature of this function is that of a PSA driver
793 * sign_hash_complete entry point. This function behaves as a
794 * sign_hash_complete entry point as defined in the PSA driver interface
795 * specification for transparent drivers.
796 *
797 * \param[in] operation The \c
798 * mbedtls_psa_sign_hash_interruptible_operation_t
799 * to use. This must be initialized first.
800 *
801 * \retval #PSA_SUCCESS
802 * Operation completed successfully, and the passed signature is valid.
803 *
804 * \retval #PSA_OPERATION_INCOMPLETE
805 * Operation was interrupted due to the setting of \c
806 * psa_interruptible_set_max_ops(), there is still work to be done,
807 * please call this function again with the same operation object.
808 *
809 * \retval #PSA_ERROR_INVALID_SIGNATURE
810 * The calculation was performed successfully, but the passed
811 * signature is not a valid signature.
812 *
813 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
814 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
815 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
816 */
817 psa_status_t mbedtls_psa_verify_hash_complete(
818 mbedtls_psa_verify_hash_interruptible_operation_t *operation);
819
820 /**
821 * \brief Abort a verify signed hash operation.
822 *
823 * \note The signature of this function is that of a PSA driver
824 * verify_hash_abort entry point. This function behaves as a
825 * verify_hash_abort entry point as defined in the PSA driver interface
826 * specification for transparent drivers.
827 *
828 * \param[in] operation The \c
829 * mbedtls_psa_verify_hash_interruptible_operation_t
830 * to abort.
831 *
832 * \retval #PSA_SUCCESS
833 * The operation was aborted successfully.
834 */
835 psa_status_t mbedtls_psa_verify_hash_abort(
836 mbedtls_psa_verify_hash_interruptible_operation_t *operation);
837
838 #endif /* PSA_CRYPTO_CORE_H */
839
