_ Git - BearSSL/blob - inc/bearssl_kdf.h

   1 /*
   2  * Copyright (c) 2018 Thomas Pornin <pornin@bolet.org>
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining
   5  * a copy of this software and associated documentation files (the
   6  * "Software"), to deal in the Software without restriction, including
   7  * without limitation the rights to use, copy, modify, merge, publish,
   8  * distribute, sublicense, and/or sell copies of the Software, and to
   9  * permit persons to whom the Software is furnished to do so, subject to
  10  * the following conditions:
  11  *
  12  * The above copyright notice and this permission notice shall be
  13  * included in all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  18  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
  19  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  20  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  21  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  22  * SOFTWARE.
  23  */
  24
  25 #ifndef BR_BEARSSL_KDF_H__
  26 #define BR_BEARSSL_KDF_H__
  27
  28 #include <stddef.h>
  29 #include <stdint.h>
  30
  31 #include "bearssl_hash.h"
  32 #include "bearssl_hmac.h"
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /** \file bearssl_kdf.h
  39  *
  40  * # Key Derivation Functions
  41  *
  42  * KDF are functions that takes a variable length input, and provide a
  43  * variable length output, meant to be used to derive subkeys from a
  44  * master key.
  45  *
  46  * ## HKDF
  47  *
  48  * HKDF is a KDF defined by [RFC 5869](https://tools.ietf.org/html/rfc5869).
  49  * It is based on HMAC, itself using an underlying hash function. Any
  50  * hash function can be used, as long as it is compatible with the rules
  51  * for the HMAC implementation (i.e. output size is 64 bytes or less, hash
  52  * internal state size is 64 bytes or less, and the internal block length is
  53  * a power of 2 between 16 and 256 bytes). HKDF has two phases:
  54  *
  55  *  - HKDF-Extract: the input data in ingested, along with a "salt" value.
  56  *
  57  *  - HKDF-Expand: the output is produced, from the result of processing
  58  *    the input and salt, and using an extra non-secret parameter called
  59  *    "info".
  60  *
  61  * The "salt" and "info" strings are non-secret and can be empty. Their role
  62  * is normally to bind the input and output, respectively, to conventional
  63  * identifiers that qualifu them within the used protocol or application.
  64  *
  65  * The implementation defined in this file uses the following functions:
  66  *
  67  *  - `br_hkdf_init()`: initialize an HKDF context, with a hash function,
  68  *    and the salt. This starts the HKDF-Extract process.
  69  *
  70  *  - `br_hkdf_inject()`: inject more input bytes. This function may be
  71  *    called repeatedly if the input data is provided by chunks.
  72  *
  73  *  - `br_hkdf_flip()`: end the HKDF-Extract process, and start the
  74  *    HKDF-Expand process.
  75  *
  76  *  - `br_hkdf_produce()`: get the next bytes of output. This function
  77  *    may be called several times to obtain the full output by chunks.
  78  *    For correct HKDF processing, the same "info" string must be
  79  *    provided for each call.
  80  *
  81  * Note that the HKDF total output size (the number of bytes that
  82  * HKDF-Expand is willing to produce) is limited: if the hash output size
  83  * is _n_ bytes, then the maximum output size is _255*n_.
  84  */
  85
  86 /**
  87  * \brief HKDF context.
  88  *
  89  * The HKDF context is initialized with a hash function implementation
  90  * and a salt value. Contents are opaque (callers should not access them
  91  * directly). The caller is responsible for allocating the context where
  92  * appropriate. Context initialisation and usage incurs no dynamic
  93  * allocation, so there is no release function.
  94  */
  95 typedef struct {
  96 #ifndef BR_DOXYGEN_IGNORE
  97         union {
  98                 br_hmac_context hmac_ctx;
  99                 br_hmac_key_context prk_ctx;
 100         } u;
 101         unsigned char buf[64];
 102         size_t ptr;
 103         size_t dig_len;
 104         unsigned chunk_num;
 105 #endif
 106 } br_hkdf_context;
 107
 108 /**
 109  * \brief HKDF context initialization.
 110  *
 111  * The underlying hash function and salt value are provided. Arbitrary
 112  * salt lengths can be used.
 113  *
 114  * HKDF makes a difference between a salt of length zero, and an
 115  * absent salt (the latter being equivalent to a salt consisting of
 116  * bytes of value zero, of the same length as the hash function output).
 117  * If `salt_len` is zero, then this function assumes that the salt is
 118  * present but of length zero. To specify an _absent_ salt, use
 119  * `BR_HKDF_NO_SALT` as `salt` parameter (`salt_len` is then ignored).
 120  *
 121  * \param hc              HKDF context to initialise.
 122  * \param digest_vtable   pointer to the hash function implementation vtable.
 123  * \param salt            HKDF-Extract salt.
 124  * \param salt_len        HKDF-Extract salt length (in bytes).
 125  */
 126 void br_hkdf_init(br_hkdf_context *hc, const br_hash_class *digest_vtable,
 127         const void *salt, size_t salt_len);
 128
 129 /**
 130  * \brief The special "absent salt" value for HKDF.
 131  */
 132 #define BR_HKDF_NO_SALT   (&br_hkdf_no_salt)
 133
 134 #ifndef BR_DOXYGEN_IGNORE
 135 extern const unsigned char br_hkdf_no_salt;
 136 #endif
 137
 138 /**
 139  * \brief HKDF input injection (HKDF-Extract).
 140  *
 141  * This function injects some more input bytes ("key material") into
 142  * HKDF. This function may be called several times, after `br_hkdf_init()`
 143  * but before `br_hkdf_flip()`.
 144  *
 145  * \param hc        HKDF context.
 146  * \param ikm       extra input bytes.
 147  * \param ikm_len   number of extra input bytes.
 148  */
 149 void br_hkdf_inject(br_hkdf_context *hc, const void *ikm, size_t ikm_len);
 150
 151 /**
 152  * \brief HKDF switch to the HKDF-Expand phase.
 153  *
 154  * This call terminates the HKDF-Extract process (input injection), and
 155  * starts the HKDF-Expand process (output production).
 156  *
 157  * \param hc   HKDF context.
 158  */
 159 void br_hkdf_flip(br_hkdf_context *hc);
 160
 161 /**
 162  * \brief HKDF output production (HKDF-Expand).
 163  *
 164  * Produce more output bytes from the current state. This function may be
 165  * called several times, but only after `br_hkdf_flip()`.
 166  *
 167  * Returned value is the number of actually produced bytes. The total
 168  * output length is limited to 255 times the output length of the
 169  * underlying hash function.
 170  *
 171  * \param hc         HKDF context.
 172  * \param info       application specific information string.
 173  * \param info_len   application specific information string length (in bytes).
 174  * \param out        destination buffer for the HKDF output.
 175  * \param out_len    the length of the requested output (in bytes).
 176  * \return  the produced output length (in bytes).
 177  */
 178 size_t br_hkdf_produce(br_hkdf_context *hc,
 179         const void *info, size_t info_len, void *out, size_t out_len);
 180
 181 #ifdef __cplusplus
 182 }
 183 #endif
 184
 185 #endif