luna - wolfssl/doc/dox_comments/header

   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. Direction for some modes (CFB and CTR) is
  15    always AES_ENCRYPTION.
  16
  17    _Example_
  18    \code
  19    Aes enc;
  20    int ret = 0;
  21    byte key[] = { some 16, 24 or 32 byte key };
  22    byte iv[]  = { some 16 byte iv };
  23    if (ret = wc_AesInit(&enc, HEAP_HINT, INVALID_DEVID) != 0) {
  24        // failed to initialize aes key
  25    }
  26    if (ret = wc_AesSetKey(&enc, key, AES_BLOCK_SIZE, iv,
  27    AES_ENCRYPTION) != 0) {
  28	// failed to set aes key
  29    }
  30    \endcode
  31
  32    \sa wc_AesSetKeyDirect
  33    \sa wc_AesSetIV
  34*/
  35int  wc_AesSetKey(Aes* aes, const byte* key, word32 len,
  36                              const byte* iv, int dir);
  37
  38/*!
  39    \ingroup AES
  40    \brief This function sets the initialization vector for a
  41    particular AES object. The AES object should be initialized before
  42    calling this function.
  43
  44    \return 0 On successfully setting initialization vector.
  45    \return BAD_FUNC_ARG Returned if AES pointer is NULL.
  46
  47    \param aes pointer to the AES structure on which to set the
  48    initialization vector
  49    \param iv initialization vector used to initialize the AES structure.
  50    If the value is NULL, the default action initializes the iv to 0.
  51
  52    _Example_
  53    \code
  54    Aes enc;
  55    // set enc key
  56    byte iv[]  = { some 16 byte iv };
  57    if (ret = wc_AesSetIV(&enc, iv) != 0) {
  58	// failed to set aes iv
  59    }
  60    \endcode
  61
  62    \sa wc_AesSetKeyDirect
  63    \sa wc_AesSetKey
  64*/
  65int  wc_AesSetIV(Aes* aes, const byte* iv);
  66
  67/*!
  68    \ingroup AES
  69    \brief Encrypts a plaintext message from the input buffer in, and places
  70    the resulting cipher text in the output buffer out using cipher block
  71    chaining with AES. This function requires that the AES object has been
  72    initialized by calling AesSetKey before a message is able to be encrypted.
  73    This function assumes that the input message is AES block length aligned,
  74    and expects the input length to be a multiple of the block length, which
  75    will optionally be checked and enforced if WOLFSSL_AES_CBC_LENGTH_CHECKS
  76    is defined in the build configuration.  In order to assure block-multiple
  77    input, PKCS#7 style padding should be added beforehand. This differs from
  78    the OpenSSL AES-CBC methods which add the padding for you. To make the
  79    wolfSSL and corresponding OpenSSL functions interoperate, one should specify
  80    the -nopad option in the OpenSSL command line function so that it behaves
  81    like the wolfSSL AesCbcEncrypt method and does not add extra padding
  82    during encryption.
  83
  84    \return 0 On successfully encrypting message.
  85    \return BAD_ALIGN_E: may be returned on block align error
  86    \return BAD_LENGTH_E will be returned if the input length isn't a
  87    multiple of the AES block length, when the library is built with
  88    WOLFSSL_AES_CBC_LENGTH_CHECKS.
  89
  90    \param aes pointer to the AES object used to encrypt data
  91    \param out pointer to the output buffer in which to store the ciphertext
  92    of the encrypted message
  93    \param in pointer to the input buffer containing message to be encrypted
  94    \param sz size of input message
  95
  96    _Example_
  97    \code
  98    Aes enc;
  99    int ret = 0;
 100    // initialize enc with wc_AesInit and wc_AesSetKey, using direction
 101    // AES_ENCRYPTION
 102    byte msg[AES_BLOCK_SIZE * n]; // multiple of 16 bytes
 103    // fill msg with data
 104    byte cipher[AES_BLOCK_SIZE * n]; // Some multiple of 16 bytes
 105    if ((ret = wc_AesCbcEncrypt(&enc, cipher, message, sizeof(msg))) != 0 ) {
 106	// block align error
 107    }
 108    \endcode
 109
 110    \sa wc_AesInit
 111    \sa wc_AesSetKey
 112    \sa wc_AesSetIV
 113    \sa wc_AesCbcDecrypt
 114*/
 115int  wc_AesCbcEncrypt(Aes* aes, byte* out,
 116                                  const byte* in, word32 sz);
 117
 118/*!
 119    \ingroup AES
 120    \brief Decrypts a cipher from the input buffer in, and places the
 121    resulting plain text in the output buffer out using cipher block chaining
 122    with AES. This function requires that the AES structure has been
 123    initialized by calling AesSetKey before a message is able to be decrypted.
 124    This function assumes that the original message was AES block length
 125    aligned, and expects the input length to be a multiple of the block length,
 126    which will optionally be checked and enforced if
 127    WOLFSSL_AES_CBC_LENGTH_CHECKS is defined in the build configuration.
 128    This differs from the OpenSSL AES-CBC methods, which add PKCS#7 padding
 129    automatically, and so do not require block-multiple input. To make the
 130    wolfSSL function and equivalent OpenSSL functions interoperate, one
 131    should specify the -nopad option in the OpenSSL command line function
 132    so that it behaves like the wolfSSL AesCbcEncrypt method and does not
 133    create errors during decryption.
 134
 135    \return 0 On successfully decrypting message.
 136    \return BAD_ALIGN_E may be returned on block align error.
 137    \return BAD_LENGTH_E will be returned if the input length isn't a
 138    multiple of the AES block length, when the library is built with
 139    WOLFSSL_AES_CBC_LENGTH_CHECKS.
 140
 141    \param aes pointer to the AES object used to decrypt data.
 142    \param out pointer to the output buffer in which to store the plain text
 143    of the decrypted message.
 144    size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
 145    \param in pointer to the input buffer containing cipher text to be
 146    decrypted.
 147    size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
 148    \param sz size of input message.
 149
 150    _Example_
 151    \code
 152    Aes dec;
 153    int ret = 0;
 154    // initialize dec with wc_AesInit and wc_AesSetKey, using direction
 155    // AES_DECRYPTION
 156    byte cipher[AES_BLOCK_SIZE * n]; // some multiple of 16 bytes
 157    // fill cipher with cipher text
 158    byte plain [AES_BLOCK_SIZE * n];
 159    if ((ret = wc_AesCbcDecrypt(&dec, plain, cipher, sizeof(cipher))) != 0 ) {
 160	// block align error
 161    }
 162    \endcode
 163
 164    \sa wc_AesInit
 165    \sa wc_AesSetKey
 166    \sa wc_AesCbcEncrypt
 167*/
 168int  wc_AesCbcDecrypt(Aes* aes, byte* out,
 169                                  const byte* in, word32 sz);
 170
 171/*!
 172    \ingroup AES
 173    \brief Encrypts/Decrypts a message from the input buffer in, and places
 174    the resulting cipher text in the output buffer out using CTR mode with
 175    AES. This function is only enabled if WOLFSSL_AES_COUNTER is enabled at
 176    compile time. The AES structure should be initialized through AesSetKey
 177    before calling this function. Note that this function is used for both
 178    decryption and encryption. _NOTE:_ Regarding using same API for encryption
 179    and decryption. User should differentiate between Aes structures
 180    for encrypt/decrypt.
 181
 182    \return int integer values corresponding to wolfSSL error or success
 183    status
 184
 185    \param aes pointer to the AES object used to decrypt data
 186    \param out pointer to the output buffer in which to store the cipher
 187    text of the encrypted message
 188    size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
 189    \param in pointer to the input buffer containing plain text to be encrypted
 190    size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
 191    \param sz size of the input plain text
 192
 193    _Example_
 194    \code
 195    Aes enc;
 196    Aes dec;
 197    // initialize enc and dec with wc_AesInit and wc_AesSetKeyDirect, using
 198    // direction AES_ENCRYPTION since the underlying API only calls Encrypt
 199    // and by default calling encrypt on a cipher results in a decryption of
 200    // the cipher
 201
 202    byte msg[AES_BLOCK_SIZE * n]; //n being a positive integer making msg
 203    some multiple of 16 bytes
 204    // fill plain with message text
 205    byte cipher[AES_BLOCK_SIZE * n];
 206    byte decrypted[AES_BLOCK_SIZE * n];
 207    wc_AesCtrEncrypt(&enc, cipher, msg, sizeof(msg)); // encrypt plain
 208    wc_AesCtrEncrypt(&dec, decrypted, cipher, sizeof(cipher));
 209    // decrypt cipher text
 210    \endcode
 211
 212    \sa wc_AesSetKey
 213*/
 214int wc_AesCtrEncrypt(Aes* aes, byte* out,
 215                                   const byte* in, word32 sz);
 216
 217/*!
 218    \ingroup AES
 219    \brief This function is a one-block encrypt of the input block, in, into
 220    the output block, out. It uses the key of the provided AES structure, which
 221    should be initialized with wc_AesSetKey before calling this function.
 222    wc_AesSetKey should have been called with the iv set to NULL. This is only
 223    enabled if the configure option WOLFSSL_AES_DIRECT is enabled. __Warning:__
 224    In nearly all use cases ECB mode is considered to be less secure. Please
 225    avoid using ECB API’s directly whenever possible.
 226
 227    \return int integer values corresponding to wolfSSL error or success
 228    status
 229
 230    \param aes pointer to the AES object used to encrypt data
 231    \param out pointer to the output buffer in which to store the cipher
 232    text of the encrypted message
 233    \param in pointer to the input buffer containing plain text to be encrypted
 234
 235    _Example_
 236    \code
 237    Aes enc;
 238    // initialize enc with wc_AesInit and wc_AesSetKey, using direction
 239    // AES_ENCRYPTION
 240    byte msg [AES_BLOCK_SIZE]; // 16 bytes
 241    // initialize msg with plain text to encrypt
 242    byte cipher[AES_BLOCK_SIZE];
 243    wc_AesEncryptDirect(&enc, cipher, msg);
 244    \endcode
 245
 246    \sa wc_AesDecryptDirect
 247    \sa wc_AesSetKeyDirect
 248*/
 249int wc_AesEncryptDirect(Aes* aes, byte* out, const byte* in);
 250
 251/*!
 252    \ingroup AES
 253    \brief This function is a one-block decrypt of the input block, in, into
 254    the output block, out. It uses the key of the provided AES structure, which
 255    should be initialized with wc_AesSetKey before calling this function.
 256    wc_AesSetKey should have been called with the iv set to NULL. This is only
 257    enabled if the configure option WOLFSSL_AES_DIRECT is enabled. __Warning:__
 258    In nearly all use cases ECB mode is considered to be less secure. Please
 259    avoid using ECB API’s directly whenever possible.
 260
 261    \return int integer values corresponding to wolfSSL error or success
 262    status
 263
 264    \param aes pointer to the AES object used to encrypt data
 265    \param out pointer to the output buffer in which to store the plain
 266    text of the decrypted cipher text
 267    \param in pointer to the input buffer containing cipher text to be
 268    decrypted
 269
 270    _Example_
 271    \code
 272    Aes dec;
 273    // initialize enc with wc_AesInit and wc_AesSetKey, using direction
 274    // AES_DECRYPTION
 275    byte cipher [AES_BLOCK_SIZE]; // 16 bytes
 276    // initialize cipher with cipher text to decrypt
 277    byte msg[AES_BLOCK_SIZE];
 278    wc_AesDecryptDirect(&dec, msg, cipher);
 279    \endcode
 280
 281    \sa wc_AesEncryptDirect
 282    \sa wc_AesSetKeyDirect
 283 */
 284int wc_AesDecryptDirect(Aes* aes, byte* out, const byte* in);
 285
 286/*!
 287    \ingroup AES
 288    \brief This function is used to set the AES keys for CTR mode with AES.
 289    It initializes an AES object with the given key, iv
 290    (initialization vector), and encryption dir (direction). It is only
 291    enabled if the configure option WOLFSSL_AES_DIRECT is enabled.
 292    Currently wc_AesSetKeyDirect uses wc_AesSetKey internally. __Warning:__ In
 293    nearly all use cases ECB mode is considered to be less secure. Please avoid
 294    using ECB API’s directly whenever possible
 295
 296    \return 0 On successfully setting the key.
 297    \return BAD_FUNC_ARG Returned if the given key is an invalid length.
 298
 299    \param aes pointer to the AES object used to encrypt data
 300    \param key 16, 24, or 32 byte secret key for encryption and decryption
 301    \param len length of the key passed in
 302    \param iv initialization vector used to initialize the key
 303    \param dir Cipher direction. Set AES_ENCRYPTION to encrypt,  or
 304    AES_DECRYPTION to decrypt. (See enum in wolfssl/wolfcrypt/aes.h)
 305    (NOTE: If using wc_AesSetKeyDirect with Aes Counter mode (Stream cipher)
 306    only use AES_ENCRYPTION for both encrypting and decrypting)
 307
 308    _Example_
 309    \code
 310    Aes enc;
 311    int ret = 0;
 312    byte key[] = { some 16, 24, or 32 byte key };
 313    byte iv[]  = { some 16 byte iv };
 314
 315    if (ret = wc_AesInit(&enc, HEAP_HINT, INVALID_DEVID) != 0) {
 316        // failed to initialize aes key
 317    }
 318    if (ret = wc_AesSetKeyDirect(&enc, key, sizeof(key), iv,
 319    AES_ENCRYPTION) != 0) {
 320	// failed to set aes key
 321    }
 322    \endcode
 323
 324    \sa wc_AesEncryptDirect
 325    \sa wc_AesDecryptDirect
 326    \sa wc_AesSetKey
 327*/
 328int  wc_AesSetKeyDirect(Aes* aes, const byte* key, word32 len,
 329                                const byte* iv, int dir);
 330
 331/*!
 332    \ingroup AES
 333    \brief This function is used to set the key for AES GCM
 334    (Galois/Counter Mode). It initializes an AES object with the
 335    given key. It is only enabled if the configure option
 336    HAVE_AESGCM is enabled at compile time.
 337
 338    \return 0 On successfully setting the key.
 339    \return BAD_FUNC_ARG Returned if the given key is an invalid length.
 340
 341    \param aes pointer to the AES object used to encrypt data
 342    \param key 16, 24, or 32 byte secret key for encryption and decryption
 343    \param len length of the key passed in
 344
 345    _Example_
 346    \code
 347    Aes enc;
 348    int ret = 0;
 349    byte key[] = { some 16, 24,32 byte key };
 350    if (ret = wc_AesInit(&enc, HEAP_HINT, INVALID_DEVID) != 0) {
 351        // failed to initialize aes key
 352    }
 353    if (ret = wc_AesGcmSetKey(&enc, key, sizeof(key)) != 0) {
 354	// failed to set aes key
 355    }
 356    \endcode
 357
 358    \sa wc_AesGcmEncrypt
 359    \sa wc_AesGcmDecrypt
 360*/
 361int  wc_AesGcmSetKey(Aes* aes, const byte* key, word32 len);
 362
 363/*!
 364    \ingroup AES
 365    \brief This function encrypts the input message, held in the buffer in,
 366    and stores the resulting cipher text in the output buffer out. It
 367    requires a new iv (initialization vector) for each call to encrypt.
 368    It also encodes the input authentication vector, authIn, into the
 369    authentication tag, authTag.
 370
 371    \return 0 On successfully encrypting the input message
 372
 373    \param aes - pointer to the AES object used to encrypt data
 374    \param out pointer to the output buffer in which to store the cipher text
 375    size must match in's size (sz)
 376    \param in pointer to the input buffer holding the message to encrypt
 377    size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
 378    \param sz length of the input message to encrypt
 379    \param iv pointer to the buffer containing the initialization vector
 380    \param ivSz length of the initialization vector
 381    \param authTag pointer to the buffer in which to store the
 382    authentication tag
 383    \param authTagSz length of the desired authentication tag
 384    \param authIn pointer to the buffer containing the input
 385    authentication vector
 386    \param authInSz length of the input authentication vector
 387
 388    _Example_
 389    \code
 390    Aes enc;
 391    // initialize Aes structure by calling wc_AesInit() and wc_AesGcmSetKey
 392
 393    byte plain[AES_BLOCK_LENGTH * n]; //n being a positive integer
 394    making plain some multiple of 16 bytes
 395    // initialize plain with msg to encrypt
 396    byte cipher[sizeof(plain)];
 397    byte iv[] = // some 16 byte iv
 398    byte authTag[AUTH_TAG_LENGTH];
 399    byte authIn[] = // Authentication Vector
 400
 401    wc_AesGcmEncrypt(&enc, cipher, plain, sizeof(cipher), iv, sizeof(iv),
 402			authTag, sizeof(authTag), authIn, sizeof(authIn));
 403    \endcode
 404
 405    \sa wc_AesGcmSetKey
 406    \sa wc_AesGcmDecrypt
 407*/
 408int  wc_AesGcmEncrypt(Aes* aes, byte* out,
 409                                   const byte* in, word32 sz,
 410                                   const byte* iv, word32 ivSz,
 411                                   byte* authTag, word32 authTagSz,
 412                                   const byte* authIn, word32 authInSz);
 413
 414/*!
 415    \ingroup AES
 416    \brief This function decrypts the input cipher text, held in the buffer
 417    in, and stores the resulting message text in the output buffer out.
 418    It also checks the input authentication vector, authIn, against the
 419    supplied authentication tag, authTag.  If a nonzero error code is returned,
 420    the output data is undefined.  However, callers must unconditionally zeroize
 421    the output buffer to guard against leakage of cleartext data.
 422
 423    \return 0 On successfully decrypting and authenticating the input message
 424    \return AES_GCM_AUTH_E If the authentication tag does not match the
 425    supplied authentication code vector, authTag.
 426
 427    \param aes pointer to the AES object used to encrypt data
 428    \param out pointer to the output buffer in which to store the message text
 429    size must match in's size (sz)
 430    \param in pointer to the input buffer holding the cipher text to decrypt
 431    size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
 432    \param sz length of the cipher text to decrypt
 433    \param iv pointer to the buffer containing the initialization vector
 434    \param ivSz length of the initialization vector
 435    \param authTag pointer to the buffer containing the authentication tag
 436    \param authTagSz length of the desired authentication tag
 437    \param authIn pointer to the buffer containing the input
 438    authentication vector
 439    \param authInSz length of the input authentication vector
 440
 441    _Example_
 442    \code
 443    Aes enc; //can use the same struct as was passed to wc_AesGcmEncrypt
 444    // initialize aes structure by calling wc_AesInit and wc_AesGcmSetKey
 445    // if not already done
 446
 447    byte cipher[AES_BLOCK_LENGTH * n]; //n being a positive integer
 448    making cipher some multiple of 16 bytes
 449    // initialize cipher with cipher text to decrypt
 450    byte output[sizeof(cipher)];
 451    byte iv[] = // some 16 byte iv
 452    byte authTag[AUTH_TAG_LENGTH];
 453    byte authIn[] = // Authentication Vector
 454
 455    wc_AesGcmDecrypt(&enc, output, cipher, sizeof(cipher), iv, sizeof(iv),
 456			authTag, sizeof(authTag), authIn, sizeof(authIn));
 457    \endcode
 458
 459    \sa wc_AesGcmSetKey
 460    \sa wc_AesGcmEncrypt
 461*/
 462int  wc_AesGcmDecrypt(Aes* aes, byte* out,
 463                                   const byte* in, word32 sz,
 464                                   const byte* iv, word32 ivSz,
 465                                   const byte* authTag, word32 authTagSz,
 466                                   const byte* authIn, word32 authInSz);
 467
 468/*!
 469    \ingroup AES
 470    \brief This function initializes and sets the key for a GMAC object
 471    to be used for Galois Message Authentication.
 472
 473    \return 0 On successfully setting the key
 474    \return BAD_FUNC_ARG Returned if key length is invalid.
 475
 476    \param gmac pointer to the gmac object used for authentication
 477    \param key 16, 24, or 32 byte secret key for authentication
 478    \param len length of the key
 479
 480    _Example_
 481    \code
 482    Gmac gmac;
 483    key[] = { some 16, 24, or 32 byte length key };
 484    wc_AesInit(gmac.aes, HEAP_HINT, INVALID_DEVID); // Make sure devId updated
 485    wc_GmacSetKey(&gmac, key, sizeof(key));
 486    \endcode
 487
 488    \sa wc_GmacUpdate
 489    \sa wc_AesInit
 490*/
 491int wc_GmacSetKey(Gmac* gmac, const byte* key, word32 len);
 492
 493/*!
 494    \ingroup AES
 495    \brief This function generates the Gmac hash of the authIn input and
 496    stores the result in the authTag buffer. After running wc_GmacUpdate,
 497    one should compare the generated authTag to a known authentication tag
 498    to verify the authenticity of a message.
 499
 500    \return 0 On successfully computing the Gmac hash.
 501
 502    \param gmac pointer to the gmac object used for authentication
 503    \param iv initialization vector used for the hash
 504    \param ivSz size of the initialization vector used
 505    \param authIn pointer to the buffer containing the authentication
 506    vector to verify
 507    \param authInSz size of the authentication vector
 508    \param authTag pointer to the output buffer in which to store the Gmac hash
 509    \param authTagSz the size of the output buffer used to store the Gmac hash
 510
 511    _Example_
 512    \code
 513    Gmac gmac;
 514    key[] = { some 16, 24, or 32 byte length key };
 515    iv[] = { some 16 byte length iv };
 516
 517    wc_AesInit(gmac.aes, HEAP_HINT, INVALID_DEVID); // Make sure devId updated
 518    wc_GmacSetKey(&gmac, key, sizeof(key));
 519    authIn[] = { some 16 byte authentication input };
 520    tag[AES_BLOCK_SIZE]; // will store authentication code
 521
 522    wc_GmacUpdate(&gmac, iv, sizeof(iv), authIn, sizeof(authIn), tag,
 523    sizeof(tag));
 524    \endcode
 525
 526    \sa wc_GmacSetKey
 527    \sa wc_AesInit
 528*/
 529int wc_GmacUpdate(Gmac* gmac, const byte* iv, word32 ivSz,
 530                               const byte* authIn, word32 authInSz,
 531                               byte* authTag, word32 authTagSz);
 532
 533/*!
 534    \ingroup AES
 535    \brief This function sets the key for an AES object using CCM
 536    (Counter with CBC-MAC). It takes a pointer to an AES structure and
 537    initializes it with supplied key.
 538
 539    \return none
 540
 541    \param aes aes structure in which to store the supplied key
 542    \param key 16, 24, or 32 byte secret key for encryption and decryption
 543    \param keySz size of the supplied key
 544
 545    _Example_
 546    \code
 547    Aes enc;
 548    key[] = { some 16, 24, or 32 byte length key };
 549
 550    wc_AesInit(&enc, HEAP_HINT, INVALID_DEVID); // Make sure devId updated
 551    wc_AesCcmSetKey(&enc, key, sizeof(key));
 552    \endcode
 553
 554    \sa wc_AesCcmEncrypt
 555    \sa wc_AesCcmDecrypt
 556*/
 557int  wc_AesCcmSetKey(Aes* aes, const byte* key, word32 keySz);
 558
 559/*!
 560    \ingroup AES
 561
 562    \brief This function encrypts the input message, in, into the output
 563    buffer, out, using CCM (Counter with CBC-MAC). It subsequently
 564    calculates and stores the authorization tag, authTag, from the
 565    authIn input.
 566
 567    \return none
 568
 569    \param aes pointer to the AES object used to encrypt data
 570    \param out pointer to the output buffer in which to store the cipher text
 571    \param in pointer to the input buffer holding the message to encrypt
 572    \param sz length of the input message to encrypt
 573    \param nonce pointer to the buffer containing the nonce
 574    (number only used once)
 575    \param nonceSz length of the nonce
 576    \param authTag pointer to the buffer in which to store the
 577    authentication tag
 578    \param authTagSz length of the desired authentication tag
 579    \param authIn pointer to the buffer containing the input
 580    authentication vector
 581    \param authInSz length of the input authentication vector
 582
 583    _Example_
 584    \code
 585    Aes enc;
 586    // initialize enc with wc_AesInit and wc_AesCcmSetKey
 587
 588    nonce[] = { initialize nonce };
 589    plain[] = { some plain text message };
 590    cipher[sizeof(plain)];
 591
 592    authIn[] = { some 16 byte authentication input };
 593    tag[AES_BLOCK_SIZE]; // will store authentication code
 594
 595    wc_AesCcmEncrypt(&enc, cipher, plain, sizeof(plain), nonce, sizeof(nonce),
 596			tag, sizeof(tag), authIn, sizeof(authIn));
 597    \endcode
 598
 599    \sa wc_AesCcmSetKey
 600    \sa wc_AesCcmDecrypt
 601*/
 602int  wc_AesCcmEncrypt(Aes* aes, byte* out,
 603                                   const byte* in, word32 inSz,
 604                                   const byte* nonce, word32 nonceSz,
 605                                   byte* authTag, word32 authTagSz,
 606                                   const byte* authIn, word32 authInSz);
 607
 608/*!
 609    \ingroup AES
 610
 611    \brief This function decrypts the input cipher text, in, into
 612    the output buffer, out, using CCM (Counter with CBC-MAC). It
 613    subsequently calculates the authorization tag, authTag, from the
 614    authIn input.  If a nonzero error code is returned, the output data is
 615    undefined.  However, callers must unconditionally zeroize the output buffer
 616    to guard against leakage of cleartext data.
 617
 618    \return 0 On successfully decrypting the input message
 619    \return AES_CCM_AUTH_E If the authentication tag does not match the
 620    supplied authentication code vector, authTag.
 621
 622    \param aes pointer to the AES object used to encrypt data
 623    \param out pointer to the output buffer in which to store the cipher text
 624    \param in pointer to the input buffer holding the message to encrypt
 625    \param sz length of the input cipher text to decrypt
 626    \param nonce pointer to the buffer containing the nonce
 627    (number only used once)
 628    \param nonceSz length of the nonce
 629    \param authTag pointer to the buffer in which to store the
 630    authentication tag
 631    \param authTagSz length of the desired authentication tag
 632    \param authIn pointer to the buffer containing the input
 633    authentication vector
 634    \param authInSz length of the input authentication vector
 635
 636    _Example_
 637    \code
 638    Aes dec;
 639    // initialize dec with wc_AesInit and wc_AesCcmSetKey
 640
 641    nonce[] = { initialize nonce };
 642    cipher[] = { encrypted message };
 643    plain[sizeof(cipher)];
 644
 645    authIn[] = { some 16 byte authentication input };
 646    tag[AES_BLOCK_SIZE] = { authentication tag received for verification };
 647
 648    int return = wc_AesCcmDecrypt(&dec, plain, cipher, sizeof(cipher),
 649    nonce, sizeof(nonce),tag, sizeof(tag), authIn, sizeof(authIn));
 650    if(return != 0) {
 651	// decrypt error, invalid authentication code
 652    }
 653    \endcode
 654
 655    \sa wc_AesCcmSetKey
 656    \sa wc_AesCcmEncrypt
 657*/
 658int  wc_AesCcmDecrypt(Aes* aes, byte* out,
 659                                   const byte* in, word32 inSz,
 660                                   const byte* nonce, word32 nonceSz,
 661                                   const byte* authTag, word32 authTagSz,
 662                                   const byte* authIn, word32 authInSz);
 663
 664/*!
 665    \ingroup AES
 666
 667    \brief This is to initialize an AES-XTS context. It is up to user to call
 668    wc_AesXtsFree on aes key when done.
 669
 670    \return 0 Success
 671
 672    \param aes   AES keys for encrypt/decrypt process
 673    \param heap  heap hint to use for memory. Can be NULL
 674    \param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
 675
 676    _Example_
 677    \code
 678    XtsAes aes;
 679
 680    if(wc_AesXtsInit(&aes, NULL, INVALID_DEVID) != 0)
 681    {
 682        // Handle error
 683    }
 684    if(wc_AesXtsSetKeyNoInit(&aes, key, sizeof(key), AES_ENCRYPTION) != 0)
 685    {
 686        // Handle error
 687    }
 688    wc_AesXtsFree(&aes);
 689    \endcode
 690
 691    \sa wc_AesXtsSetKey
 692    \sa wc_AesXtsSetKeyNoInit
 693    \sa wc_AesXtsEncrypt
 694    \sa wc_AesXtsDecrypt
 695    \sa wc_AesXtsFree
 696*/
 697int wc_AesXtsInit(XtsAes* aes, void* heap, int devId);
 698
 699
 700/*!
 701    \ingroup AES
 702
 703    \brief This is to help with setting keys to correct encrypt or decrypt type,
 704    after first calling wc_AesXtsInit(). It is up to user to call wc_AesXtsFree
 705    on aes key when done.
 706
 707    \return 0 Success
 708
 709    \param aes   AES keys for encrypt/decrypt process
 710    \param key   buffer holding aes key | tweak key
 711    \param len   length of key buffer in bytes. Should be twice that of
 712    key size.
 713                 i.e. 32 for a 16 byte key.
 714    \param dir   direction, either AES_ENCRYPTION or AES_DECRYPTION
 715
 716    _Example_
 717    \code
 718    XtsAes aes;
 719
 720    if(wc_AesXtsInit(&aes, NULL, 0) != 0)
 721    {
 722        // Handle error
 723    }
 724    if(wc_AesXtsSetKeyNoInit(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, 0)
 725       != 0)
 726    {
 727        // Handle error
 728    }
 729    wc_AesXtsFree(&aes);
 730    \endcode
 731
 732    \sa wc_AesXtsEncrypt
 733    \sa wc_AesXtsDecrypt
 734    \sa wc_AesXtsFree
 735*/
 736int wc_AesXtsSetKeyNoInit(XtsAes* aes, const byte* key,
 737         word32 len, int dir);
 738
 739
 740/*!
 741    \ingroup AES
 742
 743    \brief This is to help with setting keys to correct encrypt or
 744    decrypt type. It is up to user to call wc_AesXtsFree on aes key when done.
 745
 746    \return 0 Success
 747
 748    \param aes   AES keys for encrypt/decrypt process
 749    \param key   buffer holding aes key | tweak key
 750    \param len   length of key buffer in bytes. Should be twice that of
 751    key size.
 752                 i.e. 32 for a 16 byte key.
 753    \param dir   direction, either AES_ENCRYPTION or AES_DECRYPTION
 754    \param heap  heap hint to use for memory. Can be NULL
 755    \param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
 756
 757    _Example_
 758    \code
 759    XtsAes aes;
 760
 761    if(wc_AesXtsSetKey(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, INVALID_DEVID) != 0)
 762    {
 763        // Handle error
 764    }
 765    wc_AesXtsFree(&aes);
 766    \endcode
 767
 768    \sa wc_AesXtsInit
 769    \sa wc_AesXtsSetKeyNoInit
 770    \sa wc_AesXtsEncrypt
 771    \sa wc_AesXtsDecrypt
 772    \sa wc_AesXtsFree
 773*/
 774int wc_AesXtsSetKey(XtsAes* aes, const byte* key,
 775         word32 len, int dir, void* heap, int devId);
 776
 777/*!
 778    \ingroup AES
 779
 780    \brief Same process as wc_AesXtsEncrypt but uses a word64 type as the tweak
 781           value instead of a byte array. This just converts the word64 to a
 782           byte array and calls wc_AesXtsEncrypt.
 783
 784    \return 0 Success
 785
 786    \param aes    AES keys to use for block encrypt/decrypt
 787    \param out    output buffer to hold cipher text
 788    \param in     input plain text buffer to encrypt
 789    \param sz     size of both out and in buffers
 790    \param sector value to use for tweak
 791
 792    _Example_
 793    \code
 794    XtsAes aes;
 795    unsigned char plain[SIZE];
 796    unsigned char cipher[SIZE];
 797    word64 s = VALUE;
 798
 799    //set up keys with AES_ENCRYPTION as dir
 800
 801    if(wc_AesXtsEncryptSector(&aes, cipher, plain, SIZE, s) != 0)
 802    {
 803        // Handle error
 804    }
 805    wc_AesXtsFree(&aes);
 806    \endcode
 807
 808    \sa wc_AesXtsEncrypt
 809    \sa wc_AesXtsDecrypt
 810    \sa wc_AesXtsInit
 811    \sa wc_AesXtsSetKeyNoInit
 812    \sa wc_AesXtsSetKey
 813    \sa wc_AesXtsFree
 814*/
 815int wc_AesXtsEncryptSector(XtsAes* aes, byte* out,
 816         const byte* in, word32 sz, word64 sector);
 817
 818/*!
 819    \ingroup AES
 820
 821    \brief Same process as wc_AesXtsDecrypt but uses a word64 type as the tweak
 822           value instead of a byte array. This just converts the word64 to a
 823           byte array.
 824
 825    \return 0 Success
 826
 827    \param aes    AES keys to use for block encrypt/decrypt
 828    \param out    output buffer to hold plain text
 829    \param in     input cipher text buffer to decrypt
 830    \param sz     size of both out and in buffers
 831    \param sector value to use for tweak
 832
 833    _Example_
 834    \code
 835    XtsAes aes;
 836    unsigned char plain[SIZE];
 837    unsigned char cipher[SIZE];
 838    word64 s = VALUE;
 839
 840    //set up aes key with AES_DECRYPTION as dir and tweak with AES_ENCRYPTION
 841
 842    if(wc_AesXtsDecryptSector(&aes, plain, cipher, SIZE, s) != 0)
 843    {
 844        // Handle error
 845    }
 846    wc_AesXtsFree(&aes);
 847    \endcode
 848
 849    \sa wc_AesXtsEncrypt
 850    \sa wc_AesXtsDecrypt
 851    \sa wc_AesXtsInit
 852    \sa wc_AesXtsSetKeyNoInit
 853    \sa wc_AesXtsSetKey
 854    \sa wc_AesXtsFree
 855*/
 856int wc_AesXtsDecryptSector(XtsAes* aes, byte* out,
 857         const byte* in, word32 sz, word64 sector);
 858
 859/*!
 860    \ingroup AES
 861
 862    \brief AES with XTS mode. (XTS) XEX encryption with Tweak and cipher text
 863           Stealing.
 864
 865    \return 0 Success
 866
 867    \param aes   AES keys to use for block encrypt/decrypt
 868    \param out   output buffer to hold cipher text
 869    \param in    input plain text buffer to encrypt
 870    \param sz    size of both out and in buffers
 871    \param i     value to use for tweak
 872    \param iSz   size of i buffer, should always be AES_BLOCK_SIZE but having
 873                 this input adds a sanity check on how the user calls the
 874                 function.
 875
 876    _Example_
 877    \code
 878    XtsAes aes;
 879    unsigned char plain[SIZE];
 880    unsigned char cipher[SIZE];
 881    unsigned char i[AES_BLOCK_SIZE];
 882
 883    //set up key with AES_ENCRYPTION as dir
 884
 885    if(wc_AesXtsEncrypt(&aes, cipher, plain, SIZE, i, sizeof(i)) != 0)
 886    {
 887        // Handle error
 888    }
 889    wc_AesXtsFree(&aes);
 890    \endcode
 891
 892    \sa wc_AesXtsDecrypt
 893    \sa wc_AesXtsInit
 894    \sa wc_AesXtsSetKeyNoInit
 895    \sa wc_AesXtsSetKey
 896    \sa wc_AesXtsFree
 897*/
 898int wc_AesXtsEncrypt(XtsAes* aes, byte* out,
 899         const byte* in, word32 sz, const byte* i, word32 iSz);
 900
 901/*!
 902    \ingroup AES
 903
 904    \brief Same process as encryption but Aes key is AES_DECRYPTION type.
 905
 906    \return 0 Success
 907
 908    \param aes   AES keys to use for block encrypt/decrypt
 909    \param out   output buffer to hold plain text
 910    \param in    input cipher text buffer to decrypt
 911    \param sz    size of both out and in buffers
 912    \param i     value to use for tweak
 913    \param iSz   size of i buffer, should always be AES_BLOCK_SIZE but having
 914                 this input adds a sanity check on how the user calls the
 915                 function.
 916
 917    _Example_
 918    \code
 919    XtsAes aes;
 920    unsigned char plain[SIZE];
 921    unsigned char cipher[SIZE];
 922    unsigned char i[AES_BLOCK_SIZE];
 923
 924    //set up key with AES_DECRYPTION as dir and tweak with AES_ENCRYPTION
 925
 926    if(wc_AesXtsDecrypt(&aes, plain, cipher, SIZE, i, sizeof(i)) != 0)
 927    {
 928        // Handle error
 929    }
 930    wc_AesXtsFree(&aes);
 931    \endcode
 932
 933    \sa wc_AesXtsEncrypt
 934    \sa wc_AesXtsInit
 935    \sa wc_AesXtsSetKeyNoInit
 936    \sa wc_AesXtsSetKey
 937    \sa wc_AesXtsFree
 938*/
 939int wc_AesXtsDecrypt(XtsAes* aes, byte* out,
 940        const byte* in, word32 sz, const byte* i, word32 iSz);
 941
 942/*!
 943    \ingroup AES
 944
 945    \brief This is to free up any resources used by the XtsAes structure
 946
 947    \return 0 Success
 948
 949    \param aes AES keys to free
 950
 951    _Example_
 952    \code
 953    XtsAes aes;
 954
 955    if(wc_AesXtsSetKey(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, 0) != 0)
 956    {
 957        // Handle error
 958    }
 959    wc_AesXtsFree(&aes);
 960    \endcode
 961
 962    \sa wc_AesXtsEncrypt
 963    \sa wc_AesXtsDecrypt
 964    \sa wc_AesXtsInit
 965    \sa wc_AesXtsSetKeyNoInit
 966    \sa wc_AesXtsSetKey
 967*/
 968int wc_AesXtsFree(XtsAes* aes);
 969
 970
 971/*!
 972    \ingroup AES
 973    \brief Initialize Aes structure. Sets heap hint to be used and ID for use
 974    with async hardware. It is up to the user to call wc_AesFree on the Aes
 975    structure when done.
 976    \return 0 Success
 977
 978    \param aes aes structure in to initialize
 979    \param heap heap hint to use for malloc / free if needed
 980    \param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
 981
 982    _Example_
 983    \code
 984    Aes enc;
 985    void* hint = NULL;
 986    int devId = INVALID_DEVID; //if not using async INVALID_DEVID is default
 987
 988    //heap hint could be set here if used
 989
 990    wc_AesInit(&enc, hint, devId);
 991    \endcode
 992
 993    \sa wc_AesSetKey
 994    \sa wc_AesSetIV
 995    \sa wc_AesFree
 996*/
 997int  wc_AesInit(Aes* aes, void* heap, int devId);
 998
 999/*!
1000    \ingroup AES
1001    \brief free resources associated with the Aes structure when applicable.
1002    Internally may sometimes be a no-op but still recommended to call in all
1003    cases as a general best-practice (IE if application code is ported for use
1004    on new environments where the call is applicable).
1005    \return no return (void function)
1006
1007    \param aes aes structure in to free
1008
1009    _Example_
1010    \code
1011    Aes enc;
1012    void* hint = NULL;
1013    int devId = INVALID_DEVID; //if not using async INVALID_DEVID is default
1014
1015    //heap hint could be set here if used
1016
1017    wc_AesInit(&enc, hint, devId);
1018    // ... do some interesting things ...
1019    wc_AesFree(&enc);
1020    \endcode
1021
1022    \sa wc_AesInit
1023*/
1024void wc_AesFree(Aes* aes);
1025
1026/*!
1027    \ingroup AES
1028
1029    \brief AES with CFB mode.
1030
1031    \return 0 Success and negative error values on failure
1032
1033    \param aes   AES keys to use for block encrypt/decrypt
1034    \param out   output buffer to hold cipher text must be at least as large
1035    as inputbuffer)
1036    \param in    input plain text buffer to encrypt
1037    \param sz    size of input buffer
1038
1039    _Example_
1040    \code
1041    Aes aes;
1042    unsigned char plain[SIZE];
1043    unsigned char cipher[SIZE];
1044
1045    //set up key with AES_ENCRYPTION as dir for both encrypt and decrypt
1046
1047    if(wc_AesCfbEncrypt(&aes, cipher, plain, SIZE) != 0)
1048    {
1049        // Handle error
1050    }
1051    \endcode
1052
1053    \sa wc_AesCfbDecrypt
1054    \sa wc_AesSetKey
1055*/
1056int wc_AesCfbEncrypt(Aes* aes, byte* out, const byte* in, word32 sz);
1057
1058/*!
1059    \ingroup AES
1060
1061    \brief AES with CFB mode.
1062
1063    \return 0 Success and negative error values on failure
1064
1065    \param aes   AES keys to use for block encrypt/decrypt
1066    \param out   output buffer to hold decrypted text must be at least as large
1067    as inputbuffer)
1068    \param in    input buffer to decrypt
1069    \param sz    size of input buffer
1070
1071    _Example_
1072    \code
1073    Aes aes;
1074    unsigned char plain[SIZE];
1075    unsigned char cipher[SIZE];
1076
1077    //set up key with AES_ENCRYPTION as dir for both encrypt and decrypt
1078
1079    if(wc_AesCfbDecrypt(&aes, plain, cipher, SIZE) != 0)
1080    {
1081        // Handle error
1082    }
1083    \endcode
1084
1085    \sa wc_AesCfbEncrypt
1086    \sa wc_AesSetKey
1087*/
1088int wc_AesCfbDecrypt(Aes* aes, byte* out, const byte* in, word32 sz);
1089
1090/*!
1091    \ingroup AES
1092
1093    \brief This function performs SIV (synthetic initialization vector)
1094    encryption as described in RFC 5297.
1095
1096    \return 0 On successful encryption.
1097    \return BAD_FUNC_ARG If key, SIV, or output buffer are NULL. Also returned
1098    if the key size isn't 32, 48, or 64 bytes.
1099    \return Other Other negative error values returned if AES or CMAC operations
1100    fail.
1101
1102    \param key Byte buffer containing the key to use.
1103    \param keySz Length of the key buffer in bytes.
1104    \param assoc Additional, authenticated associated data (AD).
1105    \param assocSz Length of AD buffer in bytes.
1106    \param nonce A number used once. Used by the algorithm in the same manner as
1107    the AD.
1108    \param nonceSz Length of nonce buffer in bytes.
1109    \param in Plaintext buffer to encrypt.
1110    \param inSz Length of plaintext buffer.
1111    \param siv The SIV output by S2V (see RFC 5297 2.4).
1112    \param out Buffer to hold the ciphertext. Should be the same length as the
1113    plaintext buffer.
1114
1115    _Example_
1116    \code
1117    byte key[] = { some 32, 48, or 64 byte key };
1118    byte assoc[] = {0x01, 0x2, 0x3};
1119    byte nonce[] = {0x04, 0x5, 0x6};
1120    byte plainText[] = {0xDE, 0xAD, 0xBE, 0xEF};
1121    byte siv[AES_BLOCK_SIZE];
1122    byte cipherText[sizeof(plainText)];
1123    if (wc_AesSivEncrypt(key, sizeof(key), assoc, sizeof(assoc), nonce,
1124        sizeof(nonce), plainText, sizeof(plainText), siv, cipherText) != 0) {
1125        // failed to encrypt
1126    }
1127    \endcode
1128
1129    \sa wc_AesSivDecrypt
1130*/
1131
1132
1133int wc_AesSivEncrypt(const byte* key, word32 keySz, const byte* assoc,
1134                     word32 assocSz, const byte* nonce, word32 nonceSz,
1135                     const byte* in, word32 inSz, byte* siv, byte* out);
1136
1137/*!
1138    \ingroup AES
1139    \brief This function performs SIV (synthetic initialization vector)
1140    decryption as described in RFC 5297.  If a nonzero error code is returned,
1141    the output data is undefined.  However, callers must unconditionally zeroize
1142    the output buffer to guard against leakage of cleartext data.
1143
1144    \return 0 On successful decryption.
1145    \return BAD_FUNC_ARG If key, SIV, or output buffer are NULL. Also returned
1146    if the key size isn't 32, 48, or 64 bytes.
1147    \return AES_SIV_AUTH_E If the SIV derived by S2V doesn't match the input
1148    SIV (see RFC 5297 2.7).
1149    \return Other Other negative error values returned if AES or CMAC operations
1150    fail.
1151
1152    \param key Byte buffer containing the key to use.
1153    \param keySz Length of the key buffer in bytes.
1154    \param assoc Additional, authenticated associated data (AD).
1155    \param assocSz Length of AD buffer in bytes.
1156    \param nonce A number used once. Used by the underlying algorithm in the
1157    same manner as the AD.
1158    \param nonceSz Length of nonce buffer in bytes.
1159    \param in Ciphertext buffer to decrypt.
1160    \param inSz Length of ciphertext buffer.
1161    \param siv The SIV that accompanies the ciphertext (see RFC 5297 2.4).
1162    \param out Buffer to hold the decrypted plaintext. Should be the same length
1163    as the ciphertext buffer.
1164
1165    _Example_
1166    \code
1167    byte key[] = { some 32, 48, or 64 byte key };
1168    byte assoc[] = {0x01, 0x2, 0x3};
1169    byte nonce[] = {0x04, 0x5, 0x6};
1170    byte cipherText[] = {0xDE, 0xAD, 0xBE, 0xEF};
1171    byte siv[AES_BLOCK_SIZE] = { the SIV that came with the ciphertext };
1172    byte plainText[sizeof(cipherText)];
1173    if (wc_AesSivDecrypt(key, sizeof(key), assoc, sizeof(assoc), nonce,
1174        sizeof(nonce), cipherText, sizeof(cipherText), siv, plainText) != 0) {
1175        // failed to decrypt
1176    }
1177    \endcode
1178
1179    \sa wc_AesSivEncrypt
1180*/
1181
1182int wc_AesSivDecrypt(const byte* key, word32 keySz, const byte* assoc,
1183                     word32 assocSz, const byte* nonce, word32 nonceSz,
1184                     const byte* in, word32 inSz, byte* siv, byte* out);
1185
1186
1187
1188
1189
1190
1191
1192/*!
1193    \ingroup AES
1194
1195    \brief This function performs AES EAX encryption and authentication as
1196    described in "EAX: A Conventional Authenticated-Encryption Mode"
1197    (https://eprint.iacr.org/2003/069). It is a "one-shot" API that performs
1198    all encryption and authentication operations in one function call.
1199
1200    \return 0 on successful encryption.
1201    \return BAD_FUNC_ARG if input or output buffers are NULL. Also returned
1202    if the key size isn't a valid AES key size (16, 24, or 32 bytes)
1203    \return other negative error values returned if AES or CMAC operations
1204    fail.
1205
1206    \param [in] key buffer containing the key to use
1207    \param [in] keySz length of the key buffer in bytes
1208    \param[out] out buffer to hold the ciphertext. Should be the same length as
1209    the plaintext buffer
1210    \param [in] in plaintext buffer to encrypt
1211    \param [in] inSz length of plaintext buffer
1212    \param [in] nonce the cryptographic nonce to use for EAX operations
1213    \param [in] nonceSz length of nonce buffer in bytes
1214    \param[out] authTag pointer to the buffer in which to store the
1215    authentication tag
1216    \param [in] authTagSz length of the desired authentication tag
1217    \param [in] authIn pointer to the buffer containing input data to authenticate
1218    \param [in] authInSz length of the input authentication data
1219
1220    _Example_
1221    \code
1222    byte key[] = { some 32, 48, or 64 byte key };
1223    byte nonce[] = {0x04, 0x5, 0x6};
1224    byte plainText[] = {0xDE, 0xAD, 0xBE, 0xEF};
1225    byte authIn[] = {0x01, 0x2, 0x3};
1226
1227    byte cipherText[sizeof(plainText)]; // output ciphertext
1228    byte authTag[length, up to AES_BLOCK_SIZE]; // output authTag
1229
1230    if (wc_AesEaxEncrypt(key, sizeof(key),
1231                         cipherText, plainText, sizeof(plainText),
1232                         nonce, sizeof(nonce),
1233                         authTag, sizeof(authTag),
1234                         authIn, sizeof(authIn)) != 0) {
1235        // failed to encrypt
1236    }
1237
1238    \endcode
1239
1240    \sa wc_AesEaxDecryptAuth
1241
1242*/
1243WOLFSSL_API int  wc_AesEaxEncryptAuth(const byte* key, word32 keySz, byte* out,
1244                                      const byte* in, word32 inSz,
1245                                      const byte* nonce, word32 nonceSz,
1246                                      /* output computed auth tag */
1247                                      byte* authTag, word32 authTagSz,
1248                                      /* input data to authenticate */
1249                                      const byte* authIn, word32 authInSz);
1250/*!
1251    \ingroup AES
1252
1253    \brief This function performs AES EAX decryption and authentication as
1254    described in "EAX: A Conventional Authenticated-Encryption Mode"
1255    (https://eprint.iacr.org/2003/069). It is a "one-shot" API that performs
1256    all decryption and authentication operations in one function call.  If a
1257    nonzero error code is returned, the output data is undefined.
1258    However, callers must unconditionally zeroize the output buffer to guard
1259    against leakage of cleartext data.
1260
1261    \return 0 on successful decryption
1262    \return BAD_FUNC_ARG if input or output buffers are NULL. Also returned
1263    if the key size isn't a valid AES key size (16, 24, or 32 bytes)
1264    \return AES_EAX_AUTH_E If the authentication tag does not match the
1265    supplied authentication code vector \c authTag
1266    \return other negative error values returned if AES or CMAC operations
1267    fail.
1268
1269    \param [in] key byte buffer containing the key to use
1270    \param [in] keySz length of the key buffer in bytes
1271    \param[out] out buffer to hold the plaintext. Should be the same length as
1272    the input ciphertext buffer
1273    \param [in] in ciphertext buffer to decrypt
1274    \param [in] inSz length of ciphertext buffer
1275    \param [in] nonce the cryptographic nonce to use for EAX operations
1276    \param [in] nonceSz length of nonce buffer in bytes
1277    \param [in] authTag buffer that holds the authentication tag to check the
1278    authenticity of the data against
1279    \param [in] authTagSz Length of the input authentication tag
1280    \param [in] authIn pointer to the buffer containing input data to authenticate
1281    \param [in] authInSz length of the input authentication data
1282
1283    _Example_
1284    \code
1285    byte key[] = { some 32, 48, or 64 byte key };
1286    byte nonce[] = {0x04, 0x5, 0x6};
1287    byte cipherText[] = {0xDE, 0xAD, 0xBE, 0xEF};
1288    byte authIn[] = {0x01, 0x2, 0x3};
1289
1290    byte plainText[sizeof(cipherText)]; // output plaintext
1291    byte authTag[length, up to AES_BLOCK_SIZE]; // output authTag
1292
1293    if (wc_AesEaxDecrypt(key, sizeof(key),
1294                         cipherText, plainText, sizeof(plainText),
1295                         nonce, sizeof(nonce),
1296                         authTag, sizeof(authTag),
1297                         authIn, sizeof(authIn)) != 0) {
1298        // failed to encrypt
1299    }
1300
1301    \endcode
1302
1303    \sa wc_AesEaxEncryptAuth
1304
1305*/
1306WOLFSSL_API int  wc_AesEaxDecryptAuth(const byte* key, word32 keySz, byte* out,
1307                                      const byte* in, word32 inSz,
1308                                      const byte* nonce, word32 nonceSz,
1309                                      /* auth tag to verify against */
1310                                      const byte* authTag, word32 authTagSz,
1311                                      /* input data to authenticate */
1312                                      const byte* authIn, word32 authInSz);
1313
1314/*!
1315    \ingroup AES
1316    \brief This function initializes an AesEax object for use in authenticated
1317    encryption or decryption. This function must be called on an AesEax
1318    object before using it with any of the AES EAX incremental API functions.
1319    It does not need to be called if using the one-shot EAX API functions.
1320    All AesEax instances initialized with this function need to be freed with
1321    a call to wc_AesEaxFree() when done using the instance.
1322
1323    \return 0 on success
1324    \return error code on failure
1325
1326    \param eax AES EAX structure holding the context of the AEAD operation
1327    \param key 16, 24, or 32 byte secret key for encryption and decryption
1328    \param keySz length of the supplied key in bytes
1329    \param nonce the cryptographic nonce to use for EAX operations
1330    \param nonceSz length of nonce buffer in bytes
1331    \param authIn (optional) input data to add to the authentication stream
1332    This argument should be NULL if not used
1333    \param authInSz size in bytes of the input authentication data
1334
1335    _Example_
1336    \code
1337    AesEax eax;
1338    key[]   = { some 16, 24, or 32 byte length key };
1339    nonce[] = { some arbitrary length nonce };
1340    authIn[] = { some data to add to the authentication stream };
1341    plainText[] = {some plaintext data to encrypt};
1342
1343    cipherText[sizeof(plainText)]; // buffer to hold cipherText
1344    authTag[length, up to AES_BLOCK_SIZE]; // buffer to hold computed auth data
1345
1346    AesEax eax;
1347
1348    if ((ret = wc_AesEaxInit(eax,
1349                             key, keySz,
1350                             nonce, nonceSz,
1351                             authIn, authInSz)) != 0) {
1352        goto cleanup;
1353    }
1354
1355    // if we wanted to add more auth data, we could provide it at this point,
1356    // otherwise we use NULL for the authIn parameter, with authIn size of 0
1357    if ((ret = wc_AesEaxEncryptUpdate(eax,
1358                                      cipherText, plainText, sizeof(plainText),
1359                                      NULL, 0)) != 0) {
1360        goto cleanup;
1361    }
1362
1363    if ((ret = wc_AesEaxEncryptFinal(eax, authTag, sizeof(authTag))) != 0) {
1364        goto cleanup;
1365    }
1366
1367    cleanup:
1368        wc_AesEaxFree(eax);
1369    \endcode
1370
1371    \sa wc_AesEaxEncryptUpdate
1372    \sa wc_AesEaxDecryptUpdate
1373    \sa wc_AesEaxAuthDataUpdate
1374    \sa wc_AesEaxEncryptFinal
1375    \sa wc_AesEaxDecryptFinal
1376    \sa wc_AesEaxFree
1377
1378*/
1379WOLFSSL_API int  wc_AesEaxInit(AesEax* eax,
1380                               const byte* key, word32 keySz,
1381                               const byte* nonce, word32 nonceSz,
1382                               const byte* authIn, word32 authInSz);
1383
1384/*!
1385    \ingroup AES
1386    \brief This function uses AES EAX to encrypt input data, and optionally, add
1387    more input data to the authentication stream. \c eax must have been
1388    previously initialized with a call to \ref wc_AesEaxInit.
1389
1390    \return 0 on success
1391    \return error code on failure
1392
1393    \param [in] eax AES EAX structure holding the context of the AEAD operation
1394    \param[out] out output buffer holding the ciphertext
1395    \param [in] in input buffer holding the plaintext to encrypt
1396    \param [in] inSz size in bytes of the input data buffer
1397    \param [in] authIn (optional) input data to add to the authentication stream
1398    This argument should be NULL if not used
1399    \param [in] authInSz size in bytes of the input authentication data
1400
1401    _Example_
1402    \code
1403    AesEax eax;
1404    key[]   = { some 16, 24, or 32 byte length key };
1405    nonce[] = { some arbitrary length nonce };
1406    authIn[] = { some data to add to the authentication stream };
1407    plainText[] = {some plaintext data to encrypt};
1408
1409    cipherText[sizeof(plainText)]; // buffer to hold cipherText
1410    authTag[length, up to AES_BLOCK_SIZE]; // buffer to hold computed auth data
1411
1412    AesEax eax;
1413
1414    if ((ret = wc_AesEaxInit(eax,
1415                             key, keySz,
1416                             nonce, nonceSz,
1417                             authIn, authInSz)) != 0) {
1418        goto cleanup;
1419    }
1420
1421    // if we wanted to add more auth data, we could provide it at this point,
1422    // otherwise we use NULL for the authIn parameter, with authInSz of 0
1423    if ((ret = wc_AesEaxEncryptUpdate(eax,
1424                                      cipherText, plainText, sizeof(plainText),
1425                                      NULL, 0)) != 0) {
1426        goto cleanup;
1427    }
1428
1429    if ((ret = wc_AesEaxEncryptFinal(eax, authTag, sizeof(authTag))) != 0) {
1430        goto cleanup;
1431    }
1432
1433    cleanup:
1434        wc_AesEaxFree(eax);
1435    \endcode
1436
1437    \sa wc_AesEaxInit
1438    \sa wc_AesEaxDecryptUpdate
1439    \sa wc_AesEaxAuthDataUpdate
1440    \sa wc_AesEaxEncryptFinal
1441    \sa wc_AesEaxDecryptFinal
1442    \sa wc_AesEaxFree
1443
1444*/
1445WOLFSSL_API int  wc_AesEaxEncryptUpdate(AesEax* eax, byte* out,
1446                                        const byte* in, word32 inSz,
1447                                        const byte* authIn, word32 authInSz);
1448
1449/*!
1450    \ingroup AES
1451    \brief This function uses AES EAX to decrypt input data, and optionally, add
1452    more input data to the authentication stream. \c eax must have been
1453    previously initialized with a call to \ref wc_AesEaxInit.
1454
1455    \return 0 on success
1456    \return error code on failure
1457
1458    \param [in] eax AES EAX structure holding the context of the AEAD operation
1459    \param[out] out output buffer holding the decrypted plaintext
1460    \param [in] in input buffer holding the ciphertext
1461    \param [in] inSz size in bytes of the input data buffer
1462    \param [in] authIn (optional) input data to add to the authentication stream
1463    This argument should be NULL if not used
1464    \param [in] authInSz size in bytes of the input authentication data
1465
1466
1467    _Example_
1468    \code
1469    AesEax eax;
1470    key[]   = { some 16, 24, or 32 byte length key };
1471    nonce[] = { some arbitrary length nonce };
1472    authIn[] = { some data to add to the authentication stream };
1473    cipherText[] = {some encrypted data};
1474
1475    plainText[sizeof(cipherText)]; // buffer to hold decrypted data
1476    // auth tag is generated elsewhere by the encrypt AEAD operation
1477    authTag[length, up to AES_BLOCK_SIZE] = { the auth tag };
1478
1479    AesEax eax;
1480
1481    if ((ret = wc_AesEaxInit(eax,
1482                             key, keySz,
1483                             nonce, nonceSz,
1484                             authIn, authInSz)) != 0) {
1485        goto cleanup;
1486    }
1487
1488    // if we wanted to add more auth data, we could provide it at this point,
1489    // otherwise we use NULL for the authIn parameter, with authInSz of 0
1490    if ((ret = wc_AesEaxDecryptUpdate(eax,
1491                                      plainText, cipherText, sizeof(cipherText),
1492                                      NULL, 0)) != 0) {
1493        goto cleanup;
1494    }
1495
1496    if ((ret = wc_AesEaxDecryptFinal(eax, authTag, sizeof(authTag))) != 0) {
1497        goto cleanup;
1498    }
1499
1500    cleanup:
1501        wc_AesEaxFree(eax);
1502    \endcode
1503
1504    \sa wc_AesEaxInit
1505    \sa wc_AesEaxEncryptUpdate
1506    \sa wc_AesEaxAuthDataUpdate
1507    \sa wc_AesEaxEncryptFinal
1508    \sa wc_AesEaxDecryptFinal
1509    \sa wc_AesEaxFree
1510
1511*/
1512WOLFSSL_API int  wc_AesEaxDecryptUpdate(AesEax* eax, byte* out,
1513                                        const byte* in, word32 inSz,
1514                                        const byte* authIn, word32 authInSz);
1515/*!
1516    \ingroup AES
1517    \brief This function adds input data to the authentication stream.
1518    \c eax must have been previously initialized with a call to
1519    \ref wc_AesEaxInit.
1520
1521    \return 0 on success
1522    \return error code on failure
1523
1524    \param eax AES EAX structure holding the context of the AEAD operation
1525    \param authIn input data to add to the authentication stream
1526    \param authInSz size in bytes of the input authentication data
1527
1528    _Example_
1529    \code
1530    AesEax eax;
1531    key[]   = { some 16, 24, or 32 byte length key };
1532    nonce[] = { some arbitrary length nonce };
1533    authIn[] = { some data to add to the authentication stream };
1534    cipherText[] = {some encrypted data};
1535
1536    plainText[sizeof(cipherText)]; // buffer to hold decrypted data
1537    // auth tag is generated elsewhere by the encrypt AEAD operation
1538    authTag[length, up to AES_BLOCK_SIZE] = { the auth tag };
1539
1540    AesEax eax;
1541
1542    // No auth data to add here
1543    if ((ret = wc_AesEaxInit(eax,
1544                             key, keySz,
1545                             nonce, nonceSz,
1546                             NULL, 0)) != 0) {
1547        goto cleanup;
1548    }
1549
1550    // No auth data to add here, added later with wc_AesEaxAuthDataUpdate
1551    if ((ret = wc_AesEaxDecryptUpdate(eax,
1552                                      plainText, cipherText, sizeof(cipherText),
1553                                      NULL, 0)) != 0) {
1554        goto cleanup;
1555    }
1556
1557    if ((ret = wc_AesEaxAuthDataUpdate(eax, authIn, sizeof(authIn))) != 0) {
1558        goto cleanup;
1559    }
1560
1561    if ((ret = wc_AesEaxDecryptFinal(eax, authTag, sizeof(authTag))) != 0) {
1562        goto cleanup;
1563    }
1564
1565    cleanup:
1566        wc_AesEaxFree(eax);
1567    \endcode
1568
1569    \sa wc_AesEaxInit
1570    \sa wc_AesEaxEncryptUpdate
1571    \sa wc_AesEaxDecryptUpdate
1572    \sa wc_AesEaxEncryptFinal
1573    \sa wc_AesEaxDecryptFinal
1574    \sa wc_AesEaxFree
1575
1576*/
1577WOLFSSL_API int  wc_AesEaxAuthDataUpdate(AesEax* eax,
1578                                       const byte* authIn, word32 authInSz);
1579
1580/*!
1581    \ingroup AES
1582    \brief This function finalizes the encrypt AEAD operation, producing an auth
1583    tag over the current authentication stream. \c eax must have been previously
1584    initialized with a call to \ref wc_AesEaxInit. When done using the \c AesEax
1585    context structure, make sure to free it using \ref wc_AesEaxFree.
1586
1587    \return 0 on success
1588    \return error code on failure
1589
1590    \param eax AES EAX structure holding the context of the AEAD operation
1591    \param authTag[out] buffer that will hold the computed auth tag
1592    \param authTagSz size in bytes of \c authTag
1593
1594    _Example_
1595    \code
1596    AesEax eax;
1597    key[]   = { some 16, 24, or 32 byte length key };
1598    nonce[] = { some arbitrary length nonce };
1599    authIn[] = { some data to add to the authentication stream };
1600    plainText[] = {some plaintext data to encrypt};
1601
1602    cipherText[sizeof(plainText)]; // buffer to hold cipherText
1603    authTag[length, up to AES_BLOCK_SIZE]; // buffer to hold computed auth data
1604
1605    AesEax eax;
1606
1607    if ((ret = wc_AesEaxInit(eax,
1608                             key, keySz,
1609                             nonce, nonceSz,
1610                             authIn, authInSz)) != 0) {
1611        goto cleanup;
1612    }
1613
1614    // if we wanted to add more auth data, we could provide it at this point,
1615    // otherwise we use NULL for the authIn parameter, with authInSz of 0
1616    if ((ret = wc_AesEaxEncryptUpdate(eax,
1617                                      cipherText, plainText, sizeof(plainText),
1618                                      NULL, 0)) != 0) {
1619        goto cleanup;
1620    }
1621
1622    if ((ret = wc_AesEaxEncryptFinal(eax, authTag, sizeof(authTag))) != 0) {
1623        goto cleanup;
1624    }
1625
1626    cleanup:
1627        wc_AesEaxFree(eax);
1628    \endcode
1629
1630    \sa wc_AesEaxInit
1631    \sa wc_AesEaxEncryptUpdate
1632    \sa wc_AesEaxDecryptUpdate
1633    \sa wc_AesEaxAuthDataUpdate
1634    \sa wc_AesEaxDecryptFinal
1635    \sa wc_AesEaxFree
1636
1637*/
1638WOLFSSL_API int wc_AesEaxEncryptFinal(AesEax* eax,
1639                                      byte* authTag, word32 authTagSz);
1640
1641/*!
1642    \ingroup AES
1643    \brief This function finalizes the decrypt AEAD operation, finalizing the
1644    auth tag computation and checking it for validity against the user supplied
1645    tag. \c eax must have been previously initialized with a call to
1646    \ref wc_AesEaxInit. When done using the \c AesEax context structure, make
1647    sure to free it using \ref wc_AesEaxFree.
1648
1649    \return 0 if data is authenticated successfully
1650    \return AES_EAX_AUTH_E if the authentication tag does not match the
1651    supplied authentication code vector \c authIn
1652    \return other error code on failure
1653
1654    \param eax AES EAX structure holding the context of the AEAD operation
1655    \param authIn input auth tag to check computed auth tag against
1656    \param authInSz size in bytes of \c authIn
1657
1658    _Example_
1659    \code
1660    AesEax eax;
1661    key[]   = { some 16, 24, or 32 byte length key };
1662    nonce[] = { some arbitrary length nonce };
1663    authIn[] = { some data to add to the authentication stream };
1664    cipherText[] = {some encrypted data};
1665
1666    plainText[sizeof(cipherText)]; // buffer to hold decrypted data
1667    // auth tag is generated elsewhere by the encrypt AEAD operation
1668    authTag[length, up to AES_BLOCK_SIZE] = { the auth tag };
1669
1670    AesEax eax;
1671
1672    if ((ret = wc_AesEaxInit(eax,
1673                             key, keySz,
1674                             nonce, nonceSz,
1675                             authIn, authInSz)) != 0) {
1676        goto cleanup;
1677    }
1678
1679    // if we wanted to add more auth data, we could provide it at this point,
1680    // otherwise we use NULL for the authIn parameter, with authInSz of 0
1681    if ((ret = wc_AesEaxDecryptUpdate(eax,
1682                                      plainText, cipherText, sizeof(cipherText),
1683                                      NULL, 0)) != 0) {
1684        goto cleanup;
1685    }
1686
1687    if ((ret = wc_AesEaxDecryptFinal(eax, authTag, sizeof(authTag))) != 0) {
1688        goto cleanup;
1689    }
1690
1691    cleanup:
1692        wc_AesEaxFree(eax);
1693    \endcode
1694
1695    \sa wc_AesEaxInit
1696    \sa wc_AesEaxEncryptUpdate
1697    \sa wc_AesEaxDecryptUpdate
1698    \sa wc_AesEaxAuthDataUpdate
1699    \sa wc_AesEaxEncryptFinal
1700    \sa wc_AesEaxFree
1701
1702*/
1703WOLFSSL_API int wc_AesEaxDecryptFinal(AesEax* eax,
1704                                      const byte* authIn, word32 authInSz);
1705/*!
1706    \ingroup AES
1707
1708    \brief This frees up any resources, specifically keys, used by the Aes
1709    instance inside the AesEax wrapper struct. It should be called on the
1710    AesEax struct after it has been initialized with wc_AesEaxInit, and all
1711    desired EAX operations are complete.
1712
1713    \return 0 Success
1714
1715    \param eaxAES EAX instance to free
1716
1717    _Example_
1718    \code
1719    AesEax eax;
1720
1721    if(wc_AesEaxInit(eax, key, keySz, nonce, nonceSz, authIn, authInSz) != 0) {
1722        // handle errors, then free
1723        wc_AesEaxFree(&eax);
1724    }
1725    \endcode
1726
1727    \sa wc_AesEaxInit
1728    \sa wc_AesEaxEncryptUpdate
1729    \sa wc_AesEaxDecryptUpdate
1730    \sa wc_AesEaxAuthDataUpdate
1731    \sa wc_AesEaxEncryptFinal
1732    \sa wc_AesEaxDecryptFinal
1733*/
1734WOLFSSL_API int wc_AesEaxFree(AesEax* eax);
1735
1736/*!
1737    \ingroup AES
1738    \brief This function performs AES encryption using Ciphertext Stealing (CTS)
1739    mode. It is a one-shot API that handles all operations in a single call.
1740
1741    \return 0 on successful encryption.
1742    \return BAD_FUNC_ARG if input arguments are invalid.
1743    \return other negative error codes for encryption failures.
1744
1745    \param [in] key pointer to the AES key used for encryption.
1746    \param [in] keySz size of the AES key in bytes (16, 24, or 32 bytes).
1747    \param[out] out buffer to hold the encrypted ciphertext. Must be at least
1748    the size of the input.
1749    \param [in] in pointer to the plaintext input data to encrypt.
1750    \param [in] inSz size of the plaintext input data in bytes.
1751    \param [in] iv pointer to the initialization vector (IV) used for encryption.
1752    Must be 16 bytes.
1753
1754    _Example_
1755    \code
1756        byte key[16] = { 0 };
1757        byte iv[16] = { 0 };
1758        byte plaintext[] = { 0x01, 0x02, 0x03, 0x04, 0x05 };
1759        byte ciphertext[sizeof(plaintext)];
1760
1761        int ret = wc_AesCtsEncrypt(key, sizeof(key), ciphertext, plaintext,
1762            sizeof(plaintext), iv);
1763        if (ret != 0) {
1764        // handle encryption error
1765    }
1766    \endcode
1767
1768    \sa wc_AesCtsDecrypt
1769*/
1770int wc_AesCtsEncrypt(const byte* key, word32 keySz, byte* out,
1771                     const byte* in, word32 inSz,
1772                     const byte* iv);
1773
1774/*!
1775    \ingroup AES
1776    \brief This function performs AES encryption using Ciphertext Stealing (CTS)
1777     mode. It is a one-shot API that handles all operations in a single call.
1778
1779    \return 0 on successful encryption.
1780    \return BAD_FUNC_ARG if input arguments are invalid.
1781    \return other negative error codes for encryption failures.
1782
1783    \param [in] key pointer to the AES key used for encryption.
1784    \param [in] keySz size of the AES key in bytes (16, 24, or 32 bytes).
1785    \param[out] out buffer to hold the encrypted ciphertext. Must be at least
1786                 the same size as the input plaintext.
1787    \param [in] in pointer to the plaintext input data to encrypt.
1788    \param [in] inSz size of the plaintext input data in bytes.
1789    \param [in] iv pointer to the initialization vector (IV) used for encryption.
1790             Must be 16 bytes.
1791    _Example_
1792    \code
1793        byte key[16] = { 0 };
1794        byte iv[16] = { 0 };
1795        byte plaintext[] = { 0x01, 0x02, 0x03, 0x04, 0x05 };
1796        byte ciphertext[sizeof(plaintext)];
1797        int ret = wc_AesCtsEncrypt(key, sizeof(key), ciphertext, plaintext,
1798                                   sizeof(plaintext), iv);
1799        if (ret != 0) {
1800            // handle encryption error
1801        }
1802    \endcode
1803    \sa wc_AesCtsDecrypt
1804*/
1805int wc_AesCtsEncrypt(const byte* key, word32 keySz, byte* out,
1806                     const byte* in, word32 inSz,
1807                     const byte* iv);
1808
1809/*!
1810    \ingroup AES
1811    \brief This function performs AES decryption using Ciphertext Stealing (CTS) mode.
1812           It is a one-shot API that handles all operations in a single call.
1813    \return 0 on successful decryption.
1814    \return BAD_FUNC_ARG if input arguments are invalid.
1815    \return other negative error codes for decryption failures.
1816    \param [in] key pointer to the AES key used for decryption.
1817    \param [in] keySz size of the AES key in bytes (16, 24, or 32 bytes).
1818    \param[out] out buffer to hold the decrypted plaintext. Must be at least
1819                 the same size as the input ciphertext.
1820    \param [in] in pointer to the ciphertext input data to decrypt.
1821    \param [in] inSz size of the ciphertext input data in bytes.
1822    \param [in] iv pointer to the initialization vector (IV) used for decryption.
1823             Must be 16 bytes.
1824    _Example_
1825    \code
1826        byte key[16] = { 0 };
1827        byte iv[16] = { 0 };
1828        byte ciphertext[] = { 0x01, 0x02, 0x03, 0x04, 0x05 };
1829        byte plaintext[sizeof(ciphertext)];
1830        int ret = wc_AesCtsDecrypt(key, sizeof(key), plaintext, ciphertext,
1831                                   sizeof(ciphertext), iv);
1832        if (ret != 0) {
1833            // handle decryption error
1834        }
1835    \endcode
1836    \sa wc_AesCtsEncrypt
1837*/
1838int wc_AesCtsDecrypt(const byte* key, word32 keySz, byte* out,
1839                     const byte* in, word32 inSz,
1840                     const byte* iv);
1841
1842/*!
1843    \ingroup AES
1844    \brief This function performs an update step of the AES CTS encryption.
1845           It processes a chunk of plaintext and stores intermediate data.
1846    \return 0 on successful processing.
1847    \return BAD_FUNC_ARG if input arguments are invalid.
1848    \param [in] aes pointer to the Aes structure holding the context of the operation.
1849    \param[out] out buffer to hold the encrypted ciphertext. Must be large enough
1850                 to store the output from this update step.
1851    \param[out] outSz size in bytes of the output data written to the \c out buffer.
1852                    On input, it should contain the maximum number of bytes that can
1853                    be written to the \c out buffer.
1854    \param [in] in pointer to the plaintext input data to encrypt.
1855    \param [in] inSz size of the plaintext input data in bytes.
1856    _Example_
1857    \code
1858        Aes aes;
1859        wc_AesInit(&aes, NULL, INVALID_DEVID);
1860        byte key[16] = { 0 };
1861        byte iv[16] = { 0 };
1862        byte plaintext[] = { ... };
1863        byte ciphertext[sizeof(plaintext)];
1864        word32 outSz = sizeof(ciphertext);
1865        wc_AesSetKey(&aes, key, sizeof(key), iv, AES_ENCRYPTION);
1866        int ret = wc_AesCtsEncryptUpdate(&aes, ciphertext, &outSz, plaintext, sizeof(plaintext));
1867        if (ret != 0) {
1868            // handle error
1869        }
1870        wc_AesFree(&aes);
1871    \endcode
1872    \sa wc_AesCtsDecryptUpdate
1873*/
1874int wc_AesCtsEncryptUpdate(Aes* aes, byte* out, word32* outSz,
1875                           const byte* in, word32 inSz);
1876
1877/*!
1878    \ingroup AES
1879    \brief This function finalizes the AES CTS encryption operation.
1880           It processes any remaining plaintext and completes the encryption.
1881    \return 0 on successful encryption completion.
1882    \return BAD_FUNC_ARG if input arguments are invalid.
1883    \param [in] aes pointer to the Aes structure holding the context of the operation.
1884    \param[out] out buffer to hold the final encrypted ciphertext. Must be large
1885                 enough to store any remaining ciphertext from this final step.
1886    \param[out] outSz size in bytes of the output data written to the \c out buffer.
1887                     On input, it should contain the maximum number of bytes that can
1888                     be written to the \c out buffer.
1889    _Example_
1890    \code
1891        Aes aes;
1892        wc_AesInit(&aes, NULL, INVALID_DEVID);
1893        byte key[16] = { 0 };
1894        byte iv[16] = { 0 };
1895        byte plaintext[] = { ... };
1896        byte ciphertext[sizeof(plaintext)];
1897        word32 outSz = sizeof(ciphertext);
1898        wc_AesSetKey(&aes, key, sizeof(key), iv, AES_ENCRYPTION);
1899        // Perform any required update steps using wc_AesCtsEncryptUpdate
1900        int ret = wc_AesCtsEncryptFinal(&aes, ciphertext, &outSz);
1901        if (ret != 0) {
1902            // handle error
1903        }
1904        wc_AesFree(&aes);
1905    \endcode
1906    \sa wc_AesCtsDecryptFinal
1907*/
1908int wc_AesCtsEncryptFinal(Aes* aes, byte* out, word32* outSz);
1909
1910/*!
1911    \ingroup AES
1912    \brief This function performs an update step of the AES CTS decryption.
1913           It processes a chunk of ciphertext and stores intermediate data.
1914    \return 0 on successful processing.
1915    \return BAD_FUNC_ARG if input arguments are invalid.
1916    \param [in] aes pointer to the Aes structure holding the context of the operation.
1917    \param[out] out buffer to hold the decrypted plaintext. Must be large enough
1918                 to store the output from this update step.
1919    \param[out] outSz size in bytes of the output data written to the \c out buffer.
1920                     On input, it should contain the maximum number of bytes that can
1921                     be written to the \c out buffer.
1922    \param [in] in pointer to the ciphertext input data to decrypt.
1923    \param [in] inSz size of the ciphertext input data in bytes.
1924    _Example_
1925    \code
1926        Aes aes;
1927        wc_AesInit(&aes, NULL, INVALID_DEVID);
1928        byte key[16] = { 0 };
1929        byte iv[16] = { 0 };
1930        byte ciphertext[] = { ... };
1931        byte plaintext[sizeof(ciphertext)];
1932        word32 outSz = sizeof(plaintext);
1933        wc_AesSetKey(&aes, key, sizeof(key), iv, AES_DECRYPTION);
1934        int ret = wc_AesCtsDecryptUpdate(&aes, plaintext, &outSz, ciphertext, sizeof(ciphertext));
1935        if (ret != 0) {
1936            // handle error
1937        }
1938        wc_AesFree(&aes);
1939    \endcode
1940    \sa wc_AesCtsEncryptUpdate
1941*/
1942int wc_AesCtsDecryptUpdate(Aes* aes, byte* out, word32* outSz,
1943                           const byte* in, word32 inSz);
1944
1945/*!
1946    \ingroup AES
1947    \brief This function finalizes the AES CTS decryption operation.
1948           It processes any remaining ciphertext and completes the decryption.
1949    \return 0 on successful decryption completion.
1950    \return BAD_FUNC_ARG if input arguments are invalid.
1951    \param [in] aes pointer to the Aes structure holding the context of the operation.
1952    \param[out] out buffer to hold the final decrypted plaintext. Must be large
1953                 enough to store any remaining plaintext from this final step.
1954    \param[out] outSz size in bytes of the output data written to the \c out buffer.
1955                     On input, it should contain the maximum number of bytes that can
1956                     be written to the \c out buffer.
1957    _Example_
1958    \code
1959        Aes aes;
1960        wc_AesInit(&aes, NULL, INVALID_DEVID);
1961        byte key[16] = { 0 };
1962        byte iv[16] = { 0 };
1963        byte ciphertext[] = { ... };
1964        byte plaintext[sizeof(ciphertext)];
1965        word32 outSz = sizeof(plaintext);
1966        wc_AesSetKey(&aes, key, sizeof(key), iv, AES_DECRYPTION);
1967        // Perform any required update steps using wc_AesCtsDecryptUpdate
1968        int ret = wc_AesCtsDecryptFinal(&aes, plaintext, &outSz);
1969        if (ret != 0) {
1970            // handle error
1971        }
1972        wc_AesFree(&aes);
1973    \endcode
1974    \sa wc_AesCtsEncryptFinal
1975*/
1976int wc_AesCtsDecryptFinal(Aes* aes, byte* out, word32* outSz);
1977
1978
1979/*!
1980    \ingroup AES
1981    \brief This function encrypts data using AES CFB-1 mode (1-bit
1982    feedback). It processes data one bit at a time, making it suitable
1983    for bit-oriented applications.
1984
1985    \return 0 On success.
1986    \return BAD_FUNC_ARG If aes, out, or in is NULL.
1987    \return Other negative values on error.
1988
1989    \param aes pointer to the AES structure containing the key
1990    \param out pointer to the output buffer to store encrypted data
1991    \param in pointer to the input buffer containing data to encrypt
1992    (packed to left, e.g., 101 is 0x90)
1993    \param sz size of input in bits
1994
1995    _Example_
1996    \code
1997    Aes aes;
1998    byte key[16] = { }; // 128-bit key
1999    byte iv[16] = { }; // initialization vector
2000    byte plaintext[1] = { 0x90 }; // bits 101
2001    byte ciphertext[1];
2002
2003    wc_AesInit(&aes, NULL, INVALID_DEVID);
2004    wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION);
2005    int ret = wc_AesCfb1Encrypt(&aes, ciphertext, plaintext, 3);
2006    if (ret != 0) {
2007        // encryption failed
2008    }
2009    wc_AesFree(&aes);
2010    \endcode
2011
2012    \sa wc_AesCfb1Decrypt
2013    \sa wc_AesCfb8Encrypt
2014*/
2015int wc_AesCfb1Encrypt(Aes* aes, byte* out, const byte* in, word32 sz);
2016
2017/*!
2018    \ingroup AES
2019    \brief This function encrypts data using AES CFB-8 mode (8-bit
2020    feedback). It processes data one byte at a time, making it suitable
2021    for byte-oriented stream encryption.
2022
2023    \return 0 On success.
2024    \return BAD_FUNC_ARG If aes, out, or in is NULL.
2025    \return Other negative values on error.
2026
2027    \param aes pointer to the AES structure containing the key
2028    \param out pointer to the output buffer to store encrypted data
2029    \param in pointer to the input buffer containing data to encrypt
2030    \param sz size of input in bytes
2031
2032    _Example_
2033    \code
2034    Aes aes;
2035    byte key[16] = { }; // 128-bit key
2036    byte iv[16] = { }; // initialization vector
2037    byte plaintext[10] = { }; // data to encrypt
2038    byte ciphertext[10];
2039
2040    wc_AesInit(&aes, NULL, INVALID_DEVID);
2041    wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION);
2042    int ret = wc_AesCfb8Encrypt(&aes, ciphertext, plaintext, 10);
2043    if (ret != 0) {
2044        // encryption failed
2045    }
2046    wc_AesFree(&aes);
2047    \endcode
2048
2049    \sa wc_AesCfb8Decrypt
2050    \sa wc_AesCfb1Encrypt
2051*/
2052int wc_AesCfb8Encrypt(Aes* aes, byte* out, const byte* in, word32 sz);
2053
2054/*!
2055    \ingroup AES
2056    \brief This function decrypts data using AES CFB-1 mode (1-bit
2057    feedback). It processes data one bit at a time, making it suitable
2058    for bit-oriented applications.
2059
2060    \return 0 On success.
2061    \return BAD_FUNC_ARG If aes, out, or in is NULL.
2062    \return Other negative values on error.
2063
2064    \param aes pointer to the AES structure containing the key
2065    \param out pointer to the output buffer to store decrypted data
2066    \param in pointer to the input buffer containing data to decrypt
2067    \param sz size of input in bits
2068
2069    _Example_
2070    \code
2071    Aes aes;
2072    byte key[16] = { }; // 128-bit key
2073    byte iv[16] = { }; // initialization vector
2074    byte ciphertext[1] = { }; // encrypted bits
2075    byte plaintext[1];
2076
2077    wc_AesInit(&aes, NULL, INVALID_DEVID);
2078    wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION);
2079    int ret = wc_AesCfb1Decrypt(&aes, plaintext, ciphertext, 3);
2080    if (ret != 0) {
2081        // decryption failed
2082    }
2083    wc_AesFree(&aes);
2084    \endcode
2085
2086    \sa wc_AesCfb1Encrypt
2087    \sa wc_AesCfb8Decrypt
2088*/
2089int wc_AesCfb1Decrypt(Aes* aes, byte* out, const byte* in, word32 sz);
2090
2091/*!
2092    \ingroup AES
2093    \brief This function decrypts data using AES CFB-8 mode (8-bit
2094    feedback). It processes data one byte at a time, making it suitable
2095    for byte-oriented stream decryption.
2096
2097    \return 0 On success.
2098    \return BAD_FUNC_ARG If aes, out, or in is NULL.
2099    \return Other negative values on error.
2100
2101    \param aes pointer to the AES structure containing the key
2102    \param out pointer to the output buffer to store decrypted data
2103    \param in pointer to the input buffer containing data to decrypt
2104    \param sz size of input in bytes
2105
2106    _Example_
2107    \code
2108    Aes aes;
2109    byte key[16] = { }; // 128-bit key
2110    byte iv[16] = { }; // initialization vector
2111    byte ciphertext[10] = { }; // encrypted data
2112    byte plaintext[10];
2113
2114    wc_AesInit(&aes, NULL, INVALID_DEVID);
2115    wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION);
2116    int ret = wc_AesCfb8Decrypt(&aes, plaintext, ciphertext, 10);
2117    if (ret != 0) {
2118        // decryption failed
2119    }
2120    wc_AesFree(&aes);
2121    \endcode
2122
2123    \sa wc_AesCfb8Encrypt
2124    \sa wc_AesCfb1Decrypt
2125*/
2126int wc_AesCfb8Decrypt(Aes* aes, byte* out, const byte* in, word32 sz);
2127
2128/*!
2129    \ingroup AES
2130    \brief This function encrypts data using AES OFB mode (Output
2131    Feedback). OFB mode turns a block cipher into a stream cipher by
2132    encrypting the IV and XORing with plaintext.
2133
2134    \return 0 On success.
2135    \return BAD_FUNC_ARG If aes, out, or in is NULL.
2136    \return Other negative values on error.
2137
2138    \param aes pointer to the AES structure containing the key
2139    \param out pointer to the output buffer to store encrypted data
2140    \param in pointer to the input buffer containing data to encrypt
2141    \param sz size of input in bytes
2142
2143    _Example_
2144    \code
2145    Aes aes;
2146    byte key[16] = { }; // 128-bit key
2147    byte iv[16] = { }; // initialization vector
2148    byte plaintext[100] = { }; // data to encrypt
2149    byte ciphertext[100];
2150
2151    wc_AesInit(&aes, NULL, INVALID_DEVID);
2152    wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION);
2153    int ret = wc_AesOfbEncrypt(&aes, ciphertext, plaintext, 100);
2154    if (ret != 0) {
2155        // encryption failed
2156    }
2157    wc_AesFree(&aes);
2158    \endcode
2159
2160    \sa wc_AesOfbDecrypt
2161    \sa wc_AesSetKey
2162*/
2163int wc_AesOfbEncrypt(Aes* aes, byte* out, const byte* in, word32 sz);
2164
2165/*!
2166    \ingroup AES
2167    \brief This function decrypts data using AES OFB mode (Output
2168    Feedback). In OFB mode, encryption and decryption are the same
2169    operation.
2170
2171    \return 0 On success.
2172    \return BAD_FUNC_ARG If aes, out, or in is NULL.
2173    \return Other negative values on error.
2174
2175    \param aes pointer to the AES structure containing the key
2176    \param out pointer to the output buffer to store decrypted data
2177    \param in pointer to the input buffer containing data to decrypt
2178    \param sz size of input in bytes
2179
2180    _Example_
2181    \code
2182    Aes aes;
2183    byte key[16] = { }; // 128-bit key
2184    byte iv[16] = { }; // initialization vector
2185    byte ciphertext[100] = { }; // encrypted data
2186    byte plaintext[100];
2187
2188    wc_AesInit(&aes, NULL, INVALID_DEVID);
2189    wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION);
2190    int ret = wc_AesOfbDecrypt(&aes, plaintext, ciphertext, 100);
2191    if (ret != 0) {
2192        // decryption failed
2193    }
2194    wc_AesFree(&aes);
2195    \endcode
2196
2197    \sa wc_AesOfbEncrypt
2198    \sa wc_AesSetKey
2199*/
2200int wc_AesOfbDecrypt(Aes* aes, byte* out, const byte* in, word32 sz);
2201
2202/*!
2203    \ingroup AES
2204    \brief This function encrypts data using AES ECB mode (Electronic
2205    Codebook). Warning: ECB mode is not recommended for most use cases
2206    as it does not provide semantic security. Each block is encrypted
2207    independently.
2208
2209    \return 0 On success.
2210    \return BAD_FUNC_ARG If aes, out, or in is NULL.
2211    \return Other negative values on error.
2212
2213    \param aes pointer to the AES structure containing the key
2214    \param out pointer to the output buffer to store encrypted data
2215    \param in pointer to the input buffer containing data to encrypt
2216    \param sz size of input in bytes (must be multiple of AES_BLOCK_SIZE)
2217
2218    _Example_
2219    \code
2220    Aes aes;
2221    byte key[16] = { }; // 128-bit key
2222    byte plaintext[32] = { }; // data to encrypt
2223    byte ciphertext[32];
2224
2225    wc_AesInit(&aes, NULL, INVALID_DEVID);
2226    wc_AesSetKey(&aes, key, 16, NULL, AES_ENCRYPTION);
2227    int ret = wc_AesEcbEncrypt(&aes, ciphertext, plaintext, 32);
2228    if (ret != 0) {
2229        // encryption failed
2230    }
2231    wc_AesFree(&aes);
2232    \endcode
2233
2234    \sa wc_AesEcbDecrypt
2235    \sa wc_AesSetKey
2236*/
2237int wc_AesEcbEncrypt(Aes* aes, byte* out, const byte* in, word32 sz);
2238
2239/*!
2240    \ingroup AES
2241    \brief This function decrypts data using AES ECB mode (Electronic
2242    Codebook). Warning: ECB mode is not recommended for most use cases
2243    as it does not provide semantic security. Each block is decrypted
2244    independently.
2245
2246    \return 0 On success.
2247    \return BAD_FUNC_ARG If aes, out, or in is NULL.
2248    \return Other negative values on error.
2249
2250    \param aes pointer to the AES structure containing the key
2251    \param out pointer to the output buffer to store decrypted data
2252    \param in pointer to the input buffer containing data to decrypt
2253    \param sz size of input in bytes (must be multiple of AES_BLOCK_SIZE)
2254
2255    _Example_
2256    \code
2257    Aes aes;
2258    byte key[16] = { }; // 128-bit key
2259    byte ciphertext[32] = { }; // encrypted data
2260    byte plaintext[32];
2261
2262    wc_AesInit(&aes, NULL, INVALID_DEVID);
2263    wc_AesSetKey(&aes, key, 16, NULL, AES_DECRYPTION);
2264    int ret = wc_AesEcbDecrypt(&aes, plaintext, ciphertext, 32);
2265    if (ret != 0) {
2266        // decryption failed
2267    }
2268    wc_AesFree(&aes);
2269    \endcode
2270
2271    \sa wc_AesEcbEncrypt
2272    \sa wc_AesSetKey
2273*/
2274int wc_AesEcbDecrypt(Aes* aes, byte* out, const byte* in, word32 sz);
2275
2276/*!
2277    \ingroup AES
2278    \brief This function sets the key and IV for AES CTR mode. It
2279    initializes the AES structure for counter mode encryption or
2280    decryption.
2281
2282    \return 0 On success.
2283    \return BAD_FUNC_ARG If aes, key, or iv is NULL, or if key length
2284    is invalid.
2285
2286    \param aes pointer to the AES structure to initialize
2287    \param key pointer to the key buffer (16, 24, or 32 bytes)
2288    \param len length of the key in bytes
2289    \param iv pointer to the initialization vector (16 bytes)
2290    \param dir cipher direction (always use AES_ENCRYPTION for CTR mode)
2291
2292    _Example_
2293    \code
2294    Aes aes;
2295    byte key[16] = { }; // 128-bit key
2296    byte iv[16] = { }; // initialization vector
2297
2298    wc_AesInit(&aes, NULL, INVALID_DEVID);
2299    int ret = wc_AesCtrSetKey(&aes, key, 16, iv, AES_ENCRYPTION);
2300    if (ret != 0) {
2301        // failed to set key
2302    }
2303    wc_AesFree(&aes);
2304    \endcode
2305
2306    \sa wc_AesCtrEncrypt
2307    \sa wc_AesSetKey
2308*/
2309int wc_AesCtrSetKey(Aes* aes, const byte* key, word32 len, const byte* iv,
2310                    int dir);
2311
2312/*!
2313    \ingroup AES
2314    \brief This function sets the key for AES GCM with an extended key
2315    update parameter. It allows for key updates in certain hardware
2316    implementations.
2317
2318    \note This function is currently only available when building with
2319    Xilinx hardware acceleration. It requires one of the following build
2320    options: WOLFSSL_XILINX_CRYPT (for Xilinx SecureIP integration) or
2321    WOLFSSL_AFALG_XILINX_AES (for Xilinx AF_ALG support). This API may
2322    be exposed for additional build configurations in the future.
2323
2324    \return 0 On success.
2325    \return BAD_FUNC_ARG If aes or key is NULL, or if key length is invalid.
2326
2327    \param aes pointer to the AES structure to initialize
2328    \param key pointer to the key buffer (16, 24, or 32 bytes)
2329    \param len length of the key in bytes
2330    \param kup key update parameter for hardware implementations
2331
2332    _Example_
2333    \code
2334    Aes aes;
2335    byte key[16] = { }; // 128-bit key
2336
2337    wc_AesInit(&aes, NULL, INVALID_DEVID);
2338    int ret = wc_AesGcmSetKey_ex(&aes, key, 16, 0);
2339    if (ret != 0) {
2340        // failed to set key
2341    }
2342    wc_AesFree(&aes);
2343    \endcode
2344
2345    \sa wc_AesGcmSetKey
2346    \sa wc_AesGcmInit
2347*/
2348int wc_AesGcmSetKey_ex(Aes* aes, const byte* key, word32 len, word32 kup);
2349
2350/*!
2351    \ingroup AES
2352    \brief This function initializes an AES GCM cipher with key and IV.
2353    It can be called with NULL key to only set the IV, or with NULL IV
2354    to only set the key.
2355
2356    \return 0 On success.
2357    \return BAD_FUNC_ARG If aes is NULL, or if parameters are invalid.
2358    \return MEMORY_E If dynamic memory allocation fails.
2359
2360    \param aes pointer to the AES structure to initialize
2361    \param key pointer to the key buffer, or NULL to skip key setting
2362    \param len length of the key in bytes
2363    \param iv pointer to the IV/nonce buffer, or NULL to skip IV setting
2364    \param ivSz length of the IV/nonce in bytes
2365
2366    _Example_
2367    \code
2368    Aes aes;
2369    byte key[16] = { }; // 128-bit key
2370    byte iv[12] = { }; // 96-bit nonce
2371
2372    wc_AesInit(&aes, NULL, INVALID_DEVID);
2373    int ret = wc_AesGcmInit(&aes, key, 16, iv, 12);
2374    if (ret != 0) {
2375        // failed to initialize
2376    }
2377    wc_AesFree(&aes);
2378    \endcode
2379
2380    \sa wc_AesGcmSetKey
2381    \sa wc_AesGcmEncrypt
2382*/
2383int wc_AesGcmInit(Aes* aes, const byte* key, word32 len, const byte* iv,
2384                  word32 ivSz);
2385
2386/*!
2387    \ingroup AES
2388    \brief This function initializes an AES GCM cipher for encryption.
2389    It is a convenience wrapper around wc_AesGcmInit for encryption
2390    operations.
2391
2392    \return 0 On success.
2393    \return BAD_FUNC_ARG If aes is NULL, or if parameters are invalid.
2394
2395    \param aes pointer to the AES structure to initialize
2396    \param key pointer to the key buffer, or NULL to skip key setting
2397    \param len length of the key in bytes
2398    \param iv pointer to the IV/nonce buffer, or NULL to skip IV setting
2399    \param ivSz length of the IV/nonce in bytes
2400
2401    _Example_
2402    \code
2403    Aes aes;
2404    byte key[16] = { }; // 128-bit key
2405    byte iv[12] = { }; // 96-bit nonce
2406
2407    wc_AesInit(&aes, NULL, INVALID_DEVID);
2408    int ret = wc_AesGcmEncryptInit(&aes, key, 16, iv, 12);
2409    if (ret != 0) {
2410        // failed to initialize
2411    }
2412    wc_AesFree(&aes);
2413    \endcode
2414
2415    \sa wc_AesGcmInit
2416    \sa wc_AesGcmEncryptUpdate
2417*/
2418int wc_AesGcmEncryptInit(Aes* aes, const byte* key, word32 len,
2419                         const byte* iv, word32 ivSz);
2420
2421/*!
2422    \ingroup AES
2423    \brief This function initializes an AES GCM cipher for encryption and
2424    outputs the IV. This is useful when part of the IV is generated
2425    internally. Must call wc_AesGcmSetIV() before this function to set
2426    the fixed part of the IV.
2427
2428    \return 0 On success.
2429    \return BAD_FUNC_ARG If aes, ivOut is NULL, or if ivOutSz doesn't
2430    match the cached nonce size.
2431
2432    \param aes pointer to the AES structure to initialize
2433    \param key pointer to the key buffer, or NULL to skip key setting
2434    \param len length of the key in bytes
2435    \param ivOut pointer to buffer to receive the complete IV
2436    \param ivOutSz length of the IV output buffer in bytes
2437
2438    _Example_
2439    \code
2440    Aes aes;
2441    byte key[16] = { }; // 128-bit key
2442    byte ivFixed[4] = { }; // fixed part of IV
2443    byte ivOut[12];
2444    WC_RNG rng;
2445
2446    wc_InitRng(&rng);
2447    wc_AesInit(&aes, NULL, INVALID_DEVID);
2448    wc_AesGcmSetIV(&aes, 12, ivFixed, 4, &rng);
2449    int ret = wc_AesGcmEncryptInit_ex(&aes, key, 16, ivOut, 12);
2450    if (ret != 0) {
2451        // failed to initialize
2452    }
2453    wc_AesFree(&aes);
2454    wc_FreeRng(&rng);
2455    \endcode
2456
2457    \sa wc_AesGcmSetIV
2458    \sa wc_AesGcmEncryptUpdate
2459*/
2460int wc_AesGcmEncryptInit_ex(Aes* aes, const byte* key, word32 len,
2461                            byte* ivOut, word32 ivOutSz);
2462
2463/*!
2464    \ingroup AES
2465    \brief This function performs an update step of AES GCM encryption.
2466    It processes plaintext and/or additional authentication data (AAD)
2467    in a streaming fashion.
2468
2469    All the AAD must be passed to update before the plaintext.
2470    The last part of AAD can be passed with the first part of plaintext.
2471
2472    Must set key and IV before calling this function.
2473    Must call wc_AesGcmInit() before calling this function.
2474
2475    \return 0 On success.
2476    \return BAD_FUNC_ARG If aes is NULL, or a length is non-zero but
2477    buffer is NULL.
2478
2479    \param aes pointer to the AES structure
2480    \param out pointer to buffer to store ciphertext (can be NULL if sz=0)
2481    \param in pointer to plaintext to encrypt (can be NULL if sz=0)
2482    \param sz length of plaintext in bytes
2483    \param authIn pointer to additional authentication data (can be NULL)
2484    \param authInSz length of AAD in bytes
2485
2486    _Example_
2487    \code
2488    Aes aes;
2489    byte key[16] = { }; // 128-bit key
2490    byte iv[12] = { }; // nonce
2491    byte plaintext[100] = { }; // data
2492    byte ciphertext[100];
2493    byte aad[20] = { }; // additional data
2494
2495    wc_AesInit(&aes, NULL, INVALID_DEVID);
2496    wc_AesGcmInit(&aes, key, 16, iv, 12);
2497    int ret = wc_AesGcmEncryptUpdate(&aes, ciphertext, plaintext, 100,
2498                                     aad, 20);
2499    if (ret != 0) {
2500        // encryption failed
2501    }
2502    wc_AesFree(&aes);
2503    \endcode
2504
2505    \sa wc_AesGcmInit
2506    \sa wc_AesGcmEncryptInit
2507    \sa wc_AesGcmEncryptFinal
2508*/
2509int wc_AesGcmEncryptUpdate(Aes* aes, byte* out, const byte* in, word32 sz,
2510                           const byte* authIn, word32 authInSz);
2511
2512/*!
2513    \ingroup AES
2514    \brief This function finalizes AES GCM encryption and generates the
2515    authentication tag. This must be called after all data has been
2516    processed with wc_AesGcmEncryptUpdate.
2517
2518    \return 0 On success.
2519    \return BAD_FUNC_ARG If aes or authTag is NULL, or if authTagSz is
2520    invalid.
2521
2522    \param aes pointer to the AES structure
2523    \param authTag pointer to buffer to store the authentication tag
2524    \param authTagSz length of the authentication tag in bytes (typically
2525    12 or 16)
2526
2527    _Example_
2528    \code
2529    Aes aes;
2530    byte key[16] = { }; // 128-bit key
2531    byte iv[12] = { }; // nonce
2532    byte plaintext[100] = { }; // data
2533    byte ciphertext[100];
2534    byte authTag[16];
2535
2536    wc_AesInit(&aes, NULL, INVALID_DEVID);
2537    wc_AesGcmEncryptInit(&aes, key, 16, iv, 12);
2538    wc_AesGcmEncryptUpdate(&aes, ciphertext, plaintext, 100, NULL, 0);
2539    int ret = wc_AesGcmEncryptFinal(&aes, authTag, 16);
2540    if (ret != 0) {
2541        // failed to generate tag
2542    }
2543    wc_AesFree(&aes);
2544    \endcode
2545
2546    \sa wc_AesGcmEncryptUpdate
2547    \sa wc_AesGcmDecryptFinal
2548*/
2549int wc_AesGcmEncryptFinal(Aes* aes, byte* authTag, word32 authTagSz);
2550
2551/*!
2552    \ingroup AES
2553    \brief This function initializes an AES GCM cipher for decryption.
2554    It is a convenience wrapper around wc_AesGcmInit for decryption
2555    operations.
2556
2557    \return 0 On success.
2558    \return BAD_FUNC_ARG If aes is NULL, or if parameters are invalid.
2559
2560    \param aes pointer to the AES structure to initialize
2561    \param key pointer to the key buffer, or NULL to skip key setting
2562    \param len length of the key in bytes
2563    \param iv pointer to the IV/nonce buffer, or NULL to skip IV setting
2564    \param ivSz length of the IV/nonce in bytes
2565
2566    _Example_
2567    \code
2568    Aes aes;
2569    byte key[16] = { }; // 128-bit key
2570    byte iv[12] = { }; // 96-bit nonce
2571
2572    wc_AesInit(&aes, NULL, INVALID_DEVID);
2573    int ret = wc_AesGcmDecryptInit(&aes, key, 16, iv, 12);
2574    if (ret != 0) {
2575        // failed to initialize
2576    }
2577    wc_AesFree(&aes);
2578    \endcode
2579
2580    \sa wc_AesGcmInit
2581    \sa wc_AesGcmDecryptUpdate
2582*/
2583int wc_AesGcmDecryptInit(Aes* aes, const byte* key, word32 len,
2584                         const byte* iv, word32 ivSz);
2585
2586/*!
2587    \ingroup AES
2588    \brief This function performs an update step of AES GCM decryption.
2589    It processes ciphertext and/or additional authentication data (AAD)
2590    in a streaming fashion.
2591
2592    All the AAD must be passed to update before the ciphertext.
2593    The last part of AAD can be passed with the first part of ciphertext.
2594
2595    Must set key and IV before calling this function.
2596    Must call wc_AesGcmInit() before calling this function.
2597
2598    \return 0 On success.
2599    \return BAD_FUNC_ARG If aes is NULL, or a length is non-zero but
2600    buffer is NULL.
2601
2602    \param aes pointer to the AES structure
2603    \param out pointer to buffer to store plaintext (can be NULL if sz=0)
2604    \param in pointer to ciphertext to decrypt (can be NULL if sz=0)
2605    \param sz length of ciphertext in bytes
2606    \param authIn pointer to additional authentication data (can be NULL)
2607    \param authInSz length of AAD in bytes
2608
2609    _Example_
2610    \code
2611    Aes aes;
2612    byte key[16] = { }; // 128-bit key
2613    byte iv[12] = { }; // nonce
2614    byte ciphertext[100] = { }; // encrypted data
2615    byte plaintext[100];
2616    byte aad[20] = { }; // additional data
2617
2618    wc_AesInit(&aes, NULL, INVALID_DEVID);
2619    wc_AesGcmInit(&aes, key, 16, iv, 12);
2620    int ret = wc_AesGcmDecryptUpdate(&aes, plaintext, ciphertext, 100,
2621                                     aad, 20);
2622    if (ret != 0) {
2623        // decryption failed
2624    }
2625    wc_AesFree(&aes);
2626    \endcode
2627
2628    \sa wc_AesGcmInit
2629    \sa wc_AesGcmDecryptInit
2630    \sa wc_AesGcmDecryptFinal
2631*/
2632int wc_AesGcmDecryptUpdate(Aes* aes, byte* out, const byte* in, word32 sz,
2633                           const byte* authIn, word32 authInSz);
2634
2635/*!
2636    \ingroup AES
2637    \brief This function finalizes AES GCM decryption and verifies the
2638    authentication tag. This must be called after all data has been
2639    processed with wc_AesGcmDecryptUpdate.
2640
2641    \return 0 On success.
2642    \return AES_GCM_AUTH_E If authentication tag verification fails.
2643    \return BAD_FUNC_ARG If aes or authTag is NULL, or if authTagSz is
2644    invalid.
2645
2646    \param aes pointer to the AES structure
2647    \param authTag pointer to the authentication tag to verify
2648    \param authTagSz length of the authentication tag in bytes
2649
2650    _Example_
2651    \code
2652    Aes aes;
2653    byte key[16] = { }; // 128-bit key
2654    byte iv[12] = { }; // nonce
2655    byte ciphertext[100] = { }; // encrypted data
2656    byte plaintext[100];
2657    byte authTag[16] = { }; // received tag
2658
2659    wc_AesInit(&aes, NULL, INVALID_DEVID);
2660    wc_AesGcmDecryptInit(&aes, key, 16, iv, 12);
2661    wc_AesGcmDecryptUpdate(&aes, plaintext, ciphertext, 100, NULL, 0);
2662    int ret = wc_AesGcmDecryptFinal(&aes, authTag, 16);
2663    if (ret != 0) {
2664        // authentication failed
2665    }
2666    wc_AesFree(&aes);
2667    \endcode
2668
2669    \sa wc_AesGcmDecryptUpdate
2670    \sa wc_AesGcmEncryptFinal
2671*/
2672int wc_AesGcmDecryptFinal(Aes* aes, const byte* authTag, word32 authTagSz);
2673
2674/*!
2675    \ingroup AES
2676    \brief This function sets an external IV for AES GCM. This allows
2677    using an IV that was generated externally or received from another
2678    source.
2679
2680    \return 0 On success.
2681    \return BAD_FUNC_ARG If aes or iv is NULL, or if ivSz is invalid.
2682
2683    \param aes pointer to the AES structure
2684    \param iv pointer to the IV/nonce buffer
2685    \param ivSz length of the IV/nonce in bytes
2686
2687    _Example_
2688    \code
2689    Aes aes;
2690    byte key[16] = { }; // 128-bit key
2691    byte iv[12] = { }; // external nonce
2692
2693    wc_AesInit(&aes, NULL, INVALID_DEVID);
2694    wc_AesGcmSetKey(&aes, key, 16);
2695    int ret = wc_AesGcmSetExtIV(&aes, iv, 12);
2696    if (ret != 0) {
2697        // failed to set IV
2698    }
2699    wc_AesFree(&aes);
2700    \endcode
2701
2702    \sa wc_AesGcmSetIV
2703    \sa wc_AesGcmInit
2704*/
2705int wc_AesGcmSetExtIV(Aes* aes, const byte* iv, word32 ivSz);
2706
2707/*!
2708    \ingroup AES
2709    \brief This function sets the IV for AES GCM with optional random
2710    generation. It can generate part of the IV using an RNG, which is
2711    useful for ensuring IV uniqueness.
2712
2713    \return 0 On success.
2714    \return BAD_FUNC_ARG If aes is NULL, or if parameters are invalid.
2715    \return Other negative values on RNG or other errors.
2716
2717    \param aes pointer to the AES structure
2718    \param ivSz total length of the IV/nonce in bytes
2719    \param ivFixed pointer to the fixed part of the IV (can be NULL)
2720    \param ivFixedSz length of the fixed part in bytes
2721    \param rng pointer to initialized RNG for generating random part
2722    (can be NULL if ivFixedSz equals ivSz)
2723
2724    _Example_
2725    \code
2726    Aes aes;
2727    byte key[16] = { }; // 128-bit key
2728    byte ivFixed[4] = { }; // fixed part
2729    WC_RNG rng;
2730
2731    wc_InitRng(&rng);
2732    wc_AesInit(&aes, NULL, INVALID_DEVID);
2733    wc_AesGcmSetKey(&aes, key, 16);
2734    int ret = wc_AesGcmSetIV(&aes, 12, ivFixed, 4, &rng);
2735    if (ret != 0) {
2736        // failed to set IV
2737    }
2738    wc_AesFree(&aes);
2739    wc_FreeRng(&rng);
2740    \endcode
2741
2742    \sa wc_AesGcmSetExtIV
2743    \sa wc_AesGcmEncryptInit_ex
2744*/
2745int wc_AesGcmSetIV(Aes* aes, word32 ivSz, const byte* ivFixed,
2746                   word32 ivFixedSz, WC_RNG* rng);
2747
2748/*!
2749    \ingroup AES
2750    \brief This function performs AES GCM encryption with extended
2751    parameters, including IV output. This is a one-shot encryption
2752    function that outputs the generated IV.
2753
2754    \return 0 On success.
2755    \return BAD_FUNC_ARG If parameters are invalid.
2756    \return Other negative values on error.
2757
2758    \param aes pointer to the AES structure
2759    \param out pointer to buffer to store ciphertext
2760    \param in pointer to plaintext to encrypt
2761    \param sz length of plaintext in bytes
2762    \param ivOut pointer to buffer to receive the IV
2763    \param ivOutSz length of the IV output buffer in bytes
2764    \param authTag pointer to buffer to store authentication tag
2765    \param authTagSz length of authentication tag in bytes
2766    \param authIn pointer to additional authentication data
2767    \param authInSz length of AAD in bytes
2768
2769    _Example_
2770    \code
2771    Aes aes;
2772    byte key[16] = { }; // 128-bit key
2773    byte ivFixed[4] = { }; // fixed part
2774    byte ivOut[12];
2775    byte plaintext[100] = { }; // data
2776    byte ciphertext[100];
2777    byte authTag[16];
2778    WC_RNG rng;
2779
2780    wc_InitRng(&rng);
2781    wc_AesInit(&aes, NULL, INVALID_DEVID);
2782    wc_AesGcmSetKey(&aes, key, 16);
2783    wc_AesGcmSetIV(&aes, 12, ivFixed, 4, &rng);
2784    int ret = wc_AesGcmEncrypt_ex(&aes, ciphertext, plaintext, 100,
2785                                  ivOut, 12, authTag, 16, NULL, 0);
2786    if (ret != 0) {
2787        // encryption failed
2788    }
2789    wc_AesFree(&aes);
2790    wc_FreeRng(&rng);
2791    \endcode
2792
2793    \sa wc_AesGcmEncrypt
2794    \sa wc_AesGcmSetIV
2795*/
2796int wc_AesGcmEncrypt_ex(Aes* aes, byte* out, const byte* in, word32 sz,
2797                        byte* ivOut, word32 ivOutSz, byte* authTag,
2798                        word32 authTagSz, const byte* authIn,
2799                        word32 authInSz);
2800
2801/*!
2802    \ingroup AES
2803    \brief This function performs GMAC (Galois Message Authentication Code)
2804    generation. GMAC is essentially AES-GCM with no plaintext, used for
2805    authentication only.
2806
2807    \return 0 On success.
2808    \return BAD_FUNC_ARG If parameters are invalid.
2809    \return Other negative values on error.
2810
2811    \param key pointer to the key buffer
2812    \param keySz length of the key in bytes (16, 24, or 32)
2813    \param iv pointer to the IV/nonce buffer
2814    \param ivSz length of the IV/nonce in bytes
2815    \param authIn pointer to data to authenticate
2816    \param authInSz length of data to authenticate in bytes
2817    \param authTag pointer to buffer to store authentication tag
2818    \param authTagSz length of authentication tag in bytes
2819    \param rng pointer to initialized RNG (can be NULL if IV is complete)
2820
2821    _Example_
2822    \code
2823    byte key[16] = { }; // 128-bit key
2824    byte iv[12] = { }; // nonce
2825    byte data[100] = { }; // data to authenticate
2826    byte authTag[16];
2827
2828    int ret = wc_Gmac(key, 16, iv, 12, data, 100, authTag, 16, NULL);
2829    if (ret != 0) {
2830        // GMAC generation failed
2831    }
2832    \endcode
2833
2834    \sa wc_GmacVerify
2835    \sa wc_AesGcmEncrypt
2836*/
2837int wc_Gmac(const byte* key, word32 keySz, byte* iv, word32 ivSz,
2838            const byte* authIn, word32 authInSz, byte* authTag,
2839            word32 authTagSz, WC_RNG* rng);
2840
2841/*!
2842    \ingroup AES
2843    \brief This function verifies a GMAC (Galois Message Authentication
2844    Code). It computes the GMAC and compares it with the provided tag.
2845
2846    \return 0 On successful verification.
2847    \return AES_GCM_AUTH_E If authentication tag verification fails.
2848    \return BAD_FUNC_ARG If parameters are invalid.
2849    \return Other negative values on error.
2850
2851    \param key pointer to the key buffer
2852    \param keySz length of the key in bytes (16, 24, or 32)
2853    \param iv pointer to the IV/nonce buffer
2854    \param ivSz length of the IV/nonce in bytes
2855    \param authIn pointer to data to authenticate
2856    \param authInSz length of data to authenticate in bytes
2857    \param authTag pointer to the authentication tag to verify
2858    \param authTagSz length of authentication tag in bytes
2859
2860    _Example_
2861    \code
2862    byte key[16] = { }; // 128-bit key
2863    byte iv[12] = { }; // nonce
2864    byte data[100] = { }; // data to authenticate
2865    byte authTag[16] = { }; // received tag
2866
2867    int ret = wc_GmacVerify(key, 16, iv, 12, data, 100, authTag, 16);
2868    if (ret != 0) {
2869        // GMAC verification failed
2870    }
2871    \endcode
2872
2873    \sa wc_Gmac
2874    \sa wc_AesGcmDecrypt
2875*/
2876int wc_GmacVerify(const byte* key, word32 keySz, const byte* iv,
2877                  word32 ivSz, const byte* authIn, word32 authInSz,
2878                  const byte* authTag, word32 authTagSz);
2879
2880/*!
2881    \ingroup AES
2882    \brief This function sets the nonce for AES CCM mode. The nonce must
2883    be set before encryption or decryption operations.
2884
2885    \return 0 On success.
2886    \return BAD_FUNC_ARG If aes or nonce is NULL, or if nonceSz is invalid.
2887
2888    \param aes pointer to the AES structure
2889    \param nonce pointer to the nonce buffer
2890    \param nonceSz length of the nonce in bytes (7-13 bytes for CCM)
2891
2892    _Example_
2893    \code
2894    Aes aes;
2895    byte key[16] = { }; // 128-bit key
2896    byte nonce[12] = { }; // nonce
2897
2898    wc_AesInit(&aes, NULL, INVALID_DEVID);
2899    wc_AesCcmSetKey(&aes, key, 16);
2900    int ret = wc_AesCcmSetNonce(&aes, nonce, 12);
2901    if (ret != 0) {
2902        // failed to set nonce
2903    }
2904    wc_AesFree(&aes);
2905    \endcode
2906
2907    \sa wc_AesCcmEncrypt
2908    \sa wc_AesCcmSetKey
2909*/
2910int wc_AesCcmSetNonce(Aes* aes, const byte* nonce, word32 nonceSz);
2911
2912/*!
2913    \ingroup AES
2914    \brief This function performs AES CCM encryption with extended
2915    parameters, including nonce output. This is useful when part of the
2916    nonce is generated internally.
2917
2918    \return 0 On success.
2919    \return BAD_FUNC_ARG If parameters are invalid.
2920    \return Other negative values on error.
2921
2922    \param aes pointer to the AES structure
2923    \param out pointer to buffer to store ciphertext
2924    \param in pointer to plaintext to encrypt
2925    \param sz length of plaintext in bytes
2926    \param ivOut pointer to buffer to receive the nonce
2927    \param ivOutSz length of the nonce output buffer in bytes
2928    \param authTag pointer to buffer to store authentication tag
2929    \param authTagSz length of authentication tag in bytes
2930    \param authIn pointer to additional authentication data
2931    \param authInSz length of AAD in bytes
2932
2933    _Example_
2934    \code
2935    Aes aes;
2936    byte key[16] = { }; // 128-bit key
2937    byte nonce[12];
2938    byte plaintext[100] = { }; // data
2939    byte ciphertext[100];
2940    byte authTag[16];
2941
2942    wc_AesInit(&aes, NULL, INVALID_DEVID);
2943    wc_AesCcmSetKey(&aes, key, 16);
2944    int ret = wc_AesCcmEncrypt_ex(&aes, ciphertext, plaintext, 100,
2945                                  nonce, 12, authTag, 16, NULL, 0);
2946    if (ret != 0) {
2947        // encryption failed
2948    }
2949    wc_AesFree(&aes);
2950    \endcode
2951
2952    \sa wc_AesCcmEncrypt
2953    \sa wc_AesCcmSetNonce
2954*/
2955int wc_AesCcmEncrypt_ex(Aes* aes, byte* out, const byte* in, word32 sz,
2956                        byte* ivOut, word32 ivOutSz, byte* authTag,
2957                        word32 authTagSz, const byte* authIn,
2958                        word32 authInSz);
2959
2960/*!
2961    \ingroup AES
2962    \brief This function wraps a key using AES Key Wrap algorithm
2963    (RFC 3394). This is commonly used to securely transport
2964    cryptographic keys.
2965
2966    \return Length of wrapped key in bytes on success.
2967    \return BAD_FUNC_ARG If parameters are invalid.
2968    \return Other negative values on error.
2969
2970    \param key pointer to the key-encryption key
2971    \param keySz length of the key-encryption key in bytes
2972    \param in pointer to the key to wrap
2973    \param inSz length of the key to wrap in bytes
2974    \param out pointer to buffer to store wrapped key
2975    \param outSz size of output buffer in bytes
2976    \param iv pointer to IV (typically NULL to use default)
2977
2978    _Example_
2979    \code
2980    byte kek[16] = { }; // key-encryption key
2981    byte keyToWrap[16] = { }; // key to wrap
2982    byte wrappedKey[24];
2983
2984    int wrappedLen = wc_AesKeyWrap(kek, 16, keyToWrap, 16, wrappedKey,
2985                                   24, NULL);
2986    if (wrappedLen <= 0) {
2987        // key wrap failed
2988    }
2989    \endcode
2990
2991    \sa wc_AesKeyUnWrap
2992    \sa wc_AesKeyWrap_ex
2993*/
2994int wc_AesKeyWrap(const byte* key, word32 keySz, const byte* in,
2995                  word32 inSz, byte* out, word32 outSz, const byte* iv);
2996
2997/*!
2998    \ingroup AES
2999    \brief This function wraps a key using AES Key Wrap algorithm with
3000    an initialized AES structure. This allows reusing the same AES
3001    structure for multiple wrap operations.
3002
3003    \return Length of wrapped key in bytes on success.
3004    \return BAD_FUNC_ARG If parameters are invalid.
3005    \return Other negative values on error.
3006
3007    \param aes pointer to initialized AES structure
3008    \param in pointer to the key to wrap
3009    \param inSz length of the key to wrap in bytes
3010    \param out pointer to buffer to store wrapped key
3011    \param outSz size of output buffer in bytes
3012    \param iv pointer to IV (typically NULL to use default)
3013
3014    _Example_
3015    \code
3016    Aes aes;
3017    byte kek[16] = { }; // key-encryption key
3018    byte keyToWrap[16] = { }; // key to wrap
3019    byte wrappedKey[24];
3020
3021    wc_AesInit(&aes, NULL, INVALID_DEVID);
3022    wc_AesSetKey(&aes, kek, 16, NULL, AES_ENCRYPTION);
3023    int wrappedLen = wc_AesKeyWrap_ex(&aes, keyToWrap, 16, wrappedKey,
3024                                      24, NULL);
3025    if (wrappedLen <= 0) {
3026        // key wrap failed
3027    }
3028    wc_AesFree(&aes);
3029    \endcode
3030
3031    \sa wc_AesKeyWrap
3032    \sa wc_AesKeyUnWrap_ex
3033*/
3034int wc_AesKeyWrap_ex(Aes *aes, const byte* in, word32 inSz, byte* out,
3035                     word32 outSz, const byte* iv);
3036
3037/*!
3038    \ingroup AES
3039    \brief This function unwraps a key using AES Key Unwrap algorithm
3040    (RFC 3394). This is used to securely receive cryptographic keys
3041    that were wrapped.
3042
3043    \return Length of unwrapped key in bytes on success.
3044    \return BAD_FUNC_ARG If parameters are invalid.
3045    \return Other negative values on error.
3046
3047    \param key pointer to the key-encryption key
3048    \param keySz length of the key-encryption key in bytes
3049    \param in pointer to the wrapped key
3050    \param inSz length of the wrapped key in bytes
3051    \param out pointer to buffer to store unwrapped key
3052    \param outSz size of output buffer in bytes
3053    \param iv pointer to IV (typically NULL to use default)
3054
3055    _Example_
3056    \code
3057    byte kek[16] = { }; // key-encryption key
3058    byte wrappedKey[24] = { }; // wrapped key
3059    byte unwrappedKey[16];
3060
3061    int unwrappedLen = wc_AesKeyUnWrap(kek, 16, wrappedKey, 24,
3062                                       unwrappedKey, 16, NULL);
3063    if (unwrappedLen <= 0) {
3064        // key unwrap failed
3065    }
3066    \endcode
3067
3068    \sa wc_AesKeyWrap
3069    \sa wc_AesKeyUnWrap_ex
3070*/
3071int wc_AesKeyUnWrap(const byte* key, word32 keySz, const byte* in,
3072                    word32 inSz, byte* out, word32 outSz, const byte* iv);
3073
3074/*!
3075    \ingroup AES
3076    \brief This function unwraps a key using AES Key Unwrap algorithm
3077    with an initialized AES structure. This allows reusing the same AES
3078    structure for multiple unwrap operations.
3079
3080    \return Length of unwrapped key in bytes on success.
3081    \return BAD_FUNC_ARG If parameters are invalid.
3082    \return Other negative values on error.
3083
3084    \param aes pointer to initialized AES structure
3085    \param in pointer to the wrapped key
3086    \param inSz length of the wrapped key in bytes
3087    \param out pointer to buffer to store unwrapped key
3088    \param outSz size of output buffer in bytes
3089    \param iv pointer to IV (typically NULL to use default)
3090
3091    _Example_
3092    \code
3093    Aes aes;
3094    byte kek[16] = { }; // key-encryption key
3095    byte wrappedKey[24] = { }; // wrapped key
3096    byte unwrappedKey[16];
3097
3098    wc_AesInit(&aes, NULL, INVALID_DEVID);
3099    wc_AesSetKey(&aes, kek, 16, NULL, AES_ENCRYPTION);
3100    int unwrappedLen = wc_AesKeyUnWrap_ex(&aes, wrappedKey, 24,
3101                                          unwrappedKey, 16, NULL);
3102    if (unwrappedLen <= 0) {
3103        // key unwrap failed
3104    }
3105    wc_AesFree(&aes);
3106    \endcode
3107
3108    \sa wc_AesKeyUnWrap
3109    \sa wc_AesKeyWrap_ex
3110*/
3111int wc_AesKeyUnWrap_ex(Aes *aes, const byte* in, word32 inSz, byte* out,
3112                       word32 outSz, const byte* iv);
3113
3114/*!
3115    \ingroup AES
3116    \brief This function encrypts multiple consecutive sectors using AES XTS
3117    mode. It processes multiple sectors in sequence, automatically
3118    incrementing the sector number for each sector.
3119
3120    \return 0 On success.
3121    \return BAD_FUNC_ARG If aes, out, or in is NULL, or if sectorSz is 0,
3122    or if sz is less than AES_BLOCK_SIZE.
3123    \return Other negative values on error.
3124
3125    \param aes pointer to the XtsAes structure
3126    \param out pointer to buffer to store encrypted data
3127    \param in pointer to plaintext data to encrypt
3128    \param sz total length of data in bytes
3129    \param sector starting sector number for the tweak
3130    \param sectorSz size of each sector in bytes
3131
3132    _Example_
3133    \code
3134    XtsAes aes;
3135    byte key[32] = { }; // 256-bit key
3136    byte plaintext[1024] = { }; // data
3137    byte ciphertext[1024];
3138
3139    wc_AesXtsSetKey(&aes, key, 32, AES_ENCRYPTION, NULL, INVALID_DEVID);
3140    int ret = wc_AesXtsEncryptConsecutiveSectors(&aes, ciphertext,
3141                                                 plaintext, 1024, 0, 512);
3142    if (ret != 0) {
3143        // encryption failed
3144    }
3145    wc_AesXtsFree(&aes);
3146    \endcode
3147
3148    \sa wc_AesXtsDecryptConsecutiveSectors
3149    \sa wc_AesXtsEncryptSector
3150*/
3151int wc_AesXtsEncryptConsecutiveSectors(XtsAes* aes, byte* out,
3152                                       const byte* in, word32 sz,
3153                                       word64 sector, word32 sectorSz);
3154
3155/*!
3156    \ingroup AES
3157    \brief This function decrypts multiple consecutive sectors using AES XTS
3158    mode. It processes multiple sectors in sequence, automatically
3159    incrementing the sector number for each sector.
3160
3161    \return 0 On success.
3162    \return BAD_FUNC_ARG If aes, out, or in is NULL, or if sectorSz is 0,
3163    or if sz is less than AES_BLOCK_SIZE.
3164    \return Other negative values on error.
3165
3166    \param aes pointer to the XtsAes structure
3167    \param out pointer to buffer to store decrypted data
3168    \param in pointer to ciphertext data to decrypt
3169    \param sz total length of data in bytes
3170    \param sector starting sector number for the tweak
3171    \param sectorSz size of each sector in bytes
3172
3173    _Example_
3174    \code
3175    XtsAes aes;
3176    byte key[32] = { }; // 256-bit key
3177    byte ciphertext[1024] = { }; // encrypted data
3178    byte plaintext[1024];
3179
3180    wc_AesXtsSetKey(&aes, key, 32, AES_DECRYPTION, NULL, INVALID_DEVID);
3181    int ret = wc_AesXtsDecryptConsecutiveSectors(&aes, plaintext,
3182                                                 ciphertext, 1024, 0, 512);
3183    if (ret != 0) {
3184        // decryption failed
3185    }
3186    wc_AesXtsFree(&aes);
3187    \endcode
3188
3189    \sa wc_AesXtsEncryptConsecutiveSectors
3190    \sa wc_AesXtsDecryptSector
3191*/
3192int wc_AesXtsDecryptConsecutiveSectors(XtsAes* aes, byte* out,
3193                                       const byte* in, word32 sz,
3194                                       word64 sector, word32 sectorSz);
3195
3196/*!
3197    \ingroup AES
3198    \brief This function initializes streaming AES XTS encryption. It sets
3199    up the context for processing data in multiple update calls.
3200
3201    \return 0 On success.
3202    \return BAD_FUNC_ARG If parameters are invalid.
3203
3204    \param aes pointer to the XtsAes structure
3205    \param i pointer to the tweak/IV buffer
3206    \param iSz length of the tweak/IV in bytes
3207    \param stream pointer to XtsAesStreamData structure for streaming state
3208
3209    _Example_
3210    \code
3211    XtsAes aes;
3212    struct XtsAesStreamData stream;
3213    byte key[32] = { }; // 256-bit key
3214    byte tweak[16] = { }; // tweak value
3215
3216    wc_AesXtsSetKey(&aes, key, 32, AES_ENCRYPTION, NULL, INVALID_DEVID);
3217    int ret = wc_AesXtsEncryptInit(&aes, tweak, 16, &stream);
3218    if (ret != 0) {
3219        // initialization failed
3220    }
3221    wc_AesXtsFree(&aes);
3222    \endcode
3223
3224    \sa wc_AesXtsEncryptUpdate
3225    \sa wc_AesXtsEncryptFinal
3226*/
3227int wc_AesXtsEncryptInit(XtsAes* aes, const byte* i, word32 iSz,
3228                         struct XtsAesStreamData *stream);
3229
3230/*!
3231    \ingroup AES
3232    \brief This function initializes streaming AES XTS decryption. It sets
3233    up the context for processing data in multiple update calls.
3234
3235    \return 0 On success.
3236    \return BAD_FUNC_ARG If parameters are invalid.
3237
3238    \param aes pointer to the XtsAes structure
3239    \param i pointer to the tweak/IV buffer
3240    \param iSz length of the tweak/IV in bytes
3241    \param stream pointer to XtsAesStreamData structure for streaming state
3242
3243    _Example_
3244    \code
3245    XtsAes aes;
3246    struct XtsAesStreamData stream;
3247    byte key[32] = { }; // 256-bit key
3248    byte tweak[16] = { }; // tweak value
3249
3250    wc_AesXtsSetKey(&aes, key, 32, AES_DECRYPTION, NULL, INVALID_DEVID);
3251    int ret = wc_AesXtsDecryptInit(&aes, tweak, 16, &stream);
3252    if (ret != 0) {
3253        // initialization failed
3254    }
3255    wc_AesXtsFree(&aes);
3256    \endcode
3257
3258    \sa wc_AesXtsDecryptUpdate
3259    \sa wc_AesXtsDecryptFinal
3260*/
3261int wc_AesXtsDecryptInit(XtsAes* aes, const byte* i, word32 iSz,
3262                         struct XtsAesStreamData *stream);
3263
3264/*!
3265    \ingroup AES
3266    \brief This function performs an update step of streaming AES XTS
3267    encryption. It processes a chunk of data and can be called multiple
3268    times.
3269
3270    \return 0 On success.
3271    \return BAD_FUNC_ARG If parameters are invalid.
3272
3273    \param aes pointer to the XtsAes structure
3274    \param out pointer to buffer to store encrypted data
3275    \param in pointer to plaintext data to encrypt
3276    \param sz length of data in bytes
3277    \param stream pointer to XtsAesStreamData structure for streaming state
3278
3279    _Example_
3280    \code
3281    XtsAes aes;
3282    struct XtsAesStreamData stream;
3283    byte key[32] = { }; // 256-bit key
3284    byte tweak[16] = { }; // tweak value
3285    byte plaintext[100] = { }; // data
3286    byte ciphertext[100];
3287
3288    wc_AesXtsSetKey(&aes, key, 32, AES_ENCRYPTION, NULL, INVALID_DEVID);
3289    wc_AesXtsEncryptInit(&aes, tweak, 16, &stream);
3290    int ret = wc_AesXtsEncryptUpdate(&aes, ciphertext, plaintext, 100,
3291                                     &stream);
3292    if (ret != 0) {
3293        // encryption failed
3294    }
3295    wc_AesXtsFree(&aes);
3296    \endcode
3297
3298    \sa wc_AesXtsEncryptInit
3299    \sa wc_AesXtsEncryptFinal
3300*/
3301int wc_AesXtsEncryptUpdate(XtsAes* aes, byte* out, const byte* in,
3302                           word32 sz, struct XtsAesStreamData *stream);
3303
3304/*!
3305    \ingroup AES
3306    \brief This function performs an update step of streaming AES XTS
3307    decryption. It processes a chunk of data and can be called multiple
3308    times.
3309
3310    \return 0 On success.
3311    \return BAD_FUNC_ARG If parameters are invalid.
3312
3313    \param aes pointer to the XtsAes structure
3314    \param out pointer to buffer to store decrypted data
3315    \param in pointer to ciphertext data to decrypt
3316    \param sz length of data in bytes
3317    \param stream pointer to XtsAesStreamData structure for streaming state
3318
3319    _Example_
3320    \code
3321    XtsAes aes;
3322    struct XtsAesStreamData stream;
3323    byte key[32] = { }; // 256-bit key
3324    byte tweak[16] = { }; // tweak value
3325    byte ciphertext[100] = { }; // encrypted data
3326    byte plaintext[100];
3327
3328    wc_AesXtsSetKey(&aes, key, 32, AES_DECRYPTION, NULL, INVALID_DEVID);
3329    wc_AesXtsDecryptInit(&aes, tweak, 16, &stream);
3330    int ret = wc_AesXtsDecryptUpdate(&aes, plaintext, ciphertext, 100,
3331                                     &stream);
3332    if (ret != 0) {
3333        // decryption failed
3334    }
3335    wc_AesXtsFree(&aes);
3336    \endcode
3337
3338    \sa wc_AesXtsDecryptInit
3339    \sa wc_AesXtsDecryptFinal
3340*/
3341int wc_AesXtsDecryptUpdate(XtsAes* aes, byte* out, const byte* in,
3342                           word32 sz, struct XtsAesStreamData *stream);
3343
3344/*!
3345    \ingroup AES
3346    \brief This function finalizes streaming AES XTS encryption. It
3347    processes any remaining data and completes the encryption operation.
3348
3349    \return 0 On success.
3350    \return BAD_FUNC_ARG If parameters are invalid.
3351
3352    \param aes pointer to the XtsAes structure
3353    \param out pointer to buffer to store final encrypted data
3354    \param in pointer to final plaintext data to encrypt
3355    \param sz length of final data in bytes
3356    \param stream pointer to XtsAesStreamData structure for streaming state
3357
3358    _Example_
3359    \code
3360    XtsAes aes;
3361    struct XtsAesStreamData stream;
3362    byte key[32] = { }; // 256-bit key
3363    byte tweak[16] = { }; // tweak value
3364    byte plaintext[50] = { }; // final data
3365    byte ciphertext[50];
3366
3367    wc_AesXtsSetKey(&aes, key, 32, AES_ENCRYPTION, NULL, INVALID_DEVID);
3368    wc_AesXtsEncryptInit(&aes, tweak, 16, &stream);
3369    // ... update calls ...
3370    int ret = wc_AesXtsEncryptFinal(&aes, ciphertext, plaintext, 50,
3371                                    &stream);
3372    if (ret != 0) {
3373        // finalization failed
3374    }
3375    wc_AesXtsFree(&aes);
3376    \endcode
3377
3378    \sa wc_AesXtsEncryptUpdate
3379    \sa wc_AesXtsEncryptInit
3380*/
3381int wc_AesXtsEncryptFinal(XtsAes* aes, byte* out, const byte* in,
3382                          word32 sz, struct XtsAesStreamData *stream);
3383
3384/*!
3385    \ingroup AES
3386    \brief This function finalizes streaming AES XTS decryption. It
3387    processes any remaining data and completes the decryption operation.
3388
3389    \return 0 On success.
3390    \return BAD_FUNC_ARG If parameters are invalid.
3391
3392    \param aes pointer to the XtsAes structure
3393    \param out pointer to buffer to store final decrypted data
3394    \param in pointer to final ciphertext data to decrypt
3395    \param sz length of final data in bytes
3396    \param stream pointer to XtsAesStreamData structure for streaming state
3397
3398    _Example_
3399    \code
3400    XtsAes aes;
3401    struct XtsAesStreamData stream;
3402    byte key[32] = { }; // 256-bit key
3403    byte tweak[16] = { }; // tweak value
3404    byte ciphertext[50] = { }; // final encrypted data
3405    byte plaintext[50];
3406
3407    wc_AesXtsSetKey(&aes, key, 32, AES_DECRYPTION, NULL, INVALID_DEVID);
3408    wc_AesXtsDecryptInit(&aes, tweak, 16, &stream);
3409    // ... update calls ...
3410    int ret = wc_AesXtsDecryptFinal(&aes, plaintext, ciphertext, 50,
3411                                    &stream);
3412    if (ret != 0) {
3413        // finalization failed
3414    }
3415    wc_AesXtsFree(&aes);
3416    \endcode
3417
3418    \sa wc_AesXtsDecryptUpdate
3419    \sa wc_AesXtsDecryptInit
3420*/
3421int wc_AesXtsDecryptFinal(XtsAes* aes, byte* out, const byte* in,
3422                          word32 sz, struct XtsAesStreamData *stream);
3423
3424/*!
3425    \ingroup AES
3426    \brief This function retrieves the key size from an initialized AES
3427    structure. It returns the size of the key currently set in the AES
3428    object.
3429
3430    \return 0 On success.
3431    \return BAD_FUNC_ARG If aes or keySize is NULL.
3432
3433    \param aes pointer to the AES structure
3434    \param keySize pointer to word32 to store the key size in bytes
3435
3436    _Example_
3437    \code
3438    Aes aes;
3439    byte key[16] = { }; // 128-bit key
3440    word32 keySize;
3441
3442    wc_AesInit(&aes, NULL, INVALID_DEVID);
3443    wc_AesSetKey(&aes, key, 16, NULL, AES_ENCRYPTION);
3444    int ret = wc_AesGetKeySize(&aes, &keySize);
3445    if (ret == 0) {
3446        // keySize now contains 16
3447    }
3448    wc_AesFree(&aes);
3449    \endcode
3450
3451    \sa wc_AesSetKey
3452    \sa wc_AesInit
3453*/
3454int wc_AesGetKeySize(Aes* aes, word32* keySize);
3455
3456/*!
3457    \ingroup AES
3458    \brief This function initializes an AES structure with an ID. This is
3459    useful for tracking or identifying specific AES instances in
3460    applications that manage multiple AES contexts.
3461
3462    \note This API is only available when WOLF_PRIVATE_KEY_ID is defined,
3463    which is set for PKCS11 support.
3464
3465    \return 0 On success.
3466    \return BAD_FUNC_ARG If aes or id is NULL, or if len is invalid.
3467
3468    \param aes pointer to the AES structure to initialize
3469    \param id pointer to the ID buffer
3470    \param len length of the ID in bytes
3471    \param heap pointer to heap hint for memory allocation (can be NULL)
3472    \param devId device ID for hardware acceleration (use INVALID_DEVID
3473    for software)
3474
3475    _Example_
3476    \code
3477    Aes aes;
3478    byte id[8] = { }; // unique identifier
3479
3480    int ret = wc_AesInit_Id(&aes, id, 8, NULL, INVALID_DEVID);
3481    if (ret != 0) {
3482        // initialization failed
3483    }
3484    wc_AesFree(&aes);
3485    \endcode
3486
3487    \sa wc_AesInit
3488    \sa wc_AesInit_Label
3489*/
3490int wc_AesInit_Id(Aes* aes, unsigned char* id, int len, void* heap,
3491                  int devId);
3492
3493/*!
3494    \ingroup AES
3495    \brief This function initializes an AES structure with a label string.
3496    This is useful for tracking or identifying specific AES instances with
3497    human-readable names.
3498
3499    \note This API is only available when WOLF_PRIVATE_KEY_ID is defined,
3500    which is set for PKCS11 support.
3501
3502    \return 0 On success.
3503    \return BAD_FUNC_ARG If aes or label is NULL.
3504
3505    \param aes pointer to the AES structure to initialize
3506    \param label pointer to the null-terminated label string
3507    \param heap pointer to heap hint for memory allocation (can be NULL)
3508    \param devId device ID for hardware acceleration (use INVALID_DEVID
3509    for software)
3510
3511    _Example_
3512    \code
3513    Aes aes;
3514
3515    int ret = wc_AesInit_Label(&aes, "MyAESContext", NULL, INVALID_DEVID);
3516    if (ret != 0) {
3517        // initialization failed
3518    }
3519    wc_AesFree(&aes);
3520    \endcode
3521
3522    \sa wc_AesInit
3523    \sa wc_AesInit_Id
3524*/
3525int wc_AesInit_Label(Aes* aes, const char* label, void* heap, int devId);
3526
3527/*!
3528    \ingroup AES
3529    \brief This function allocates and initializes a new AES structure.
3530    It returns a pointer to the allocated structure, which must be freed
3531    with wc_AesDelete when no longer needed. These New/Delete functions
3532    are exposed to support allocation of the structure using dynamic memory
3533    to provide better ABI compatibility.
3534
3535    \note This API is only available when WC_NO_CONSTRUCTORS is not defined.
3536    WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is
3537    defined.
3538
3539    \return Pointer to allocated Aes structure on success.
3540    \return NULL on allocation failure.
3541
3542    \param heap pointer to heap hint for memory allocation (can be NULL)
3543    \param devId device ID for hardware acceleration (use INVALID_DEVID
3544    for software)
3545    \param result_code pointer to int to store result code (can be NULL)
3546
3547    _Example_
3548    \code
3549    int result;
3550    Aes* aes = wc_AesNew(NULL, INVALID_DEVID, &result);
3551    if (aes == NULL || result != 0) {
3552        // allocation or initialization failed
3553    }
3554    // use aes...
3555    wc_AesDelete(aes, &aes);
3556    \endcode
3557
3558    \sa wc_AesDelete
3559    \sa wc_AesInit
3560*/
3561Aes* wc_AesNew(void* heap, int devId, int *result_code);
3562
3563/*!
3564    \ingroup AES
3565    \brief This function frees an AES structure that was allocated with
3566    wc_AesNew. It also sets the pointer to NULL to prevent use-after-free.
3567    These New/Delete functions are exposed to support allocation of the
3568    structure using dynamic memory to provide better ABI compatibility.
3569
3570    \note This API is only available when WC_NO_CONSTRUCTORS is not defined.
3571    WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is
3572    defined.
3573
3574    \return 0 On success.
3575    \return BAD_FUNC_ARG If aes or aes_p is NULL.
3576
3577    \param aes pointer to the AES structure to free
3578    \param aes_p pointer to the AES pointer (will be set to NULL)
3579
3580    _Example_
3581    \code
3582    Aes* aes = wc_AesNew(NULL, INVALID_DEVID, NULL);
3583    if (aes != NULL) {
3584        // use aes...
3585        int ret = wc_AesDelete(aes, &aes);
3586        // aes is now NULL
3587    }
3588    \endcode
3589
3590    \sa wc_AesNew
3591    \sa wc_AesFree
3592*/
3593int wc_AesDelete(Aes* aes, Aes** aes_p);
3594
3595/*!
3596    \ingroup AES
3597    \brief This function performs AES-SIV (Synthetic IV) encryption with
3598    extended parameters. AES-SIV provides nonce-misuse resistance and
3599    deterministic authenticated encryption.
3600
3601    \return 0 On success.
3602    \return BAD_FUNC_ARG If parameters are invalid.
3603    \return Other negative values on error.
3604
3605    \param key pointer to the key buffer (32, 48, or 64 bytes for SIV)
3606    \param keySz length of the key in bytes
3607    \param assoc pointer to array of associated data structures
3608    \param numAssoc number of associated data items
3609    \param nonce pointer to the nonce buffer (can be NULL)
3610    \param nonceSz length of the nonce in bytes
3611    \param in pointer to plaintext to encrypt
3612    \param inSz length of plaintext in bytes
3613    \param siv pointer to buffer to store the SIV (16 bytes)
3614    \param out pointer to buffer to store ciphertext
3615
3616    _Example_
3617    \code
3618    byte key[32] = { }; // 256-bit key for AES-128-SIV
3619    AesSivAssoc assoc[1];
3620    byte aad[20] = { }; // associated data
3621    byte nonce[12] = { }; // nonce
3622    byte plaintext[100] = { }; // data
3623    byte siv[16];
3624    byte ciphertext[100];
3625
3626    assoc[0].data = aad;
3627    assoc[0].sz = 20;
3628
3629    int ret = wc_AesSivEncrypt_ex(key, 32, assoc, 1, nonce, 12,
3630                                  plaintext, 100, siv, ciphertext);
3631    if (ret != 0) {
3632        // encryption failed
3633    }
3634    \endcode
3635
3636    \sa wc_AesSivDecrypt_ex
3637    \sa wc_AesSivEncrypt
3638*/
3639int wc_AesSivEncrypt_ex(const byte* key, word32 keySz,
3640                        const AesSivAssoc* assoc, word32 numAssoc,
3641                        const byte* nonce, word32 nonceSz, const byte* in,
3642                        word32 inSz, byte* siv, byte* out);
3643
3644/*!
3645    \ingroup AES
3646    \brief This function performs AES-SIV (Synthetic IV) decryption with
3647    extended parameters. It verifies the SIV and decrypts the ciphertext.
3648
3649    \return 0 On successful decryption and verification.
3650    \return AES_SIV_AUTH_E If SIV verification fails.
3651    \return BAD_FUNC_ARG If parameters are invalid.
3652    \return Other negative values on error.
3653
3654    \param key pointer to the key buffer (32, 48, or 64 bytes for SIV)
3655    \param keySz length of the key in bytes
3656    \param assoc pointer to array of associated data structures
3657    \param numAssoc number of associated data items
3658    \param nonce pointer to the nonce buffer (can be NULL)
3659    \param nonceSz length of the nonce in bytes
3660    \param in pointer to ciphertext to decrypt
3661    \param inSz length of ciphertext in bytes
3662    \param siv pointer to the SIV to verify (16 bytes)
3663    \param out pointer to buffer to store plaintext
3664
3665    _Example_
3666    \code
3667    byte key[32] = { }; // 256-bit key for AES-128-SIV
3668    AesSivAssoc assoc[1];
3669    byte aad[20] = { }; // associated data
3670    byte nonce[12] = { }; // nonce
3671    byte ciphertext[100] = { }; // encrypted data
3672    byte siv[16] = { }; // received SIV
3673    byte plaintext[100];
3674
3675    assoc[0].data = aad;
3676    assoc[0].sz = 20;
3677
3678    int ret = wc_AesSivDecrypt_ex(key, 32, assoc, 1, nonce, 12,
3679                                  ciphertext, 100, siv, plaintext);
3680    if (ret != 0) {
3681        // decryption or verification failed
3682    }
3683    \endcode
3684
3685    \sa wc_AesSivEncrypt_ex
3686    \sa wc_AesSivDecrypt
3687*/
3688int wc_AesSivDecrypt_ex(const byte* key, word32 keySz,
3689                        const AesSivAssoc* assoc, word32 numAssoc,
3690                        const byte* nonce, word32 nonceSz, const byte* in,
3691                        word32 inSz, byte* siv, byte* out);