1
0

aes.h 58 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729
  1. /*!
  2. \ingroup AES
  3. \brief This function initializes an AES structure by setting the key and
  4. then setting the initialization vector.
  5. \return 0 On successfully setting key and initialization vector.
  6. \return BAD_FUNC_ARG Returned if key length is invalid.
  7. \param aes pointer to the AES structure to modify
  8. \param key 16, 24, or 32 byte secret key for encryption and decryption
  9. \param len length of the key passed in
  10. \param iv pointer to the initialization vector used to initialize the key
  11. \param dir Cipher direction. Set AES_ENCRYPTION to encrypt, or
  12. AES_DECRYPTION to decrypt. Direction for some modes (CFB and CTR) is
  13. always AES_ENCRYPTION.
  14. _Example_
  15. \code
  16. Aes enc;
  17. int ret = 0;
  18. byte key[] = { some 16, 24 or 32 byte key };
  19. byte iv[] = { some 16 byte iv };
  20. if (ret = wc_AesInit(&enc, HEAP_HINT, INVALID_DEVID) != 0) {
  21. // failed to initialize aes key
  22. }
  23. if (ret = wc_AesSetKey(&enc, key, AES_BLOCK_SIZE, iv,
  24. AES_ENCRYPTION) != 0) {
  25. // failed to set aes key
  26. }
  27. \endcode
  28. \sa wc_AesSetKeyDirect
  29. \sa wc_AesSetIV
  30. */
  31. int wc_AesSetKey(Aes* aes, const byte* key, word32 len,
  32. const byte* iv, int dir);
  33. /*!
  34. \ingroup AES
  35. \brief This function sets the initialization vector for a
  36. particular AES object. The AES object should be initialized before
  37. calling this function.
  38. \return 0 On successfully setting initialization vector.
  39. \return BAD_FUNC_ARG Returned if AES pointer is NULL.
  40. \param aes pointer to the AES structure on which to set the
  41. initialization vector
  42. \param iv initialization vector used to initialize the AES structure.
  43. If the value is NULL, the default action initializes the iv to 0.
  44. _Example_
  45. \code
  46. Aes enc;
  47. // set enc key
  48. byte iv[] = { some 16 byte iv };
  49. if (ret = wc_AesSetIV(&enc, iv) != 0) {
  50. // failed to set aes iv
  51. }
  52. \endcode
  53. \sa wc_AesSetKeyDirect
  54. \sa wc_AesSetKey
  55. */
  56. int wc_AesSetIV(Aes* aes, const byte* iv);
  57. /*!
  58. \ingroup AES
  59. \brief Encrypts a plaintext message from the input buffer in, and places
  60. the resulting cipher text in the output buffer out using cipher block
  61. chaining with AES. This function requires that the AES object has been
  62. initialized by calling AesSetKey before a message is able to be encrypted.
  63. This function assumes that the input message is AES block length aligned,
  64. and expects the input length to be a multiple of the block length, which
  65. will optionally be checked and enforced if WOLFSSL_AES_CBC_LENGTH_CHECKS
  66. is defined in the build configuration. In order to assure block-multiple
  67. input, PKCS#7 style padding should be added beforehand. This differs from
  68. the OpenSSL AES-CBC methods which add the padding for you. To make the
  69. wolfSSL and corresponding OpenSSL functions interoperate, one should specify
  70. the -nopad option in the OpenSSL command line function so that it behaves
  71. like the wolfSSL AesCbcEncrypt method and does not add extra padding
  72. during encryption.
  73. \return 0 On successfully encrypting message.
  74. \return BAD_ALIGN_E: may be returned on block align error
  75. \return BAD_LENGTH_E will be returned if the input length isn't a
  76. multiple of the AES block length, when the library is built with
  77. WOLFSSL_AES_CBC_LENGTH_CHECKS.
  78. \param aes pointer to the AES object used to encrypt data
  79. \param out pointer to the output buffer in which to store the ciphertext
  80. of the encrypted message
  81. \param in pointer to the input buffer containing message to be encrypted
  82. \param sz size of input message
  83. _Example_
  84. \code
  85. Aes enc;
  86. int ret = 0;
  87. // initialize enc with wc_AesInit and wc_AesSetKey, using direction
  88. // AES_ENCRYPTION
  89. byte msg[AES_BLOCK_SIZE * n]; // multiple of 16 bytes
  90. // fill msg with data
  91. byte cipher[AES_BLOCK_SIZE * n]; // Some multiple of 16 bytes
  92. if ((ret = wc_AesCbcEncrypt(&enc, cipher, message, sizeof(msg))) != 0 ) {
  93. // block align error
  94. }
  95. \endcode
  96. \sa wc_AesInit
  97. \sa wc_AesSetKey
  98. \sa wc_AesSetIV
  99. \sa wc_AesCbcDecrypt
  100. */
  101. int wc_AesCbcEncrypt(Aes* aes, byte* out,
  102. const byte* in, word32 sz);
  103. /*!
  104. \ingroup AES
  105. \brief Decrypts a cipher from the input buffer in, and places the
  106. resulting plain text in the output buffer out using cipher block chaining
  107. with AES. This function requires that the AES structure has been
  108. initialized by calling AesSetKey before a message is able to be decrypted.
  109. This function assumes that the original message was AES block length
  110. aligned, and expects the input length to be a multiple of the block length,
  111. which will optionally be checked and enforced if
  112. WOLFSSL_AES_CBC_LENGTH_CHECKS is defined in the build configuration.
  113. This differs from the OpenSSL AES-CBC methods, which add PKCS#7 padding
  114. automatically, and so do not require block-multiple input. To make the
  115. wolfSSL function and equivalent OpenSSL functions interoperate, one
  116. should specify the -nopad option in the OpenSSL command line function
  117. so that it behaves like the wolfSSL AesCbcEncrypt method and does not
  118. create errors during decryption.
  119. \return 0 On successfully decrypting message.
  120. \return BAD_ALIGN_E may be returned on block align error.
  121. \return BAD_LENGTH_E will be returned if the input length isn't a
  122. multiple of the AES block length, when the library is built with
  123. WOLFSSL_AES_CBC_LENGTH_CHECKS.
  124. \param aes pointer to the AES object used to decrypt data.
  125. \param out pointer to the output buffer in which to store the plain text
  126. of the decrypted message.
  127. size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
  128. \param in pointer to the input buffer containing cipher text to be
  129. decrypted.
  130. size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
  131. \param sz size of input message.
  132. _Example_
  133. \code
  134. Aes dec;
  135. int ret = 0;
  136. // initialize dec with wc_AesInit and wc_AesSetKey, using direction
  137. // AES_DECRYPTION
  138. byte cipher[AES_BLOCK_SIZE * n]; // some multiple of 16 bytes
  139. // fill cipher with cipher text
  140. byte plain [AES_BLOCK_SIZE * n];
  141. if ((ret = wc_AesCbcDecrypt(&dec, plain, cipher, sizeof(cipher))) != 0 ) {
  142. // block align error
  143. }
  144. \endcode
  145. \sa wc_AesInit
  146. \sa wc_AesSetKey
  147. \sa wc_AesCbcEncrypt
  148. */
  149. int wc_AesCbcDecrypt(Aes* aes, byte* out,
  150. const byte* in, word32 sz);
  151. /*!
  152. \ingroup AES
  153. \brief Encrypts/Decrypts a message from the input buffer in, and places
  154. the resulting cipher text in the output buffer out using CTR mode with
  155. AES. This function is only enabled if WOLFSSL_AES_COUNTER is enabled at
  156. compile time. The AES structure should be initialized through AesSetKey
  157. before calling this function. Note that this function is used for both
  158. decryption and encryption. _NOTE:_ Regarding using same API for encryption
  159. and decryption. User should differentiate between Aes structures
  160. for encrypt/decrypt.
  161. \return int integer values corresponding to wolfSSL error or success
  162. status
  163. \param aes pointer to the AES object used to decrypt data
  164. \param out pointer to the output buffer in which to store the cipher
  165. text of the encrypted message
  166. size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
  167. \param in pointer to the input buffer containing plain text to be encrypted
  168. size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
  169. \param sz size of the input plain text
  170. _Example_
  171. \code
  172. Aes enc;
  173. Aes dec;
  174. // initialize enc and dec with wc_AesInit and wc_AesSetKeyDirect, using
  175. // direction AES_ENCRYPTION since the underlying API only calls Encrypt
  176. // and by default calling encrypt on a cipher results in a decryption of
  177. // the cipher
  178. byte msg[AES_BLOCK_SIZE * n]; //n being a positive integer making msg
  179. some multiple of 16 bytes
  180. // fill plain with message text
  181. byte cipher[AES_BLOCK_SIZE * n];
  182. byte decrypted[AES_BLOCK_SIZE * n];
  183. wc_AesCtrEncrypt(&enc, cipher, msg, sizeof(msg)); // encrypt plain
  184. wc_AesCtrEncrypt(&dec, decrypted, cipher, sizeof(cipher));
  185. // decrypt cipher text
  186. \endcode
  187. \sa wc_AesSetKey
  188. */
  189. int wc_AesCtrEncrypt(Aes* aes, byte* out,
  190. const byte* in, word32 sz);
  191. /*!
  192. \ingroup AES
  193. \brief This function is a one-block encrypt of the input block, in, into
  194. the output block, out. It uses the key of the provided AES structure, which
  195. should be initialized with wc_AesSetKey before calling this function.
  196. wc_AesSetKey should have been called with the iv set to NULL. This is only
  197. enabled if the configure option WOLFSSL_AES_DIRECT is enabled. __Warning:__
  198. In nearly all use cases ECB mode is considered to be less secure. Please
  199. avoid using ECB API’s directly whenever possible.
  200. \return int integer values corresponding to wolfSSL error or success
  201. status
  202. \param aes pointer to the AES object used to encrypt data
  203. \param out pointer to the output buffer in which to store the cipher
  204. text of the encrypted message
  205. \param in pointer to the input buffer containing plain text to be encrypted
  206. _Example_
  207. \code
  208. Aes enc;
  209. // initialize enc with wc_AesInit and wc_AesSetKey, using direction
  210. // AES_ENCRYPTION
  211. byte msg [AES_BLOCK_SIZE]; // 16 bytes
  212. // initialize msg with plain text to encrypt
  213. byte cipher[AES_BLOCK_SIZE];
  214. wc_AesEncryptDirect(&enc, cipher, msg);
  215. \endcode
  216. \sa wc_AesDecryptDirect
  217. \sa wc_AesSetKeyDirect
  218. */
  219. int wc_AesEncryptDirect(Aes* aes, byte* out, const byte* in);
  220. /*!
  221. \ingroup AES
  222. \brief This function is a one-block decrypt of the input block, in, into
  223. the output block, out. It uses the key of the provided AES structure, which
  224. should be initialized with wc_AesSetKey before calling this function.
  225. wc_AesSetKey should have been called with the iv set to NULL. This is only
  226. enabled if the configure option WOLFSSL_AES_DIRECT is enabled. __Warning:__
  227. In nearly all use cases ECB mode is considered to be less secure. Please
  228. avoid using ECB API’s directly whenever possible.
  229. \return int integer values corresponding to wolfSSL error or success
  230. status
  231. \param aes pointer to the AES object used to encrypt data
  232. \param out pointer to the output buffer in which to store the plain
  233. text of the decrypted cipher text
  234. \param in pointer to the input buffer containing cipher text to be
  235. decrypted
  236. _Example_
  237. \code
  238. Aes dec;
  239. // initialize enc with wc_AesInit and wc_AesSetKey, using direction
  240. // AES_DECRYPTION
  241. byte cipher [AES_BLOCK_SIZE]; // 16 bytes
  242. // initialize cipher with cipher text to decrypt
  243. byte msg[AES_BLOCK_SIZE];
  244. wc_AesDecryptDirect(&dec, msg, cipher);
  245. \endcode
  246. \sa wc_AesEncryptDirect
  247. \sa wc_AesSetKeyDirect
  248. */
  249. int wc_AesDecryptDirect(Aes* aes, byte* out, const byte* in);
  250. /*!
  251. \ingroup AES
  252. \brief This function is used to set the AES keys for CTR mode with AES.
  253. It initializes an AES object with the given key, iv
  254. (initialization vector), and encryption dir (direction). It is only
  255. enabled if the configure option WOLFSSL_AES_DIRECT is enabled.
  256. Currently wc_AesSetKeyDirect uses wc_AesSetKey internally. __Warning:__ In
  257. nearly all use cases ECB mode is considered to be less secure. Please avoid
  258. using ECB API’s directly whenever possible
  259. \return 0 On successfully setting the key.
  260. \return BAD_FUNC_ARG Returned if the given key is an invalid length.
  261. \param aes pointer to the AES object used to encrypt data
  262. \param key 16, 24, or 32 byte secret key for encryption and decryption
  263. \param len length of the key passed in
  264. \param iv initialization vector used to initialize the key
  265. \param dir Cipher direction. Set AES_ENCRYPTION to encrypt, or
  266. AES_DECRYPTION to decrypt. (See enum in wolfssl/wolfcrypt/aes.h)
  267. (NOTE: If using wc_AesSetKeyDirect with Aes Counter mode (Stream cipher)
  268. only use AES_ENCRYPTION for both encrypting and decrypting)
  269. _Example_
  270. \code
  271. Aes enc;
  272. int ret = 0;
  273. byte key[] = { some 16, 24, or 32 byte key };
  274. byte iv[] = { some 16 byte iv };
  275. if (ret = wc_AesInit(&enc, HEAP_HINT, INVALID_DEVID) != 0) {
  276. // failed to initialize aes key
  277. }
  278. if (ret = wc_AesSetKeyDirect(&enc, key, sizeof(key), iv,
  279. AES_ENCRYPTION) != 0) {
  280. // failed to set aes key
  281. }
  282. \endcode
  283. \sa wc_AesEncryptDirect
  284. \sa wc_AesDecryptDirect
  285. \sa wc_AesSetKey
  286. */
  287. int wc_AesSetKeyDirect(Aes* aes, const byte* key, word32 len,
  288. const byte* iv, int dir);
  289. /*!
  290. \ingroup AES
  291. \brief This function is used to set the key for AES GCM
  292. (Galois/Counter Mode). It initializes an AES object with the
  293. given key. It is only enabled if the configure option
  294. HAVE_AESGCM is enabled at compile time.
  295. \return 0 On successfully setting the key.
  296. \return BAD_FUNC_ARG Returned if the given key is an invalid length.
  297. \param aes pointer to the AES object used to encrypt data
  298. \param key 16, 24, or 32 byte secret key for encryption and decryption
  299. \param len length of the key passed in
  300. _Example_
  301. \code
  302. Aes enc;
  303. int ret = 0;
  304. byte key[] = { some 16, 24,32 byte key };
  305. if (ret = wc_AesInit(&enc, HEAP_HINT, INVALID_DEVID) != 0) {
  306. // failed to initialize aes key
  307. }
  308. if (ret = wc_AesGcmSetKey(&enc, key, sizeof(key)) != 0) {
  309. // failed to set aes key
  310. }
  311. \endcode
  312. \sa wc_AesGcmEncrypt
  313. \sa wc_AesGcmDecrypt
  314. */
  315. int wc_AesGcmSetKey(Aes* aes, const byte* key, word32 len);
  316. /*!
  317. \ingroup AES
  318. \brief This function encrypts the input message, held in the buffer in,
  319. and stores the resulting cipher text in the output buffer out. It
  320. requires a new iv (initialization vector) for each call to encrypt.
  321. It also encodes the input authentication vector, authIn, into the
  322. authentication tag, authTag.
  323. \return 0 On successfully encrypting the input message
  324. \param aes - pointer to the AES object used to encrypt data
  325. \param out pointer to the output buffer in which to store the cipher text
  326. size must match in's size (sz)
  327. \param in pointer to the input buffer holding the message to encrypt
  328. size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
  329. \param sz length of the input message to encrypt
  330. \param iv pointer to the buffer containing the initialization vector
  331. \param ivSz length of the initialization vector
  332. \param authTag pointer to the buffer in which to store the
  333. authentication tag
  334. \param authTagSz length of the desired authentication tag
  335. \param authIn pointer to the buffer containing the input
  336. authentication vector
  337. \param authInSz length of the input authentication vector
  338. _Example_
  339. \code
  340. Aes enc;
  341. // initialize Aes structure by calling wc_AesInit() and wc_AesGcmSetKey
  342. byte plain[AES_BLOCK_LENGTH * n]; //n being a positive integer
  343. making plain some multiple of 16 bytes
  344. // initialize plain with msg to encrypt
  345. byte cipher[sizeof(plain)];
  346. byte iv[] = // some 16 byte iv
  347. byte authTag[AUTH_TAG_LENGTH];
  348. byte authIn[] = // Authentication Vector
  349. wc_AesGcmEncrypt(&enc, cipher, plain, sizeof(cipher), iv, sizeof(iv),
  350. authTag, sizeof(authTag), authIn, sizeof(authIn));
  351. \endcode
  352. \sa wc_AesGcmSetKey
  353. \sa wc_AesGcmDecrypt
  354. */
  355. int wc_AesGcmEncrypt(Aes* aes, byte* out,
  356. const byte* in, word32 sz,
  357. const byte* iv, word32 ivSz,
  358. byte* authTag, word32 authTagSz,
  359. const byte* authIn, word32 authInSz);
  360. /*!
  361. \ingroup AES
  362. \brief This function decrypts the input cipher text, held in the buffer
  363. in, and stores the resulting message text in the output buffer out.
  364. It also checks the input authentication vector, authIn, against the
  365. supplied authentication tag, authTag.
  366. \return 0 On successfully decrypting the input message
  367. \return AES_GCM_AUTH_E If the authentication tag does not match the
  368. supplied authentication code vector, authTag.
  369. \param aes pointer to the AES object used to encrypt data
  370. \param out pointer to the output buffer in which to store the message text
  371. size must match in's size (sz)
  372. \param in pointer to the input buffer holding the cipher text to decrypt
  373. size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
  374. \param sz length of the cipher text to decrypt
  375. \param iv pointer to the buffer containing the initialization vector
  376. \param ivSz length of the initialization vector
  377. \param authTag pointer to the buffer containing the authentication tag
  378. \param authTagSz length of the desired authentication tag
  379. \param authIn pointer to the buffer containing the input
  380. authentication vector
  381. \param authInSz length of the input authentication vector
  382. _Example_
  383. \code
  384. Aes enc; //can use the same struct as was passed to wc_AesGcmEncrypt
  385. // initialize aes structure by calling wc_AesInit and wc_AesGcmSetKey
  386. // if not already done
  387. byte cipher[AES_BLOCK_LENGTH * n]; //n being a positive integer
  388. making cipher some multiple of 16 bytes
  389. // initialize cipher with cipher text to decrypt
  390. byte output[sizeof(cipher)];
  391. byte iv[] = // some 16 byte iv
  392. byte authTag[AUTH_TAG_LENGTH];
  393. byte authIn[] = // Authentication Vector
  394. wc_AesGcmDecrypt(&enc, output, cipher, sizeof(cipher), iv, sizeof(iv),
  395. authTag, sizeof(authTag), authIn, sizeof(authIn));
  396. \endcode
  397. \sa wc_AesGcmSetKey
  398. \sa wc_AesGcmEncrypt
  399. */
  400. int wc_AesGcmDecrypt(Aes* aes, byte* out,
  401. const byte* in, word32 sz,
  402. const byte* iv, word32 ivSz,
  403. const byte* authTag, word32 authTagSz,
  404. const byte* authIn, word32 authInSz);
  405. /*!
  406. \ingroup AES
  407. \brief This function initializes and sets the key for a GMAC object
  408. to be used for Galois Message Authentication.
  409. \return 0 On successfully setting the key
  410. \return BAD_FUNC_ARG Returned if key length is invalid.
  411. \param gmac pointer to the gmac object used for authentication
  412. \param key 16, 24, or 32 byte secret key for authentication
  413. \param len length of the key
  414. _Example_
  415. \code
  416. Gmac gmac;
  417. key[] = { some 16, 24, or 32 byte length key };
  418. wc_AesInit(gmac.aes, HEAP_HINT, INVALID_DEVID); // Make sure devId updated
  419. wc_GmacSetKey(&gmac, key, sizeof(key));
  420. \endcode
  421. \sa wc_GmacUpdate
  422. \sa wc_AesInit
  423. */
  424. int wc_GmacSetKey(Gmac* gmac, const byte* key, word32 len);
  425. /*!
  426. \ingroup AES
  427. \brief This function generates the Gmac hash of the authIn input and
  428. stores the result in the authTag buffer. After running wc_GmacUpdate,
  429. one should compare the generated authTag to a known authentication tag
  430. to verify the authenticity of a message.
  431. \return 0 On successfully computing the Gmac hash.
  432. \param gmac pointer to the gmac object used for authentication
  433. \param iv initialization vector used for the hash
  434. \param ivSz size of the initialization vector used
  435. \param authIn pointer to the buffer containing the authentication
  436. vector to verify
  437. \param authInSz size of the authentication vector
  438. \param authTag pointer to the output buffer in which to store the Gmac hash
  439. \param authTagSz the size of the output buffer used to store the Gmac hash
  440. _Example_
  441. \code
  442. Gmac gmac;
  443. key[] = { some 16, 24, or 32 byte length key };
  444. iv[] = { some 16 byte length iv };
  445. wc_AesInit(gmac.aes, HEAP_HINT, INVALID_DEVID); // Make sure devId updated
  446. wc_GmacSetKey(&gmac, key, sizeof(key));
  447. authIn[] = { some 16 byte authentication input };
  448. tag[AES_BLOCK_SIZE]; // will store authentication code
  449. wc_GmacUpdate(&gmac, iv, sizeof(iv), authIn, sizeof(authIn), tag,
  450. sizeof(tag));
  451. \endcode
  452. \sa wc_GmacSetKey
  453. \sa wc_AesInit
  454. */
  455. int wc_GmacUpdate(Gmac* gmac, const byte* iv, word32 ivSz,
  456. const byte* authIn, word32 authInSz,
  457. byte* authTag, word32 authTagSz);
  458. /*!
  459. \ingroup AES
  460. \brief This function sets the key for an AES object using CCM
  461. (Counter with CBC-MAC). It takes a pointer to an AES structure and
  462. initializes it with supplied key.
  463. \return none
  464. \param aes aes structure in which to store the supplied key
  465. \param key 16, 24, or 32 byte secret key for encryption and decryption
  466. \param keySz size of the supplied key
  467. _Example_
  468. \code
  469. Aes enc;
  470. key[] = { some 16, 24, or 32 byte length key };
  471. wc_AesInit(&enc, HEAP_HINT, INVALID_DEVID); // Make sure devId updated
  472. wc_AesCcmSetKey(&enc, key, sizeof(key));
  473. \endcode
  474. \sa wc_AesCcmEncrypt
  475. \sa wc_AesCcmDecrypt
  476. */
  477. int wc_AesCcmSetKey(Aes* aes, const byte* key, word32 keySz);
  478. /*!
  479. \ingroup AES
  480. \brief This function encrypts the input message, in, into the output
  481. buffer, out, using CCM (Counter with CBC-MAC). It subsequently
  482. calculates and stores the authorization tag, authTag, from the
  483. authIn input.
  484. \return none
  485. \param aes pointer to the AES object used to encrypt data
  486. \param out pointer to the output buffer in which to store the cipher text
  487. \param in pointer to the input buffer holding the message to encrypt
  488. \param sz length of the input message to encrypt
  489. \param nonce pointer to the buffer containing the nonce
  490. (number only used once)
  491. \param nonceSz length of the nonce
  492. \param authTag pointer to the buffer in which to store the
  493. authentication tag
  494. \param authTagSz length of the desired authentication tag
  495. \param authIn pointer to the buffer containing the input
  496. authentication vector
  497. \param authInSz length of the input authentication vector
  498. _Example_
  499. \code
  500. Aes enc;
  501. // initialize enc with wc_AesInit and wc_AesCcmSetKey
  502. nonce[] = { initialize nonce };
  503. plain[] = { some plain text message };
  504. cipher[sizeof(plain)];
  505. authIn[] = { some 16 byte authentication input };
  506. tag[AES_BLOCK_SIZE]; // will store authentication code
  507. wc_AesCcmEncrypt(&enc, cipher, plain, sizeof(plain), nonce, sizeof(nonce),
  508. tag, sizeof(tag), authIn, sizeof(authIn));
  509. \endcode
  510. \sa wc_AesCcmSetKey
  511. \sa wc_AesCcmDecrypt
  512. */
  513. int wc_AesCcmEncrypt(Aes* aes, byte* out,
  514. const byte* in, word32 inSz,
  515. const byte* nonce, word32 nonceSz,
  516. byte* authTag, word32 authTagSz,
  517. const byte* authIn, word32 authInSz);
  518. /*!
  519. \ingroup AES
  520. \brief This function decrypts the input cipher text, in, into
  521. the output buffer, out, using CCM (Counter with CBC-MAC). It
  522. subsequently calculates the authorization tag, authTag, from the
  523. authIn input. If the authorization tag is invalid, it sets the
  524. output buffer to zero and returns the error: AES_CCM_AUTH_E.
  525. \return 0 On successfully decrypting the input message
  526. \return AES_CCM_AUTH_E If the authentication tag does not match the
  527. supplied authentication code vector, authTag.
  528. \param aes pointer to the AES object used to encrypt data
  529. \param out pointer to the output buffer in which to store the cipher text
  530. \param in pointer to the input buffer holding the message to encrypt
  531. \param sz length of the input cipher text to decrypt
  532. \param nonce pointer to the buffer containing the nonce
  533. (number only used once)
  534. \param nonceSz length of the nonce
  535. \param authTag pointer to the buffer in which to store the
  536. authentication tag
  537. \param authTagSz length of the desired authentication tag
  538. \param authIn pointer to the buffer containing the input
  539. authentication vector
  540. \param authInSz length of the input authentication vector
  541. _Example_
  542. \code
  543. Aes dec;
  544. // initialize dec with wc_AesInit and wc_AesCcmSetKey
  545. nonce[] = { initialize nonce };
  546. cipher[] = { encrypted message };
  547. plain[sizeof(cipher)];
  548. authIn[] = { some 16 byte authentication input };
  549. tag[AES_BLOCK_SIZE] = { authentication tag received for verification };
  550. int return = wc_AesCcmDecrypt(&dec, plain, cipher, sizeof(cipher),
  551. nonce, sizeof(nonce),tag, sizeof(tag), authIn, sizeof(authIn));
  552. if(return != 0) {
  553. // decrypt error, invalid authentication code
  554. }
  555. \endcode
  556. \sa wc_AesCcmSetKey
  557. \sa wc_AesCcmEncrypt
  558. */
  559. int wc_AesCcmDecrypt(Aes* aes, byte* out,
  560. const byte* in, word32 inSz,
  561. const byte* nonce, word32 nonceSz,
  562. const byte* authTag, word32 authTagSz,
  563. const byte* authIn, word32 authInSz);
  564. /*!
  565. \ingroup AES
  566. \brief This is to initialize an AES-XTS context. It is up to user to call
  567. wc_AesXtsFree on aes key when done.
  568. \return 0 Success
  569. \param aes AES keys for encrypt/decrypt process
  570. \param heap heap hint to use for memory. Can be NULL
  571. \param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
  572. _Example_
  573. \code
  574. XtsAes aes;
  575. if(wc_AesXtsInit(&aes, NULL, INVALID_DEVID) != 0)
  576. {
  577. // Handle error
  578. }
  579. if(wc_AesXtsSetKeyNoInit(&aes, key, sizeof(key), AES_ENCRYPTION) != 0)
  580. {
  581. // Handle error
  582. }
  583. wc_AesXtsFree(&aes);
  584. \endcode
  585. \sa wc_AesXtsSetKey
  586. \sa wc_AesXtsSetKeyNoInit
  587. \sa wc_AesXtsEncrypt
  588. \sa wc_AesXtsDecrypt
  589. \sa wc_AesXtsFree
  590. */
  591. int wc_AesXtsInit(XtsAes* aes, void* heap, int devId);
  592. /*!
  593. \ingroup AES
  594. \brief This is to help with setting keys to correct encrypt or decrypt type,
  595. after first calling wc_AesXtsInit(). It is up to user to call wc_AesXtsFree
  596. on aes key when done.
  597. \return 0 Success
  598. \param aes AES keys for encrypt/decrypt process
  599. \param key buffer holding aes key | tweak key
  600. \param len length of key buffer in bytes. Should be twice that of
  601. key size.
  602. i.e. 32 for a 16 byte key.
  603. \param dir direction, either AES_ENCRYPTION or AES_DECRYPTION
  604. _Example_
  605. \code
  606. XtsAes aes;
  607. if(wc_AesXtsInit(&aes, NULL, 0) != 0)
  608. {
  609. // Handle error
  610. }
  611. if(wc_AesXtsSetKeyNoInit(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, 0)
  612. != 0)
  613. {
  614. // Handle error
  615. }
  616. wc_AesXtsFree(&aes);
  617. \endcode
  618. \sa wc_AesXtsEncrypt
  619. \sa wc_AesXtsDecrypt
  620. \sa wc_AesXtsFree
  621. */
  622. int wc_AesXtsSetKeyNoInit(XtsAes* aes, const byte* key,
  623. word32 len, int dir);
  624. /*!
  625. \ingroup AES
  626. \brief This is to help with setting keys to correct encrypt or
  627. decrypt type. It is up to user to call wc_AesXtsFree on aes key when done.
  628. \return 0 Success
  629. \param aes AES keys for encrypt/decrypt process
  630. \param key buffer holding aes key | tweak key
  631. \param len length of key buffer in bytes. Should be twice that of
  632. key size.
  633. i.e. 32 for a 16 byte key.
  634. \param dir direction, either AES_ENCRYPTION or AES_DECRYPTION
  635. \param heap heap hint to use for memory. Can be NULL
  636. \param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
  637. _Example_
  638. \code
  639. XtsAes aes;
  640. if(wc_AesXtsSetKey(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, INVALID_DEVID) != 0)
  641. {
  642. // Handle error
  643. }
  644. wc_AesXtsFree(&aes);
  645. \endcode
  646. \sa wc_AesXtsInit
  647. \sa wc_AesXtsSetKeyNoInit
  648. \sa wc_AesXtsEncrypt
  649. \sa wc_AesXtsDecrypt
  650. \sa wc_AesXtsFree
  651. */
  652. int wc_AesXtsSetKey(XtsAes* aes, const byte* key,
  653. word32 len, int dir, void* heap, int devId);
  654. /*!
  655. \ingroup AES
  656. \brief Same process as wc_AesXtsEncrypt but uses a word64 type as the tweak
  657. value instead of a byte array. This just converts the word64 to a
  658. byte array and calls wc_AesXtsEncrypt.
  659. \return 0 Success
  660. \param aes AES keys to use for block encrypt/decrypt
  661. \param out output buffer to hold cipher text
  662. \param in input plain text buffer to encrypt
  663. \param sz size of both out and in buffers
  664. \param sector value to use for tweak
  665. _Example_
  666. \code
  667. XtsAes aes;
  668. unsigned char plain[SIZE];
  669. unsigned char cipher[SIZE];
  670. word64 s = VALUE;
  671. //set up keys with AES_ENCRYPTION as dir
  672. if(wc_AesXtsEncryptSector(&aes, cipher, plain, SIZE, s) != 0)
  673. {
  674. // Handle error
  675. }
  676. wc_AesXtsFree(&aes);
  677. \endcode
  678. \sa wc_AesXtsEncrypt
  679. \sa wc_AesXtsDecrypt
  680. \sa wc_AesXtsInit
  681. \sa wc_AesXtsSetKeyNoInit
  682. \sa wc_AesXtsSetKey
  683. \sa wc_AesXtsFree
  684. */
  685. int wc_AesXtsEncryptSector(XtsAes* aes, byte* out,
  686. const byte* in, word32 sz, word64 sector);
  687. /*!
  688. \ingroup AES
  689. \brief Same process as wc_AesXtsDecrypt but uses a word64 type as the tweak
  690. value instead of a byte array. This just converts the word64 to a
  691. byte array.
  692. \return 0 Success
  693. \param aes AES keys to use for block encrypt/decrypt
  694. \param out output buffer to hold plain text
  695. \param in input cipher text buffer to decrypt
  696. \param sz size of both out and in buffers
  697. \param sector value to use for tweak
  698. _Example_
  699. \code
  700. XtsAes aes;
  701. unsigned char plain[SIZE];
  702. unsigned char cipher[SIZE];
  703. word64 s = VALUE;
  704. //set up aes key with AES_DECRYPTION as dir and tweak with AES_ENCRYPTION
  705. if(wc_AesXtsDecryptSector(&aes, plain, cipher, SIZE, s) != 0)
  706. {
  707. // Handle error
  708. }
  709. wc_AesXtsFree(&aes);
  710. \endcode
  711. \sa wc_AesXtsEncrypt
  712. \sa wc_AesXtsDecrypt
  713. \sa wc_AesXtsInit
  714. \sa wc_AesXtsSetKeyNoInit
  715. \sa wc_AesXtsSetKey
  716. \sa wc_AesXtsFree
  717. */
  718. int wc_AesXtsDecryptSector(XtsAes* aes, byte* out,
  719. const byte* in, word32 sz, word64 sector);
  720. /*!
  721. \ingroup AES
  722. \brief AES with XTS mode. (XTS) XEX encryption with Tweak and cipher text
  723. Stealing.
  724. \return 0 Success
  725. \param aes AES keys to use for block encrypt/decrypt
  726. \param out output buffer to hold cipher text
  727. \param in input plain text buffer to encrypt
  728. \param sz size of both out and in buffers
  729. \param i value to use for tweak
  730. \param iSz size of i buffer, should always be AES_BLOCK_SIZE but having
  731. this input adds a sanity check on how the user calls the
  732. function.
  733. _Example_
  734. \code
  735. XtsAes aes;
  736. unsigned char plain[SIZE];
  737. unsigned char cipher[SIZE];
  738. unsigned char i[AES_BLOCK_SIZE];
  739. //set up key with AES_ENCRYPTION as dir
  740. if(wc_AesXtsEncrypt(&aes, cipher, plain, SIZE, i, sizeof(i)) != 0)
  741. {
  742. // Handle error
  743. }
  744. wc_AesXtsFree(&aes);
  745. \endcode
  746. \sa wc_AesXtsDecrypt
  747. \sa wc_AesXtsInit
  748. \sa wc_AesXtsSetKeyNoInit
  749. \sa wc_AesXtsSetKey
  750. \sa wc_AesXtsFree
  751. */
  752. int wc_AesXtsEncrypt(XtsAes* aes, byte* out,
  753. const byte* in, word32 sz, const byte* i, word32 iSz);
  754. /*!
  755. \ingroup AES
  756. \brief Same process as encryption but Aes key is AES_DECRYPTION type.
  757. \return 0 Success
  758. \param aes AES keys to use for block encrypt/decrypt
  759. \param out output buffer to hold plain text
  760. \param in input cipher text buffer to decrypt
  761. \param sz size of both out and in buffers
  762. \param i value to use for tweak
  763. \param iSz size of i buffer, should always be AES_BLOCK_SIZE but having
  764. this input adds a sanity check on how the user calls the
  765. function.
  766. _Example_
  767. \code
  768. XtsAes aes;
  769. unsigned char plain[SIZE];
  770. unsigned char cipher[SIZE];
  771. unsigned char i[AES_BLOCK_SIZE];
  772. //set up key with AES_DECRYPTION as dir and tweak with AES_ENCRYPTION
  773. if(wc_AesXtsDecrypt(&aes, plain, cipher, SIZE, i, sizeof(i)) != 0)
  774. {
  775. // Handle error
  776. }
  777. wc_AesXtsFree(&aes);
  778. \endcode
  779. \sa wc_AesXtsEncrypt
  780. \sa wc_AesXtsInit
  781. \sa wc_AesXtsSetKeyNoInit
  782. \sa wc_AesXtsSetKey
  783. \sa wc_AesXtsFree
  784. */
  785. int wc_AesXtsDecrypt(XtsAes* aes, byte* out,
  786. const byte* in, word32 sz, const byte* i, word32 iSz);
  787. /*!
  788. \ingroup AES
  789. \brief This is to free up any resources used by the XtsAes structure
  790. \return 0 Success
  791. \param aes AES keys to free
  792. _Example_
  793. \code
  794. XtsAes aes;
  795. if(wc_AesXtsSetKey(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, 0) != 0)
  796. {
  797. // Handle error
  798. }
  799. wc_AesXtsFree(&aes);
  800. \endcode
  801. \sa wc_AesXtsEncrypt
  802. \sa wc_AesXtsDecrypt
  803. \sa wc_AesXtsInit
  804. \sa wc_AesXtsSetKeyNoInit
  805. \sa wc_AesXtsSetKey
  806. */
  807. int wc_AesXtsFree(XtsAes* aes);
  808. /*!
  809. \ingroup AES
  810. \brief Initialize Aes structure. Sets heap hint to be used and ID for use
  811. with async hardware. It is up to the user to call wc_AesFree on the Aes
  812. structure when done.
  813. \return 0 Success
  814. \param aes aes structure in to initialize
  815. \param heap heap hint to use for malloc / free if needed
  816. \param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
  817. _Example_
  818. \code
  819. Aes enc;
  820. void* hint = NULL;
  821. int devId = INVALID_DEVID; //if not using async INVALID_DEVID is default
  822. //heap hint could be set here if used
  823. wc_AesInit(&enc, hint, devId);
  824. \endcode
  825. \sa wc_AesSetKey
  826. \sa wc_AesSetIV
  827. \sa wc_AesFree
  828. */
  829. int wc_AesInit(Aes* aes, void* heap, int devId);
  830. /*!
  831. \ingroup AES
  832. \brief free resources associated with the Aes structure when applicable.
  833. Internally may sometimes be a no-op but still recommended to call in all
  834. cases as a general best-practice (IE if application code is ported for use
  835. on new environments where the call is applicable).
  836. \return no return (void function)
  837. \param aes aes structure in to free
  838. _Example_
  839. \code
  840. Aes enc;
  841. void* hint = NULL;
  842. int devId = INVALID_DEVID; //if not using async INVALID_DEVID is default
  843. //heap hint could be set here if used
  844. wc_AesInit(&enc, hint, devId);
  845. // ... do some interesting things ...
  846. wc_AesFree(&enc);
  847. \endcode
  848. \sa wc_AesInit
  849. */
  850. int wc_AesFree(Aes* aes);
  851. /*!
  852. \ingroup AES
  853. \brief AES with CFB mode.
  854. \return 0 Success and negative error values on failure
  855. \param aes AES keys to use for block encrypt/decrypt
  856. \param out output buffer to hold cipher text must be at least as large
  857. as inputbuffer)
  858. \param in input plain text buffer to encrypt
  859. \param sz size of input buffer
  860. _Example_
  861. \code
  862. Aes aes;
  863. unsigned char plain[SIZE];
  864. unsigned char cipher[SIZE];
  865. //set up key with AES_ENCRYPTION as dir for both encrypt and decrypt
  866. if(wc_AesCfbEncrypt(&aes, cipher, plain, SIZE) != 0)
  867. {
  868. // Handle error
  869. }
  870. \endcode
  871. \sa wc_AesCfbDecrypt
  872. \sa wc_AesSetKey
  873. */
  874. int wc_AesCfbEncrypt(Aes* aes, byte* out, const byte* in, word32 sz);
  875. /*!
  876. \ingroup AES
  877. \brief AES with CFB mode.
  878. \return 0 Success and negative error values on failure
  879. \param aes AES keys to use for block encrypt/decrypt
  880. \param out output buffer to hold decrypted text must be at least as large
  881. as inputbuffer)
  882. \param in input buffer to decrypt
  883. \param sz size of input buffer
  884. _Example_
  885. \code
  886. Aes aes;
  887. unsigned char plain[SIZE];
  888. unsigned char cipher[SIZE];
  889. //set up key with AES_ENCRYPTION as dir for both encrypt and decrypt
  890. if(wc_AesCfbDecrypt(&aes, plain, cipher, SIZE) != 0)
  891. {
  892. // Handle error
  893. }
  894. \endcode
  895. \sa wc_AesCfbEncrypt
  896. \sa wc_AesSetKey
  897. */
  898. int wc_AesCfbDecrypt(Aes* aes, byte* out, const byte* in, word32 sz);
  899. /*!
  900. \ingroup AES
  901. \brief This function performs SIV (synthetic initialization vector)
  902. encryption as described in RFC 5297.
  903. \return 0 On successful encryption.
  904. \return BAD_FUNC_ARG If key, SIV, or output buffer are NULL. Also returned
  905. if the key size isn't 32, 48, or 64 bytes.
  906. \return Other Other negative error values returned if AES or CMAC operations
  907. fail.
  908. \param key Byte buffer containing the key to use.
  909. \param keySz Length of the key buffer in bytes.
  910. \param assoc Additional, authenticated associated data (AD).
  911. \param assocSz Length of AD buffer in bytes.
  912. \param nonce A number used once. Used by the algorithm in the same manner as
  913. the AD.
  914. \param nonceSz Length of nonce buffer in bytes.
  915. \param in Plaintext buffer to encrypt.
  916. \param inSz Length of plaintext buffer.
  917. \param siv The SIV output by S2V (see RFC 5297 2.4).
  918. \param out Buffer to hold the ciphertext. Should be the same length as the
  919. plaintext buffer.
  920. _Example_
  921. \code
  922. byte key[] = { some 32, 48, or 64 byte key };
  923. byte assoc[] = {0x01, 0x2, 0x3};
  924. byte nonce[] = {0x04, 0x5, 0x6};
  925. byte plainText[] = {0xDE, 0xAD, 0xBE, 0xEF};
  926. byte siv[AES_BLOCK_SIZE];
  927. byte cipherText[sizeof(plainText)];
  928. if (wc_AesSivEncrypt(key, sizeof(key), assoc, sizeof(assoc), nonce,
  929. sizeof(nonce), plainText, sizeof(plainText), siv, cipherText) != 0) {
  930. // failed to encrypt
  931. }
  932. \endcode
  933. \sa wc_AesSivDecrypt
  934. */
  935. int wc_AesSivEncrypt(const byte* key, word32 keySz, const byte* assoc,
  936. word32 assocSz, const byte* nonce, word32 nonceSz,
  937. const byte* in, word32 inSz, byte* siv, byte* out);
  938. /*!
  939. \ingroup AES
  940. \brief This function performs SIV (synthetic initialization vector)
  941. decryption as described in RFC 5297.
  942. \return 0 On successful decryption.
  943. \return BAD_FUNC_ARG If key, SIV, or output buffer are NULL. Also returned
  944. if the key size isn't 32, 48, or 64 bytes.
  945. \return AES_SIV_AUTH_E If the SIV derived by S2V doesn't match the input
  946. SIV (see RFC 5297 2.7).
  947. \return Other Other negative error values returned if AES or CMAC operations
  948. fail.
  949. \param key Byte buffer containing the key to use.
  950. \param keySz Length of the key buffer in bytes.
  951. \param assoc Additional, authenticated associated data (AD).
  952. \param assocSz Length of AD buffer in bytes.
  953. \param nonce A number used once. Used by the underlying algorithm in the
  954. same manner as the AD.
  955. \param nonceSz Length of nonce buffer in bytes.
  956. \param in Ciphertext buffer to decrypt.
  957. \param inSz Length of ciphertext buffer.
  958. \param siv The SIV that accompanies the ciphertext (see RFC 5297 2.4).
  959. \param out Buffer to hold the decrypted plaintext. Should be the same length
  960. as the ciphertext buffer.
  961. _Example_
  962. \code
  963. byte key[] = { some 32, 48, or 64 byte key };
  964. byte assoc[] = {0x01, 0x2, 0x3};
  965. byte nonce[] = {0x04, 0x5, 0x6};
  966. byte cipherText[] = {0xDE, 0xAD, 0xBE, 0xEF};
  967. byte siv[AES_BLOCK_SIZE] = { the SIV that came with the ciphertext };
  968. byte plainText[sizeof(cipherText)];
  969. if (wc_AesSivDecrypt(key, sizeof(key), assoc, sizeof(assoc), nonce,
  970. sizeof(nonce), cipherText, sizeof(cipherText), siv, plainText) != 0) {
  971. // failed to decrypt
  972. }
  973. \endcode
  974. \sa wc_AesSivEncrypt
  975. */
  976. int wc_AesSivDecrypt(const byte* key, word32 keySz, const byte* assoc,
  977. word32 assocSz, const byte* nonce, word32 nonceSz,
  978. const byte* in, word32 inSz, byte* siv, byte* out);
  979. /*!
  980. \ingroup AES
  981. \brief This function performs AES EAX encryption and authentication as
  982. described in "EAX: A Conventional Authenticated-Encryption Mode"
  983. (https://eprint.iacr.org/2003/069). It is a "one-shot" API that performs
  984. all encryption and authentication operations in one function call.
  985. \return 0 on successful encryption.
  986. \return BAD_FUNC_ARG if input or output buffers are NULL. Also returned
  987. if the key size isn't a valid AES key size (16, 24, or 32 bytes)
  988. \return other negative error values returned if AES or CMAC operations
  989. fail.
  990. \param key buffer containing the key to use
  991. \param keySz length of the key buffer in bytes
  992. \param[out] out buffer to hold the ciphertext. Should be the same length as
  993. the plaintext buffer
  994. \param in plaintext buffer to encrypt
  995. \param inSz length of plaintext buffer
  996. \param nonce the cryptographic nonce to use for EAX operations
  997. \param nonceSz length of nonce buffer in bytes
  998. \param[out] authTag pointer to the buffer in which to store the
  999. authentication tag
  1000. \param authTagSz length of the desired authentication tag
  1001. \param authIn pointer to the buffer containing input data to authenticate
  1002. \param authInSz length of the input authentication data
  1003. _Example_
  1004. \code
  1005. byte key[] = { some 32, 48, or 64 byte key };
  1006. byte nonce[] = {0x04, 0x5, 0x6};
  1007. byte plainText[] = {0xDE, 0xAD, 0xBE, 0xEF};
  1008. byte authIn[] = {0x01, 0x2, 0x3};
  1009. byte cipherText[sizeof(plainText)]; // output ciphertext
  1010. byte authTag[length, up to AES_BLOCK_SIZE]; // output authTag
  1011. if (wc_AesEaxEncrypt(key, sizeof(key),
  1012. cipherText, plainText, sizeof(plainText),
  1013. nonce, sizeof(nonce),
  1014. authTag, sizeof(authTag),
  1015. authIn, sizeof(authIn)) != 0) {
  1016. // failed to encrypt
  1017. }
  1018. \endcode
  1019. \sa wc_AesEaxDecryptAuth
  1020. */
  1021. WOLFSSL_API int wc_AesEaxEncryptAuth(const byte* key, word32 keySz, byte* out,
  1022. const byte* in, word32 inSz,
  1023. const byte* nonce, word32 nonceSz,
  1024. /* output computed auth tag */
  1025. byte* authTag, word32 authTagSz,
  1026. /* input data to authenticate */
  1027. const byte* authIn, word32 authInSz);
  1028. /*!
  1029. \ingroup AES
  1030. \brief This function performs AES EAX decryption and authentication as
  1031. described in "EAX: A Conventional Authenticated-Encryption Mode"
  1032. (https://eprint.iacr.org/2003/069). It is a "one-shot" API that performs
  1033. all decryption and authentication operations in one function call.
  1034. \return 0 on successful decryption
  1035. \return BAD_FUNC_ARG if input or output buffers are NULL. Also returned
  1036. if the key size isn't a valid AES key size (16, 24, or 32 bytes)
  1037. \return AES_EAX_AUTH_E If the authentication tag does not match the
  1038. supplied authentication code vector \c authTag
  1039. \return other negative error values returned if AES or CMAC operations
  1040. fail.
  1041. \param key byte buffer containing the key to use
  1042. \param keySz length of the key buffer in bytes
  1043. \param[out] out buffer to hold the plaintext. Should be the same length as
  1044. the input ciphertext buffer
  1045. \param in ciphertext buffer to decrypt
  1046. \param inSz length of ciphertext buffer
  1047. \param nonce the cryptographic nonce to use for EAX operations
  1048. \param nonceSz length of nonce buffer in bytes
  1049. \param authTag buffer that holds the authentication tag to check the
  1050. authenticity of the data against
  1051. \param authTagSz Length of the input authentication tag
  1052. \param authIn pointer to the buffer containing input data to authenticate
  1053. \param authInSz length of the input authentication data
  1054. _Example_
  1055. \code
  1056. byte key[] = { some 32, 48, or 64 byte key };
  1057. byte nonce[] = {0x04, 0x5, 0x6};
  1058. byte cipherText[] = {0xDE, 0xAD, 0xBE, 0xEF};
  1059. byte authIn[] = {0x01, 0x2, 0x3};
  1060. byte plainText[sizeof(cipherText)]; // output plaintext
  1061. byte authTag[length, up to AES_BLOCK_SIZE]; // output authTag
  1062. if (wc_AesEaxDecrypt(key, sizeof(key),
  1063. cipherText, plainText, sizeof(plainText),
  1064. nonce, sizeof(nonce),
  1065. authTag, sizeof(authTag),
  1066. authIn, sizeof(authIn)) != 0) {
  1067. // failed to encrypt
  1068. }
  1069. \endcode
  1070. \sa wc_AesEaxEncryptAuth
  1071. */
  1072. WOLFSSL_API int wc_AesEaxDecryptAuth(const byte* key, word32 keySz, byte* out,
  1073. const byte* in, word32 inSz,
  1074. const byte* nonce, word32 nonceSz,
  1075. /* auth tag to verify against */
  1076. const byte* authTag, word32 authTagSz,
  1077. /* input data to authenticate */
  1078. const byte* authIn, word32 authInSz);
  1079. /*!
  1080. \ingroup AES
  1081. \brief This function initializes an AesEax object for use in authenticated
  1082. encryption or decryption. This function must be called on an AesEax
  1083. object before using it with any of the AES EAX incremental API functions.
  1084. It does not need to be called if using the one-shot EAX API functions.
  1085. All AesEax instances initialized with this function need to be freed with
  1086. a call to wc_AesEaxFree() when done using the instance.
  1087. \return 0 on success
  1088. \return error code on failure
  1089. \param eax AES EAX structure holding the context of the AEAD operation
  1090. \param key 16, 24, or 32 byte secret key for encryption and decryption
  1091. \param keySz length of the supplied key in bytes
  1092. \param nonce the cryptographic nonce to use for EAX operations
  1093. \param nonceSz length of nonce buffer in bytes
  1094. \param authIn (optional) input data to add to the authentication stream
  1095. This argument should be NULL if not used
  1096. \param authInSz size in bytes of the input authentication data
  1097. _Example_
  1098. \code
  1099. AesEax eax;
  1100. key[] = { some 16, 24, or 32 byte length key };
  1101. nonce[] = { some arbitrary length nonce };
  1102. authIn[] = { some data to add to the authentication stream };
  1103. plainText[] = {some plaintext data to encrypt};
  1104. cipherText[sizeof(plainText)]; // buffer to hold cipherText
  1105. authTag[length, up to AES_BLOCK_SIZE]; // buffer to hold computed auth data
  1106. AesEax eax;
  1107. if ((ret = wc_AesEaxInit(eax,
  1108. key, keySz,
  1109. nonce, nonceSz,
  1110. authIn, authInSz)) != 0) {
  1111. goto cleanup;
  1112. }
  1113. // if we wanted to add more auth data, we could provide it at this point,
  1114. // otherwise we use NULL for the authIn parameter, with authIn size of 0
  1115. if ((ret = wc_AesEaxEncryptUpdate(eax,
  1116. cipherText, plainText, sizeof(plainText),
  1117. NULL, 0)) != 0) {
  1118. goto cleanup;
  1119. }
  1120. if ((ret = wc_AesEaxEncryptFinal(eax, authTag, sizeof(authTag))) != 0) {
  1121. goto cleanup;
  1122. }
  1123. cleanup:
  1124. wc_AesEaxFree(eax);
  1125. \endcode
  1126. \sa wc_AesEaxEncryptUpdate
  1127. \sa wc_AesEaxDecryptUpdate
  1128. \sa wc_AesEaxAuthDataUpdate
  1129. \sa wc_AesEaxEncryptFinal
  1130. \sa wc_AesEaxDecryptFinal
  1131. \sa wc_AesEaxFree
  1132. */
  1133. WOLFSSL_API int wc_AesEaxInit(AesEax* eax,
  1134. const byte* key, word32 keySz,
  1135. const byte* nonce, word32 nonceSz,
  1136. const byte* authIn, word32 authInSz);
  1137. /*!
  1138. \ingroup AES
  1139. \brief This function uses AES EAX to encrypt input data, and optionally, add
  1140. more input data to the authentication stream. \c eax must have been
  1141. previously initialized with a call to \ref wc_AesEaxInit.
  1142. \return 0 on success
  1143. \return error code on failure
  1144. \param eax AES EAX structure holding the context of the AEAD operation
  1145. \param[out] out output buffer holding the ciphertext
  1146. \param in input buffer holding the plaintext to encrypt
  1147. \param inSz size in bytes of the input data buffer
  1148. \param authIn (optional) input data to add to the authentication stream
  1149. This argument should be NULL if not used
  1150. \param authInSz size in bytes of the input authentication data
  1151. _Example_
  1152. \code
  1153. AesEax eax;
  1154. key[] = { some 16, 24, or 32 byte length key };
  1155. nonce[] = { some arbitrary length nonce };
  1156. authIn[] = { some data to add to the authentication stream };
  1157. plainText[] = {some plaintext data to encrypt};
  1158. cipherText[sizeof(plainText)]; // buffer to hold cipherText
  1159. authTag[length, up to AES_BLOCK_SIZE]; // buffer to hold computed auth data
  1160. AesEax eax;
  1161. if ((ret = wc_AesEaxInit(eax,
  1162. key, keySz,
  1163. nonce, nonceSz,
  1164. authIn, authInSz)) != 0) {
  1165. goto cleanup;
  1166. }
  1167. // if we wanted to add more auth data, we could provide it at this point,
  1168. // otherwise we use NULL for the authIn parameter, with authInSz of 0
  1169. if ((ret = wc_AesEaxEncryptUpdate(eax,
  1170. cipherText, plainText, sizeof(plainText),
  1171. NULL, 0)) != 0) {
  1172. goto cleanup;
  1173. }
  1174. if ((ret = wc_AesEaxEncryptFinal(eax, authTag, sizeof(authTag))) != 0) {
  1175. goto cleanup;
  1176. }
  1177. cleanup:
  1178. wc_AesEaxFree(eax);
  1179. \endcode
  1180. \sa wc_AesEaxInit
  1181. \sa wc_AesEaxDecryptUpdate
  1182. \sa wc_AesEaxAuthDataUpdate
  1183. \sa wc_AesEaxEncryptFinal
  1184. \sa wc_AesEaxDecryptFinal
  1185. \sa wc_AesEaxFree
  1186. */
  1187. WOLFSSL_API int wc_AesEaxEncryptUpdate(AesEax* eax, byte* out,
  1188. const byte* in, word32 inSz,
  1189. const byte* authIn, word32 authInSz);
  1190. /*!
  1191. \ingroup AES
  1192. \brief This function uses AES EAX to decrypt input data, and optionally, add
  1193. more input data to the authentication stream. \c eax must have been
  1194. previously initialized with a call to \ref wc_AesEaxInit.
  1195. \return 0 on success
  1196. \return error code on failure
  1197. \param eax AES EAX structure holding the context of the AEAD operation
  1198. \param[out] out output buffer holding the decrypted plaintext
  1199. \param in input buffer holding the ciphertext
  1200. \param inSz size in bytes of the input data buffer
  1201. \param authIn (optional) input data to add to the authentication stream
  1202. This argument should be NULL if not used
  1203. \param authInSz size in bytes of the input authentication data
  1204. _Example_
  1205. \code
  1206. AesEax eax;
  1207. key[] = { some 16, 24, or 32 byte length key };
  1208. nonce[] = { some arbitrary length nonce };
  1209. authIn[] = { some data to add to the authentication stream };
  1210. cipherText[] = {some encrypted data};
  1211. plainText[sizeof(cipherText)]; // buffer to hold decrypted data
  1212. // auth tag is generated elsewhere by the encrypt AEAD operation
  1213. authTag[length, up to AES_BLOCK_SIZE] = { the auth tag };
  1214. AesEax eax;
  1215. if ((ret = wc_AesEaxInit(eax,
  1216. key, keySz,
  1217. nonce, nonceSz,
  1218. authIn, authInSz)) != 0) {
  1219. goto cleanup;
  1220. }
  1221. // if we wanted to add more auth data, we could provide it at this point,
  1222. // otherwise we use NULL for the authIn parameter, with authInSz of 0
  1223. if ((ret = wc_AesEaxDecryptUpdate(eax,
  1224. plainText, cipherText, sizeof(cipherText),
  1225. NULL, 0)) != 0) {
  1226. goto cleanup;
  1227. }
  1228. if ((ret = wc_AesEaxDecryptFinal(eax, authTag, sizeof(authTag))) != 0) {
  1229. goto cleanup;
  1230. }
  1231. cleanup:
  1232. wc_AesEaxFree(eax);
  1233. \endcode
  1234. \sa wc_AesEaxInit
  1235. \sa wc_AesEaxEncryptUpdate
  1236. \sa wc_AesEaxAuthDataUpdate
  1237. \sa wc_AesEaxEncryptFinal
  1238. \sa wc_AesEaxDecryptFinal
  1239. \sa wc_AesEaxFree
  1240. */
  1241. WOLFSSL_API int wc_AesEaxDecryptUpdate(AesEax* eax, byte* out,
  1242. const byte* in, word32 inSz,
  1243. const byte* authIn, word32 authInSz);
  1244. /*!
  1245. \ingroup AES
  1246. \brief This function adds input data to the authentication stream.
  1247. \c eax must have been previously initialized with a call to
  1248. \ref wc_AesEaxInit.
  1249. \return 0 on success
  1250. \return error code on failure
  1251. \param eax AES EAX structure holding the context of the AEAD operation
  1252. \param authIn input data to add to the authentication stream
  1253. \param authInSz size in bytes of the input authentication data
  1254. _Example_
  1255. \code
  1256. AesEax eax;
  1257. key[] = { some 16, 24, or 32 byte length key };
  1258. nonce[] = { some arbitrary length nonce };
  1259. authIn[] = { some data to add to the authentication stream };
  1260. cipherText[] = {some encrypted data};
  1261. plainText[sizeof(cipherText)]; // buffer to hold decrypted data
  1262. // auth tag is generated elsewhere by the encrypt AEAD operation
  1263. authTag[length, up to AES_BLOCK_SIZE] = { the auth tag };
  1264. AesEax eax;
  1265. // No auth data to add here
  1266. if ((ret = wc_AesEaxInit(eax,
  1267. key, keySz,
  1268. nonce, nonceSz,
  1269. NULL, 0)) != 0) {
  1270. goto cleanup;
  1271. }
  1272. // No auth data to add here, added later with wc_AesEaxAuthDataUpdate
  1273. if ((ret = wc_AesEaxDecryptUpdate(eax,
  1274. plainText, cipherText, sizeof(cipherText),
  1275. NULL, 0)) != 0) {
  1276. goto cleanup;
  1277. }
  1278. if ((ret = wc_AesEaxAuthDataUpdate(eax, authIn, sizeof(authIn))) != 0) {
  1279. goto cleanup;
  1280. }
  1281. if ((ret = wc_AesEaxDecryptFinal(eax, authTag, sizeof(authTag))) != 0) {
  1282. goto cleanup;
  1283. }
  1284. cleanup:
  1285. wc_AesEaxFree(eax);
  1286. \endcode
  1287. \sa wc_AesEaxInit
  1288. \sa wc_AesEaxEncryptUpdate
  1289. \sa wc_AesEaxDecryptUpdate
  1290. \sa wc_AesEaxEncryptFinal
  1291. \sa wc_AesEaxDecryptFinal
  1292. \sa wc_AesEaxFree
  1293. */
  1294. WOLFSSL_API int wc_AesEaxAuthDataUpdate(AesEax* eax,
  1295. const byte* authIn, word32 authInSz);
  1296. /*!
  1297. \ingroup AES
  1298. \brief This function finalizes the encrypt AEAD operation, producing an auth
  1299. tag over the current authentication stream. \c eax must have been previously
  1300. initialized with a call to \ref wc_AesEaxInit. When done using the \c AesEax
  1301. context structure, make sure to free it using \ref wc_AesEaxFree.
  1302. \return 0 on success
  1303. \return error code on failure
  1304. \param eax AES EAX structure holding the context of the AEAD operation
  1305. \param authTag[out] buffer that will hold the computed auth tag
  1306. \param authTagSz size in bytes of \c authTag
  1307. _Example_
  1308. \code
  1309. AesEax eax;
  1310. key[] = { some 16, 24, or 32 byte length key };
  1311. nonce[] = { some arbitrary length nonce };
  1312. authIn[] = { some data to add to the authentication stream };
  1313. plainText[] = {some plaintext data to encrypt};
  1314. cipherText[sizeof(plainText)]; // buffer to hold cipherText
  1315. authTag[length, up to AES_BLOCK_SIZE]; // buffer to hold computed auth data
  1316. AesEax eax;
  1317. if ((ret = wc_AesEaxInit(eax,
  1318. key, keySz,
  1319. nonce, nonceSz,
  1320. authIn, authInSz)) != 0) {
  1321. goto cleanup;
  1322. }
  1323. // if we wanted to add more auth data, we could provide it at this point,
  1324. // otherwise we use NULL for the authIn parameter, with authInSz of 0
  1325. if ((ret = wc_AesEaxEncryptUpdate(eax,
  1326. cipherText, plainText, sizeof(plainText),
  1327. NULL, 0)) != 0) {
  1328. goto cleanup;
  1329. }
  1330. if ((ret = wc_AesEaxEncryptFinal(eax, authTag, sizeof(authTag))) != 0) {
  1331. goto cleanup;
  1332. }
  1333. cleanup:
  1334. wc_AesEaxFree(eax);
  1335. \endcode
  1336. \sa wc_AesEaxInit
  1337. \sa wc_AesEaxEncryptUpdate
  1338. \sa wc_AesEaxDecryptUpdate
  1339. \sa wc_AesEaxAuthDataUpdate
  1340. \sa wc_AesEaxDecryptFinal
  1341. \sa wc_AesEaxFree
  1342. */
  1343. WOLFSSL_API int wc_AesEaxEncryptFinal(AesEax* eax,
  1344. byte* authTag, word32 authTagSz);
  1345. /*!
  1346. \ingroup AES
  1347. \brief This function finalizes the decrypt AEAD operation, finalizing the
  1348. auth tag computation and checking it for validity against the user supplied
  1349. tag. \c eax must have been previously initialized with a call to
  1350. \ref wc_AesEaxInit. When done using the \c AesEax context structure, make
  1351. sure to free it using \ref wc_AesEaxFree.
  1352. \return 0 if data is authenticated successfully
  1353. \return AES_EAX_AUTH_E if the authentication tag does not match the
  1354. supplied authentication code vector \c authIn
  1355. \return other error code on failure
  1356. \param eax AES EAX structure holding the context of the AEAD operation
  1357. \param authIn input auth tag to check computed auth tag against
  1358. \param authInSz size in bytes of \c authIn
  1359. _Example_
  1360. \code
  1361. AesEax eax;
  1362. key[] = { some 16, 24, or 32 byte length key };
  1363. nonce[] = { some arbitrary length nonce };
  1364. authIn[] = { some data to add to the authentication stream };
  1365. cipherText[] = {some encrypted data};
  1366. plainText[sizeof(cipherText)]; // buffer to hold decrypted data
  1367. // auth tag is generated elsewhere by the encrypt AEAD operation
  1368. authTag[length, up to AES_BLOCK_SIZE] = { the auth tag };
  1369. AesEax eax;
  1370. if ((ret = wc_AesEaxInit(eax,
  1371. key, keySz,
  1372. nonce, nonceSz,
  1373. authIn, authInSz)) != 0) {
  1374. goto cleanup;
  1375. }
  1376. // if we wanted to add more auth data, we could provide it at this point,
  1377. // otherwise we use NULL for the authIn parameter, with authInSz of 0
  1378. if ((ret = wc_AesEaxDecryptUpdate(eax,
  1379. plainText, cipherText, sizeof(cipherText),
  1380. NULL, 0)) != 0) {
  1381. goto cleanup;
  1382. }
  1383. if ((ret = wc_AesEaxDecryptFinal(eax, authTag, sizeof(authTag))) != 0) {
  1384. goto cleanup;
  1385. }
  1386. cleanup:
  1387. wc_AesEaxFree(eax);
  1388. \endcode
  1389. \sa wc_AesEaxInit
  1390. \sa wc_AesEaxEncryptUpdate
  1391. \sa wc_AesEaxDecryptUpdate
  1392. \sa wc_AesEaxAuthDataUpdate
  1393. \sa wc_AesEaxEncryptFinal
  1394. \sa wc_AesEaxFree
  1395. */
  1396. WOLFSSL_API int wc_AesEaxDecryptFinal(AesEax* eax,
  1397. const byte* authIn, word32 authInSz);
  1398. /*!
  1399. \ingroup AES
  1400. \brief This frees up any resources, specifically keys, used by the Aes
  1401. instance inside the AesEax wrapper struct. It should be called on the
  1402. AesEax struct after it has been initialized with wc_AesEaxInit, and all
  1403. desired EAX operations are complete.
  1404. \return 0 Success
  1405. \param eaxAES EAX instance to free
  1406. _Example_
  1407. \code
  1408. AesEax eax;
  1409. if(wc_AesEaxInit(eax, key, keySz, nonce, nonceSz, authIn, authInSz) != 0) {
  1410. // handle errors, then free
  1411. wc_AesEaxFree(&eax);
  1412. }
  1413. \endcode
  1414. \sa wc_AesEaxInit
  1415. \sa wc_AesEaxEncryptUpdate
  1416. \sa wc_AesEaxDecryptUpdate
  1417. \sa wc_AesEaxAuthDataUpdate
  1418. \sa wc_AesEaxEncryptFinal
  1419. \sa wc_AesEaxDecryptFinal
  1420. */
  1421. WOLFSSL_API int wc_AesEaxFree(AesEax* eax);