Mbed OS Reference
Loading...
Searching...
No Matches
crypto_accel_driver.h
Go to the documentation of this file.
1/**
2 * \file psa/crypto_accel_driver.h
3 * \brief PSA cryptography accelerator driver module
4 *
5 * This header declares types and function signatures for cryptography
6 * drivers that access key material directly. This is meant for
7 * on-chip cryptography accelerators.
8 *
9 * This file is part of the PSA Crypto Driver Model, containing functions for
10 * driver developers to implement to enable hardware to be called in a
11 * standardized way by a PSA Cryptographic API implementation. The functions
12 * comprising the driver model, which driver authors implement, are not
13 * intended to be called by application developers.
14 */
15
16/*
17 * Copyright The Mbed TLS Contributors
18 * SPDX-License-Identifier: Apache-2.0
19 *
20 * Licensed under the Apache License, Version 2.0 (the "License"); you may
21 * not use this file except in compliance with the License.
22 * You may obtain a copy of the License at
23 *
24 * http://www.apache.org/licenses/LICENSE-2.0
25 *
26 * Unless required by applicable law or agreed to in writing, software
27 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
28 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
29 * See the License for the specific language governing permissions and
30 * limitations under the License.
31 */
32#ifndef PSA_CRYPTO_ACCEL_DRIVER_H
33#define PSA_CRYPTO_ACCEL_DRIVER_H
34
35#include "crypto_driver_common.h"
36
37#ifdef __cplusplus
38extern "C" {
39#endif
40
41/** \defgroup driver_digest Hardware-Accelerated Message Digests
42 * \ingroup experimental-crypto-psa
43 *
44 * Generation and authentication of Message Digests (aka hashes) must be done
45 * in parts using the following sequence:
46 * - `psa_drv_hash_setup_t`
47 * - `psa_drv_hash_update_t`
48 * - `psa_drv_hash_update_t`
49 * - ...
50 * - `psa_drv_hash_finish_t`
51 *
52 * If a previously started Message Digest operation needs to be terminated
53 * before the `psa_drv_hash_finish_t` operation is complete, it should be aborted
54 * by the `psa_drv_hash_abort_t`. Failure to do so may result in allocated
55 * resources not being freed or in other undefined behavior.
56 */
57/**@{*/
58
59/** \brief The hardware-specific hash context structure
60 *
61 * The contents of this structure are implementation dependent and are
62 * therefore not described here
63 */
64typedef struct psa_drv_hash_context_s psa_drv_hash_context_t;
65
66/** \brief The function prototype for the start operation of a hash (message
67 * digest) operation
68 *
69 * Functions that implement this prototype should be named in the following
70 * convention:
71 * ~~~~~~~~~~~~~{.c}
72 * psa_drv_hash_<ALGO>_setup
73 * ~~~~~~~~~~~~~
74 * Where `ALGO` is the name of the underlying hash function
75 *
76 * \param[in,out] p_context A structure that will contain the
77 * hardware-specific hash context
78 *
79 * \retval #PSA_SUCCESS Success.
80 */
81typedef psa_status_t (*psa_drv_hash_setup_t)(psa_drv_hash_context_t *p_context);
82
83/** \brief The function prototype for the update operation of a hash (message
84 * digest) operation
85 *
86 * Functions that implement this prototype should be named in the following
87 * convention:
88 * ~~~~~~~~~~~~~{.c}
89 * psa_drv_hash_<ALGO>_update
90 * ~~~~~~~~~~~~~
91 * Where `ALGO` is the name of the underlying algorithm
92 *
93 * \param[in,out] p_context A hardware-specific structure for the
94 * previously-established hash operation to be
95 * continued
96 * \param[in] p_input A buffer containing the message to be appended
97 * to the hash operation
98 * \param[in] input_length The size in bytes of the input message buffer
99 */
100typedef psa_status_t (*psa_drv_hash_update_t)(psa_drv_hash_context_t *p_context,
101 const uint8_t *p_input,
102 size_t input_length);
103
104/** \brief The function prototype for the finish operation of a hash (message
105 * digest) operation
106 *
107 * Functions that implement this prototype should be named in the following
108 * convention:
109 * ~~~~~~~~~~~~~{.c}
110 * psa_drv_hash_<ALGO>_finish
111 * ~~~~~~~~~~~~~
112 * Where `ALGO` is the name of the underlying algorithm
113 *
114 * \param[in,out] p_context A hardware-specific structure for the
115 * previously started hash operation to be
116 * fiinished
117 * \param[out] p_output A buffer where the generated digest will be
118 * placed
119 * \param[in] output_size The size in bytes of the buffer that has been
120 * allocated for the `p_output` buffer
121 * \param[out] p_output_length The number of bytes placed in `p_output` after
122 * success
123 *
124 * \retval #PSA_SUCCESS
125 * Success.
126 */
127typedef psa_status_t (*psa_drv_hash_finish_t)(psa_drv_hash_context_t *p_context,
128 uint8_t *p_output,
129 size_t output_size,
130 size_t *p_output_length);
131
132/** \brief The function prototype for the abort operation of a hash (message
133 * digest) operation
134 *
135 * Functions that implement this prototype should be named in the following
136 * convention:
137 * ~~~~~~~~~~~~~{.c}
138 * psa_drv_hash_<ALGO>_abort
139 * ~~~~~~~~~~~~~
140 * Where `ALGO` is the name of the underlying algorithm
141 *
142 * \param[in,out] p_context A hardware-specific structure for the previously
143 * started hash operation to be aborted
144 */
145typedef void (*psa_drv_hash_abort_t)(psa_drv_hash_context_t *p_context);
146
147/**@}*/
148
149/** \defgroup accel_mac Hardware-Accelerated Message Authentication Code
150 * \ingroup experimental-crypto-psa
151 * Generation and authentication of Message Authentication Codes (MACs) using
152 * cryptographic accelerators can be done either as a single function call (via the
153 * `psa_drv_accel_mac_generate_t` or `psa_drv_accel_mac_verify_t`
154 * functions), or in parts using the following sequence:
155 * - `psa_drv_accel_mac_setup_t`
156 * - `psa_drv_accel_mac_update_t`
157 * - `psa_drv_accel_mac_update_t`
158 * - ...
159 * - `psa_drv_accel_mac_finish_t` or `psa_drv_accel_mac_finish_verify_t`
160 *
161 * If a previously started MAC operation needs to be terminated, it
162 * should be done so by the `psa_drv_accel_mac_abort_t`. Failure to do so may
163 * result in allocated resources not being freed or in other undefined
164 * behavior.
165 *
166 */
167/**@{*/
168
169/** \brief The hardware-accelerator-specific MAC context structure
170 *
171 * The contents of this structure are implementation dependent and are
172 * therefore not described here.
173 */
174typedef struct psa_drv_accel_mac_context_s psa_drv_accel_mac_context_t;
175
176/** \brief The function prototype for the setup operation of a
177 * hardware-accelerated MAC operation
178 *
179 * Functions that implement this prototype should be named in the following
180 * convention:
181 * ~~~~~~~~~~~~~{.c}
182 * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_setup
183 * ~~~~~~~~~~~~~
184 * Where `ALGO` is the name of the underlying primitive, and `MAC_VARIANT`
185 * is the specific variant of a MAC operation (such as HMAC or CMAC)
186 *
187 * \param[in,out] p_context A structure that will contain the
188 * hardware-specific MAC context
189 * \param[in] p_key A buffer containing the cleartext key material
190 * to be used in the operation
191 * \param[in] key_length The size in bytes of the key material
192 *
193 * \retval #PSA_SUCCESS
194 * Success.
195 */
196typedef psa_status_t (*psa_drv_accel_mac_setup_t)(psa_drv_accel_mac_context_t *p_context,
197 const uint8_t *p_key,
198 size_t key_length);
199
200/** \brief The function prototype for the update operation of a
201 * hardware-accelerated MAC operation
202 *
203 * Functions that implement this prototype should be named in the following
204 * convention:
205 * ~~~~~~~~~~~~~{.c}
206 * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_update
207 * ~~~~~~~~~~~~~
208 * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT`
209 * is the specific variant of a MAC operation (such as HMAC or CMAC)
210 *
211 * \param[in,out] p_context A hardware-specific structure for the
212 * previously-established MAC operation to be
213 * continued
214 * \param[in] p_input A buffer containing the message to be appended
215 * to the MAC operation
216 * \param[in] input_length The size in bytes of the input message buffer
217 */
218typedef psa_status_t (*psa_drv_accel_mac_update_t)(psa_drv_accel_mac_context_t *p_context,
219 const uint8_t *p_input,
220 size_t input_length);
221
222/** \brief The function prototype for the finish operation of a
223 * hardware-accelerated MAC operation
224 *
225 * Functions that implement this prototype should be named in the following
226 * convention:
227 * ~~~~~~~~~~~~~{.c}
228 * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_finish
229 * ~~~~~~~~~~~~~
230 * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
231 * the specific variant of a MAC operation (such as HMAC or CMAC)
232 *
233 * \param[in,out] p_context A hardware-specific structure for the
234 * previously started MAC operation to be
235 * finished
236 * \param[out] p_mac A buffer where the generated MAC will be placed
237 * \param[in] mac_length The size in bytes of the buffer that has been
238 * allocated for the `p_mac` buffer
239 *
240 * \retval #PSA_SUCCESS
241 * Success.
242 */
243typedef psa_status_t (*psa_drv_accel_mac_finish_t)(psa_drv_accel_mac_context_t *p_context,
244 uint8_t *p_mac,
245 size_t mac_length);
246
247/** \brief The function prototype for the finish and verify operation of a
248 * hardware-accelerated MAC operation
249 *
250 * Functions that implement this prototype should be named in the following
251 * convention:
252 * ~~~~~~~~~~~~~{.c}
253 * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_finish_verify
254 * ~~~~~~~~~~~~~
255 * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
256 * the specific variant of a MAC operation (such as HMAC or CMAC)
257 *
258 * \param[in,out] p_context A hardware-specific structure for the
259 * previously started MAC operation to be
260 * verified and finished
261 * \param[in] p_mac A buffer containing the MAC that will be used
262 * for verification
263 * \param[in] mac_length The size in bytes of the data in the `p_mac`
264 * buffer
265 *
266 * \retval #PSA_SUCCESS
267 * The operation completed successfully and the comparison matched
268 */
269typedef psa_status_t (*psa_drv_accel_mac_finish_verify_t)(psa_drv_accel_mac_context_t *p_context,
270 const uint8_t *p_mac,
271 size_t mac_length);
272
273/** \brief The function prototype for the abort operation for a previously
274 * started hardware-accelerated MAC operation
275 *
276 * Functions that implement this prototype should be named in the following
277 * convention:
278 * ~~~~~~~~~~~~~{.c}
279 * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_abort
280 * ~~~~~~~~~~~~~
281 * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
282 * the specific variant of a MAC operation (such as HMAC or CMAC)
283 *
284 * \param[in,out] p_context A hardware-specific structure for the
285 * previously started MAC operation to be
286 * aborted
287 *
288 */
289typedef psa_status_t (*psa_drv_accel_mac_abort_t)(psa_drv_accel_mac_context_t *p_context);
290
291/** \brief The function prototype for the one-shot operation of a
292 * hardware-accelerated MAC operation
293 *
294 * Functions that implement this prototype should be named in the following
295 * convention:
296 * ~~~~~~~~~~~~~{.c}
297 * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>
298 * ~~~~~~~~~~~~~
299 * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
300 * the specific variant of a MAC operation (such as HMAC or CMAC)
301 *
302 * \param[in] p_input A buffer containing the data to be MACed
303 * \param[in] input_length The length in bytes of the `p_input` data
304 * \param[in] p_key A buffer containing the key material to be used
305 * for the MAC operation
306 * \param[in] key_length The length in bytes of the `p_key` data
307 * \param[in] alg The algorithm to be performed
308 * \param[out] p_mac The buffer where the resulting MAC will be placed
309 * upon success
310 * \param[in] mac_length The length in bytes of the `p_mac` buffer
311 */
312typedef psa_status_t (*psa_drv_accel_mac_t)(const uint8_t *p_input,
313 size_t input_length,
314 const uint8_t *p_key,
315 size_t key_length,
316 psa_algorithm_t alg,
317 uint8_t *p_mac,
318 size_t mac_length);
319
320/** \brief The function prototype for the one-shot hardware-accelerated MAC
321 * Verify operation
322 *
323 * Functions that implement this prototype should be named in the following
324 * convention:
325 * ~~~~~~~~~~~~~{.c}
326 * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_verify
327 * ~~~~~~~~~~~~~
328 * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
329 * the specific variant of a MAC operation (such as HMAC or CMAC)
330 *
331 * \param[in] p_input A buffer containing the data to be MACed
332 * \param[in] input_length The length in bytes of the `p_input` data
333 * \param[in] p_key A buffer containing the key material to be used
334 * for the MAC operation
335 * \param[in] key_length The length in bytes of the `p_key` data
336 * \param[in] alg The algorithm to be performed
337 * \param[in] p_mac The MAC data to be compared
338 * \param[in] mac_length The length in bytes of the `p_mac` buffer
339 *
340 * \retval #PSA_SUCCESS
341 * The operation completed successfully and the comparison matched
342 */
343typedef psa_status_t (*psa_drv_accel_mac_verify_t)(const uint8_t *p_input,
344 size_t input_length,
345 const uint8_t *p_key,
346 size_t key_length,
347 psa_algorithm_t alg,
348 const uint8_t *p_mac,
349 size_t mac_length);
350/**@}*/
351
352/** \defgroup accel_cipher Hardware-Accelerated Block Ciphers
353 * \ingroup experimental-crypto-psa
354 * Encryption and Decryption using hardware-acceleration in block modes other
355 * than ECB must be done in multiple parts, using the following flow:
356 * - `psa_drv_accel_ciphersetup_t`
357 * - `psa_drv_accel_cipher_set_iv_t` (optional depending upon block mode)
358 * - `psa_drv_accel_cipher_update_t`
359 * - `psa_drv_accel_cipher_update_t`
360 * - ...
361 * - `psa_drv_accel_cipher_finish_t`
362 *
363 * If a previously started hardware-accelerated Cipher operation needs to be
364 * terminated, it should be done so by the `psa_drv_accel_cipher_abort_t`.
365 * Failure to do so may result in allocated resources not being freed or in
366 * other undefined behavior.
367 */
368/**@{*/
369
370/** \brief The hardware-accelerator-specific cipher context structure
371 *
372 * The contents of this structure are implementation dependent and are
373 * therefore not described here.
374 */
375typedef struct psa_drv_accel_cipher_context_s psa_drv_accel_cipher_context_t;
376
377/** \brief The function prototype for the setup operation of
378 * hardware-accelerated block cipher operations.
379 * Functions that implement this prototype should be named in the following
380 * conventions:
381 * ~~~~~~~~~~~~~{.c}
382 * psa_drv_accel_cipher_setup_<CIPHER_NAME>_<MODE>
383 * ~~~~~~~~~~~~~
384 * Where
385 * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
386 * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)
387 *
388 * For stream ciphers:
389 * ~~~~~~~~~~~~~{.c}
390 * psa_drv_accel_cipher_setup_<CIPHER_NAME>
391 * ~~~~~~~~~~~~~
392 * Where `CIPHER_NAME` is the name of a stream cipher (i.e. RC4)
393 *
394 * \param[in,out] p_context A structure that will contain the
395 * hardware-specific cipher context
396 * \param[in] direction Indicates if the operation is an encrypt or a
397 * decrypt
398 * \param[in] p_key_data A buffer containing the cleartext key material
399 * to be used in the operation
400 * \param[in] key_data_size The size in bytes of the key material
401 *
402 * \retval #PSA_SUCCESS
403 */
404typedef psa_status_t (*psa_drv_accel_cipher_setup_t)(psa_drv_accel_cipher_context_t *p_context,
405 psa_encrypt_or_decrypt_t direction,
406 const uint8_t *p_key_data,
407 size_t key_data_size);
408
409/** \brief The function prototype for the set initialization vector operation
410 * of hardware-accelerated block cipher operations
411 * Functions that implement this prototype should be named in the following
412 * convention:
413 * ~~~~~~~~~~~~~{.c}
414 * psa_drv_accel_cipher_set_iv_<CIPHER_NAME>_<MODE>
415 * ~~~~~~~~~~~~~
416 * Where
417 * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
418 * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)
419 *
420 * \param[in,out] p_context A structure that contains the previously setup
421 * hardware-specific cipher context
422 * \param[in] p_iv A buffer containing the initialization vecotr
423 * \param[in] iv_length The size in bytes of the contents of `p_iv`
424 *
425 * \retval #PSA_SUCCESS
426 */
427typedef psa_status_t (*psa_drv_accel_cipher_set_iv_t)(psa_drv_accel_cipher_context_t *p_context,
428 const uint8_t *p_iv,
429 size_t iv_length);
430
431/** \brief The function prototype for the update operation of
432 * hardware-accelerated block cipher operations.
433 *
434 * Functions that implement this prototype should be named in the following
435 * convention:
436 * ~~~~~~~~~~~~~{.c}
437 * psa_drv_accel_cipher_update_<CIPHER_NAME>_<MODE>
438 * ~~~~~~~~~~~~~
439 * Where
440 * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
441 * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)
442 *
443 * \param[in,out] p_context A hardware-specific structure for the
444 * previously started cipher operation
445 * \param[in] p_input A buffer containing the data to be
446 * encrypted or decrypted
447 * \param[in] input_size The size in bytes of the `p_input` buffer
448 * \param[out] p_output A caller-allocated buffer where the
449 * generated output will be placed
450 * \param[in] output_size The size in bytes of the `p_output` buffer
451 * \param[out] p_output_length After completion, will contain the number
452 * of bytes placed in the `p_output` buffer
453 *
454 * \retval #PSA_SUCCESS
455 */
456typedef psa_status_t (*psa_drv_accel_cipher_update_t)(psa_drv_accel_cipher_context_t *p_context,
457 const uint8_t *p_input,
458 size_t input_size,
459 uint8_t *p_output,
460 size_t output_size,
461 size_t *p_output_length);
462
463/** \brief The function prototype for the finish operation of
464 * hardware-accelerated block cipher operations.
465 *
466 * Functions that implement this prototype should be named in the following
467 * convention:
468 * ~~~~~~~~~~~~~{.c}
469 * psa_drv_accel_cipher_finish_<CIPHER_NAME>_<MODE>
470 * ~~~~~~~~~~~~~
471 * Where
472 * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
473 * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)
474 *
475 * \param[in,out] p_context A hardware-specific structure for the
476 * previously started cipher operation
477 * \param[out] p_output A caller-allocated buffer where the generated
478 * output will be placed
479 * \param[in] output_size The size in bytes of the `p_output` buffer
480 * \param[out] p_output_length After completion, will contain the number of
481 * bytes placed in the `p_output` buffer
482 *
483 * \retval #PSA_SUCCESS
484 */
485typedef psa_status_t (*psa_drv_accel_cipher_finish_t)(psa_drv_accel_cipher_context_t *p_context,
486 uint8_t *p_output,
487 size_t output_size,
488 size_t *p_output_length);
489
490/** \brief The function prototype for the abort operation of
491 * hardware-accelerated block cipher operations.
492 *
493 * Functions that implement the following prototype should be named in the
494 * following convention:
495 * ~~~~~~~~~~~~~{.c}
496 * psa_drv_accel_cipher_abort_<CIPHER_NAME>_<MODE>
497 * ~~~~~~~~~~~~~
498 * Where
499 * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
500 * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)
501 *
502 * \param[in,out] p_context A hardware-specific structure for the
503 * previously started cipher operation
504 *
505 * \retval #PSA_SUCCESS
506 */
507typedef psa_status_t (*psa_drv_accel_cipher_abort_t)(psa_drv_accel_cipher_context_t *p_context);
508
509/**@}*/
510
511/** \defgroup accel_aead Hardware-Accelerated Authenticated Encryption with Additional Data
512 * \ingroup experimental-crypto-psa
513 *
514 * Hardware-accelerated Authenticated Encryption with Additional Data (AEAD)
515 * operations must be done in one function call. While this creates a burden
516 * for implementers as there must be sufficient space in memory for the entire
517 * message, it prevents decrypted data from being made available before the
518 * authentication operation is complete and the data is known to be authentic.
519 */
520/**@{*/
521
522/** \brief The function prototype for the hardware-accelerated authenticated
523 * encryption operation.
524 *
525 * Functions that implement this prototype should be named in the following
526 * convention:
527 * ~~~~~~~~~~~~~{.c}
528 * psa_drv_accel_aead_<ALGO>_encrypt
529 * ~~~~~~~~~~~~~
530 * Where `ALGO` is the name of the AEAD algorithm
531 *
532 * \param[in] p_key A pointer to the key material
533 * \param[in] key_length The size in bytes of the key material
534 * \param[in] alg The AEAD algorithm to compute
535 * (\c PSA_ALG_XXX value such that
536 * #PSA_ALG_IS_AEAD(`alg`) is true)
537 * \param[in] nonce Nonce or IV to use
538 * \param[in] nonce_length Size of the `nonce` buffer in bytes
539 * \param[in] additional_data Additional data that will be MACed
540 * but not encrypted.
541 * \param[in] additional_data_length Size of `additional_data` in bytes
542 * \param[in] plaintext Data that will be MACed and
543 * encrypted.
544 * \param[in] plaintext_length Size of `plaintext` in bytes
545 * \param[out] ciphertext Output buffer for the authenticated and
546 * encrypted data. The additional data is
547 * not part of this output. For algorithms
548 * where the encrypted data and the
549 * authentication tag are defined as
550 * separate outputs, the authentication
551 * tag is appended to the encrypted data.
552 * \param[in] ciphertext_size Size of the `ciphertext` buffer in
553 * bytes
554 * This must be at least
555 * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(`alg`,
556 * `plaintext_length`).
557 * \param[out] ciphertext_length On success, the size of the output in
558 * the `ciphertext` buffer
559 *
560 * \retval #PSA_SUCCESS
561 *
562 */
563typedef psa_status_t (*psa_drv_accel_aead_encrypt_t)(const uint8_t *p_key,
564 size_t key_length,
565 psa_algorithm_t alg,
566 const uint8_t *nonce,
567 size_t nonce_length,
568 const uint8_t *additional_data,
569 size_t additional_data_length,
570 const uint8_t *plaintext,
571 size_t plaintext_length,
572 uint8_t *ciphertext,
573 size_t ciphertext_size,
574 size_t *ciphertext_length);
575
576/** \brief The function prototype for the hardware-accelerated authenticated
577 * decryption operation.
578 *
579 * Functions that implement this prototype should be named in the following
580 * convention:
581 * ~~~~~~~~~~~~~{.c}
582 * psa_drv_accel_aead_<ALGO>_decrypt
583 * ~~~~~~~~~~~~~
584 * Where `ALGO` is the name of the AEAD algorithm
585 * \param[in] p_key A pointer to the key material
586 * \param[in] key_length The size in bytes of the key material
587 * \param[in] alg The AEAD algorithm to compute
588 * (\c PSA_ALG_XXX value such that
589 * #PSA_ALG_IS_AEAD(`alg`) is true)
590 * \param[in] nonce Nonce or IV to use
591 * \param[in] nonce_length Size of the `nonce` buffer in bytes
592 * \param[in] additional_data Additional data that has been MACed
593 * but not encrypted
594 * \param[in] additional_data_length Size of `additional_data` in bytes
595 * \param[in] ciphertext Data that has been MACed and
596 * encrypted
597 * For algorithms where the encrypted data
598 * and the authentication tag are defined
599 * as separate inputs, the buffer must
600 * contain the encrypted data followed by
601 * the authentication tag.
602 * \param[in] ciphertext_length Size of `ciphertext` in bytes
603 * \param[out] plaintext Output buffer for the decrypted data
604 * \param[in] plaintext_size Size of the `plaintext` buffer in
605 * bytes
606 * This must be at least
607 * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(`alg`,
608 * `ciphertext_length`).
609 * \param[out] plaintext_length On success, the size of the output
610 * in the \b plaintext buffer
611 *
612 * \retval #PSA_SUCCESS
613 * Success.
614 */
615typedef psa_status_t (*psa_drv_accel_aead_decrypt_t)(const uint8_t *p_key,
616 size_t key_length,
617 psa_algorithm_t alg,
618 const uint8_t *nonce,
619 size_t nonce_length,
620 const uint8_t *additional_data,
621 size_t additional_data_length,
622 const uint8_t *ciphertext,
623 size_t ciphertext_length,
624 uint8_t *plaintext,
625 size_t plaintext_size,
626 size_t *plaintext_length);
627
628/**@}*/
629
630/** \defgroup accel_asymmetric Hardware-Accelerated Asymmetric Cryptography
631 * \ingroup experimental-crypto-psa
632 *
633 * Since the amount of data that can (or should) be encrypted or signed using
634 * asymmetric keys is limited by the key size, hardware-accelerated asymmetric
635 * key operations must be done in single function calls.
636 */
637/**@{*/
638
639
640/**
641 * \brief The function prototype for the hardware-accelerated asymmetric sign
642 * operation.
643 *
644 * Functions that implement this prototype should be named in the following
645 * convention:
646 * ~~~~~~~~~~~~~{.c}
647 * psa_drv_accel_asymmetric_<ALGO>_sign
648 * ~~~~~~~~~~~~~
649 * Where `ALGO` is the name of the signing algorithm
650 *
651 * This function supports any asymmetric-key output from psa_export_key() as
652 * the buffer in \p p_key. Refer to the documentation of \ref
653 * psa_export_key() for the formats.
654 *
655 * \param[in] p_key A buffer containing the private key
656 * material
657 * \param[in] key_size The size in bytes of the `p_key` data
658 * \param[in] alg A signature algorithm that is compatible
659 * with the type of `p_key`
660 * \param[in] key_type Key type (one of the PSA_KEY_TYPE_xxx constants)
661 * \param[in] p_hash The hash or message to sign
662 * \param[in] hash_length Size of the `p_hash` buffer in bytes
663 * \param[out] p_signature Buffer where the signature is to be written
664 * \param[in] signature_size Size of the `p_signature` buffer in bytes
665 * \param[out] p_signature_length On success, the number of bytes
666 * that make up the returned signature value
667 *
668 * \retval #PSA_SUCCESS
669 */
670typedef psa_status_t (*psa_drv_accel_asymmetric_sign_t)(const uint8_t *p_key,
671 size_t key_size,
672 psa_algorithm_t alg,
673 psa_key_type_t key_type,
674 const uint8_t *p_hash,
675 size_t hash_length,
676 uint8_t *p_signature,
677 size_t signature_size,
678 size_t *p_signature_length);
679
680/**
681 * \brief The function prototype for the hardware-accelerated signature verify
682 * operation
683 *
684 * Functions that implement this prototype should be named in the following
685 * convention:
686 * ~~~~~~~~~~~~~{.c}
687 * psa_drv_accel_asymmetric_<ALGO>_verify
688 * ~~~~~~~~~~~~~
689 * Where `ALGO` is the name of the signing algorithm
690 *
691 * This function supports any output from \ref psa_export_public_key() as the
692 * buffer in \p p_key. Refer to the documentation of \ref
693 * psa_export_public_key() for the format of public keys and to the
694 * documentation of \ref psa_export_key() for the format for other key types.
695 *
696 * \param[in] p_key A buffer containing the public key material
697 * \param[in] key_size The size in bytes of the `p_key` data
698 * \param[in] alg A signature algorithm that is compatible with
699 * the type of `key`
700 * \param[in] key_type Key type (one of the PSA_KEY_TYPE_xxx constants)
701 * \param[in] p_hash The hash or message whose signature is to be
702 * verified
703 * \param[in] hash_length Size of the `p_hash` buffer in bytes
704 * \param[in] p_signature Buffer containing the signature to verify
705 * \param[in] signature_length Size of the `p_signature` buffer in bytes
706 *
707 * \retval #PSA_SUCCESS
708 * The signature is valid.
709 */
710typedef psa_status_t (*psa_drv_accel_asymmetric_verify_t)(const uint8_t *p_key,
711 size_t key_size,
712 psa_algorithm_t alg,
713 psa_key_type_t key_type,
714 const uint8_t *p_hash,
715 size_t hash_length,
716 const uint8_t *p_signature,
717 size_t signature_length);
718
719/**
720 * \brief The function prototype for the hardware-accelerated asymmetric
721 * encrypt operation
722 *
723 * Functions that implement this prototype should be named in the following
724 * convention:
725 * ~~~~~~~~~~~~~{.c}
726 * psa_drv_accel_asymmetric_<ALGO>_encrypt
727 * ~~~~~~~~~~~~~
728 * Where `ALGO` is the name of the encryption algorithm
729 *
730 * This function supports any output from \ref psa_export_public_key() as the
731 * buffer in \p p_key. Refer to the documentation of \ref
732 * psa_export_public_key() for the format of public keys and to the
733 * documentation of \ref psa_export_key() for the format for other key types.
734 *
735 * \param[in] p_key A buffer containing the public key material
736 * \param[in] key_size The size in bytes of the `p_key` data
737 * \param[in] alg An asymmetric encryption algorithm that is
738 * compatible with the type of `key`
739 * \param[in] key_type Key type (one of the PSA_KEY_TYPE_xxx constants)
740 * \param[in] p_input The message to encrypt
741 * \param[in] input_length Size of the `p_input` buffer in bytes
742 * \param[in] p_salt A salt or label, if supported by the
743 * encryption algorithm
744 * If the algorithm does not support a
745 * salt, pass `NULL`
746 * If the algorithm supports an optional
747 * salt and you do not want to pass a salt,
748 * pass `NULL`.
749 * For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
750 * supported.
751 * \param[in] salt_length Size of the `p_salt` buffer in bytes
752 * If `p_salt` is `NULL`, pass 0.
753 * \param[out] p_output Buffer where the encrypted message is to
754 * be written
755 * \param[in] output_size Size of the `p_output` buffer in bytes
756 * \param[out] p_output_length On success, the number of bytes
757 * that make up the returned output
758 *
759 * \retval #PSA_SUCCESS
760 */
761typedef psa_status_t (*psa_drv_accel_asymmetric_encrypt_t)(const uint8_t *p_key,
762 size_t key_size,
763 psa_algorithm_t alg,
764 psa_key_type_t key_type,
765 const uint8_t *p_input,
766 size_t input_length,
767 const uint8_t *p_salt,
768 size_t salt_length,
769 uint8_t *p_output,
770 size_t output_size,
771 size_t *p_output_length);
772
773/**
774 * \brief The function prototype for the hardware=acce;erated asymmetric
775 * decrypt operation
776 *
777 * Functions that implement this prototype should be named in the following
778 * convention:
779 * ~~~~~~~~~~~~~{.c}
780 * psa_drv_accel_asymmetric_<ALGO>_decrypt
781 * ~~~~~~~~~~~~~
782 * Where `ALGO` is the name of the encryption algorithm
783 *
784 * This function supports any asymmetric-key output from psa_export_key() as
785 * the buffer in \p p_key. Refer to the documentation of \ref
786 * psa_export_key() for the formats.
787 *
788 * \param[in] p_key A buffer containing the private key material
789 * \param[in] key_size The size in bytes of the `p_key` data
790 * \param[in] alg An asymmetric encryption algorithm that is
791 * compatible with the type of `key`
792 * \param[in] key_type Key type (one of the PSA_KEY_TYPE_xxx constants)
793 * \param[in] p_input The message to decrypt
794 * \param[in] input_length Size of the `p_input` buffer in bytes
795 * \param[in] p_salt A salt or label, if supported by the
796 * encryption algorithm
797 * If the algorithm does not support a
798 * salt, pass `NULL`.
799 * If the algorithm supports an optional
800 * salt and you do not want to pass a salt,
801 * pass `NULL`.
802 * For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
803 * supported
804 * \param[in] salt_length Size of the `p_salt` buffer in bytes
805 * If `p_salt` is `NULL`, pass 0
806 * \param[out] p_output Buffer where the decrypted message is to
807 * be written
808 * \param[in] output_size Size of the `p_output` buffer in bytes
809 * \param[out] p_output_length On success, the number of bytes
810 * that make up the returned output
811 *
812 * \retval #PSA_SUCCESS
813 */
814typedef psa_status_t (*psa_drv_accel_asymmetric_decrypt_t)(const uint8_t *p_key,
815 size_t key_size,
816 psa_algorithm_t alg,
817 psa_key_type_t key_type,
818 const uint8_t *p_input,
819 size_t input_length,
820 const uint8_t *p_salt,
821 size_t salt_length,
822 uint8_t *p_output,
823 size_t output_size,
824 size_t *p_output_length);
825
826/**@}*/
827
828#ifdef __cplusplus
829}
830#endif
831
832#endif /* PSA_CRYPTO_ACCEL_DRIVER_H */
crypto_driver_common.h
Definitions for all PSA crypto drivers.
psa_encrypt_or_decrypt_t
psa_encrypt_or_decrypt_t
For encrypt-decrypt functions, whether the operation is an encryption or a decryption.
Definition: crypto_driver_common.h:49
psa_drv_accel_aead_encrypt_t
psa_status_t(* psa_drv_accel_aead_encrypt_t)(const uint8_t *p_key, size_t key_length, psa_algorithm_t alg, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *plaintext, size_t plaintext_length, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length)
The function prototype for the hardware-accelerated authenticated encryption operation.
Definition: crypto_accel_driver.h:563
psa_drv_accel_aead_decrypt_t
psa_status_t(* psa_drv_accel_aead_decrypt_t)(const uint8_t *p_key, size_t key_length, psa_algorithm_t alg, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *ciphertext, size_t ciphertext_length, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length)
The function prototype for the hardware-accelerated authenticated decryption operation.
Definition: crypto_accel_driver.h:615
psa_drv_accel_asymmetric_encrypt_t
psa_status_t(* psa_drv_accel_asymmetric_encrypt_t)(const uint8_t *p_key, size_t key_size, psa_algorithm_t alg, psa_key_type_t key_type, const uint8_t *p_input, size_t input_length, const uint8_t *p_salt, size_t salt_length, uint8_t *p_output, size_t output_size, size_t *p_output_length)
The function prototype for the hardware-accelerated asymmetric encrypt operation.
Definition: crypto_accel_driver.h:761
psa_drv_accel_asymmetric_decrypt_t
psa_status_t(* psa_drv_accel_asymmetric_decrypt_t)(const uint8_t *p_key, size_t key_size, psa_algorithm_t alg, psa_key_type_t key_type, const uint8_t *p_input, size_t input_length, const uint8_t *p_salt, size_t salt_length, uint8_t *p_output, size_t output_size, size_t *p_output_length)
The function prototype for the hardware=acce;erated asymmetric decrypt operation.
Definition: crypto_accel_driver.h:814
psa_drv_accel_asymmetric_sign_t
psa_status_t(* psa_drv_accel_asymmetric_sign_t)(const uint8_t *p_key, size_t key_size, psa_algorithm_t alg, psa_key_type_t key_type, const uint8_t *p_hash, size_t hash_length, uint8_t *p_signature, size_t signature_size, size_t *p_signature_length)
The function prototype for the hardware-accelerated asymmetric sign operation.
Definition: crypto_accel_driver.h:670
psa_drv_accel_asymmetric_verify_t
psa_status_t(* psa_drv_accel_asymmetric_verify_t)(const uint8_t *p_key, size_t key_size, psa_algorithm_t alg, psa_key_type_t key_type, const uint8_t *p_hash, size_t hash_length, const uint8_t *p_signature, size_t signature_length)
The function prototype for the hardware-accelerated signature verify operation.
Definition: crypto_accel_driver.h:710
psa_drv_accel_cipher_setup_t
psa_status_t(* psa_drv_accel_cipher_setup_t)(psa_drv_accel_cipher_context_t *p_context, psa_encrypt_or_decrypt_t direction, const uint8_t *p_key_data, size_t key_data_size)
The function prototype for the setup operation of hardware-accelerated block cipher operations.
Definition: crypto_accel_driver.h:404
psa_drv_accel_cipher_set_iv_t
psa_status_t(* psa_drv_accel_cipher_set_iv_t)(psa_drv_accel_cipher_context_t *p_context, const uint8_t *p_iv, size_t iv_length)
The function prototype for the set initialization vector operation of hardware-accelerated block ciph...
Definition: crypto_accel_driver.h:427
psa_drv_accel_cipher_update_t
psa_status_t(* psa_drv_accel_cipher_update_t)(psa_drv_accel_cipher_context_t *p_context, const uint8_t *p_input, size_t input_size, uint8_t *p_output, size_t output_size, size_t *p_output_length)
The function prototype for the update operation of hardware-accelerated block cipher operations.
Definition: crypto_accel_driver.h:456
psa_drv_accel_cipher_finish_t
psa_status_t(* psa_drv_accel_cipher_finish_t)(psa_drv_accel_cipher_context_t *p_context, uint8_t *p_output, size_t output_size, size_t *p_output_length)
The function prototype for the finish operation of hardware-accelerated block cipher operations.
Definition: crypto_accel_driver.h:485
psa_drv_accel_cipher_context_t
struct psa_drv_accel_cipher_context_s psa_drv_accel_cipher_context_t
The hardware-accelerator-specific cipher context structure.
Definition: crypto_accel_driver.h:375
psa_drv_accel_cipher_abort_t
psa_status_t(* psa_drv_accel_cipher_abort_t)(psa_drv_accel_cipher_context_t *p_context)
The function prototype for the abort operation of hardware-accelerated block cipher operations.
Definition: crypto_accel_driver.h:507
psa_drv_accel_mac_update_t
psa_status_t(* psa_drv_accel_mac_update_t)(psa_drv_accel_mac_context_t *p_context, const uint8_t *p_input, size_t input_length)
The function prototype for the update operation of a hardware-accelerated MAC operation.
Definition: crypto_accel_driver.h:218
psa_drv_accel_mac_finish_t
psa_status_t(* psa_drv_accel_mac_finish_t)(psa_drv_accel_mac_context_t *p_context, uint8_t *p_mac, size_t mac_length)
The function prototype for the finish operation of a hardware-accelerated MAC operation.
Definition: crypto_accel_driver.h:243
psa_drv_accel_mac_abort_t
psa_status_t(* psa_drv_accel_mac_abort_t)(psa_drv_accel_mac_context_t *p_context)
The function prototype for the abort operation for a previously started hardware-accelerated MAC oper...
Definition: crypto_accel_driver.h:289
psa_drv_accel_mac_t
psa_status_t(* psa_drv_accel_mac_t)(const uint8_t *p_input, size_t input_length, const uint8_t *p_key, size_t key_length, psa_algorithm_t alg, uint8_t *p_mac, size_t mac_length)
The function prototype for the one-shot operation of a hardware-accelerated MAC operation.
Definition: crypto_accel_driver.h:312
psa_drv_accel_mac_context_t
struct psa_drv_accel_mac_context_s psa_drv_accel_mac_context_t
The hardware-accelerator-specific MAC context structure.
Definition: crypto_accel_driver.h:174
psa_drv_accel_mac_setup_t
psa_status_t(* psa_drv_accel_mac_setup_t)(psa_drv_accel_mac_context_t *p_context, const uint8_t *p_key, size_t key_length)
The function prototype for the setup operation of a hardware-accelerated MAC operation.
Definition: crypto_accel_driver.h:196
psa_drv_accel_mac_verify_t
psa_status_t(* psa_drv_accel_mac_verify_t)(const uint8_t *p_input, size_t input_length, const uint8_t *p_key, size_t key_length, psa_algorithm_t alg, const uint8_t *p_mac, size_t mac_length)
The function prototype for the one-shot hardware-accelerated MAC Verify operation.
Definition: crypto_accel_driver.h:343
psa_drv_accel_mac_finish_verify_t
psa_status_t(* psa_drv_accel_mac_finish_verify_t)(psa_drv_accel_mac_context_t *p_context, const uint8_t *p_mac, size_t mac_length)
The function prototype for the finish and verify operation of a hardware-accelerated MAC operation.
Definition: crypto_accel_driver.h:269
psa_key_type_t
uint16_t psa_key_type_t
Encoding of a key type.
Definition: crypto_types.h:66
psa_algorithm_t
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
Definition: crypto_types.h:98
psa_drv_hash_abort_t
void(* psa_drv_hash_abort_t)(psa_drv_hash_context_t *p_context)
The function prototype for the abort operation of a hash (message digest) operation.
Definition: crypto_accel_driver.h:145
psa_drv_hash_update_t
psa_status_t(* psa_drv_hash_update_t)(psa_drv_hash_context_t *p_context, const uint8_t *p_input, size_t input_length)
The function prototype for the update operation of a hash (message digest) operation.
Definition: crypto_accel_driver.h:100
psa_drv_hash_setup_t
psa_status_t(* psa_drv_hash_setup_t)(psa_drv_hash_context_t *p_context)
The function prototype for the start operation of a hash (message digest) operation.
Definition: crypto_accel_driver.h:81
psa_drv_hash_finish_t
psa_status_t(* psa_drv_hash_finish_t)(psa_drv_hash_context_t *p_context, uint8_t *p_output, size_t output_size, size_t *p_output_length)
The function prototype for the finish operation of a hash (message digest) operation.
Definition: crypto_accel_driver.h:127
psa_drv_hash_context_t
struct psa_drv_hash_context_s psa_drv_hash_context_t
The hardware-specific hash context structure.
Definition: crypto_accel_driver.h:64
psa_status_t
int32_t psa_status_t
Function return status.
Definition: crypto_types.h:55