hkdf.h

00001 /**
00002  * \file hkdf.h
00003  *
00004  * \brief   This file contains the HKDF interface.
00005  *
00006  *          The HMAC-based Extract-and-Expand Key Derivation Function (HKDF) is
00007  *          specified by RFC 5869.
00008  */
00009 /*
00010  *  Copyright (C) 2018-2019, ARM Limited, All Rights Reserved
00011  *  SPDX-License-Identifier: Apache-2.0
00012  *
00013  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00014  *  not use this file except in compliance with the License.
00015  *  You may obtain a copy of the License at
00016  *
00017  *  http://www.apache.org/licenses/LICENSE-2.0
00018  *
00019  *  Unless required by applicable law or agreed to in writing, software
00020  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00021  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00022  *  See the License for the specific language governing permissions and
00023  *  limitations under the License.
00024  *
00025  *  This file is part of mbed TLS (https://tls.mbed.org)
00026  */
00027 #ifndef MBEDTLS_HKDF_H
00028 #define MBEDTLS_HKDF_H
00029 
00030 #if !defined(MBEDTLS_CONFIG_FILE)
00031 #include "mbedtls/config.h"
00032 #else
00033 #include MBEDTLS_CONFIG_FILE
00034 #endif
00035 
00036 #include "mbedtls/md.h"
00037 
00038 /**
00039  *  \name HKDF Error codes
00040  *  \{
00041  */
00042 #define MBEDTLS_ERR_HKDF_BAD_INPUT_DATA  -0x5F80  /**< Bad input parameters to function. */
00043 /* \} name */
00044 
00045 #ifdef __cplusplus
00046 extern "C" {
00047 #endif
00048 
00049 /**
00050  *  \brief  This is the HMAC-based Extract-and-Expand Key Derivation Function
00051  *          (HKDF).
00052  *
00053  *  \param  md        A hash function; md.size denotes the length of the hash
00054  *                    function output in bytes.
00055  *  \param  salt      An optional salt value (a non-secret random value);
00056  *                    if the salt is not provided, a string of all zeros of
00057  *                    md.size length is used as the salt.
00058  *  \param  salt_len  The length in bytes of the optional \p salt.
00059  *  \param  ikm       The input keying material.
00060  *  \param  ikm_len   The length in bytes of \p ikm.
00061  *  \param  info      An optional context and application specific information
00062  *                    string. This can be a zero-length string.
00063  *  \param  info_len  The length of \p info in bytes.
00064  *  \param  okm       The output keying material of \p okm_len bytes.
00065  *  \param  okm_len   The length of the output keying material in bytes. This
00066  *                    must be less than or equal to 255 * md.size bytes.
00067  *
00068  *  \return 0 on success.
00069  *  \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
00070  *  \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
00071  *          MD layer.
00072  */
00073 int mbedtls_hkdf( const mbedtls_md_info_t *md, const unsigned char *salt,
00074                   size_t salt_len, const unsigned char *ikm, size_t ikm_len,
00075                   const unsigned char *info, size_t info_len,
00076                   unsigned char *okm, size_t okm_len );
00077 
00078 /**
00079  *  \brief  Take the input keying material \p ikm and extract from it a
00080  *          fixed-length pseudorandom key \p prk.
00081  *
00082  *  \warning    This function should only be used if the security of it has been
00083  *              studied and established in that particular context (eg. TLS 1.3
00084  *              key schedule). For standard HKDF security guarantees use
00085  *              \c mbedtls_hkdf instead.
00086  *
00087  *  \param       md        A hash function; md.size denotes the length of the
00088  *                         hash function output in bytes.
00089  *  \param       salt      An optional salt value (a non-secret random value);
00090  *                         if the salt is not provided, a string of all zeros
00091  *                         of md.size length is used as the salt.
00092  *  \param       salt_len  The length in bytes of the optional \p salt.
00093  *  \param       ikm       The input keying material.
00094  *  \param       ikm_len   The length in bytes of \p ikm.
00095  *  \param[out]  prk       A pseudorandom key of at least md.size bytes.
00096  *
00097  *  \return 0 on success.
00098  *  \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
00099  *  \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
00100  *          MD layer.
00101  */
00102 int mbedtls_hkdf_extract( const mbedtls_md_info_t *md,
00103                           const unsigned char *salt, size_t salt_len,
00104                           const unsigned char *ikm, size_t ikm_len,
00105                           unsigned char *prk );
00106 
00107 /**
00108  *  \brief  Expand the supplied \p prk into several additional pseudorandom
00109  *          keys, which is the output of the HKDF.
00110  *
00111  *  \warning    This function should only be used if the security of it has been
00112  *              studied and established in that particular context (eg. TLS 1.3
00113  *              key schedule). For standard HKDF security guarantees use
00114  *              \c mbedtls_hkdf instead.
00115  *
00116  *  \param  md        A hash function; md.size denotes the length of the hash
00117  *                    function output in bytes.
00118  *  \param  prk       A pseudorandom key of at least md.size bytes. \p prk is
00119  *                    usually the output from the HKDF extract step.
00120  *  \param  prk_len   The length in bytes of \p prk.
00121  *  \param  info      An optional context and application specific information
00122  *                    string. This can be a zero-length string.
00123  *  \param  info_len  The length of \p info in bytes.
00124  *  \param  okm       The output keying material of \p okm_len bytes.
00125  *  \param  okm_len   The length of the output keying material in bytes. This
00126  *                    must be less than or equal to 255 * md.size bytes.
00127  *
00128  *  \return 0 on success.
00129  *  \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
00130  *  \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
00131  *          MD layer.
00132  */
00133 int mbedtls_hkdf_expand( const mbedtls_md_info_t *md, const unsigned char *prk,
00134                          size_t prk_len, const unsigned char *info,
00135                          size_t info_len, unsigned char *okm, size_t okm_len );
00136 
00137 #ifdef __cplusplus
00138 }
00139 #endif
00140 
00141 #endif /* hkdf.h */