luna - wolfssl/doc/dox_comments/header

   1/*!
   2    \ingroup SHA
   3
   4    \brief This function initializes SHA3-224. This is automatically
   5    called by wc_Sha3_224Hash.
   6
   7    \return 0 Returned upon successfully initializing
   8
   9    \param sha3 pointer to the sha3 structure to use for encryption
  10
  11    _Example_
  12    \code
  13    wc_Sha3 sha3[1];
  14    if ((ret = wc_InitSha3_224(sha3, NULL, INVALID_DEVID)) != 0) {
  15        WOLFSSL_MSG("wc_InitSha3_224 failed");
  16    }
  17    else {
  18        wc_Sha3_224_Update(sha3, data, len);
  19        wc_Sha3_224_Final(sha3, hash);
  20    }
  21    \endcode
  22
  23    \sa wc_Sha3_224Hash
  24    \sa wc_Sha3_224_Update
  25    \sa wc_Sha3_224_Final
  26*/
  27int wc_InitSha3_224(wc_Sha3* sha3, void* heap, int devId);
  28
  29/*!
  30    \ingroup SHA
  31
  32    \brief Can be called to continually hash the provided byte
  33    array of length len.
  34
  35    \return 0 Returned upon successfully adding the data to the digest.
  36
  37    \param sha3 pointer to the sha3 structure to use for encryption
  38    \param data the data to be hashed
  39    \param len length of data to be hashed
  40
  41    _Example_
  42    \code
  43    wc_Sha3 sha3[1];
  44    byte data[] = { Data to be hashed };
  45    word32 len = sizeof(data);
  46
  47    if ((ret = wc_InitSha3_224(sha3, NULL, INVALID_DEVID)) != 0) {
  48       WOLFSSL_MSG("wc_InitSha3_224 failed");
  49    }
  50    else {
  51        wc_Sha3_224_Update(sha3, data, len);
  52        wc_Sha3_224_Final(sha3, hash);
  53    }
  54    \endcode
  55
  56    \sa wc_Sha3_224Hash
  57    \sa wc_Sha3_224_Final
  58    \sa wc_InitSha3_224
  59*/
  60int wc_Sha3_224_Update(wc_Sha3* sha, const byte* data, word32 len);
  61
  62/*!
  63    \ingroup SHA
  64
  65    \brief Finalizes hashing of data. Result is placed into hash.
  66    Resets state of sha3 struct.
  67
  68    \return 0 Returned upon successfully finalizing.
  69
  70    \param sha3 pointer to the sha3 structure to use for encryption
  71    \param hash Byte array to hold hash value.
  72
  73    _Example_
  74    \code
  75    wc_Sha3 sha3[1];
  76    byte data[] = { Data to be hashed };
  77    word32 len = sizeof(data);
  78
  79    if ((ret = wc_InitSha3_224(sha3, NULL, INVALID_DEVID)) != 0) {
  80       WOLFSSL_MSG("wc_InitSha3_224 failed");
  81    }
  82    else {
  83       wc_Sha3_224_Update(sha3, data, len);
  84       wc_Sha3_224_Final(sha3, hash);
  85    }
  86    \endcode
  87
  88    \sa wc_Sha3_224Hash
  89    \sa wc_Sha3_224_GetHash
  90    \sa wc_InitSha3_224
  91*/
  92int wc_Sha3_224_Final(wc_Sha3* sha3, byte* hash);
  93
  94/*!
  95    \ingroup SHA
  96
  97    \brief Resets the wc_Sha3 structure.  Note: this is only supported
  98    if you have WOLFSSL_TI_HASH defined.
  99
 100    \return none No returns.
 101
 102    \param sha3 Pointer to the sha3 structure to be freed.
 103
 104    _Example_
 105    \code
 106    wc_Sha3 sha3;
 107    byte data[] = { Data to be hashed };
 108    word32 len = sizeof(data);
 109
 110    if ((ret = wc_InitSha3_224(&sha3, NULL, INVALID_DEVID)) != 0) {
 111        WOLFSSL_MSG("wc_InitSha3_224 failed");
 112    }
 113    else {
 114        wc_Sha3_224_Update(&sha3, data, len);
 115        wc_Sha3_224_Final(&sha3, hash);
 116        wc_Sha3_224_Free(&sha3);
 117    }
 118    \endcode
 119
 120    \sa wc_InitSha3_224
 121    \sa wc_Sha3_224_Update
 122    \sa wc_Sha3_224_Final
 123*/
 124void wc_Sha3_224_Free(wc_Sha3* sha3);
 125
 126/*!
 127    \ingroup SHA
 128
 129    \brief Gets hash data. Result is placed into hash.  Does not
 130    reset state of sha3 struct.
 131
 132    \return 0 Returned upon successful copying of the hash.
 133
 134    \param sha3 pointer to the sha3 structure to use for encryption
 135    \param hash Byte array to hold hash value.
 136
 137    _Example_
 138    \code
 139    wc_Sha3 sha3[1];
 140    if ((ret = wc_InitSha3_224(sha3, NULL, INVALID_DEVID)) != 0) {
 141       WOLFSSL_MSG("wc_InitSha3_224 failed");
 142    }
 143    else {
 144       wc_Sha3_224_Update(sha3, data, len);
 145       wc_Sha3_224_GetHash(sha3, hash);
 146    }
 147    \endcode
 148
 149    \sa wc_Sha3_224Hash
 150    \sa wc_Sha3_224_Final
 151    \sa wc_InitSha3_224
 152    \sa wc_Sha3_224_Copy
 153*/
 154int wc_Sha3_224_GetHash(wc_Sha3* sha3, byte* hash);
 155
 156/*!
 157    \ingroup SHA
 158
 159    \brief Copy the state of the hash.
 160
 161    \return 0 Returned upon successful copying.
 162
 163    \param sha3 pointer to the sha3 structure to copy
 164    \param dst  pointer to the sha3 structure to copy into
 165
 166    _Example_
 167    \code
 168    wc_Sha3 sha3[1];
 169    wc_Sha3 sha3_dup[1];
 170    if ((ret = wc_InitSha3_224(sha3, NULL, INVALID_DEVID)) != 0) {
 171       WOLFSSL_MSG("wc_InitSha3_224 failed");
 172    }
 173    else {
 174       wc_Sha3_224_Update(sha3, data, len);
 175       wc_Sha3_224_Copy(sha3, sha3_dup);
 176    }
 177    \endcode
 178
 179    \sa wc_Sha3_224Hash
 180    \sa wc_Sha3_224_Final
 181    \sa wc_InitSha3_224
 182    \sa wc_Sha3_224_GetHash
 183*/
 184int wc_Sha3_224_Copy(wc_Sha3* sha3, wc_Sha3* dst);
 185
 186/*!
 187    \ingroup SHA
 188
 189    \brief This function initializes SHA3-256. This is automatically
 190    called by wc_Sha3_256Hash.
 191
 192    \return 0 Returned upon successfully initializing
 193
 194    \param sha3 pointer to the sha3 structure to use for encryption
 195
 196    _Example_
 197    \code
 198    wc_Sha3 sha3[1];
 199    if ((ret = wc_InitSha3_256(sha3, NULL, INVALID_DEVID)) != 0) {
 200        WOLFSSL_MSG("wc_InitSha3_256 failed");
 201    }
 202    else {
 203        wc_Sha3_256_Update(sha3, data, len);
 204        wc_Sha3_256_Final(sha3, hash);
 205    }
 206    \endcode
 207
 208    \sa wc_Sha3_256Hash
 209    \sa wc_Sha3_256_Update
 210    \sa wc_Sha3_256_Final
 211*/
 212int wc_InitSha3_256(wc_Sha3* sha3, void* heap, int devId);
 213
 214/*!
 215    \ingroup SHA
 216
 217    \brief Can be called to continually hash the provided byte
 218    array of length len.
 219
 220    \return 0 Returned upon successfully adding the data to the digest.
 221
 222    \param sha3 pointer to the sha3 structure to use for encryption
 223    \param data the data to be hashed
 224    \param len length of data to be hashed
 225
 226    _Example_
 227    \code
 228    wc_Sha3 sha3[1];
 229    byte data[] = { Data to be hashed };
 230    word32 len = sizeof(data);
 231
 232    if ((ret = wc_InitSha3_256(sha3, NULL, INVALID_DEVID)) != 0) {
 233       WOLFSSL_MSG("wc_InitSha3_256 failed");
 234    }
 235    else {
 236        wc_Sha3_256_Update(sha3, data, len);
 237        wc_Sha3_256_Final(sha3, hash);
 238    }
 239    \endcode
 240
 241    \sa wc_Sha3_256Hash
 242    \sa wc_Sha3_256_Final
 243    \sa wc_InitSha3_256
 244*/
 245int wc_Sha3_256_Update(wc_Sha3* sha, const byte* data, word32 len);
 246
 247/*!
 248    \ingroup SHA
 249
 250    \brief Finalizes hashing of data. Result is placed into hash.
 251    Resets state of sha3 struct.
 252
 253    \return 0 Returned upon successfully finalizing.
 254
 255    \param sha3 pointer to the sha3 structure to use for encryption
 256    \param hash Byte array to hold hash value.
 257
 258    _Example_
 259    \code
 260    wc_Sha3 sha3[1];
 261    byte data[] = { Data to be hashed };
 262    word32 len = sizeof(data);
 263
 264    if ((ret = wc_InitSha3_256(sha3, NULL, INVALID_DEVID)) != 0) {
 265       WOLFSSL_MSG("wc_InitSha3_256 failed");
 266    }
 267    else {
 268       wc_Sha3_256_Update(sha3, data, len);
 269       wc_Sha3_256_Final(sha3, hash);
 270    }
 271    \endcode
 272
 273    \sa wc_Sha3_256Hash
 274    \sa wc_Sha3_256_GetHash
 275    \sa wc_InitSha3_256
 276*/
 277int wc_Sha3_256_Final(wc_Sha3* sha3, byte* hash);
 278
 279/*!
 280    \ingroup SHA
 281
 282    \brief Resets the wc_Sha3 structure.  Note: this is only supported
 283    if you have WOLFSSL_TI_HASH defined.
 284
 285    \return none No returns.
 286
 287    \param sha3 Pointer to the sha3 structure to be freed.
 288
 289    _Example_
 290    \code
 291    wc_Sha3 sha3;
 292    byte data[] = { Data to be hashed };
 293    word32 len = sizeof(data);
 294
 295    if ((ret = wc_InitSha3_256(&sha3, NULL, INVALID_DEVID)) != 0) {
 296        WOLFSSL_MSG("wc_InitSha3_256 failed");
 297    }
 298    else {
 299        wc_Sha3_256_Update(&sha3, data, len);
 300        wc_Sha3_256_Final(&sha3, hash);
 301        wc_Sha3_256_Free(&sha3);
 302    }
 303    \endcode
 304
 305    \sa wc_InitSha3_256
 306    \sa wc_Sha3_256_Update
 307    \sa wc_Sha3_256_Final
 308*/
 309void wc_Sha3_256_Free(wc_Sha3* sha3);
 310
 311/*!
 312    \ingroup SHA
 313
 314    \brief Gets hash data. Result is placed into hash.  Does not
 315    reset state of sha3 struct.
 316
 317    \return 0 Returned upon successful copying of the hash.
 318
 319    \param sha3 pointer to the sha3 structure to use for encryption
 320    \param hash Byte array to hold hash value.
 321
 322    _Example_
 323    \code
 324    wc_Sha3 sha3[1];
 325    if ((ret = wc_InitSha3_256(sha3, NULL, INVALID_DEVID)) != 0) {
 326       WOLFSSL_MSG("wc_InitSha3_256 failed");
 327    }
 328    else {
 329       wc_Sha3_256_Update(sha3, data, len);
 330       wc_Sha3_256_GetHash(sha3, hash);
 331    }
 332    \endcode
 333
 334    \sa wc_Sha3_256Hash
 335    \sa wc_Sha3_256_Final
 336    \sa wc_InitSha3_256
 337    \sa wc_Sha3_256_Copy
 338*/
 339int wc_Sha3_256_GetHash(wc_Sha3* sha3, byte* hash);
 340
 341/*!
 342    \ingroup SHA
 343
 344    \brief Copy the state of the hash.
 345
 346    \return 0 Returned upon successful copying.
 347
 348    \param sha3 pointer to the sha3 structure to copy
 349    \param dst  pointer to the sha3 structure to copy into
 350
 351    _Example_
 352    \code
 353    wc_Sha3 sha3[1];
 354    wc_Sha3 sha3_dup[1];
 355    if ((ret = wc_InitSha3_256(sha3, NULL, INVALID_DEVID)) != 0) {
 356       WOLFSSL_MSG("wc_InitSha3_256 failed");
 357    }
 358    else {
 359       wc_Sha3_256_Update(sha3, data, len);
 360       wc_Sha3_256_Copy(sha3, sha3_dup);
 361    }
 362    \endcode
 363
 364    \sa wc_Sha3_256Hash
 365    \sa wc_Sha3_256_Final
 366    \sa wc_InitSha3_256
 367    \sa wc_Sha3_256_GetHash
 368*/
 369int wc_Sha3_256_Copy(wc_Sha3* sha3, wc_Sha3* dst);
 370
 371/*!
 372    \ingroup SHA
 373
 374    \brief This function initializes SHA3-384. This is automatically
 375    called by wc_Sha3_384Hash.
 376
 377    \return 0 Returned upon successfully initializing
 378
 379    \param sha3 pointer to the sha3 structure to use for encryption
 380
 381    _Example_
 382    \code
 383    wc_Sha3 sha3[1];
 384    if ((ret = wc_InitSha3_384(sha3, NULL, INVALID_DEVID)) != 0) {
 385        WOLFSSL_MSG("wc_InitSha3_384 failed");
 386    }
 387    else {
 388        wc_Sha3_384_Update(sha3, data, len);
 389        wc_Sha3_384_Final(sha3, hash);
 390    }
 391    \endcode
 392
 393    \sa wc_Sha3_384Hash
 394    \sa wc_Sha3_384_Update
 395    \sa wc_Sha3_384_Final
 396*/
 397int wc_InitSha3_384(wc_Sha3* sha3, void* heap, int devId);
 398
 399/*!
 400    \ingroup SHA
 401
 402    \brief Can be called to continually hash the provided byte
 403    array of length len.
 404
 405    \return 0 Returned upon successfully adding the data to the digest.
 406
 407    \param sha3 pointer to the sha3 structure to use for encryption
 408    \param data the data to be hashed
 409    \param len length of data to be hashed
 410
 411    _Example_
 412    \code
 413    wc_Sha3 sha3[1];
 414    byte data[] = { Data to be hashed };
 415    word32 len = sizeof(data);
 416
 417    if ((ret = wc_InitSha3_384(sha3, NULL, INVALID_DEVID)) != 0) {
 418       WOLFSSL_MSG("wc_InitSha3_384 failed");
 419    }
 420    else {
 421        wc_Sha3_384_Update(sha3, data, len);
 422        wc_Sha3_384_Final(sha3, hash);
 423    }
 424    \endcode
 425
 426    \sa wc_Sha3_384Hash
 427    \sa wc_Sha3_384_Final
 428    \sa wc_InitSha3_384
 429*/
 430int wc_Sha3_384_Update(wc_Sha3* sha, const byte* data, word32 len);
 431
 432/*!
 433    \ingroup SHA
 434
 435    \brief Finalizes hashing of data. Result is placed into hash.
 436    Resets state of sha3 struct.
 437
 438    \return 0 Returned upon successfully finalizing.
 439
 440    \param sha3 pointer to the sha3 structure to use for encryption
 441    \param hash Byte array to hold hash value.
 442
 443    _Example_
 444    \code
 445    wc_Sha3 sha3[1];
 446    byte data[] = { Data to be hashed };
 447    word32 len = sizeof(data);
 448
 449    if ((ret = wc_InitSha3_384(sha3, NULL, INVALID_DEVID)) != 0) {
 450       WOLFSSL_MSG("wc_InitSha3_384 failed");
 451    }
 452    else {
 453       wc_Sha3_384_Update(sha3, data, len);
 454       wc_Sha3_384_Final(sha3, hash);
 455    }
 456    \endcode
 457
 458    \sa wc_Sha3_384Hash
 459    \sa wc_Sha3_384_GetHash
 460    \sa wc_InitSha3_384
 461*/
 462int wc_Sha3_384_Final(wc_Sha3* sha3, byte* hash);
 463
 464/*!
 465    \ingroup SHA
 466
 467    \brief Resets the wc_Sha3 structure.  Note: this is only supported
 468    if you have WOLFSSL_TI_HASH defined.
 469
 470    \return none No returns.
 471
 472    \param sha3 Pointer to the sha3 structure to be freed.
 473
 474    _Example_
 475    \code
 476    wc_Sha3 sha3;
 477    byte data[] = { Data to be hashed };
 478    word32 len = sizeof(data);
 479
 480    if ((ret = wc_InitSha3_384(&sha3, NULL, INVALID_DEVID)) != 0) {
 481        WOLFSSL_MSG("wc_InitSha3_384 failed");
 482    }
 483    else {
 484        wc_Sha3_384_Update(&sha3, data, len);
 485        wc_Sha3_384_Final(&sha3, hash);
 486        wc_Sha3_384_Free(&sha3);
 487    }
 488    \endcode
 489
 490    \sa wc_InitSha3_384
 491    \sa wc_Sha3_384_Update
 492    \sa wc_Sha3_384_Final
 493*/
 494void wc_Sha3_384_Free(wc_Sha3* sha3);
 495
 496/*!
 497    \ingroup SHA
 498
 499    \brief Gets hash data. Result is placed into hash.  Does not
 500    reset state of sha3 struct.
 501
 502    \return 0 Returned upon successful copying of the hash.
 503
 504    \param sha3 pointer to the sha3 structure to use for encryption
 505    \param hash Byte array to hold hash value.
 506
 507    _Example_
 508    \code
 509    wc_Sha3 sha3[1];
 510    if ((ret = wc_InitSha3_384(sha3, NULL, INVALID_DEVID)) != 0) {
 511       WOLFSSL_MSG("wc_InitSha3_38384ailed");
 512    }
 513    else {
 514       wc_Sha3_384_Update(sha3, data, len);
 515       wc_Sha3_384_GetHash(sha3, hash);
 516    }
 517    \endcode
 518
 519    \sa wc_Sha3_384Hash
 520    \sa wc_Sha3_384_Final
 521    \sa wc_InitSha3_384
 522    \sa wc_Sha3_384_Copy
 523*/
 524int wc_Sha3_384_GetHash(wc_Sha3* sha3, byte* hash);
 525
 526/*!
 527    \ingroup SHA
 528
 529    \brief Copy the state of the hash.
 530
 531    \return 0 Returned upon successful copying.
 532
 533    \param sha3 pointer to the sha3 structure to copy
 534    \param dst  pointer to the sha3 structure to copy into
 535
 536    _Example_
 537    \code
 538    wc_Sha3 sha3[1];
 539    wc_Sha3 sha3_dup[1];
 540    if ((ret = wc_InitSha3_384(sha3, NULL, INVALID_DEVID)) != 0) {
 541       WOLFSSL_MSG("wc_InitSha3_384 failed");
 542    }
 543    else {
 544       wc_Sha3_384_Update(sha3, data, len);
 545       wc_Sha3_384_Copy(sha3, sha3_dup);
 546    }
 547    \endcode
 548
 549    \sa wc_Sha3_384Hash
 550    \sa wc_Sha3_384_Final
 551    \sa wc_InitSha3_384
 552    \sa wc_Sha3_384_GetHash
 553*/
 554int wc_Sha3_384_Copy(wc_Sha3* sha3, wc_Sha3* dst);
 555
 556/*!
 557    \ingroup SHA
 558
 559    \brief This function initializes SHA3-512. This is automatically
 560    called by wc_Sha3_512Hash.
 561
 562    \return 0 Returned upon successfully initializing
 563
 564    \param sha3 pointer to the sha3 structure to use for encryption
 565
 566    _Example_
 567    \code
 568    wc_Sha3 sha3[1];
 569    if ((ret = wc_InitSha3_512(sha3, NULL, INVALID_DEVID)) != 0) {
 570        WOLFSSL_MSG("wc_InitSha3_512 failed");
 571    }
 572    else {
 573        wc_Sha3_512_Update(sha3, data, len);
 574        wc_Sha3_512_Final(sha3, hash);
 575    }
 576    \endcode
 577
 578    \sa wc_Sha3_512Hash
 579    \sa wc_Sha3_512_Update
 580    \sa wc_Sha3_512_Final
 581*/
 582int wc_InitSha3_512(wc_Sha3* sha3, void* heap, int devId);
 583
 584/*!
 585    \ingroup SHA
 586
 587    \brief Can be called to continually hash the provided byte
 588    array of length len.
 589
 590    \return 0 Returned upon successfully adding the data to the digest.
 591
 592    \param sha3 pointer to the sha3 structure to use for encryption
 593    \param data the data to be hashed
 594    \param len length of data to be hashed
 595
 596    _Example_
 597    \code
 598    wc_Sha3 sha3[1];
 599    byte data[] = { Data to be hashed };
 600    word32 len = sizeof(data);
 601
 602    if ((ret = wc_InitSha3_512(sha3, NULL, INVALID_DEVID)) != 0) {
 603       WOLFSSL_MSG("wc_InitSha3_512 failed");
 604    }
 605    else {
 606        wc_Sha3_512_Update(sha3, data, len);
 607        wc_Sha3_512_Final(sha3, hash);
 608    }
 609    \endcode
 610
 611    \sa wc_Sha3_512Hash
 612    \sa wc_Sha3_512_Final
 613    \sa wc_InitSha3_512
 614*/
 615int wc_Sha3_512_Update(wc_Sha3* sha, const byte* data, word32 len);
 616
 617/*!
 618    \ingroup SHA
 619
 620    \brief Finalizes hashing of data. Result is placed into hash.
 621    Resets state of sha3 struct.
 622
 623    \return 0 Returned upon successfully finalizing.
 624
 625    \param sha3 pointer to the sha3 structure to use for encryption
 626    \param hash Byte array to hold hash value.
 627
 628    _Example_
 629    \code
 630    wc_Sha3 sha3[1];
 631    byte data[] = { Data to be hashed };
 632    word32 len = sizeof(data);
 633
 634    if ((ret = wc_InitSha3_512(sha3, NULL, INVALID_DEVID)) != 0) {
 635       WOLFSSL_MSG("wc_InitSha3_512 failed");
 636    }
 637    else {
 638       wc_Sha3_512_Update(sha3, data, len);
 639       wc_Sha3_512_Final(sha3, hash);
 640    }
 641    \endcode
 642
 643    \sa wc_Sha3_512Hash
 644    \sa wc_Sha3_512_GetHash
 645    \sa wc_InitSha3_512
 646*/
 647int wc_Sha3_512_Final(wc_Sha3* sha3, byte* hash);
 648
 649/*!
 650    \ingroup SHA
 651
 652    \brief Resets the wc_Sha3 structure.  Note: this is only supported
 653    if you have WOLFSSL_TI_HASH defined.
 654
 655    \return none No returns.
 656
 657    \param sha3 Pointer to the sha3 structure to be freed.
 658
 659    _Example_
 660    \code
 661    wc_Sha3 sha3;
 662    byte data[] = { Data to be hashed };
 663    word32 len = sizeof(data);
 664
 665    if ((ret = wc_InitSha3_512(&sha3, NULL, INVALID_DEVID)) != 0) {
 666        WOLFSSL_MSG("wc_InitSha3_512 failed");
 667    }
 668    else {
 669        wc_Sha3_512_Update(&sha3, data, len);
 670        wc_Sha3_512_Final(&sha3, hash);
 671        wc_Sha3_512_Free(&sha3);
 672    }
 673    \endcode
 674
 675    \sa wc_InitSha3_512
 676    \sa wc_Sha3_512_Update
 677    \sa wc_Sha3_512_Final
 678*/
 679void wc_Sha3_512_Free(wc_Sha3* sha3);
 680
 681/*!
 682    \ingroup SHA
 683
 684    \brief Gets hash data. Result is placed into hash.  Does not
 685    reset state of sha3 struct.
 686
 687    \return 0 Returned upon successful copying of the hash.
 688
 689    \param sha3 pointer to the sha3 structure to use for encryption
 690    \param hash Byte array to hold hash value.
 691
 692    _Example_
 693    \code
 694    wc_Sha3 sha3[1];
 695    if ((ret = wc_InitSha3_512(sha3, NULL, INVALID_DEVID)) != 0) {
 696       WOLFSSL_MSG("wc_InitSha3_512 failed");
 697    }
 698    else {
 699       wc_Sha3_512_Update(sha3, data, len);
 700       wc_Sha3_512_GetHash(sha3, hash);
 701    }
 702    \endcode
 703
 704    \sa wc_Sha3_512Hash
 705    \sa wc_Sha3_512_Final
 706    \sa wc_InitSha3_512
 707    \sa wc_Sha3_512_Copy
 708*/
 709int wc_Sha3_512_GetHash(wc_Sha3* sha3, byte* hash);
 710
 711/*!
 712    \ingroup SHA
 713
 714    \brief Copy the state of the hash.
 715
 716    \return 0 Returned upon successful copying.
 717
 718    \param sha3 pointer to the sha3 structure to copy
 719    \param dst  pointer to the sha3 structure to copy into
 720
 721    _Example_
 722    \code
 723    wc_Sha3 sha3[1];
 724    wc_Sha3 sha3_dup[1];
 725    if ((ret = wc_InitSha3_512(sha3, NULL, INVALID_DEVID)) != 0) {
 726       WOLFSSL_MSG("wc_InitSha3_512 failed");
 727    }
 728    else {
 729       wc_Sha3_512_Update(sha3, data, len);
 730       wc_Sha3_512_Copy(sha3, sha3_dup);
 731    }
 732    \endcode
 733
 734    \sa wc_Sha3_512Hash
 735    \sa wc_Sha3_512_Final
 736    \sa wc_InitSha3_512
 737    \sa wc_Sha3_512_GetHash
 738*/
 739int wc_Sha3_512_Copy(wc_Sha3* sha3, wc_Sha3* dst);
 740
 741/*!
 742    \ingroup SHA
 743
 744    \brief This function initializes SHAKE-128. This is automatically
 745    called by wc_Shake128Hash.
 746
 747    \return 0 Returned upon successfully initializing
 748
 749    \param shake pointer to the shake structure to use for encryption
 750
 751    _Example_
 752    \code
 753    wc_Shake shake[1];
 754    if ((ret = wc_InitShake128(shake, NULL, INVALID_DEVID)) != 0) {
 755        WOLFSSL_MSG("wc_InitShake128 failed");
 756    }
 757    else {
 758        wc_Shake128_Update(shake, data, len);
 759        wc_Shake128_Final(shake, hash);
 760    }
 761    \endcode
 762
 763    \sa wc_Shake128Hash
 764    \sa wc_Shake128_Update
 765    \sa wc_Shake128_Final
 766*/
 767int wc_InitShake128(wc_Shake* shake, void* heap, int devId);
 768
 769/*!
 770    \ingroup SHA
 771
 772    \brief Can be called to continually hash the provided byte
 773    array of length len.
 774
 775    \return 0 Returned upon successfully adding the data to the digest.
 776
 777    \param shake pointer to the shake structure to use for encryption
 778    \param data the data to be hashed
 779    \param len length of data to be hashed
 780
 781    _Example_
 782    \code
 783    wc_Shake shake[1];
 784    byte data[] = { Data to be hashed };
 785    word32 len = sizeof(data);
 786
 787    if ((ret = wc_InitShake128(shake, NULL, INVALID_DEVID)) != 0) {
 788       WOLFSSL_MSG("wc_InitShake128 failed");
 789    }
 790    else {
 791        wc_Shake128_Update(shake, data, len);
 792        wc_Shake128_Final(shake, hash);
 793    }
 794    \endcode
 795
 796    \sa wc_Shake128Hash
 797    \sa wc_Shake128_Final
 798    \sa wc_InitShake128
 799*/
 800int wc_Shake128_Update(wc_Shake* sha, const byte* data, word32 len);
 801
 802/*!
 803    \ingroup SHA
 804
 805    \brief Finalizes hashing of data. Result is placed into hash.
 806    Resets state of shake struct.
 807
 808    \return 0 Returned upon successfully finalizing.
 809
 810    \param shake pointer to the shake structure to use for encryption
 811    \param hash Byte array to hold hash value.
 812    \param hashLen Number of bytes to write to hash.
 813
 814    _Example_
 815    \code
 816    wc_Shake shake[1];
 817    byte data[] = { Data to be hashed };
 818    word32 len = sizeof(data);
 819
 820    if ((ret = wc_InitShake128(shake, NULL, INVALID_DEVID)) != 0) {
 821       WOLFSSL_MSG("wc_InitShake128 failed");
 822    }
 823    else {
 824       wc_Shake128_Update(shake, data, len);
 825       wc_Shake128_Final(shake, hash);
 826    }
 827    \endcode
 828
 829    \sa wc_Shake128Hash
 830    \sa wc_Shake128_GetHash
 831    \sa wc_InitShake128
 832*/
 833int wc_Shake128_Final(wc_Shake* shake, byte* hash, word32 hashLen);
 834
 835/*!
 836    \ingroup SHA
 837
 838    \brief Called to absorb the provided byte array of length len. Cannot
 839    be called incrementally.
 840
 841    \return 0 Returned upon successfully absorbed the data.
 842
 843    \param shake pointer to the shake structure to use for encryption
 844    \param data the data to be absorbed
 845    \param len length of data to be absorbed
 846
 847    _Example_
 848    \code
 849    wc_Shake shake[1];
 850    byte data[] = { Data to be hashed };
 851    word32 len = sizeof(data);
 852    byte out[2 * WC_SHA3_128_BLOCK_SIZE];
 853    int blocks = 2;
 854
 855    if ((ret = wc_InitShake128(shake, NULL, INVALID_DEVID)) != 0) {
 856       WOLFSSL_MSG("wc_InitShake128 failed");
 857    }
 858    else {
 859       wc_Shake128_Absorb(shake, data, len);
 860       wc_Shake128_SqueezeBlocks(shake, out, blocks);
 861    }
 862    \endcode
 863
 864    \sa wc_Shake128_SqueezeBlocks
 865    \sa wc_InitShake128
 866*/
 867int wc_Shake128_Absorb(wc_Shake* sha, const byte* data, word32 len);
 868
 869/*!
 870    \ingroup SHA
 871
 872    \brief Squeeze out more blocks of data. Result is placed into out. Can be
 873    called inrementally.
 874
 875    \return 0 Returned upon successfully squeezing.
 876
 877    \param shake pointer to the shake structure to use for encryption
 878    \param hash Byte array to hold output.
 879    \param blocks Number of blocks to squeeze out. Each block is
 880    WC_SHA3_128_BLOCK_SIZE bytes in length.
 881
 882    _Example_
 883    \code
 884    wc_Shake shake[1];
 885    byte data[] = { Data to be hashed };
 886    word32 len = sizeof(data);
 887    byte out[2 * WC_SHA3_128_BLOCK_SIZE];
 888    int blocks = 2;
 889
 890    if ((ret = wc_InitShake128(shake, NULL, INVALID_DEVID)) != 0) {
 891       WOLFSSL_MSG("wc_InitShake128 failed");
 892    }
 893    else {
 894       wc_Shake128_Absorb(shake, data, len);
 895       wc_Shake128_SqueezeBlocks(shake, out, blocks);
 896    }
 897    \endcode
 898
 899    \sa wc_Shake128_Absorb
 900    \sa wc_InitShake128
 901*/
 902int wc_Shake128_SqueezeBlocks(wc_Shake* shake, byte* out, word32 blockCnt);
 903
 904/*!
 905    \ingroup SHA
 906
 907    \brief Resets the wc_Shake structure.  Note: this is only supported
 908    if you have WOLFSSL_TI_HASH defined.
 909
 910    \return none No returns.
 911
 912    \param shake Pointer to the shake structure to be freed.
 913
 914    _Example_
 915    \code
 916    wc_Shake shake;
 917    byte data[] = { Data to be hashed };
 918    word32 len = sizeof(data);
 919
 920    if ((ret = wc_InitShake128(&shake, NULL, INVALID_DEVID)) != 0) {
 921        WOLFSSL_MSG("wc_InitShake128 failed");
 922    }
 923    else {
 924        wc_Shake128_Update(&shake, data, len);
 925        wc_Shake128_Final(&shake, hash);
 926        wc_Shake128_Free(&shake);
 927    }
 928    \endcode
 929
 930    \sa wc_InitShake128
 931    \sa wc_Shake128_Update
 932    \sa wc_Shake128_Final
 933*/
 934void wc_Shake128_Free(wc_Shake* shake);
 935
 936/*!
 937    \ingroup SHA
 938
 939    \brief Gets hash data. Result is placed into hash.  Does not
 940    reset state of shake struct.
 941
 942    \return 0 Returned upon successful copying of the hash.
 943
 944    \param shake pointer to the shake structure to use for encryption
 945    \param hash Byte array to hold hash value.
 946
 947    _Example_
 948    \code
 949    wc_Shake shake[1];
 950    if ((ret = wc_InitShake128(shake, NULL, INVALID_DEVID)) != 0) {
 951       WOLFSSL_MSG("wc_InitShake128 failed");
 952    }
 953    else {
 954       wc_Shake128_Update(shake, data, len);
 955       wc_Shake128_GetHash(shake, hash);
 956    }
 957    \endcode
 958
 959    \sa wc_Shake128Hash
 960    \sa wc_Shake128_Final
 961    \sa wc_InitShake128
 962    \sa wc_Shake128_Copy
 963*/
 964int wc_Shake128_GetHash(wc_Shake* shake, byte* hash);
 965
 966/*!
 967    \ingroup SHA
 968
 969    \brief Copy the state of the hash.
 970
 971    \return 0 Returned upon successful copying.
 972
 973    \param shake pointer to the shake structure to copy
 974    \param dst  pointer to the shake structure to copy into
 975
 976    _Example_
 977    \code
 978    wc_Shake shake[1];
 979    wc_Shake shake_dup[1];
 980    if ((ret = wc_InitShake128(shake, NULL, INVALID_DEVID)) != 0) {
 981       WOLFSSL_MSG("wc_InitShake128 failed");
 982    }
 983    else {
 984       wc_Shake128_Update(shake, data, len);
 985       wc_Shake128_Copy(shake, shake_dup);
 986    }
 987    \endcode
 988
 989    \sa wc_Shake128Hash
 990    \sa wc_Shake128_Final
 991    \sa wc_InitShake128
 992    \sa wc_Shake128_GetHash
 993*/
 994int wc_Shake128_Copy(wc_Shake* src, wc_Sha3* dst);
 995
 996/*!
 997    \ingroup SHA
 998
 999    \brief This function initializes SHAKE-256. This is automatically
1000    called by wc_Shake256Hash.
1001
1002    \return 0 Returned upon successfully initializing
1003
1004    \param shake pointer to the shake structure to use for encryption
1005
1006    _Example_
1007    \code
1008    wc_Shake shake[1];
1009    if ((ret = wc_InitShake256(shake, NULL, INVALID_DEVID)) != 0) {
1010        WOLFSSL_MSG("wc_InitShake256 failed");
1011    }
1012    else {
1013        wc_Shake256_Update(shake, data, len);
1014        wc_Shake256_Final(shake, hash, sizeof(hash));
1015    }
1016    \endcode
1017
1018    \sa wc_Shake256Hash
1019    \sa wc_Shake256_Update
1020    \sa wc_Shake256_Final
1021*/
1022int wc_InitShake256(wc_Shake* shake, void* heap, int devId);
1023
1024/*!
1025    \ingroup SHA
1026
1027    \brief Can be called to continually hash the provided byte
1028    array of length len.
1029
1030    \return 0 Returned upon successfully adding the data to the digest.
1031
1032    \param shake pointer to the shake structure to use for encryption
1033    \param data the data to be hashed
1034    \param len length of data to be hashed
1035
1036    _Example_
1037    \code
1038    wc_Shake shake[1];
1039    byte data[] = { Data to be hashed };
1040    word32 len = sizeof(data);
1041
1042    if ((ret = wc_InitShake256(shake, NULL, INVALID_DEVID)) != 0) {
1043       WOLFSSL_MSG("wc_InitShake256 failed");
1044    }
1045    else {
1046        wc_Shake256_Update(shake, data, len);
1047        wc_Shake256_Final(shake, hash, sizeof(hash));
1048    }
1049    \endcode
1050
1051    \sa wc_Shake256Hash
1052    \sa wc_Shake256_Final
1053    \sa wc_InitShake256
1054*/
1055int wc_Shake256_Update(wc_Shake* sha, const byte* data, word32 len);
1056
1057/*!
1058    \ingroup SHA
1059
1060    \brief Finalizes hashing of data. Result is placed into hash.
1061    Resets state of shake struct.
1062
1063    \return 0 Returned upon successfully finalizing.
1064
1065    \param shake pointer to the shake structure to use for encryption
1066    \param hash Byte array to hold hash value.
1067    \param hashLen Size of hash in bytes.
1068
1069    _Example_
1070    \code
1071    wc_Shake shake[1];
1072    byte data[] = { Data to be hashed };
1073    word32 len = sizeof(data);
1074
1075    if ((ret = wc_InitShake256(shake, NULL, INVALID_DEVID)) != 0) {
1076       WOLFSSL_MSG("wc_InitShake256 failed");
1077    }
1078    else {
1079       wc_Shake256_Update(shake, data, len);
1080       wc_Shake256_Final(shake, hash, sizeof(hash));
1081    }
1082    \endcode
1083
1084    \sa wc_Shake256Hash
1085    \sa wc_Shake256_GetHash
1086    \sa wc_InitShake256
1087*/
1088int wc_Shake256_Final(wc_Shake* shake, byte* hash, word32 hashLen);
1089
1090/*!
1091    \ingroup SHA
1092
1093    \brief Called to absorb the provided byte array of length len. Cannot
1094    be called incrementally.
1095
1096    \return 0 Returned upon successfully absorbed the data.
1097
1098    \param shake pointer to the shake structure to use for encryption
1099    \param data the data to be absorbed
1100    \param len length of data to be absorbed
1101
1102    _Example_
1103    \code
1104    wc_Shake shake[1];
1105    byte data[] = { Data to be hashed };
1106    word32 len = sizeof(data);
1107    byte out[2 * WC_SHA3_256_BLOCK_SIZE];
1108    int blocks = 2;
1109
1110    if ((ret = wc_InitShake256(shake, NULL, INVALID_DEVID)) != 0) {
1111       WOLFSSL_MSG("wc_InitShake256 failed");
1112    }
1113    else {
1114       wc_Shake256_Absorb(shake, data, len);
1115       wc_Shake256_SqueezeBlocks(shake, out, blocks);
1116    }
1117    \endcode
1118
1119    \sa wc_Shake256_SqueezeBlocks
1120    \sa wc_InitShake256
1121*/
1122int wc_Shake256_Absorb(wc_Shake* sha, const byte* data, word32 len);
1123
1124/*!
1125    \ingroup SHA
1126
1127    \brief Squeeze out more blocks of data. Result is placed into out. Can be
1128    called incrementally.
1129
1130    \return 0 Returned upon successfully squeezing.
1131
1132    \param shake pointer to the shake structure to use for encryption
1133    \param hash Byte array to hold output.
1134    \param blocks Number of blocks to squeeze out. Each block is
1135    WC_SHA3_256_BLOCK_SIZE bytes in length.
1136
1137    _Example_
1138    \code
1139    wc_Shake shake[1];
1140    byte data[] = { Data to be hashed };
1141    word32 len = sizeof(data);
1142    byte out[2 * WC_SHA3_256_BLOCK_SIZE];
1143    int blocks = 2;
1144
1145    if ((ret = wc_InitShake256(shake, NULL, INVALID_DEVID)) != 0) {
1146       WOLFSSL_MSG("wc_InitShake256 failed");
1147    }
1148    else {
1149       wc_Shake256_Absorb(shake, data, len);
1150       wc_Shake256_SqueezeBlocks(shake, out, blocks);
1151    }
1152    \endcode
1153
1154    \sa wc_Shake256_Absorb
1155    \sa wc_InitShake256
1156*/
1157int wc_Shake256_SqueezeBlocks(wc_Shake* shake, byte* out, word32 blockCnt);
1158
1159/*!
1160    \ingroup SHA
1161
1162    \brief Resets the wc_Shake structure.  Note: this is only supported
1163    if you have WOLFSSL_TI_HASH defined.
1164
1165    \return none No returns.
1166
1167    \param shake Pointer to the shake structure to be freed.
1168
1169    _Example_
1170    \code
1171    wc_Shake shake;
1172    byte data[] = { Data to be hashed };
1173    word32 len = sizeof(data);
1174
1175    if ((ret = wc_InitShake256(&shake, NULL, INVALID_DEVID)) != 0) {
1176        WOLFSSL_MSG("wc_InitShake256 failed");
1177    }
1178    else {
1179        wc_Shake256_Update(&shake, data, len);
1180        wc_Shake256_Final(&shake, hash, sizeof(hash));
1181        wc_Shake256_Free(&shake);
1182    }
1183    \endcode
1184
1185    \sa wc_InitShake256
1186    \sa wc_Shake256_Update
1187    \sa wc_Shake256_Final
1188*/
1189void wc_Shake256_Free(wc_Shake* shake);
1190
1191/*!
1192    \ingroup SHA
1193
1194    \brief Gets hash data. Result is placed into hash.  Does not
1195    reset state of shake struct.
1196
1197    \return 0 Returned upon successful copying of the hash.
1198
1199    \param shake pointer to the shake structure to use for encryption
1200    \param hash Byte array to hold hash value.
1201
1202    _Example_
1203    \code
1204    wc_Shake shake[1];
1205    if ((ret = wc_InitShake256(shake, NULL, INVALID_DEVID)) != 0) {
1206       WOLFSSL_MSG("wc_InitShake256 failed");
1207    }
1208    else {
1209       wc_Shake256_Update(shake, data, len);
1210       wc_Shake256_GetHash(shake, hash);
1211    }
1212    \endcode
1213
1214    \sa wc_Shake256Hash
1215    \sa wc_Shake256_Final
1216    \sa wc_InitShake256
1217    \sa wc_Shake256_Copy
1218*/
1219int wc_Shake256_GetHash(wc_Shake* shake, byte* hash);
1220
1221/*!
1222    \ingroup SHA
1223
1224    \brief Copy the state of the hash.
1225
1226    \return 0 Returned upon successful copying.
1227
1228    \param shake pointer to the shake structure to copy
1229    \param dst  pointer to the shake structure to copy into
1230
1231    _Example_
1232    \code
1233    wc_Shake shake[1];
1234    wc_Shake shake_dup[1];
1235    if ((ret = wc_InitShake256(shake, NULL, INVALID_DEVID)) != 0) {
1236       WOLFSSL_MSG("wc_InitShake256 failed");
1237    }
1238    else {
1239       wc_Shake256_Update(shake, data, len);
1240       wc_Shake256_Copy(shake, shake_dup);
1241    }
1242    \endcode
1243
1244    \sa wc_Shake256Hash
1245    \sa wc_Shake256_Final
1246    \sa wc_InitShake256
1247    \sa wc_Shake256_GetHash
1248*/
1249int wc_Shake256_Copy(wc_Shake* src, wc_Sha3* dst);