1
0

cmac.h 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208
  1. /*!
  2. \ingroup CMAC
  3. \brief Initialize the Cmac structure with defaults
  4. \return 0 on success
  5. \param cmac pointer to the Cmac structure
  6. \param key key pointer
  7. \param keySz size of the key pointer (16, 24 or 32)
  8. \param type Always WC_CMAC_AES = 1
  9. \param unused not used, exists for potential future use around compatibility
  10. _Example_
  11. \code
  12. Cmac cmac[1];
  13. ret = wc_InitCmac(cmac, key, keySz, WC_CMAC_AES, NULL);
  14. if (ret == 0) {
  15. ret = wc_CmacUpdate(cmac, in, inSz);
  16. }
  17. if (ret == 0) {
  18. ret = wc_CmacFinal(cmac, out, outSz);
  19. }
  20. \endcode
  21. \sa wc_InitCmac_ex
  22. \sa wc_CmacUpdate
  23. \sa wc_CmacFinal
  24. \sa wc_CmacFinalNoFree
  25. \sa wc_CmacFree
  26. */
  27. int wc_InitCmac(Cmac* cmac,
  28. const byte* key, word32 keySz,
  29. int type, void* unused);
  30. /*!
  31. \ingroup CMAC
  32. \brief Initialize the Cmac structure with defaults
  33. \return 0 on success
  34. \param cmac pointer to the Cmac structure
  35. \param key key pointer
  36. \param keySz size of the key pointer (16, 24 or 32)
  37. \param type Always WC_CMAC_AES = 1
  38. \param unused not used, exists for potential future use around compatibility
  39. \param heap pointer to the heap hint used for dynamic allocation. Typically used with our static memory option. Can be NULL.
  40. \param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
  41. _Example_
  42. \code
  43. Cmac cmac[1];
  44. ret = wc_InitCmac_ex(cmac, key, keySz, WC_CMAC_AES, NULL, NULL, INVALID_DEVID);
  45. if (ret == 0) {
  46. ret = wc_CmacUpdate(cmac, in, inSz);
  47. }
  48. if (ret == 0) {
  49. ret = wc_CmacFinal(cmac, out, &outSz);
  50. }
  51. \endcode
  52. \sa wc_InitCmac_ex
  53. \sa wc_CmacUpdate
  54. \sa wc_CmacFinal
  55. \sa wc_CmacFinalNoFree
  56. \sa wc_CmacFree
  57. */
  58. int wc_InitCmac_ex(Cmac* cmac,
  59. const byte* key, word32 keySz,
  60. int type, void* unused, void* heap, int devId);
  61. /*!
  62. \ingroup CMAC
  63. \brief Add Cipher-based Message Authentication Code input data
  64. \return 0 on success
  65. \param cmac pointer to the Cmac structure
  66. \param in input data to process
  67. \param inSz size of input data
  68. _Example_
  69. \code
  70. ret = wc_CmacUpdate(cmac, in, inSz);
  71. \endcode
  72. \sa wc_InitCmac
  73. \sa wc_CmacFinal
  74. \sa wc_CmacFinalNoFree
  75. \sa wc_CmacFree
  76. */
  77. int wc_CmacUpdate(Cmac* cmac,
  78. const byte* in, word32 inSz);
  79. /*!
  80. \ingroup CMAC
  81. \brief Generate the final result using Cipher-based Message Authentication Code, deferring context cleanup.
  82. \return 0 on success
  83. \param cmac pointer to the Cmac structure
  84. \param out pointer to return the result
  85. \param outSz pointer size of output (in/out)
  86. _Example_
  87. \code
  88. ret = wc_CmacFinalNoFree(cmac, out, &outSz);
  89. (void)wc_CmacFree(cmac);
  90. \endcode
  91. \sa wc_InitCmac
  92. \sa wc_CmacFinal
  93. \sa wc_CmacFinalNoFree
  94. \sa wc_CmacFree
  95. */
  96. int wc_CmacFinalNoFree(Cmac* cmac,
  97. byte* out, word32* outSz);
  98. /*!
  99. \ingroup CMAC
  100. \brief Generate the final result using Cipher-based Message Authentication Code, and clean up the context with wc_CmacFree().
  101. \return 0 on success
  102. \param cmac pointer to the Cmac structure
  103. \param out pointer to return the result
  104. \param outSz pointer size of output (in/out)
  105. _Example_
  106. \code
  107. ret = wc_CmacFinal(cmac, out, &outSz);
  108. \endcode
  109. \sa wc_InitCmac
  110. \sa wc_CmacFinalNoFree
  111. \sa wc_CmacFinalNoFree
  112. \sa wc_CmacFree
  113. */
  114. int wc_CmacFinal(Cmac* cmac,
  115. byte* out, word32* outSz);
  116. /*!
  117. \ingroup CMAC
  118. \brief Clean up allocations in a CMAC context.
  119. \return 0 on success
  120. \param cmac pointer to the Cmac structure
  121. _Example_
  122. \code
  123. ret = wc_CmacFinalNoFree(cmac, out, &outSz);
  124. (void)wc_CmacFree(cmac);
  125. \endcode
  126. \sa wc_InitCmac
  127. \sa wc_CmacFinalNoFree
  128. \sa wc_CmacFinal
  129. \sa wc_CmacFree
  130. */
  131. int wc_CmacFree(Cmac* cmac);
  132. /*!
  133. \ingroup CMAC
  134. \brief Single shot function for generating a CMAC
  135. \return 0 on success
  136. \param out pointer to return the result
  137. \param outSz pointer size of output (in/out)
  138. \param in input data to process
  139. \param inSz size of input data
  140. \param key key pointer
  141. \param keySz size of the key pointer (16, 24 or 32)
  142. _Example_
  143. \code
  144. ret = wc_AesCmacGenerate(mac, &macSz, msg, msgSz, key, keySz);
  145. \endcode
  146. \sa wc_AesCmacVerify
  147. */
  148. int wc_AesCmacGenerate(byte* out, word32* outSz,
  149. const byte* in, word32 inSz,
  150. const byte* key, word32 keySz);
  151. /*!
  152. \ingroup CMAC
  153. \brief Single shot function for validating a CMAC
  154. \return 0 on success
  155. \param check pointer to return the result
  156. \param checkSz size of checkout buffer
  157. \param in input data to process
  158. \param inSz size of input data
  159. \param key key pointer
  160. \param keySz size of the key pointer (16, 24 or 32)
  161. _Example_
  162. \code
  163. ret = wc_AesCmacVerify(mac, macSz, msg, msgSz, key, keySz);
  164. \endcode
  165. \sa wc_AesCmacGenerate
  166. */
  167. int wc_AesCmacVerify(const byte* check, word32 checkSz,
  168. const byte* in, word32 inSz,
  169. const byte* key, word32 keySz);
  170. /*!
  171. \ingroup CMAC
  172. \brief Only used with WOLFSSL_HASH_KEEP when hardware requires single-shot and the updates must be cached in memory
  173. \return 0 on success
  174. \param in input data to process
  175. \param inSz size of input data
  176. _Example_
  177. \code
  178. ret = wc_CMAC_Grow(cmac, in, inSz)
  179. \endcode
  180. */
  181. int wc_CMAC_Grow(Cmac* cmac, const byte* in, int inSz);