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