1 /*! 2 \ingroup AES 3 \brief This function initializes an AES structure by setting the key and 4 then setting the initialization vector. 5 6 \return 0 On successfully setting key and initialization vector. 7 \return BAD_FUNC_ARG Returned if key length is invalid. 8 9 \param aes pointer to the AES structure to modify 10 \param key 16, 24, or 32 byte secret key for encryption and decryption 11 \param len length of the key passed in 12 \param iv pointer to the initialization vector used to initialize the key 13 \param dir Cipher direction. Set AES_ENCRYPTION to encrypt, or 14 AES_DECRYPTION to decrypt. 15 16 _Example_ 17 \code 18 Aes enc; 19 int ret = 0; 20 byte key[] = { some 16, 24 or 32 byte key }; 21 byte iv[] = { some 16 byte iv }; 22 if (ret = wc_AesSetKey(&enc, key, AES_BLOCK_SIZE, iv, 23 AES_ENCRYPTION) != 0) { 24 // failed to set aes key 25 } 26 \endcode 27 28 \sa wc_AesSetKeyDirect 29 \sa wc_AesSetIV 30 */ 31 WOLFSSL_API int wc_AesSetKey(Aes* aes, const byte* key, word32 len, 32 const byte* iv, int dir); 33 34 /*! 35 \ingroup AES 36 \brief This function sets the initialization vector for a 37 particular AES object. The AES object should be initialized before 38 calling this function. 39 40 \return 0 On successfully setting initialization vector. 41 \return BAD_FUNC_ARG Returned if AES pointer is NULL. 42 43 \param aes pointer to the AES structure on which to set the 44 initialization vector 45 \param iv initialization vector used to initialize the AES structure. 46 If the value is NULL, the default action initializes the iv to 0. 47 48 _Example_ 49 \code 50 Aes enc; 51 // set enc key 52 byte iv[] = { some 16 byte iv }; 53 if (ret = wc_AesSetIV(&enc, iv) != 0) { 54 // failed to set aes iv 55 } 56 \endcode 57 58 \sa wc_AesSetKeyDirect 59 \sa wc_AesSetKey 60 */ 61 WOLFSSL_API int wc_AesSetIV(Aes* aes, const byte* iv); 62 63 /*! 64 \ingroup AES 65 \brief Encrypts a plaintext message from the input buffer in, and places 66 the resulting cipher text in the output buffer out using cipher block 67 chaining with AES. This function requires that the AES object has been 68 initialized by calling AesSetKey before a message is able to be encrypted. 69 This function assumes that the input message is AES block length aligned, 70 and expects the input length to be a multiple of the block length, which 71 will optionally be checked and enforced if WOLFSSL_AES_CBC_LENGTH_CHECKS 72 is defined in the build configuration. In order to assure block-multiple 73 input, PKCS#7 style padding should be added beforehand. This differs from 74 the OpenSSL AES-CBC methods which add the padding for you. To make the 75 wolfSSL and corresponding OpenSSL functions interoperate, one should specify 76 the -nopad option in the OpenSSL command line function so that it behaves 77 like the wolfSSL AesCbcEncrypt method and does not add extra padding 78 during encryption. 79 80 \return 0 On successfully encrypting message. 81 \return BAD_ALIGN_E: may be returned on block align error 82 \return BAD_LENGTH_E will be returned if the input length isn't a 83 multiple of the AES block length, when the library is built with 84 WOLFSSL_AES_CBC_LENGTH_CHECKS. 85 86 \param aes pointer to the AES object used to encrypt data 87 \param out pointer to the output buffer in which to store the ciphertext 88 of the encrypted message 89 \param in pointer to the input buffer containing message to be encrypted 90 \param sz size of input message 91 92 _Example_ 93 \code 94 Aes enc; 95 int ret = 0; 96 // initialize enc with AesSetKey, using direction AES_ENCRYPTION 97 byte msg[AES_BLOCK_SIZE * n]; // multiple of 16 bytes 98 // fill msg with data 99 byte cipher[AES_BLOCK_SIZE * n]; // Some multiple of 16 bytes 100 if ((ret = wc_AesCbcEncrypt(&enc, cipher, message, sizeof(msg))) != 0 ) { 101 // block align error 102 } 103 \endcode 104 105 \sa wc_AesSetKey 106 \sa wc_AesSetIV 107 \sa wc_AesCbcDecrypt 108 */ 109 WOLFSSL_API int wc_AesCbcEncrypt(Aes* aes, byte* out, 110 const byte* in, word32 sz); 111 112 /*! 113 \ingroup AES 114 \brief Decrypts a cipher from the input buffer in, and places the 115 resulting plain text in the output buffer out using cipher block chaining 116 with AES. This function requires that the AES structure has been 117 initialized by calling AesSetKey before a message is able to be decrypted. 118 This function assumes that the original message was AES block length 119 aligned, and expects the input length to be a multiple of the block length, 120 which will optionally be checked and enforced if 121 WOLFSSL_AES_CBC_LENGTH_CHECKS is defined in the build configuration. 122 This differs from the OpenSSL AES-CBC methods, which add PKCS#7 padding 123 automatically, and so do not require block-multiple input. To make the 124 wolfSSL function and equivalent OpenSSL functions interoperate, one 125 should specify the -nopad option in the OpenSSL command line function 126 so that it behaves like the wolfSSL AesCbcEncrypt method and does not 127 create errors during decryption. 128 129 \return 0 On successfully decrypting message. 130 \return BAD_ALIGN_E may be returned on block align error. 131 \return BAD_LENGTH_E will be returned if the input length isn't a 132 multiple of the AES block length, when the library is built with 133 WOLFSSL_AES_CBC_LENGTH_CHECKS. 134 135 \param aes pointer to the AES object used to decrypt data. 136 \param out pointer to the output buffer in which to store the plain text 137 of the decrypted message. 138 \param in pointer to the input buffer containing cipher text to be 139 decrypted. 140 \param sz size of input message. 141 142 _Example_ 143 \code 144 Aes dec; 145 int ret = 0; 146 // initialize dec with AesSetKey, using direction AES_DECRYPTION 147 byte cipher[AES_BLOCK_SIZE * n]; // some multiple of 16 bytes 148 // fill cipher with cipher text 149 byte plain [AES_BLOCK_SIZE * n]; 150 if ((ret = wc_AesCbcDecrypt(&dec, plain, cipher, sizeof(cipher))) != 0 ) { 151 // block align error 152 } 153 \endcode 154 155 \sa wc_AesSetKey 156 \sa wc_AesCbcEncrypt 157 */ 158 WOLFSSL_API int wc_AesCbcDecrypt(Aes* aes, byte* out, 159 const byte* in, word32 sz); 160 161 /*! 162 \ingroup AES 163 \brief Encrypts/Decrypts a message from the input buffer in, and places 164 the resulting cipher text in the output buffer out using CTR mode with 165 AES. This function is only enabled if WOLFSSL_AES_COUNTER is enabled at 166 compile time. The AES structure should be initialized through AesSetKey 167 before calling this function. Note that this function is used for both 168 decryption and encryption. _NOTE:_ Regarding using same API for encryption 169 and decryption. User should differentiate between Aes structures 170 for encrypt/decrypt. 171 172 \return int integer values corresponding to wolfSSL error or success 173 status 174 175 \param aes pointer to the AES object used to decrypt data 176 \param out pointer to the output buffer in which to store the cipher 177 text of the encrypted message 178 \param in pointer to the input buffer containing plain text to be encrypted 179 \param sz size of the input plain text 180 181 _Example_ 182 \code 183 Aes enc; 184 Aes dec; 185 // initialize enc and dec with AesSetKeyDirect, using direction 186 AES_ENCRYPTION 187 // since the underlying API only calls Encrypt and by default calling 188 encrypt on 189 // a cipher results in a decryption of the cipher 190 191 byte msg[AES_BLOCK_SIZE * n]; //n being a positive integer making msg 192 some multiple of 16 bytes 193 // fill plain with message text 194 byte cipher[AES_BLOCK_SIZE * n]; 195 byte decrypted[AES_BLOCK_SIZE * n]; 196 wc_AesCtrEncrypt(&enc, cipher, msg, sizeof(msg)); // encrypt plain 197 wc_AesCtrEncrypt(&dec, decrypted, cipher, sizeof(cipher)); 198 // decrypt cipher text 199 \endcode 200 201 \sa wc_AesSetKey 202 */ 203 WOLFSSL_API int wc_AesCtrEncrypt(Aes* aes, byte* out, 204 const byte* in, word32 sz); 205 206 /*! 207 \ingroup AES 208 \brief This function is a one-block encrypt of the input block, in, into 209 the output block, out. It uses the key and iv (initialization vector) 210 of the provided AES structure, which should be initialized with 211 wc_AesSetKey before calling this function. It is only enabled if the 212 configure option WOLFSSL_AES_DIRECT is enabled. __Warning:__ In nearly all 213 use cases ECB mode is considered to be less secure. Please avoid using ECB 214 API’s directly whenever possible 215 216 \param aes pointer to the AES object used to encrypt data 217 \param out pointer to the output buffer in which to store the cipher 218 text of the encrypted message 219 \param in pointer to the input buffer containing plain text to be encrypted 220 221 _Example_ 222 \code 223 Aes enc; 224 // initialize enc with AesSetKey, using direction AES_ENCRYPTION 225 byte msg [AES_BLOCK_SIZE]; // 16 bytes 226 // initialize msg with plain text to encrypt 227 byte cipher[AES_BLOCK_SIZE]; 228 wc_AesEncryptDirect(&enc, cipher, msg); 229 \endcode 230 231 \sa wc_AesDecryptDirect 232 \sa wc_AesSetKeyDirect 233 */ 234 WOLFSSL_API void wc_AesEncryptDirect(Aes* aes, byte* out, const byte* in); 235 236 /*! 237 \ingroup AES 238 \brief This function is a one-block decrypt of the input block, in, into 239 the output block, out. It uses the key and iv (initialization vector) of 240 the provided AES structure, which should be initialized with wc_AesSetKey 241 before calling this function. It is only enabled if the configure option 242 WOLFSSL_AES_DIRECT is enabled, and there is support for direct AES 243 encryption on the system in question. __Warning:__ In nearly all use cases 244 ECB mode is considered to be less secure. Please avoid using ECB API’s 245 directly whenever possible 246 247 \return none 248 249 \param aes pointer to the AES object used to encrypt data 250 \param out pointer to the output buffer in which to store the plain 251 text of the decrypted cipher text 252 \param in pointer to the input buffer containing cipher text to be 253 decrypted 254 255 _Example_ 256 \code 257 Aes dec; 258 // initialize enc with AesSetKey, using direction AES_DECRYPTION 259 byte cipher [AES_BLOCK_SIZE]; // 16 bytes 260 // initialize cipher with cipher text to decrypt 261 byte msg[AES_BLOCK_SIZE]; 262 wc_AesDecryptDirect(&dec, msg, cipher); 263 \endcode 264 265 \sa wc_AesEncryptDirect 266 \sa wc_AesSetKeyDirect 267 */ 268 WOLFSSL_API void wc_AesDecryptDirect(Aes* aes, byte* out, const byte* in); 269 270 /*! 271 \ingroup AES 272 \brief This function is used to set the AES keys for CTR mode with AES. 273 It initializes an AES object with the given key, iv 274 (initialization vector), and encryption dir (direction). It is only 275 enabled if the configure option WOLFSSL_AES_DIRECT is enabled. 276 Currently wc_AesSetKeyDirect uses wc_AesSetKey internally. __Warning:__ In 277 nearly all use cases ECB mode is considered to be less secure. Please avoid 278 using ECB API’s directly whenever possible 279 280 \return 0 On successfully setting the key. 281 \return BAD_FUNC_ARG Returned if the given key is an invalid length. 282 283 \param aes pointer to the AES object used to encrypt data 284 \param key 16, 24, or 32 byte secret key for encryption and decryption 285 \param len length of the key passed in 286 \param iv initialization vector used to initialize the key 287 \param dir Cipher direction. Set AES_ENCRYPTION to encrypt, or 288 AES_DECRYPTION to decrypt. (See enum in wolfssl/wolfcrypt/aes.h) 289 (NOTE: If using wc_AesSetKeyDirect with Aes Counter mode (Stream cipher) 290 only use AES_ENCRYPTION for both encrypting and decrypting) 291 292 _Example_ 293 \code 294 Aes enc; 295 int ret = 0; 296 byte key[] = { some 16, 24, or 32 byte key }; 297 byte iv[] = { some 16 byte iv }; 298 if (ret = wc_AesSetKeyDirect(&enc, key, sizeof(key), iv, 299 AES_ENCRYPTION) != 0) { 300 // failed to set aes key 301 } 302 \endcode 303 304 \sa wc_AesEncryptDirect 305 \sa wc_AesDecryptDirect 306 \sa wc_AesSetKey 307 */ 308 WOLFSSL_API int wc_AesSetKeyDirect(Aes* aes, const byte* key, word32 len, 309 const byte* iv, int dir); 310 311 /*! 312 \ingroup AES 313 \brief This function is used to set the key for AES GCM 314 (Galois/Counter Mode). It initializes an AES object with the 315 given key. It is only enabled if the configure option 316 HAVE_AESGCM is enabled at compile time. 317 318 \return 0 On successfully setting the key. 319 \return BAD_FUNC_ARG Returned if the given key is an invalid length. 320 321 \param aes pointer to the AES object used to encrypt data 322 \param key 16, 24, or 32 byte secret key for encryption and decryption 323 \param len length of the key passed in 324 325 _Example_ 326 \code 327 Aes enc; 328 int ret = 0; 329 byte key[] = { some 16, 24,32 byte key }; 330 if (ret = wc_AesGcmSetKey(&enc, key, sizeof(key)) != 0) { 331 // failed to set aes key 332 } 333 \endcode 334 335 \sa wc_AesGcmEncrypt 336 \sa wc_AesGcmDecrypt 337 */ 338 WOLFSSL_API int wc_AesGcmSetKey(Aes* aes, const byte* key, word32 len); 339 340 /*! 341 \ingroup AES 342 \brief This function encrypts the input message, held in the buffer in, 343 and stores the resulting cipher text in the output buffer out. It 344 requires a new iv (initialization vector) for each call to encrypt. 345 It also encodes the input authentication vector, authIn, into the 346 authentication tag, authTag. 347 348 \return 0 On successfully encrypting the input message 349 350 \param aes - pointer to the AES object used to encrypt data 351 \param out pointer to the output buffer in which to store the cipher text 352 \param in pointer to the input buffer holding the message to encrypt 353 \param sz length of the input message to encrypt 354 \param iv pointer to the buffer containing the initialization vector 355 \param ivSz length of the initialization vector 356 \param authTag pointer to the buffer in which to store the 357 authentication tag 358 \param authTagSz length of the desired authentication tag 359 \param authIn pointer to the buffer containing the input 360 authentication vector 361 \param authInSz length of the input authentication vector 362 363 _Example_ 364 \code 365 Aes enc; 366 // initialize aes structure by calling wc_AesGcmSetKey 367 368 byte plain[AES_BLOCK_LENGTH * n]; //n being a positive integer 369 making plain some multiple of 16 bytes 370 // initialize plain with msg to encrypt 371 byte cipher[sizeof(plain)]; 372 byte iv[] = // some 16 byte iv 373 byte authTag[AUTH_TAG_LENGTH]; 374 byte authIn[] = // Authentication Vector 375 376 wc_AesGcmEncrypt(&enc, cipher, plain, sizeof(cipher), iv, sizeof(iv), 377 authTag, sizeof(authTag), authIn, sizeof(authIn)); 378 \endcode 379 380 \sa wc_AesGcmSetKey 381 \sa wc_AesGcmDecrypt 382 */ 383 WOLFSSL_API int wc_AesGcmEncrypt(Aes* aes, byte* out, 384 const byte* in, word32 sz, 385 const byte* iv, word32 ivSz, 386 byte* authTag, word32 authTagSz, 387 const byte* authIn, word32 authInSz); 388 389 /*! 390 \ingroup AES 391 \brief This function decrypts the input cipher text, held in the buffer 392 in, and stores the resulting message text in the output buffer out. 393 It also checks the input authentication vector, authIn, against the 394 supplied authentication tag, authTag. 395 396 \return 0 On successfully decrypting the input message 397 \return AES_GCM_AUTH_E If the authentication tag does not match the 398 supplied authentication code vector, authTag. 399 400 \param aes pointer to the AES object used to encrypt data 401 \param out pointer to the output buffer in which to store the message text 402 \param in pointer to the input buffer holding the cipher text to decrypt 403 \param sz length of the cipher text to decrypt 404 \param iv pointer to the buffer containing the initialization vector 405 \param ivSz length of the initialization vector 406 \param authTag pointer to the buffer containing the authentication tag 407 \param authTagSz length of the desired authentication tag 408 \param authIn pointer to the buffer containing the input 409 authentication vector 410 \param authInSz length of the input authentication vector 411 412 _Example_ 413 \code 414 Aes enc; //can use the same struct as was passed to wc_AesGcmEncrypt 415 // initialize aes structure by calling wc_AesGcmSetKey if not already done 416 417 byte cipher[AES_BLOCK_LENGTH * n]; //n being a positive integer 418 making cipher some multiple of 16 bytes 419 // initialize cipher with cipher text to decrypt 420 byte output[sizeof(cipher)]; 421 byte iv[] = // some 16 byte iv 422 byte authTag[AUTH_TAG_LENGTH]; 423 byte authIn[] = // Authentication Vector 424 425 wc_AesGcmDecrypt(&enc, output, cipher, sizeof(cipher), iv, sizeof(iv), 426 authTag, sizeof(authTag), authIn, sizeof(authIn)); 427 \endcode 428 429 \sa wc_AesGcmSetKey 430 \sa wc_AesGcmEncrypt 431 */ 432 WOLFSSL_API int wc_AesGcmDecrypt(Aes* aes, byte* out, 433 const byte* in, word32 sz, 434 const byte* iv, word32 ivSz, 435 const byte* authTag, word32 authTagSz, 436 const byte* authIn, word32 authInSz); 437 438 /*! 439 \ingroup AES 440 \brief This function initializes and sets the key for a GMAC object 441 to be used for Galois Message Authentication. 442 443 \return 0 On successfully setting the key 444 \return BAD_FUNC_ARG Returned if key length is invalid. 445 446 \param gmac pointer to the gmac object used for authentication 447 \param key 16, 24, or 32 byte secret key for authentication 448 \param len length of the key 449 450 _Example_ 451 \code 452 Gmac gmac; 453 key[] = { some 16, 24, or 32 byte length key }; 454 wc_GmacSetKey(&gmac, key, sizeof(key)); 455 \endcode 456 457 \sa wc_GmacUpdate 458 */ 459 WOLFSSL_API int wc_GmacSetKey(Gmac* gmac, const byte* key, word32 len); 460 461 /*! 462 \ingroup AES 463 \brief This function generates the Gmac hash of the authIn input and 464 stores the result in the authTag buffer. After running wc_GmacUpdate, 465 one should compare the generated authTag to a known authentication tag 466 to verify the authenticity of a message. 467 468 \return 0 On successfully computing the Gmac hash. 469 470 \param gmac pointer to the gmac object used for authentication 471 \param iv initialization vector used for the hash 472 \param ivSz size of the initialization vector used 473 \param authIn pointer to the buffer containing the authentication 474 vector to verify 475 \param authInSz size of the authentication vector 476 \param authTag pointer to the output buffer in which to store the Gmac hash 477 \param authTagSz the size of the output buffer used to store the Gmac hash 478 479 _Example_ 480 \code 481 Gmac gmac; 482 key[] = { some 16, 24, or 32 byte length key }; 483 iv[] = { some 16 byte length iv }; 484 485 wc_GmacSetKey(&gmac, key, sizeof(key)); 486 authIn[] = { some 16 byte authentication input }; 487 tag[AES_BLOCK_SIZE]; // will store authentication code 488 489 wc_GmacUpdate(&gmac, iv, sizeof(iv), authIn, sizeof(authIn), tag, 490 sizeof(tag)); 491 \endcode 492 493 \sa wc_GmacSetKey 494 */ 495 WOLFSSL_API int wc_GmacUpdate(Gmac* gmac, const byte* iv, word32 ivSz, 496 const byte* authIn, word32 authInSz, 497 byte* authTag, word32 authTagSz); 498 499 /*! 500 \ingroup AES 501 \brief This function sets the key for an AES object using CCM 502 (Counter with CBC-MAC). It takes a pointer to an AES structure and 503 initializes it with supplied key. 504 505 \return none 506 507 \param aes aes structure in which to store the supplied key 508 \param key 16, 24, or 32 byte secret key for encryption and decryption 509 \param keySz size of the supplied key 510 511 _Example_ 512 \code 513 Aes enc; 514 key[] = { some 16, 24, or 32 byte length key }; 515 516 wc_AesCcmSetKey(&aes, key, sizeof(key)); 517 \endcode 518 519 \sa wc_AesCcmEncrypt 520 \sa wc_AesCcmDecrypt 521 */ 522 WOLFSSL_API int wc_AesCcmSetKey(Aes* aes, const byte* key, word32 keySz); 523 524 /*! 525 \ingroup AES 526 527 \brief This function encrypts the input message, in, into the output 528 buffer, out, using CCM (Counter with CBC-MAC). It subsequently 529 calculates and stores the authorization tag, authTag, from the 530 authIn input. 531 532 \return none 533 534 \param aes pointer to the AES object used to encrypt data 535 \param out pointer to the output buffer in which to store the cipher text 536 \param in pointer to the input buffer holding the message to encrypt 537 \param sz length of the input message to encrypt 538 \param nonce pointer to the buffer containing the nonce 539 (number only used once) 540 \param nonceSz length of the nonce 541 \param authTag pointer to the buffer in which to store the 542 authentication tag 543 \param authTagSz length of the desired authentication tag 544 \param authIn pointer to the buffer containing the input 545 authentication vector 546 \param authInSz length of the input authentication vector 547 548 _Example_ 549 \code 550 Aes enc; 551 // initialize enc with wc_AesCcmSetKey 552 553 nonce[] = { initialize nonce }; 554 plain[] = { some plain text message }; 555 cipher[sizeof(plain)]; 556 557 authIn[] = { some 16 byte authentication input }; 558 tag[AES_BLOCK_SIZE]; // will store authentication code 559 560 wc_AesCcmEncrypt(&enc, cipher, plain, sizeof(plain), nonce, sizeof(nonce), 561 tag, sizeof(tag), authIn, sizeof(authIn)); 562 \endcode 563 564 \sa wc_AesCcmSetKey 565 \sa wc_AesCcmDecrypt 566 */ 567 WOLFSSL_API int wc_AesCcmEncrypt(Aes* aes, byte* out, 568 const byte* in, word32 inSz, 569 const byte* nonce, word32 nonceSz, 570 byte* authTag, word32 authTagSz, 571 const byte* authIn, word32 authInSz); 572 573 /*! 574 \ingroup AES 575 576 \brief This function decrypts the input cipher text, in, into 577 the output buffer, out, using CCM (Counter with CBC-MAC). It 578 subsequently calculates the authorization tag, authTag, from the 579 authIn input. If the authorization tag is invalid, it sets the 580 output buffer to zero and returns the error: AES_CCM_AUTH_E. 581 582 \return 0 On successfully decrypting the input message 583 \return AES_CCM_AUTH_E If the authentication tag does not match the 584 supplied authentication code vector, authTag. 585 586 \param aes pointer to the AES object used to encrypt data 587 \param out pointer to the output buffer in which to store the cipher text 588 \param in pointer to the input buffer holding the message to encrypt 589 \param sz length of the input cipher text to decrypt 590 \param nonce pointer to the buffer containing the nonce 591 (number only used once) 592 \param nonceSz length of the nonce 593 \param authTag pointer to the buffer in which to store the 594 authentication tag 595 \param authTagSz length of the desired authentication tag 596 \param authIn pointer to the buffer containing the input 597 authentication vector 598 \param authInSz length of the input authentication vector 599 600 _Example_ 601 \code 602 Aes dec; 603 // initialize dec with wc_AesCcmSetKey 604 605 nonce[] = { initialize nonce }; 606 cipher[] = { encrypted message }; 607 plain[sizeof(cipher)]; 608 609 authIn[] = { some 16 byte authentication input }; 610 tag[AES_BLOCK_SIZE] = { authentication tag received for verification }; 611 612 int return = wc_AesCcmDecrypt(&dec, plain, cipher, sizeof(cipher), 613 nonce, sizeof(nonce),tag, sizeof(tag), authIn, sizeof(authIn)); 614 if(return != 0) { 615 // decrypt error, invalid authentication code 616 } 617 \endcode 618 619 \sa wc_AesCcmSetKey 620 \sa wc_AesCcmEncrypt 621 */ 622 WOLFSSL_API int wc_AesCcmDecrypt(Aes* aes, byte* out, 623 const byte* in, word32 inSz, 624 const byte* nonce, word32 nonceSz, 625 const byte* authTag, word32 authTagSz, 626 const byte* authIn, word32 authInSz); 627 628 /*! 629 \ingroup AES 630 631 \brief This is to help with setting keys to correct encrypt or 632 decrypt type. It is up to user to call wc_AesXtsFree on aes key when done. 633 634 \return 0 Success 635 636 \param aes AES keys for encrypt/decrypt process 637 \param key buffer holding aes key | tweak key 638 \param len length of key buffer in bytes. Should be twice that of 639 key size. 640 i.e. 32 for a 16 byte key. 641 \param dir direction, either AES_ENCRYPTION or AES_DECRYPTION 642 \param heap heap hint to use for memory. Can be NULL 643 \param devId id to use with async crypto. Can be 0 644 645 _Example_ 646 \code 647 XtsAes aes; 648 649 if(wc_AesXtsSetKey(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, 0) != 0) 650 { 651 // Handle error 652 } 653 wc_AesXtsFree(&aes); 654 \endcode 655 656 \sa wc_AesXtsEncrypt 657 \sa wc_AesXtsDecrypt 658 \sa wc_AesXtsFree 659 */ 660 WOLFSSL_API int wc_AesXtsSetKey(XtsAes* aes, const byte* key, 661 word32 len, int dir, void* heap, int devId); 662 663 /*! 664 \ingroup AES 665 666 \brief Same process as wc_AesXtsEncrypt but uses a word64 type as the tweak 667 value instead of a byte array. This just converts the word64 to a 668 byte array and calls wc_AesXtsEncrypt. 669 670 \return 0 Success 671 672 \param aes AES keys to use for block encrypt/decrypt 673 \param out output buffer to hold cipher text 674 \param in input plain text buffer to encrypt 675 \param sz size of both out and in buffers 676 \param sector value to use for tweak 677 678 _Example_ 679 \code 680 XtsAes aes; 681 unsigned char plain[SIZE]; 682 unsigned char cipher[SIZE]; 683 word64 s = VALUE; 684 685 //set up keys with AES_ENCRYPTION as dir 686 687 if(wc_AesXtsEncryptSector(&aes, cipher, plain, SIZE, s) != 0) 688 { 689 // Handle error 690 } 691 wc_AesXtsFree(&aes); 692 \endcode 693 694 \sa wc_AesXtsEncrypt 695 \sa wc_AesXtsDecrypt 696 \sa wc_AesXtsSetKey 697 \sa wc_AesXtsFree 698 */ 699 WOLFSSL_API int wc_AesXtsEncryptSector(XtsAes* aes, byte* out, 700 const byte* in, word32 sz, word64 sector); 701 702 /*! 703 \ingroup AES 704 705 \brief Same process as wc_AesXtsDecrypt but uses a word64 type as the tweak 706 value instead of a byte array. This just converts the word64 to a 707 byte array. 708 709 \return 0 Success 710 711 \param aes AES keys to use for block encrypt/decrypt 712 \param out output buffer to hold plain text 713 \param in input cipher text buffer to decrypt 714 \param sz size of both out and in buffers 715 \param sector value to use for tweak 716 717 _Example_ 718 \code 719 XtsAes aes; 720 unsigned char plain[SIZE]; 721 unsigned char cipher[SIZE]; 722 word64 s = VALUE; 723 724 //set up aes key with AES_DECRYPTION as dir and tweak with AES_ENCRYPTION 725 726 if(wc_AesXtsDecryptSector(&aes, plain, cipher, SIZE, s) != 0) 727 { 728 // Handle error 729 } 730 wc_AesXtsFree(&aes); 731 \endcode 732 733 \sa wc_AesXtsEncrypt 734 \sa wc_AesXtsDecrypt 735 \sa wc_AesXtsSetKey 736 \sa wc_AesXtsFree 737 */ 738 WOLFSSL_API int wc_AesXtsDecryptSector(XtsAes* aes, byte* out, 739 const byte* in, word32 sz, word64 sector); 740 741 /*! 742 \ingroup AES 743 744 \brief AES with XTS mode. (XTS) XEX encryption with Tweak and cipher text 745 Stealing. 746 747 \return 0 Success 748 749 \param aes AES keys to use for block encrypt/decrypt 750 \param out output buffer to hold cipher text 751 \param in input plain text buffer to encrypt 752 \param sz size of both out and in buffers 753 \param i value to use for tweak 754 \param iSz size of i buffer, should always be AES_BLOCK_SIZE but having 755 this input adds a sanity check on how the user calls the 756 function. 757 758 _Example_ 759 \code 760 XtsAes aes; 761 unsigned char plain[SIZE]; 762 unsigned char cipher[SIZE]; 763 unsigned char i[AES_BLOCK_SIZE]; 764 765 //set up key with AES_ENCRYPTION as dir 766 767 if(wc_AesXtsEncrypt(&aes, cipher, plain, SIZE, i, sizeof(i)) != 0) 768 { 769 // Handle error 770 } 771 wc_AesXtsFree(&aes); 772 \endcode 773 774 \sa wc_AesXtsDecrypt 775 \sa wc_AesXtsSetKey 776 \sa wc_AesXtsFree 777 */ 778 WOLFSSL_API int wc_AesXtsEncrypt(XtsAes* aes, byte* out, 779 const byte* in, word32 sz, const byte* i, word32 iSz); 780 781 /*! 782 \ingroup AES 783 784 \brief Same process as encryption but Aes key is AES_DECRYPTION type. 785 786 \return 0 Success 787 788 \param aes AES keys to use for block encrypt/decrypt 789 \param out output buffer to hold plain text 790 \param in input cipher text buffer to decrypt 791 \param sz size of both out and in buffers 792 \param i value to use for tweak 793 \param iSz size of i buffer, should always be AES_BLOCK_SIZE but having 794 this input adds a sanity check on how the user calls the 795 function. 796 797 _Example_ 798 \code 799 XtsAes aes; 800 unsigned char plain[SIZE]; 801 unsigned char cipher[SIZE]; 802 unsigned char i[AES_BLOCK_SIZE]; 803 804 //set up key with AES_DECRYPTION as dir and tweak with AES_ENCRYPTION 805 806 if(wc_AesXtsDecrypt(&aes, plain, cipher, SIZE, i, sizeof(i)) != 0) 807 { 808 // Handle error 809 } 810 wc_AesXtsFree(&aes); 811 \endcode 812 813 \sa wc_AesXtsEncrypt 814 \sa wc_AesXtsSetKey 815 \sa wc_AesXtsFree 816 */ 817 WOLFSSL_API int wc_AesXtsDecrypt(XtsAes* aes, byte* out, 818 const byte* in, word32 sz, const byte* i, word32 iSz); 819 820 /*! 821 \ingroup AES 822 823 \brief This is to free up any resources used by the XtsAes structure 824 825 \return 0 Success 826 827 \param aes AES keys to free 828 829 _Example_ 830 \code 831 XtsAes aes; 832 833 if(wc_AesXtsSetKey(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, 0) != 0) 834 { 835 // Handle error 836 } 837 wc_AesXtsFree(&aes); 838 \endcode 839 840 \sa wc_AesXtsEncrypt 841 \sa wc_AesXtsDecrypt 842 \sa wc_AesXtsSetKey 843 */ 844 WOLFSSL_API int wc_AesXtsFree(XtsAes* aes); 845 846 847 /*! 848 \ingroup AES 849 \brief Initialize Aes structure. Sets heap hint to be used and ID for use 850 with async hardware 851 \return 0 Success 852 853 \param aes aes structure in to initialize 854 \param heap heap hint to use for malloc / free if needed 855 \param devId ID to use with async hardware 856 857 _Example_ 858 \code 859 Aes enc; 860 void* hint = NULL; 861 int devId = INVALID_DEVID; //if not using async INVALID_DEVID is default 862 863 //heap hint could be set here if used 864 865 wc_AesInit(&aes, hint, devId); 866 \endcode 867 868 \sa wc_AesSetKey 869 \sa wc_AesSetIV 870 */ 871 WOLFSSL_API int wc_AesInit(Aes*, void*, int); 872 873