Kenji Arai
/
mbed-os_TYBLE16
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
Embed:
(wiki syntax)
Show/hide line numbers
crypto_accel_driver.h
Go to the documentation of this file.
00001 /** 00002 * \file psa/crypto_accel_driver.h 00003 * \brief PSA cryptography accelerator driver module 00004 * 00005 * This header declares types and function signatures for cryptography 00006 * drivers that access key material directly. This is meant for 00007 * on-chip cryptography accelerators. 00008 * 00009 * This file is part of the PSA Crypto Driver Model, containing functions for 00010 * driver developers to implement to enable hardware to be called in a 00011 * standardized way by a PSA Cryptographic API implementation. The functions 00012 * comprising the driver model, which driver authors implement, are not 00013 * intended to be called by application developers. 00014 */ 00015 00016 /* 00017 * Copyright (C) 2018, ARM Limited, All Rights Reserved 00018 * SPDX-License-Identifier: Apache-2.0 00019 * 00020 * Licensed under the Apache License, Version 2.0 (the "License"); you may 00021 * not use this file except in compliance with the License. 00022 * You may obtain a copy of the License at 00023 * 00024 * http://www.apache.org/licenses/LICENSE-2.0 00025 * 00026 * Unless required by applicable law or agreed to in writing, software 00027 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 00028 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00029 * See the License for the specific language governing permissions and 00030 * limitations under the License. 00031 */ 00032 #ifndef PSA_CRYPTO_ACCEL_DRIVER_H 00033 #define PSA_CRYPTO_ACCEL_DRIVER_H 00034 00035 #include "crypto_driver_common.h" 00036 00037 #ifdef __cplusplus 00038 extern "C" { 00039 #endif 00040 00041 /** \defgroup driver_digest Hardware-Accelerated Message Digests 00042 * 00043 * Generation and authentication of Message Digests (aka hashes) must be done 00044 * in parts using the following sequence: 00045 * - `psa_drv_hash_setup_t` 00046 * - `psa_drv_hash_update_t` 00047 * - `psa_drv_hash_update_t` 00048 * - ... 00049 * - `psa_drv_hash_finish_t` 00050 * 00051 * If a previously started Message Digest operation needs to be terminated 00052 * before the `psa_drv_hash_finish_t` operation is complete, it should be aborted 00053 * by the `psa_drv_hash_abort_t`. Failure to do so may result in allocated 00054 * resources not being freed or in other undefined behavior. 00055 */ 00056 /**@{*/ 00057 00058 /** \brief The hardware-specific hash context structure 00059 * 00060 * The contents of this structure are implementation dependent and are 00061 * therefore not described here 00062 */ 00063 typedef struct psa_drv_hash_context_s psa_drv_hash_context_t; 00064 00065 /** \brief The function prototype for the start operation of a hash (message 00066 * digest) operation 00067 * 00068 * Functions that implement this prototype should be named in the following 00069 * convention: 00070 * ~~~~~~~~~~~~~{.c} 00071 * psa_drv_hash_<ALGO>_setup 00072 * ~~~~~~~~~~~~~ 00073 * Where `ALGO` is the name of the underlying hash function 00074 * 00075 * \param[in,out] p_context A structure that will contain the 00076 * hardware-specific hash context 00077 * 00078 * \retval PSA_SUCCESS Success. 00079 */ 00080 typedef psa_status_t (*psa_drv_hash_setup_t)(psa_drv_hash_context_t *p_context); 00081 00082 /** \brief The function prototype for the update operation of a hash (message 00083 * digest) operation 00084 * 00085 * Functions that implement this prototype should be named in the following 00086 * convention: 00087 * ~~~~~~~~~~~~~{.c} 00088 * psa_drv_hash_<ALGO>_update 00089 * ~~~~~~~~~~~~~ 00090 * Where `ALGO` is the name of the underlying algorithm 00091 * 00092 * \param[in,out] p_context A hardware-specific structure for the 00093 * previously-established hash operation to be 00094 * continued 00095 * \param[in] p_input A buffer containing the message to be appended 00096 * to the hash operation 00097 * \param[in] input_length The size in bytes of the input message buffer 00098 */ 00099 typedef psa_status_t (*psa_drv_hash_update_t)(psa_drv_hash_context_t *p_context, 00100 const uint8_t *p_input, 00101 size_t input_length); 00102 00103 /** \brief The function prototype for the finish operation of a hash (message 00104 * digest) operation 00105 * 00106 * Functions that implement this prototype should be named in the following 00107 * convention: 00108 * ~~~~~~~~~~~~~{.c} 00109 * psa_drv_hash_<ALGO>_finish 00110 * ~~~~~~~~~~~~~ 00111 * Where `ALGO` is the name of the underlying algorithm 00112 * 00113 * \param[in,out] p_context A hardware-specific structure for the 00114 * previously started hash operation to be 00115 * fiinished 00116 * \param[out] p_output A buffer where the generated digest will be 00117 * placed 00118 * \param[in] output_size The size in bytes of the buffer that has been 00119 * allocated for the `p_output` buffer 00120 * \param[out] p_output_length The number of bytes placed in `p_output` after 00121 * success 00122 * 00123 * \retval PSA_SUCCESS 00124 * Success. 00125 */ 00126 typedef psa_status_t (*psa_drv_hash_finish_t)(psa_drv_hash_context_t *p_context, 00127 uint8_t *p_output, 00128 size_t output_size, 00129 size_t *p_output_length); 00130 00131 /** \brief The function prototype for the abort operation of a hash (message 00132 * digest) operation 00133 * 00134 * Functions that implement this prototype should be named in the following 00135 * convention: 00136 * ~~~~~~~~~~~~~{.c} 00137 * psa_drv_hash_<ALGO>_abort 00138 * ~~~~~~~~~~~~~ 00139 * Where `ALGO` is the name of the underlying algorithm 00140 * 00141 * \param[in,out] p_context A hardware-specific structure for the previously 00142 * started hash operation to be aborted 00143 */ 00144 typedef void (*psa_drv_hash_abort_t)(psa_drv_hash_context_t *p_context); 00145 00146 /**@}*/ 00147 00148 /** \defgroup accel_mac Hardware-Accelerated Message Authentication Code 00149 * Generation and authentication of Message Authentication Codes (MACs) using 00150 * cryptographic accelerators can be done either as a single function call (via the 00151 * `psa_drv_accel_mac_generate_t` or `psa_drv_accel_mac_verify_t` 00152 * functions), or in parts using the following sequence: 00153 * - `psa_drv_accel_mac_setup_t` 00154 * - `psa_drv_accel_mac_update_t` 00155 * - `psa_drv_accel_mac_update_t` 00156 * - ... 00157 * - `psa_drv_accel_mac_finish_t` or `psa_drv_accel_mac_finish_verify_t` 00158 * 00159 * If a previously started MAC operation needs to be terminated, it 00160 * should be done so by the `psa_drv_accel_mac_abort_t`. Failure to do so may 00161 * result in allocated resources not being freed or in other undefined 00162 * behavior. 00163 * 00164 */ 00165 /**@{*/ 00166 00167 /** \brief The hardware-accelerator-specific MAC context structure 00168 * 00169 * The contents of this structure are implementation dependent and are 00170 * therefore not described here. 00171 */ 00172 typedef struct psa_drv_accel_mac_context_s psa_drv_accel_mac_context_t; 00173 00174 /** \brief The function prototype for the setup operation of a 00175 * hardware-accelerated MAC operation 00176 * 00177 * Functions that implement this prototype should be named in the following 00178 * convention: 00179 * ~~~~~~~~~~~~~{.c} 00180 * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_setup 00181 * ~~~~~~~~~~~~~ 00182 * Where `ALGO` is the name of the underlying primitive, and `MAC_VARIANT` 00183 * is the specific variant of a MAC operation (such as HMAC or CMAC) 00184 * 00185 * \param[in,out] p_context A structure that will contain the 00186 * hardware-specific MAC context 00187 * \param[in] p_key A buffer containing the cleartext key material 00188 * to be used in the operation 00189 * \param[in] key_length The size in bytes of the key material 00190 * 00191 * \retval PSA_SUCCESS 00192 * Success. 00193 */ 00194 typedef psa_status_t (*psa_drv_accel_mac_setup_t)(psa_drv_accel_mac_context_t *p_context, 00195 const uint8_t *p_key, 00196 size_t key_length); 00197 00198 /** \brief The function prototype for the update operation of a 00199 * hardware-accelerated MAC operation 00200 * 00201 * Functions that implement this prototype should be named in the following 00202 * convention: 00203 * ~~~~~~~~~~~~~{.c} 00204 * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_update 00205 * ~~~~~~~~~~~~~ 00206 * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` 00207 * is the specific variant of a MAC operation (such as HMAC or CMAC) 00208 * 00209 * \param[in,out] p_context A hardware-specific structure for the 00210 * previously-established MAC operation to be 00211 * continued 00212 * \param[in] p_input A buffer containing the message to be appended 00213 * to the MAC operation 00214 * \param[in] input_length The size in bytes of the input message buffer 00215 */ 00216 typedef psa_status_t (*psa_drv_accel_mac_update_t)(psa_drv_accel_mac_context_t *p_context, 00217 const uint8_t *p_input, 00218 size_t input_length); 00219 00220 /** \brief The function prototype for the finish operation of a 00221 * hardware-accelerated MAC operation 00222 * 00223 * Functions that implement this prototype should be named in the following 00224 * convention: 00225 * ~~~~~~~~~~~~~{.c} 00226 * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_finish 00227 * ~~~~~~~~~~~~~ 00228 * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is 00229 * the specific variant of a MAC operation (such as HMAC or CMAC) 00230 * 00231 * \param[in,out] p_context A hardware-specific structure for the 00232 * previously started MAC operation to be 00233 * finished 00234 * \param[out] p_mac A buffer where the generated MAC will be placed 00235 * \param[in] mac_length The size in bytes of the buffer that has been 00236 * allocated for the `p_mac` buffer 00237 * 00238 * \retval PSA_SUCCESS 00239 * Success. 00240 */ 00241 typedef psa_status_t (*psa_drv_accel_mac_finish_t)(psa_drv_accel_mac_context_t *p_context, 00242 uint8_t *p_mac, 00243 size_t mac_length); 00244 00245 /** \brief The function prototype for the finish and verify operation of a 00246 * hardware-accelerated MAC operation 00247 * 00248 * Functions that implement this prototype should be named in the following 00249 * convention: 00250 * ~~~~~~~~~~~~~{.c} 00251 * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_finish_verify 00252 * ~~~~~~~~~~~~~ 00253 * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is 00254 * the specific variant of a MAC operation (such as HMAC or CMAC) 00255 * 00256 * \param[in,out] p_context A hardware-specific structure for the 00257 * previously started MAC operation to be 00258 * verified and finished 00259 * \param[in] p_mac A buffer containing the MAC that will be used 00260 * for verification 00261 * \param[in] mac_length The size in bytes of the data in the `p_mac` 00262 * buffer 00263 * 00264 * \retval PSA_SUCCESS 00265 * The operation completed successfully and the comparison matched 00266 */ 00267 typedef psa_status_t (*psa_drv_accel_mac_finish_verify_t)(psa_drv_accel_mac_context_t *p_context, 00268 const uint8_t *p_mac, 00269 size_t mac_length); 00270 00271 /** \brief The function prototype for the abort operation for a previously 00272 * started hardware-accelerated MAC operation 00273 * 00274 * Functions that implement this prototype should be named in the following 00275 * convention: 00276 * ~~~~~~~~~~~~~{.c} 00277 * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_abort 00278 * ~~~~~~~~~~~~~ 00279 * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is 00280 * the specific variant of a MAC operation (such as HMAC or CMAC) 00281 * 00282 * \param[in,out] p_context A hardware-specific structure for the 00283 * previously started MAC operation to be 00284 * aborted 00285 * 00286 */ 00287 typedef psa_status_t (*psa_drv_accel_mac_abort_t)(psa_drv_accel_mac_context_t *p_context); 00288 00289 /** \brief The function prototype for the one-shot operation of a 00290 * hardware-accelerated MAC operation 00291 * 00292 * Functions that implement this prototype should be named in the following 00293 * convention: 00294 * ~~~~~~~~~~~~~{.c} 00295 * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT> 00296 * ~~~~~~~~~~~~~ 00297 * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is 00298 * the specific variant of a MAC operation (such as HMAC or CMAC) 00299 * 00300 * \param[in] p_input A buffer containing the data to be MACed 00301 * \param[in] input_length The length in bytes of the `p_input` data 00302 * \param[in] p_key A buffer containing the key material to be used 00303 * for the MAC operation 00304 * \param[in] key_length The length in bytes of the `p_key` data 00305 * \param[in] alg The algorithm to be performed 00306 * \param[out] p_mac The buffer where the resulting MAC will be placed 00307 * upon success 00308 * \param[in] mac_length The length in bytes of the `p_mac` buffer 00309 */ 00310 typedef psa_status_t (*psa_drv_accel_mac_t)(const uint8_t *p_input, 00311 size_t input_length, 00312 const uint8_t *p_key, 00313 size_t key_length, 00314 psa_algorithm_t alg, 00315 uint8_t *p_mac, 00316 size_t mac_length); 00317 00318 /** \brief The function prototype for the one-shot hardware-accelerated MAC 00319 * Verify operation 00320 * 00321 * Functions that implement this prototype should be named in the following 00322 * convention: 00323 * ~~~~~~~~~~~~~{.c} 00324 * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_verify 00325 * ~~~~~~~~~~~~~ 00326 * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is 00327 * the specific variant of a MAC operation (such as HMAC or CMAC) 00328 * 00329 * \param[in] p_input A buffer containing the data to be MACed 00330 * \param[in] input_length The length in bytes of the `p_input` data 00331 * \param[in] p_key A buffer containing the key material to be used 00332 * for the MAC operation 00333 * \param[in] key_length The length in bytes of the `p_key` data 00334 * \param[in] alg The algorithm to be performed 00335 * \param[in] p_mac The MAC data to be compared 00336 * \param[in] mac_length The length in bytes of the `p_mac` buffer 00337 * 00338 * \retval PSA_SUCCESS 00339 * The operation completed successfully and the comparison matched 00340 */ 00341 typedef psa_status_t (*psa_drv_accel_mac_verify_t)(const uint8_t *p_input, 00342 size_t input_length, 00343 const uint8_t *p_key, 00344 size_t key_length, 00345 psa_algorithm_t alg, 00346 const uint8_t *p_mac, 00347 size_t mac_length); 00348 /**@}*/ 00349 00350 /** \defgroup accel_cipher Hardware-Accelerated Block Ciphers 00351 * Encryption and Decryption using hardware-acceleration in block modes other 00352 * than ECB must be done in multiple parts, using the following flow: 00353 * - `psa_drv_accel_ciphersetup_t` 00354 * - `psa_drv_accel_cipher_set_iv_t` (optional depending upon block mode) 00355 * - `psa_drv_accel_cipher_update_t` 00356 * - `psa_drv_accel_cipher_update_t` 00357 * - ... 00358 * - `psa_drv_accel_cipher_finish_t` 00359 * 00360 * If a previously started hardware-accelerated Cipher operation needs to be 00361 * terminated, it should be done so by the `psa_drv_accel_cipher_abort_t`. 00362 * Failure to do so may result in allocated resources not being freed or in 00363 * other undefined behavior. 00364 */ 00365 /**@{*/ 00366 00367 /** \brief The hardware-accelerator-specific cipher context structure 00368 * 00369 * The contents of this structure are implementation dependent and are 00370 * therefore not described here. 00371 */ 00372 typedef struct psa_drv_accel_cipher_context_s psa_drv_accel_cipher_context_t; 00373 00374 /** \brief The function prototype for the setup operation of 00375 * hardware-accelerated block cipher operations. 00376 * Functions that implement this prototype should be named in the following 00377 * conventions: 00378 * ~~~~~~~~~~~~~{.c} 00379 * psa_drv_accel_cipher_setup_<CIPHER_NAME>_<MODE> 00380 * ~~~~~~~~~~~~~ 00381 * Where 00382 * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES) 00383 * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR) 00384 * 00385 * For stream ciphers: 00386 * ~~~~~~~~~~~~~{.c} 00387 * psa_drv_accel_cipher_setup_<CIPHER_NAME> 00388 * ~~~~~~~~~~~~~ 00389 * Where `CIPHER_NAME` is the name of a stream cipher (i.e. RC4) 00390 * 00391 * \param[in,out] p_context A structure that will contain the 00392 * hardware-specific cipher context 00393 * \param[in] direction Indicates if the operation is an encrypt or a 00394 * decrypt 00395 * \param[in] p_key_data A buffer containing the cleartext key material 00396 * to be used in the operation 00397 * \param[in] key_data_size The size in bytes of the key material 00398 * 00399 * \retval PSA_SUCCESS 00400 */ 00401 typedef psa_status_t (*psa_drv_accel_cipher_setup_t)(psa_drv_accel_cipher_context_t *p_context, 00402 psa_encrypt_or_decrypt_t direction, 00403 const uint8_t *p_key_data, 00404 size_t key_data_size); 00405 00406 /** \brief The function prototype for the set initialization vector operation 00407 * of hardware-accelerated block cipher operations 00408 * Functions that implement this prototype should be named in the following 00409 * convention: 00410 * ~~~~~~~~~~~~~{.c} 00411 * psa_drv_accel_cipher_set_iv_<CIPHER_NAME>_<MODE> 00412 * ~~~~~~~~~~~~~ 00413 * Where 00414 * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES) 00415 * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR) 00416 * 00417 * \param[in,out] p_context A structure that contains the previously setup 00418 * hardware-specific cipher context 00419 * \param[in] p_iv A buffer containing the initialization vecotr 00420 * \param[in] iv_length The size in bytes of the contents of `p_iv` 00421 * 00422 * \retval PSA_SUCCESS 00423 */ 00424 typedef psa_status_t (*psa_drv_accel_cipher_set_iv_t)(psa_drv_accel_cipher_context_t *p_context, 00425 const uint8_t *p_iv, 00426 size_t iv_length); 00427 00428 /** \brief The function prototype for the update operation of 00429 * hardware-accelerated block cipher operations. 00430 * 00431 * Functions that implement this prototype should be named in the following 00432 * convention: 00433 * ~~~~~~~~~~~~~{.c} 00434 * psa_drv_accel_cipher_update_<CIPHER_NAME>_<MODE> 00435 * ~~~~~~~~~~~~~ 00436 * Where 00437 * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES) 00438 * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR) 00439 * 00440 * \param[in,out] p_context A hardware-specific structure for the 00441 * previously started cipher operation 00442 * \param[in] p_input A buffer containing the data to be 00443 * encrypted or decrypted 00444 * \param[in] input_size The size in bytes of the `p_input` buffer 00445 * \param[out] p_output A caller-allocated buffer where the 00446 * generated output will be placed 00447 * \param[in] output_size The size in bytes of the `p_output` buffer 00448 * \param[out] p_output_length After completion, will contain the number 00449 * of bytes placed in the `p_output` buffer 00450 * 00451 * \retval PSA_SUCCESS 00452 */ 00453 typedef psa_status_t (*psa_drv_accel_cipher_update_t)(psa_drv_accel_cipher_context_t *p_context, 00454 const uint8_t *p_input, 00455 size_t input_size, 00456 uint8_t *p_output, 00457 size_t output_size, 00458 size_t *p_output_length); 00459 00460 /** \brief The function prototype for the finish operation of 00461 * hardware-accelerated block cipher operations. 00462 * 00463 * Functions that implement this prototype should be named in the following 00464 * convention: 00465 * ~~~~~~~~~~~~~{.c} 00466 * psa_drv_accel_cipher_finish_<CIPHER_NAME>_<MODE> 00467 * ~~~~~~~~~~~~~ 00468 * Where 00469 * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES) 00470 * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR) 00471 * 00472 * \param[in,out] p_context A hardware-specific structure for the 00473 * previously started cipher operation 00474 * \param[out] p_output A caller-allocated buffer where the generated 00475 * output will be placed 00476 * \param[in] output_size The size in bytes of the `p_output` buffer 00477 * \param[out] p_output_length After completion, will contain the number of 00478 * bytes placed in the `p_output` buffer 00479 * 00480 * \retval PSA_SUCCESS 00481 */ 00482 typedef psa_status_t (*psa_drv_accel_cipher_finish_t)(psa_drv_accel_cipher_context_t *p_context, 00483 uint8_t *p_output, 00484 size_t output_size, 00485 size_t *p_output_length); 00486 00487 /** \brief The function prototype for the abort operation of 00488 * hardware-accelerated block cipher operations. 00489 * 00490 * Functions that implement the following prototype should be named in the 00491 * following convention: 00492 * ~~~~~~~~~~~~~{.c} 00493 * psa_drv_accel_cipher_abort_<CIPHER_NAME>_<MODE> 00494 * ~~~~~~~~~~~~~ 00495 * Where 00496 * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES) 00497 * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR) 00498 * 00499 * \param[in,out] p_context A hardware-specific structure for the 00500 * previously started cipher operation 00501 * 00502 * \retval PSA_SUCCESS 00503 */ 00504 typedef psa_status_t (*psa_drv_accel_cipher_abort_t)(psa_drv_accel_cipher_context_t *p_context); 00505 00506 /**@}*/ 00507 00508 /** \defgroup accel_aead Hardware-Accelerated Authenticated Encryption with Additional Data 00509 * 00510 * Hardware-accelerated Authenticated Encryption with Additional Data (AEAD) 00511 * operations must be done in one function call. While this creates a burden 00512 * for implementers as there must be sufficient space in memory for the entire 00513 * message, it prevents decrypted data from being made available before the 00514 * authentication operation is complete and the data is known to be authentic. 00515 */ 00516 /**@{*/ 00517 00518 /** \brief The function prototype for the hardware-accelerated authenticated 00519 * encryption operation. 00520 * 00521 * Functions that implement this prototype should be named in the following 00522 * convention: 00523 * ~~~~~~~~~~~~~{.c} 00524 * psa_drv_accel_aead_<ALGO>_encrypt 00525 * ~~~~~~~~~~~~~ 00526 * Where `ALGO` is the name of the AEAD algorithm 00527 * 00528 * \param[in] p_key A pointer to the key material 00529 * \param[in] key_length The size in bytes of the key material 00530 * \param[in] alg The AEAD algorithm to compute 00531 * (\c PSA_ALG_XXX value such that 00532 * #PSA_ALG_IS_AEAD(`alg`) is true) 00533 * \param[in] nonce Nonce or IV to use 00534 * \param[in] nonce_length Size of the `nonce` buffer in bytes 00535 * \param[in] additional_data Additional data that will be MACed 00536 * but not encrypted. 00537 * \param[in] additional_data_length Size of `additional_data` in bytes 00538 * \param[in] plaintext Data that will be MACed and 00539 * encrypted. 00540 * \param[in] plaintext_length Size of `plaintext` in bytes 00541 * \param[out] ciphertext Output buffer for the authenticated and 00542 * encrypted data. The additional data is 00543 * not part of this output. For algorithms 00544 * where the encrypted data and the 00545 * authentication tag are defined as 00546 * separate outputs, the authentication 00547 * tag is appended to the encrypted data. 00548 * \param[in] ciphertext_size Size of the `ciphertext` buffer in 00549 * bytes 00550 * This must be at least 00551 * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(`alg`, 00552 * `plaintext_length`). 00553 * \param[out] ciphertext_length On success, the size of the output in 00554 * the `ciphertext` buffer 00555 * 00556 * \retval #PSA_SUCCESS 00557 * 00558 */ 00559 typedef psa_status_t (*psa_drv_accel_aead_encrypt_t)(const uint8_t *p_key, 00560 size_t key_length, 00561 psa_algorithm_t alg, 00562 const uint8_t *nonce, 00563 size_t nonce_length, 00564 const uint8_t *additional_data, 00565 size_t additional_data_length, 00566 const uint8_t *plaintext, 00567 size_t plaintext_length, 00568 uint8_t *ciphertext, 00569 size_t ciphertext_size, 00570 size_t *ciphertext_length); 00571 00572 /** \brief The function prototype for the hardware-accelerated authenticated 00573 * decryption operation. 00574 * 00575 * Functions that implement this prototype should be named in the following 00576 * convention: 00577 * ~~~~~~~~~~~~~{.c} 00578 * psa_drv_accel_aead_<ALGO>_decrypt 00579 * ~~~~~~~~~~~~~ 00580 * Where `ALGO` is the name of the AEAD algorithm 00581 * \param[in] p_key A pointer to the key material 00582 * \param[in] key_length The size in bytes of the key material 00583 * \param[in] alg The AEAD algorithm to compute 00584 * (\c PSA_ALG_XXX value such that 00585 * #PSA_ALG_IS_AEAD(`alg`) is true) 00586 * \param[in] nonce Nonce or IV to use 00587 * \param[in] nonce_length Size of the `nonce` buffer in bytes 00588 * \param[in] additional_data Additional data that has been MACed 00589 * but not encrypted 00590 * \param[in] additional_data_length Size of `additional_data` in bytes 00591 * \param[in] ciphertext Data that has been MACed and 00592 * encrypted 00593 * For algorithms where the encrypted data 00594 * and the authentication tag are defined 00595 * as separate inputs, the buffer must 00596 * contain the encrypted data followed by 00597 * the authentication tag. 00598 * \param[in] ciphertext_length Size of `ciphertext` in bytes 00599 * \param[out] plaintext Output buffer for the decrypted data 00600 * \param[in] plaintext_size Size of the `plaintext` buffer in 00601 * bytes 00602 * This must be at least 00603 * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(`alg`, 00604 * `ciphertext_length`). 00605 * \param[out] plaintext_length On success, the size of the output 00606 * in the \b plaintext buffer 00607 * 00608 * \retval #PSA_SUCCESS 00609 * Success. 00610 */ 00611 typedef psa_status_t (*psa_drv_accel_aead_decrypt_t)(const uint8_t *p_key, 00612 size_t key_length, 00613 psa_algorithm_t alg, 00614 const uint8_t *nonce, 00615 size_t nonce_length, 00616 const uint8_t *additional_data, 00617 size_t additional_data_length, 00618 const uint8_t *ciphertext, 00619 size_t ciphertext_length, 00620 uint8_t *plaintext, 00621 size_t plaintext_size, 00622 size_t *plaintext_length); 00623 00624 /**@}*/ 00625 00626 /** \defgroup accel_asymmetric Hardware-Accelerated Asymmetric Cryptography 00627 * 00628 * Since the amount of data that can (or should) be encrypted or signed using 00629 * asymmetric keys is limited by the key size, hardware-accelerated asymmetric 00630 * key operations must be done in single function calls. 00631 */ 00632 /**@{*/ 00633 00634 00635 /** 00636 * \brief The function prototype for the hardware-accelerated asymmetric sign 00637 * operation. 00638 * 00639 * Functions that implement this prototype should be named in the following 00640 * convention: 00641 * ~~~~~~~~~~~~~{.c} 00642 * psa_drv_accel_asymmetric_<ALGO>_sign 00643 * ~~~~~~~~~~~~~ 00644 * Where `ALGO` is the name of the signing algorithm 00645 * 00646 * This function supports any asymmetric-key output from psa_export_key() as 00647 * the buffer in \p p_key. Refer to the documentation of \ref 00648 * psa_export_key() for the formats. 00649 * 00650 * \param[in] p_key A buffer containing the private key 00651 * material 00652 * \param[in] key_size The size in bytes of the `p_key` data 00653 * \param[in] alg A signature algorithm that is compatible 00654 * with the type of `p_key` 00655 * \param[in] p_hash The hash or message to sign 00656 * \param[in] hash_length Size of the `p_hash` buffer in bytes 00657 * \param[out] p_signature Buffer where the signature is to be written 00658 * \param[in] signature_size Size of the `p_signature` buffer in bytes 00659 * \param[out] p_signature_length On success, the number of bytes 00660 * that make up the returned signature value 00661 * 00662 * \retval PSA_SUCCESS 00663 */ 00664 typedef psa_status_t (*psa_drv_accel_asymmetric_sign_t)(const uint8_t *p_key, 00665 size_t key_size, 00666 psa_algorithm_t alg, 00667 psa_key_type_t key_type, 00668 const uint8_t *p_hash, 00669 size_t hash_length, 00670 uint8_t *p_signature, 00671 size_t signature_size, 00672 size_t *p_signature_length); 00673 00674 /** 00675 * \brief The function prototype for the hardware-accelerated signature verify 00676 * operation 00677 * 00678 * Functions that implement this prototype should be named in the following 00679 * convention: 00680 * ~~~~~~~~~~~~~{.c} 00681 * psa_drv_accel_asymmetric_<ALGO>_verify 00682 * ~~~~~~~~~~~~~ 00683 * Where `ALGO` is the name of the signing algorithm 00684 * 00685 * This function supports any output from \ref psa_export_public_key() as the 00686 * buffer in \p p_key. Refer to the documentation of \ref 00687 * psa_export_public_key() for the format of public keys and to the 00688 * documentation of \ref psa_export_key() for the format for other key types. 00689 * 00690 * \param[in] p_key A buffer containing the public key material 00691 * \param[in] key_size The size in bytes of the `p_key` data 00692 * \param[in] alg A signature algorithm that is compatible with 00693 * the type of `key` 00694 * \param[in] p_hash The hash or message whose signature is to be 00695 * verified 00696 * \param[in] hash_length Size of the `p_hash` buffer in bytes 00697 * \param[in] p_signature Buffer containing the signature to verify 00698 * \param[in] signature_length Size of the `p_signature` buffer in bytes 00699 * 00700 * \retval PSA_SUCCESS 00701 * The signature is valid. 00702 */ 00703 typedef psa_status_t (*psa_drv_accel_asymmetric_verify_t)(const uint8_t *p_key, 00704 size_t key_size, 00705 psa_algorithm_t alg, 00706 psa_key_type_t key_type, 00707 const uint8_t *p_hash, 00708 size_t hash_length, 00709 const uint8_t *p_signature, 00710 size_t signature_length); 00711 00712 /** 00713 * \brief The function prototype for the hardware-accelerated asymmetric 00714 * encrypt operation 00715 * 00716 * Functions that implement this prototype should be named in the following 00717 * convention: 00718 * ~~~~~~~~~~~~~{.c} 00719 * psa_drv_accel_asymmetric_<ALGO>_encrypt 00720 * ~~~~~~~~~~~~~ 00721 * Where `ALGO` is the name of the encryption algorithm 00722 * 00723 * This function supports any output from \ref psa_export_public_key() as the 00724 * buffer in \p p_key. Refer to the documentation of \ref 00725 * psa_export_public_key() for the format of public keys and to the 00726 * documentation of \ref psa_export_key() for the format for other key types. 00727 * 00728 * \param[in] p_key A buffer containing the public key material 00729 * \param[in] key_size The size in bytes of the `p_key` data 00730 * \param[in] alg An asymmetric encryption algorithm that is 00731 * compatible with the type of `key` 00732 * \param[in] p_input The message to encrypt 00733 * \param[in] input_length Size of the `p_input` buffer in bytes 00734 * \param[in] p_salt A salt or label, if supported by the 00735 * encryption algorithm 00736 * If the algorithm does not support a 00737 * salt, pass `NULL` 00738 * If the algorithm supports an optional 00739 * salt and you do not want to pass a salt, 00740 * pass `NULL`. 00741 * For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is 00742 * supported. 00743 * \param[in] salt_length Size of the `p_salt` buffer in bytes 00744 * If `p_salt` is `NULL`, pass 0. 00745 * \param[out] p_output Buffer where the encrypted message is to 00746 * be written 00747 * \param[in] output_size Size of the `p_output` buffer in bytes 00748 * \param[out] p_output_length On success, the number of bytes 00749 * that make up the returned output 00750 * 00751 * \retval PSA_SUCCESS 00752 */ 00753 typedef psa_status_t (*psa_drv_accel_asymmetric_encrypt_t)(const uint8_t *p_key, 00754 size_t key_size, 00755 psa_algorithm_t alg, 00756 psa_key_type_t key_type, 00757 const uint8_t *p_input, 00758 size_t input_length, 00759 const uint8_t *p_salt, 00760 size_t salt_length, 00761 uint8_t *p_output, 00762 size_t output_size, 00763 size_t *p_output_length); 00764 00765 /** 00766 * \brief The function prototype for the hardware=acce;erated asymmetric 00767 * decrypt operation 00768 * 00769 * Functions that implement this prototype should be named in the following 00770 * convention: 00771 * ~~~~~~~~~~~~~{.c} 00772 * psa_drv_accel_asymmetric_<ALGO>_decrypt 00773 * ~~~~~~~~~~~~~ 00774 * Where `ALGO` is the name of the encryption algorithm 00775 * 00776 * This function supports any asymmetric-key output from psa_export_key() as 00777 * the buffer in \p p_key. Refer to the documentation of \ref 00778 * psa_export_key() for the formats. 00779 * 00780 * \param[in] p_key A buffer containing the private key material 00781 * \param[in] key_size The size in bytes of the `p_key` data 00782 * \param[in] alg An asymmetric encryption algorithm that is 00783 * compatible with the type of `key` 00784 * \param[in] p_input The message to decrypt 00785 * \param[in] input_length Size of the `p_input` buffer in bytes 00786 * \param[in] p_salt A salt or label, if supported by the 00787 * encryption algorithm 00788 * If the algorithm does not support a 00789 * salt, pass `NULL`. 00790 * If the algorithm supports an optional 00791 * salt and you do not want to pass a salt, 00792 * pass `NULL`. 00793 * For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is 00794 * supported 00795 * \param[in] salt_length Size of the `p_salt` buffer in bytes 00796 * If `p_salt` is `NULL`, pass 0 00797 * \param[out] p_output Buffer where the decrypted message is to 00798 * be written 00799 * \param[in] output_size Size of the `p_output` buffer in bytes 00800 * \param[out] p_output_length On success, the number of bytes 00801 * that make up the returned output 00802 * 00803 * \retval PSA_SUCCESS 00804 */ 00805 typedef psa_status_t (*psa_drv_accel_asymmetric_decrypt_t)(const uint8_t *p_key, 00806 size_t key_size, 00807 psa_algorithm_t alg, 00808 psa_key_type_t key_type, 00809 const uint8_t *p_input, 00810 size_t input_length, 00811 const uint8_t *p_salt, 00812 size_t salt_length, 00813 uint8_t *p_output, 00814 size_t output_size, 00815 size_t *p_output_length); 00816 00817 /**@}*/ 00818 00819 #ifdef __cplusplus 00820 } 00821 #endif 00822 00823 #endif /* PSA_CRYPTO_ACCEL_DRIVER_H */
Generated on Tue Jul 12 2022 13:54:14 by
1.7.2