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