Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
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
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 */
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:401
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:216
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:664
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_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:194
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:63
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:310
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:144
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:172
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:703
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:424
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:504
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:805
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:559
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:80
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:241
psa_algorithm_t
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:98
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:482
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:611
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:99
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:341
psa_key_type_t
uint16_t psa_key_type_t
Encoding of a key type.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:66
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:267
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:453
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:287
crypto_driver_common.h
Definitions for all PSA crypto drivers.
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:372
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:753
psa_status_t
int32_t psa_status_t
Function return status.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:55
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:126
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.