sha3.h 30 KB

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