hmac.h 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172
  1. /*!
  2. \ingroup HMAC
  3. \brief This function initializes an Hmac object, setting its
  4. encryption type, key and HMAC length.
  5. \return 0 Returned on successfully initializing the Hmac object
  6. \return BAD_FUNC_ARG Returned if the input type is invalid. Valid options
  7. are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID
  8. \return MEMORY_E Returned if there is an error allocating memory for the
  9. structure to use for hashing
  10. \return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation
  11. and the key length specified is shorter than the minimum acceptable
  12. FIPS standard
  13. \param hmac pointer to the Hmac object to initialize
  14. \param type type specifying which encryption method the Hmac object
  15. should use. Valid options are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID
  16. \param key pointer to a buffer containing the key with which to
  17. initialize the Hmac object
  18. \param length length of the key
  19. _Example_
  20. \code
  21. Hmac hmac;
  22. byte key[] = { // initialize with key to use for encryption };
  23. if (wc_HmacSetKey(&hmac, MD5, key, sizeof(key)) != 0) {
  24. // error initializing Hmac object
  25. }
  26. \endcode
  27. \sa wc_HmacUpdate
  28. \sa wc_HmacFinal
  29. */
  30. WOLFSSL_API int wc_HmacSetKey(Hmac*, int type, const byte* key, word32 keySz);
  31. /*!
  32. \ingroup HMAC
  33. \brief This function updates the message to authenticate using HMAC.
  34. It should be called after the Hmac object has been initialized with
  35. wc_HmacSetKey. This function may be called multiple times to update
  36. the message to hash. After calling wc_HmacUpdate as desired, one should
  37. call wc_HmacFinal to obtain the final authenticated message tag.
  38. \return 0 Returned on successfully updating the message to authenticate
  39. \return MEMORY_E Returned if there is an error allocating memory for
  40. use with a hashing algorithm
  41. \param hmac pointer to the Hmac object for which to update the message
  42. \param msg pointer to the buffer containing the message to append
  43. \param length length of the message to append
  44. _Example_
  45. \code
  46. Hmac hmac;
  47. byte msg[] = { // initialize with message to authenticate };
  48. byte msg2[] = { // initialize with second half of message };
  49. // initialize hmac
  50. if( wc_HmacUpdate(&hmac, msg, sizeof(msg)) != 0) {
  51. // error updating message
  52. }
  53. if( wc_HmacUpdate(&hmac, msg2, sizeof(msg)) != 0) {
  54. // error updating with second message
  55. }
  56. \endcode
  57. \sa wc_HmacSetKey
  58. \sa wc_HmacFinal
  59. */
  60. WOLFSSL_API int wc_HmacUpdate(Hmac*, const byte*, word32);
  61. /*!
  62. \ingroup HMAC
  63. \brief This function computes the final hash of an Hmac object's message.
  64. \return 0 Returned on successfully computing the final hash
  65. \return MEMORY_E Returned if there is an error allocating memory for
  66. use with a hashing algorithm
  67. \param hmac pointer to the Hmac object for which to calculate the
  68. final hash
  69. \param hash pointer to the buffer in which to store the final hash.
  70. Should have room available as required by the hashing algorithm chosen
  71. _Example_
  72. \code
  73. Hmac hmac;
  74. byte hash[MD5_DIGEST_SIZE];
  75. // initialize hmac with MD5 as type
  76. // wc_HmacUpdate() with messages
  77. if (wc_HmacFinal(&hmac, hash) != 0) {
  78. // error computing hash
  79. }
  80. \endcode
  81. \sa wc_HmacSetKey
  82. \sa wc_HmacUpdate
  83. */
  84. WOLFSSL_API int wc_HmacFinal(Hmac*, byte*);
  85. /*!
  86. \ingroup HMAC
  87. \brief This function returns the largest HMAC digest size available
  88. based on the configured cipher suites.
  89. \return Success Returns the largest HMAC digest size available based
  90. on the configured cipher suites
  91. \param none No parameters.
  92. _Example_
  93. \code
  94. int maxDigestSz = wolfSSL_GetHmacMaxSize();
  95. \endcode
  96. \sa none
  97. */
  98. WOLFSSL_API int wolfSSL_GetHmacMaxSize(void);
  99. /*!
  100. \ingroup HMAC
  101. \brief This function provides access to a HMAC Key Derivation Function
  102. (HKDF). It utilizes HMAC to convert inKey, with an optional salt and
  103. optional info into a derived key, which it stores in out. The hash type
  104. defaults to MD5 if 0 or NULL is given.
  105. \return 0 Returned upon successfully generating a key with the given inputs
  106. \return BAD_FUNC_ARG Returned if an invalid hash type is given as
  107. argument. Valid types are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID
  108. \return MEMORY_E Returned if there is an error allocating memory
  109. \return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation
  110. and the key length specified is shorter than the minimum acceptable FIPS
  111. standard
  112. \param type hash type to use for the HKDF. Valid types are: MD5, SHA,
  113. SHA256, SHA384, SHA512, BLAKE2B_ID
  114. \param inKey pointer to the buffer containing the key to use for KDF
  115. \param inKeySz length of the input key
  116. \param salt pointer to a buffer containing an optional salt. Use NULL
  117. instead if not using a salt
  118. \param saltSz length of the salt. Use 0 if not using a salt
  119. \param info pointer to a buffer containing optional additional info.
  120. Use NULL if not appending extra info
  121. \param infoSz length of additional info. Use 0 if not using additional info
  122. \param out pointer to the buffer in which to store the derived key
  123. \param outSz space available in the output buffer to store the
  124. generated key
  125. _Example_
  126. \code
  127. byte key[] = { // initialize with key };
  128. byte salt[] = { // initialize with salt };
  129. byte derivedKey[MAX_DIGEST_SIZE];
  130. int ret = wc_HKDF(SHA512, key, sizeof(key), salt, sizeof(salt),
  131. NULL, 0, derivedKey, sizeof(derivedKey));
  132. if ( ret != 0 ) {
  133. // error generating derived key
  134. }
  135. \endcode
  136. \sa wc_HmacSetKey
  137. */
  138. WOLFSSL_API int wc_HKDF(int type, const byte* inKey, word32 inKeySz,
  139. const byte* salt, word32 saltSz,
  140. const byte* info, word32 infoSz,
  141. byte* out, word32 outSz);