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) 2016-2018, 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 #include "md.h"
00031 
00032 /**
00033  *  \name HKDF Error codes
00034  *  \{
00035  */
00036 #define MBEDTLS_ERR_HKDF_BAD_INPUT_DATA  -0x5F80  /**< Bad input parameters to function. */
00037 /* \} name */
00038 
00039 #ifdef __cplusplus
00040 extern "C" {
00041 #endif
00042 
00043 /**
00044  *  \brief  This is the HMAC-based Extract-and-Expand Key Derivation Function
00045  *          (HKDF).
00046  *
00047  *  \param  md        A hash function; md.size denotes the length of the hash
00048  *                    function output in bytes.
00049  *  \param  salt      An optional salt value (a non-secret random value);
00050  *                    if the salt is not provided, a string of all zeros of
00051  *                    md.size length is used as the salt.
00052  *  \param  salt_len  The length in bytes of the optional \p salt.
00053  *  \param  ikm       The input keying material.
00054  *  \param  ikm_len   The length in bytes of \p ikm.
00055  *  \param  info      An optional context and application specific information
00056  *                    string. This can be a zero-length string.
00057  *  \param  info_len  The length of \p info in bytes.
00058  *  \param  okm       The output keying material of \p okm_len bytes.
00059  *  \param  okm_len   The length of the output keying material in bytes. This
00060  *                    must be less than or equal to 255 * md.size bytes.
00061  *
00062  *  \return 0 on success.
00063  *  \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
00064  *  \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
00065  *          MD layer.
00066  */
00067 int mbedtls_hkdf( const mbedtls_md_info_t *md, const unsigned char *salt,
00068                   size_t salt_len, const unsigned char *ikm, size_t ikm_len,
00069                   const unsigned char *info, size_t info_len,
00070                   unsigned char *okm, size_t okm_len );
00071 
00072 /**
00073  *  \brief  Take the input keying material \p ikm and extract from it a
00074  *          fixed-length pseudorandom key \p prk.
00075  *
00076  *  \warning    This function should only be used if the security of it has been
00077  *              studied and established in that particular context (eg. TLS 1.3
00078  *              key schedule). For standard HKDF security guarantees use
00079  *              \c mbedtls_hkdf instead.
00080  *
00081  *  \param       md        A hash function; md.size denotes the length of the
00082  *                         hash function output in bytes.
00083  *  \param       salt      An optional salt value (a non-secret random value);
00084  *                         if the salt is not provided, a string of all zeros
00085  *                         of md.size length is used as the salt.
00086  *  \param       salt_len  The length in bytes of the optional \p salt.
00087  *  \param       ikm       The input keying material.
00088  *  \param       ikm_len   The length in bytes of \p ikm.
00089  *  \param[out]  prk       A pseudorandom key of at least md.size bytes.
00090  *
00091  *  \return 0 on success.
00092  *  \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
00093  *  \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
00094  *          MD layer.
00095  */
00096 int mbedtls_hkdf_extract( const mbedtls_md_info_t *md,
00097                           const unsigned char *salt, size_t salt_len,
00098                           const unsigned char *ikm, size_t ikm_len,
00099                           unsigned char *prk );
00100 
00101 /**
00102  *  \brief  Expand the supplied \p prk into several additional pseudorandom
00103  *          keys, which is the output of the HKDF.
00104  *
00105  *  \warning    This function should only be used if the security of it has been
00106  *              studied and established in that particular context (eg. TLS 1.3
00107  *              key schedule). For standard HKDF security guarantees use
00108  *              \c mbedtls_hkdf instead.
00109  *
00110  *  \param  md        A hash function; md.size denotes the length of the hash
00111  *                    function output in bytes.
00112  *  \param  prk       A pseudorandom key of at least md.size bytes. \p prk is
00113  *                    usually the output from the HKDF extract step.
00114  *  \param  prk_len   The length in bytes of \p prk.
00115  *  \param  info      An optional context and application specific information
00116  *                    string. This can be a zero-length string.
00117  *  \param  info_len  The length of \p info in bytes.
00118  *  \param  okm       The output keying material of \p okm_len bytes.
00119  *  \param  okm_len   The length of the output keying material in bytes. This
00120  *                    must be less than or equal to 255 * md.size bytes.
00121  *
00122  *  \return 0 on success.
00123  *  \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
00124  *  \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
00125  *          MD layer.
00126  */
00127 int mbedtls_hkdf_expand( const mbedtls_md_info_t *md, const unsigned char *prk,
00128                          size_t prk_len, const unsigned char *info,
00129                          size_t info_len, unsigned char *okm, size_t okm_len );
00130 
00131 #ifdef __cplusplus
00132 }
00133 #endif
00134 
00135 #endif /* hkdf.h */