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