_ 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  * ## SHAKE
  86  *
  87  * SHAKE is defined in
  88  * [FIPS 202](https://csrc.nist.gov/publications/detail/fips/202/final)
  89  * under two versions: SHAKE128 and SHAKE256, offering an alleged
  90  * "security level" of 128 and 256 bits, respectively (SHAKE128 is
  91  * about 20 to 25% faster than SHAKE256). SHAKE internally relies on
  92  * the Keccak family of sponge functions, not on any externally provided
  93  * hash function. Contrary to HKDF, SHAKE does not have a concept of
  94  * either a "salt" or an "info" string. The API consists in four
  95  * functions:
  96  *
  97  *  - `br_shake_init()`: initialize a SHAKE context for a given
  98  *    security level.
  99  *
 100  *  - `br_shake_inject()`: inject more input bytes. This function may be
 101  *    called repeatedly if the input data is provided by chunks.
 102  *
 103  *  - `br_shake_flip()`: end the data injection process, and start the
 104  *    data production process.
 105  *
 106  *  - `br_shake_produce()`: get the next bytes of output. This function
 107  *    may be called several times to obtain the full output by chunks.
 108  */
 109
 110 /**
 111  * \brief HKDF context.
 112  *
 113  * The HKDF context is initialized with a hash function implementation
 114  * and a salt value. Contents are opaque (callers should not access them
 115  * directly). The caller is responsible for allocating the context where
 116  * appropriate. Context initialisation and usage incurs no dynamic
 117  * allocation, so there is no release function.
 118  */
 119 typedef struct {
 120 #ifndef BR_DOXYGEN_IGNORE
 121         union {
 122                 br_hmac_context hmac_ctx;
 123                 br_hmac_key_context prk_ctx;
 124         } u;
 125         unsigned char buf[64];
 126         size_t ptr;
 127         size_t dig_len;
 128         unsigned chunk_num;
 129 #endif
 130 } br_hkdf_context;
 131
 132 /**
 133  * \brief HKDF context initialization.
 134  *
 135  * The underlying hash function and salt value are provided. Arbitrary
 136  * salt lengths can be used.
 137  *
 138  * HKDF makes a difference between a salt of length zero, and an
 139  * absent salt (the latter being equivalent to a salt consisting of
 140  * bytes of value zero, of the same length as the hash function output).
 141  * If `salt_len` is zero, then this function assumes that the salt is
 142  * present but of length zero. To specify an _absent_ salt, use
 143  * `BR_HKDF_NO_SALT` as `salt` parameter (`salt_len` is then ignored).
 144  *
 145  * \param hc              HKDF context to initialise.
 146  * \param digest_vtable   pointer to the hash function implementation vtable.
 147  * \param salt            HKDF-Extract salt.
 148  * \param salt_len        HKDF-Extract salt length (in bytes).
 149  */
 150 void br_hkdf_init(br_hkdf_context *hc, const br_hash_class *digest_vtable,
 151         const void *salt, size_t salt_len);
 152
 153 /**
 154  * \brief The special "absent salt" value for HKDF.
 155  */
 156 #define BR_HKDF_NO_SALT   (&br_hkdf_no_salt)
 157
 158 #ifndef BR_DOXYGEN_IGNORE
 159 extern const unsigned char br_hkdf_no_salt;
 160 #endif
 161
 162 /**
 163  * \brief HKDF input injection (HKDF-Extract).
 164  *
 165  * This function injects some more input bytes ("key material") into
 166  * HKDF. This function may be called several times, after `br_hkdf_init()`
 167  * but before `br_hkdf_flip()`.
 168  *
 169  * \param hc        HKDF context.
 170  * \param ikm       extra input bytes.
 171  * \param ikm_len   number of extra input bytes.
 172  */
 173 void br_hkdf_inject(br_hkdf_context *hc, const void *ikm, size_t ikm_len);
 174
 175 /**
 176  * \brief HKDF switch to the HKDF-Expand phase.
 177  *
 178  * This call terminates the HKDF-Extract process (input injection), and
 179  * starts the HKDF-Expand process (output production).
 180  *
 181  * \param hc   HKDF context.
 182  */
 183 void br_hkdf_flip(br_hkdf_context *hc);
 184
 185 /**
 186  * \brief HKDF output production (HKDF-Expand).
 187  *
 188  * Produce more output bytes from the current state. This function may be
 189  * called several times, but only after `br_hkdf_flip()`.
 190  *
 191  * Returned value is the number of actually produced bytes. The total
 192  * output length is limited to 255 times the output length of the
 193  * underlying hash function.
 194  *
 195  * \param hc         HKDF context.
 196  * \param info       application specific information string.
 197  * \param info_len   application specific information string length (in bytes).
 198  * \param out        destination buffer for the HKDF output.
 199  * \param out_len    the length of the requested output (in bytes).
 200  * \return  the produced output length (in bytes).
 201  */
 202 size_t br_hkdf_produce(br_hkdf_context *hc,
 203         const void *info, size_t info_len, void *out, size_t out_len);
 204
 205 /**
 206  * \brief SHAKE context.
 207  *
 208  * The HKDF context is initialized with a "security level". The internal
 209  * notion is called "capacity"; the capacity is twice the security level
 210  * (for instance, SHAKE128 has capacity 256).
 211  *
 212  * The caller is responsible for allocating the context where
 213  * appropriate. Context initialisation and usage incurs no dynamic
 214  * allocation, so there is no release function.
 215  */
 216 typedef struct {
 217 #ifndef BR_DOXYGEN_IGNORE
 218         unsigned char dbuf[200];
 219         size_t dptr;
 220         size_t rate;
 221         uint64_t A[25];
 222 #endif
 223 } br_shake_context;
 224
 225 /**
 226  * \brief SHAKE context initialization.
 227  *
 228  * The context is initialized for the provided "security level".
 229  * Internally, this sets the "capacity" to twice the security level;
 230  * thus, for SHAKE128, the `security_level` parameter should be 128,
 231  * which corresponds to a 256-bit capacity.
 232  *
 233  * Allowed security levels are all multiples of 32, from 32 to 768,
 234  * inclusive. Larger security levels imply lower performance; levels
 235  * beyond 256 bits don't make much sense. Standard levels are 128
 236  * and 256 bits (for SHAKE128 and SHAKE256, respectively).
 237  *
 238  * \param sc               SHAKE context to initialise.
 239  * \param security_level   security level (in bits).
 240  */
 241 void br_shake_init(br_shake_context *sc, int security_level);
 242
 243 /**
 244  * \brief SHAKE input injection.
 245  *
 246  * This function injects some more input bytes ("key material") into
 247  * SHAKE. This function may be called several times, after `br_shake_init()`
 248  * but before `br_shake_flip()`.
 249  *
 250  * \param sc     SHAKE context.
 251  * \param data   extra input bytes.
 252  * \param len    number of extra input bytes.
 253  */
 254 void br_shake_inject(br_shake_context *sc, const void *data, size_t len);
 255
 256 /**
 257  * \brief SHAKE switch to production phase.
 258  *
 259  * This call terminates the input injection process, and starts the
 260  * output production process.
 261  *
 262  * \param sc   SHAKE context.
 263  */
 264 void br_shake_flip(br_shake_context *hc);
 265
 266 /**
 267  * \brief SHAKE output production.
 268  *
 269  * Produce more output bytes from the current state. This function may be
 270  * called several times, but only after `br_shake_flip()`.
 271  *
 272  * There is no practical limit to the number of bytes that may be produced.
 273  *
 274  * \param sc    SHAKE context.
 275  * \param out   destination buffer for the SHAKE output.
 276  * \param len   the length of the requested output (in bytes).
 277  */
 278 void br_shake_produce(br_shake_context *sc, void *out, size_t len);
 279
 280 #ifdef __cplusplus
 281 }
 282 #endif
 283
 284 #endif