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