_ 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 /*
  34  * HMAC
  35  * ----
  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  *   hash output size does not exceed 64 bytes
  48  *   hash internal state size does not exceed 64 bytes
  49  *   internal block length is a power of 2 between 16 and 256 bytes
  50  */
  51
  52 /*
  53  * Key context.
  54  */
  55 typedef struct {
  56         const br_hash_class *dig_vtable;
  57         unsigned char ksi[64], kso[64];
  58 } br_hmac_key_context;
  59
  60 /*
  61  * Initialize the key context with the provided key, using the hash function
  62  * identified by digest_class.
  63  */
  64 void br_hmac_key_init(br_hmac_key_context *kc,
  65         const br_hash_class *digest_class, const void *key, size_t key_len);
  66
  67 /*
  68  * A helper structure that is big enough to accommodate all context
  69  * structures for all hash functions for which HMAC is supported.
  70  */
  71 typedef union {
  72         const br_hash_class *vtable;
  73         br_md5_context md5;
  74         br_sha1_context sha1;
  75         br_sha224_context sha224;
  76         br_sha256_context sha256;
  77         br_sha384_context sha384;
  78         br_sha512_context sha512;
  79 } br_hmac_allhash_context;
  80
  81 /*
  82  * Context for an HMAC computation.
  83  */
  84 typedef struct {
  85         br_hmac_allhash_context dig;
  86         unsigned char kso[64];
  87         size_t out_len;
  88 } br_hmac_context;
  89
  90 /*
  91  * Initialize a HMAC context with a key context. The key context is
  92  * unmodified. Relevant data from the key context is immediately copied;
  93  * the key context can thus be independently reused, modified or released
  94  * without impacting this HMAC computation.
  95  *
  96  * An explicit output length can be specified; the actual output length
  97  * will be the minimum of that value and the natural HMAC output length.
  98  * If out_len is 0, then the natural HMAC output length is selected.
  99  */
 100 void br_hmac_init(br_hmac_context *ctx,
 101         const br_hmac_key_context *kc, size_t out_len);
 102
 103 /*
 104  * Get the MAC output size. The context must have been initialized.
 105  */
 106 #define br_hmac_size(ctx)   ((ctx)->out_len)
 107
 108 /*
 109  * Process some more bytes.
 110  */
 111 void br_hmac_update(br_hmac_context *ctx, const void *data, size_t len);
 112
 113 /*
 114  * Compute the HMAC output. The destination buffer MUST be large enough
 115  * to accomodate the result. The context is NOT modified; further bytes
 116  * may be processed. Thus, "partial HMAC" values can be efficiently
 117  * obtained.
 118  *
 119  * Returned value is the output length (in bytes).
 120  */
 121 size_t br_hmac_out(const br_hmac_context *ctx, void *out);
 122
 123 /*
 124  * Compute the HMAC output in constant time. Some extra input bytes are
 125  * processed, then the output is computed. The extra input consists in
 126  * the 'len' bytes pointed to by 'data'. The 'len' parameter must lie
 127  * between 'min_len' and 'max_len' (inclusive); max_len bytes are
 128  * actually read from 'data'. Computing time (and memory access pattern)
 129  * will not depend upon the data bytes or the value of 'len'.
 130  *
 131  * The output is written in the 'out' buffer, that MUST be large enough
 132  * to receive it.
 133  *
 134  * The difference max_len-min_len MUST be less than 2^30.
 135  *
 136  * This function computes the output properly only if the underlying
 137  * hash function uses MD padding (i.e. MD5, SHA-1, SHA-224, SHA-256,
 138  * SHA-384 or SHA-512).
 139  *
 140  * The provided context is NOT modified.
 141  *
 142  * Returned value is the MAC length (in bytes).
 143  */
 144 size_t br_hmac_outCT(const br_hmac_context *ctx,
 145         const void *data, size_t len, size_t min_len, size_t max_len,
 146         void *out);
 147
 148 #endif