hkdf.h 5.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139
  1. /**
  2. * \file hkdf.h
  3. *
  4. * \brief This file contains the HKDF interface.
  5. *
  6. * The HMAC-based Extract-and-Expand Key Derivation Function (HKDF) is
  7. * specified by RFC 5869.
  8. */
  9. /*
  10. * Copyright The Mbed TLS Contributors
  11. * SPDX-License-Identifier: Apache-2.0
  12. *
  13. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  14. * not use this file except in compliance with the License.
  15. * You may obtain a copy of the License at
  16. *
  17. * http://www.apache.org/licenses/LICENSE-2.0
  18. *
  19. * Unless required by applicable law or agreed to in writing, software
  20. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  21. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  22. * See the License for the specific language governing permissions and
  23. * limitations under the License.
  24. */
  25. #ifndef MBEDTLS_HKDF_H
  26. #define MBEDTLS_HKDF_H
  27. #if !defined(MBEDTLS_CONFIG_FILE)
  28. #include "mbedtls/config.h"
  29. #else
  30. #include MBEDTLS_CONFIG_FILE
  31. #endif
  32. #include "mbedtls/md.h"
  33. /**
  34. * \name HKDF Error codes
  35. * \{
  36. */
  37. #define MBEDTLS_ERR_HKDF_BAD_INPUT_DATA -0x5F80 /**< Bad input parameters to function. */
  38. /* \} name */
  39. #ifdef __cplusplus
  40. extern "C" {
  41. #endif
  42. /**
  43. * \brief This is the HMAC-based Extract-and-Expand Key Derivation Function
  44. * (HKDF).
  45. *
  46. * \param md A hash function; md.size denotes the length of the hash
  47. * function output in bytes.
  48. * \param salt An optional salt value (a non-secret random value);
  49. * if the salt is not provided, a string of all zeros of
  50. * md.size length is used as the salt.
  51. * \param salt_len The length in bytes of the optional \p salt.
  52. * \param ikm The input keying material.
  53. * \param ikm_len The length in bytes of \p ikm.
  54. * \param info An optional context and application specific information
  55. * string. This can be a zero-length string.
  56. * \param info_len The length of \p info in bytes.
  57. * \param okm The output keying material of \p okm_len bytes.
  58. * \param okm_len The length of the output keying material in bytes. This
  59. * must be less than or equal to 255 * md.size bytes.
  60. *
  61. * \return 0 on success.
  62. * \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
  63. * \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
  64. * MD layer.
  65. */
  66. int mbedtls_hkdf( const mbedtls_md_info_t *md, const unsigned char *salt,
  67. size_t salt_len, const unsigned char *ikm, size_t ikm_len,
  68. const unsigned char *info, size_t info_len,
  69. unsigned char *okm, size_t okm_len );
  70. /**
  71. * \brief Take the input keying material \p ikm and extract from it a
  72. * fixed-length pseudorandom key \p prk.
  73. *
  74. * \warning This function should only be used if the security of it has been
  75. * studied and established in that particular context (eg. TLS 1.3
  76. * key schedule). For standard HKDF security guarantees use
  77. * \c mbedtls_hkdf instead.
  78. *
  79. * \param md A hash function; md.size denotes the length of the
  80. * hash function output in bytes.
  81. * \param salt An optional salt value (a non-secret random value);
  82. * if the salt is not provided, a string of all zeros
  83. * of md.size length is used as the salt.
  84. * \param salt_len The length in bytes of the optional \p salt.
  85. * \param ikm The input keying material.
  86. * \param ikm_len The length in bytes of \p ikm.
  87. * \param[out] prk A pseudorandom key of at least md.size bytes.
  88. *
  89. * \return 0 on success.
  90. * \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
  91. * \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
  92. * MD layer.
  93. */
  94. int mbedtls_hkdf_extract( const mbedtls_md_info_t *md,
  95. const unsigned char *salt, size_t salt_len,
  96. const unsigned char *ikm, size_t ikm_len,
  97. unsigned char *prk );
  98. /**
  99. * \brief Expand the supplied \p prk into several additional pseudorandom
  100. * keys, which is the output of the HKDF.
  101. *
  102. * \warning This function should only be used if the security of it has been
  103. * studied and established in that particular context (eg. TLS 1.3
  104. * key schedule). For standard HKDF security guarantees use
  105. * \c mbedtls_hkdf instead.
  106. *
  107. * \param md A hash function; md.size denotes the length of the hash
  108. * function output in bytes.
  109. * \param prk A pseudorandom key of at least md.size bytes. \p prk is
  110. * usually the output from the HKDF extract step.
  111. * \param prk_len The length in bytes of \p prk.
  112. * \param info An optional context and application specific information
  113. * string. This can be a zero-length string.
  114. * \param info_len The length of \p info in bytes.
  115. * \param okm The output keying material of \p okm_len bytes.
  116. * \param okm_len The length of the output keying material in bytes. This
  117. * must be less than or equal to 255 * md.size bytes.
  118. *
  119. * \return 0 on success.
  120. * \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
  121. * \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
  122. * MD layer.
  123. */
  124. int mbedtls_hkdf_expand( const mbedtls_md_info_t *md, const unsigned char *prk,
  125. size_t prk_len, const unsigned char *info,
  126. size_t info_len, unsigned char *okm, size_t okm_len );
  127. #ifdef __cplusplus
  128. }
  129. #endif
  130. #endif /* hkdf.h */