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

   1 /*
   2  * Copyright (c) 2016 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_HMAC_H__
  26 #define BR_BEARSSL_HMAC_H__
  27
  28 #include <stddef.h>
  29 #include <stdint.h>
  30
  31 #include "bearssl_hash.h"
  32
  33 /** \file bearssl_hmac.h
  34  *
  35  * # HMAC
  36  *
  37  * HMAC is initialized with a key and an underlying hash function; it
  38  * then fills a "key context". That context contains the processed
  39  * key.
  40  *
  41  * With the key context, a HMAC context can be initialized to process
  42  * the input bytes and obtain the MAC output. The key context is not
  43  * modified during that process, and can be reused.
  44  *
  45  * IMPORTANT: HMAC shall be used only with functions that have the
  46  * following properties:
  47  *
  48  *   - hash output size does not exceed 64 bytes;
  49  *   - hash internal state size does not exceed 64 bytes;
  50  *   - internal block length is a power of 2 between 16 and 256 bytes.
  51  */
  52
  53 /**
  54  * \brief HMAC key context.
  55  *
  56  * The HMAC key context is initialised with a hash function implementation
  57  * and a secret key. Contents are opaque (callers should not access them
  58  * directly). The caller is responsible for allocating the context where
  59  * appropriate. Context initialisation and usage incurs no dynamic
  60  * allocation, so there is no release function.
  61  */
  62 typedef struct {
  63 #ifndef BR_DOXYGEN_IGNORE
  64         const br_hash_class *dig_vtable;
  65         unsigned char ksi[64], kso[64];
  66 #endif
  67 } br_hmac_key_context;
  68
  69 /**
  70  * \brief HMAC key context initialisation.
  71  *
  72  * Initialise the key context with the provided key, using the hash function
  73  * identified by `digest_vtable`. This supports arbitrary key lengths.
  74  *
  75  * \param kc              HMAC key context to initialise.
  76  * \param digest_vtable   pointer to the hash function implementation vtable.
  77  * \param key             pointer to the HMAC secret key.
  78  * \param key_len         HMAC secret key length (in bytes).
  79  */
  80 void br_hmac_key_init(br_hmac_key_context *kc,
  81         const br_hash_class *digest_vtable, const void *key, size_t key_len);
  82
  83 /**
  84  * \brief HMAC computation context.
  85  *
  86  * The HMAC computation context maintains the state for a single HMAC
  87  * computation. It is modified as input bytes are injected. The context
  88  * is caller-allocated and has no release function since it does not
  89  * dynamically allocate external resources. Its contents are opaque.
  90  */
  91 typedef struct {
  92 #ifndef BR_DOXYGEN_IGNORE
  93         br_hash_compat_context dig;
  94         unsigned char kso[64];
  95         size_t out_len;
  96 #endif
  97 } br_hmac_context;
  98
  99 /**
 100  * \brief HMAC computation initialisation.
 101  *
 102  * Initialise a HMAC context with a key context. The key context is
 103  * unmodified. Relevant data from the key context is immediately copied;
 104  * the key context can thus be independently reused, modified or released
 105  * without impacting this HMAC computation.
 106  *
 107  * An explicit output length can be specified; the actual output length
 108  * will be the minimum of that value and the natural HMAC output length.
 109  * If `out_len` is 0, then the natural HMAC output length is selected. The
 110  * "natural output length" is the output length of the underlying hash
 111  * function.
 112  *
 113  * \param ctx       HMAC context to initialise.
 114  * \param kc        HMAC key context (already initialised with the key).
 115  * \param out_len   HMAC output length (0 to select "natural length").
 116  */
 117 void br_hmac_init(br_hmac_context *ctx,
 118         const br_hmac_key_context *kc, size_t out_len);
 119
 120 /**
 121  * \brief Get the HMAC output size.
 122  *
 123  * The HMAC output size is the number of bytes that will actually be
 124  * produced with `br_hmac_out()` with the provided context. This function
 125  * MUST NOT be called on a non-initialised HMAC computation context.
 126  * The returned value is the minimum of the HMAC natural length (output
 127  * size of the underlying hash function) and the `out_len` parameter which
 128  * was used with the last `br_hmac_init()` call on that context (if the
 129  * initialisation `out_len` parameter was 0, then this function will
 130  * return the HMAC natural length).
 131  *
 132  * \param ctx   the (already initialised) HMAC computation context.
 133  * \return  the HMAC actual output size.
 134  */
 135 static inline size_t
 136 br_hmac_size(br_hmac_context *ctx)
 137 {
 138         return ctx->out_len;
 139 }
 140
 141 /**
 142  * \brief Inject some bytes in HMAC.
 143  *
 144  * The provided `len` bytes are injected as extra input in the HMAC
 145  * computation incarnated by the `ctx` HMAC context. It is acceptable
 146  * that `len` is zero, in which case `data` is ignored (and may be
 147  * `NULL`) and this function does nothing.
 148  */
 149 void br_hmac_update(br_hmac_context *ctx, const void *data, size_t len);
 150
 151 /**
 152  * \brief Compute the HMAC output.
 153  *
 154  * The destination buffer MUST be large enough to accomodate the result;
 155  * its length is at most the "natural length" of HMAC (i.e. the output
 156  * length of the underlying hash function). The context is NOT modified;
 157  * further bytes may be processed. Thus, "partial HMAC" values can be
 158  * efficiently obtained.
 159  *
 160  * Returned value is the output length (in bytes).
 161  *
 162  * \param ctx   HMAC computation context.
 163  * \param out   destination buffer for the HMAC output.
 164  * \return  the produced value length (in bytes).
 165  */
 166 size_t br_hmac_out(const br_hmac_context *ctx, void *out);
 167
 168 /**
 169  * \brief Constant-time HMAC computation.
 170  *
 171  * This function compute the HMAC output in constant time. Some extra
 172  * input bytes are processed, then the output is computed. The extra
 173  * input consists in the `len` bytes pointed to by `data`. The `len`
 174  * parameter must lie between `min_len` and `max_len` (inclusive);
 175  * `max_len` bytes are actually read from `data`. Computing time (and
 176  * memory access pattern) will not depend upon the data byte contents or
 177  * the value of `len`.
 178  *
 179  * The output is written in the `out` buffer, that MUST be large enough
 180  * to receive it.
 181  *
 182  * The difference `max_len - min_len` MUST be less than 2<sup>30</sup>
 183  * (i.e. about one gigabyte).
 184  *
 185  * This function computes the output properly only if the underlying
 186  * hash function uses MD padding (i.e. MD5, SHA-1, SHA-224, SHA-256,
 187  * SHA-384 or SHA-512).
 188  *
 189  * The provided context is NOT modified.
 190  *
 191  * \param ctx       the (already initialised) HMAC computation context.
 192  * \param data      the extra input bytes.
 193  * \param len       the extra input length (in bytes).
 194  * \param min_len   minimum extra input length (in bytes).
 195  * \param max_len   maximum extra input length (in bytes).
 196  * \param out       destination buffer for the HMAC output.
 197  * \return  the produced value length (in bytes).
 198  */
 199 size_t br_hmac_outCT(const br_hmac_context *ctx,
 200         const void *data, size_t len, size_t min_len, size_t max_len,
 201         void *out);
 202
 203 #endif