hkdf.h 5.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141
  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 (C) 2016-2019, ARM Limited, All Rights Reserved
  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. * This file is part of mbed TLS (https://tls.mbed.org)
  26. */
  27. #ifndef MBEDTLS_HKDF_H
  28. #define MBEDTLS_HKDF_H
  29. #if !defined(MBEDTLS_CONFIG_FILE)
  30. #include "config.h"
  31. #else
  32. #include MBEDTLS_CONFIG_FILE
  33. #endif
  34. #include "md.h"
  35. /**
  36. * \name HKDF Error codes
  37. * \{
  38. */
  39. #define MBEDTLS_ERR_HKDF_BAD_INPUT_DATA -0x5F80 /**< Bad input parameters to function. */
  40. /* \} name */
  41. #ifdef __cplusplus
  42. extern "C" {
  43. #endif
  44. /**
  45. * \brief This is the HMAC-based Extract-and-Expand Key Derivation Function
  46. * (HKDF).
  47. *
  48. * \param md A hash function; md.size denotes the length of the hash
  49. * function output in bytes.
  50. * \param salt An optional salt value (a non-secret random value);
  51. * if the salt is not provided, a string of all zeros of
  52. * md.size length is used as the salt.
  53. * \param salt_len The length in bytes of the optional \p salt.
  54. * \param ikm The input keying material.
  55. * \param ikm_len The length in bytes of \p ikm.
  56. * \param info An optional context and application specific information
  57. * string. This can be a zero-length string.
  58. * \param info_len The length of \p info in bytes.
  59. * \param okm The output keying material of \p okm_len bytes.
  60. * \param okm_len The length of the output keying material in bytes. This
  61. * must be less than or equal to 255 * md.size bytes.
  62. *
  63. * \return 0 on success.
  64. * \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
  65. * \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
  66. * MD layer.
  67. */
  68. int mbedtls_hkdf( const mbedtls_md_info_t *md, const unsigned char *salt,
  69. size_t salt_len, const unsigned char *ikm, size_t ikm_len,
  70. const unsigned char *info, size_t info_len,
  71. unsigned char *okm, size_t okm_len );
  72. /**
  73. * \brief Take the input keying material \p ikm and extract from it a
  74. * fixed-length pseudorandom key \p prk.
  75. *
  76. * \warning This function should only be used if the security of it has been
  77. * studied and established in that particular context (eg. TLS 1.3
  78. * key schedule). For standard HKDF security guarantees use
  79. * \c mbedtls_hkdf instead.
  80. *
  81. * \param md A hash function; md.size denotes the length of the
  82. * hash function output in bytes.
  83. * \param salt An optional salt value (a non-secret random value);
  84. * if the salt is not provided, a string of all zeros
  85. * of md.size length is used as the salt.
  86. * \param salt_len The length in bytes of the optional \p salt.
  87. * \param ikm The input keying material.
  88. * \param ikm_len The length in bytes of \p ikm.
  89. * \param[out] prk A pseudorandom key of at least md.size bytes.
  90. *
  91. * \return 0 on success.
  92. * \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
  93. * \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
  94. * MD layer.
  95. */
  96. int mbedtls_hkdf_extract( const mbedtls_md_info_t *md,
  97. const unsigned char *salt, size_t salt_len,
  98. const unsigned char *ikm, size_t ikm_len,
  99. unsigned char *prk );
  100. /**
  101. * \brief Expand the supplied \p prk into several additional pseudorandom
  102. * keys, which is the output of the HKDF.
  103. *
  104. * \warning This function should only be used if the security of it has been
  105. * studied and established in that particular context (eg. TLS 1.3
  106. * key schedule). For standard HKDF security guarantees use
  107. * \c mbedtls_hkdf instead.
  108. *
  109. * \param md A hash function; md.size denotes the length of the hash
  110. * function output in bytes.
  111. * \param prk A pseudorandom key of at least md.size bytes. \p prk is
  112. * usually the output from the HKDF extract step.
  113. * \param prk_len The length in bytes of \p prk.
  114. * \param info An optional context and application specific information
  115. * string. This can be a zero-length string.
  116. * \param info_len The length of \p info in bytes.
  117. * \param okm The output keying material of \p okm_len bytes.
  118. * \param okm_len The length of the output keying material in bytes. This
  119. * must be less than or equal to 255 * md.size bytes.
  120. *
  121. * \return 0 on success.
  122. * \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
  123. * \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
  124. * MD layer.
  125. */
  126. int mbedtls_hkdf_expand( const mbedtls_md_info_t *md, const unsigned char *prk,
  127. size_t prk_len, const unsigned char *info,
  128. size_t info_len, unsigned char *okm, size_t okm_len );
  129. #ifdef __cplusplus
  130. }
  131. #endif
  132. #endif /* hkdf.h */