_ Git - BearSSL/blob - inc/bearssl_prf.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_PRF_H__
  26 #define BR_BEARSSL_PRF_H__
  27
  28 #include <stddef.h>
  29 #include <stdint.h>
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /** \file bearssl_prf.h
  36  *
  37  * # The TLS PRF
  38  *
  39  * The "PRF" is the pseudorandom function used internally during the
  40  * SSL/TLS handshake, notably to expand negociated shared secrets into
  41  * the symmetric encryption keys that will be used to process the
  42  * application data.
  43  *
  44  * TLS 1.0 and 1.1 define a PRF that is based on both MD5 and SHA-1. This
  45  * is implemented by the `br_tls10_prf()` function.
  46  *
  47  * TLS 1.2 redefines the PRF, using an explicit hash function. The
  48  * `br_tls12_sha256_prf()` and `br_tls12_sha384_prf()` functions apply that
  49  * PRF with, respectively, SHA-256 and SHA-384. Most standard cipher suites
  50  * rely on the SHA-256 based PRF, but some use SHA-384.
  51  *
  52  * The PRF always uses as input three parameters: a "secret" (some
  53  * bytes), a "label" (ASCII string), and a "seed" (again some bytes). An
  54  * arbitrary output length can be produced. The "seed" is provided as an
  55  * arbitrary number of binary chunks, that gets internally concatenated.
  56  */
  57
  58 /**
  59  * \brief Type for a seed chunk.
  60  *
  61  * Each chunk may have an arbitrary length, and may be empty (no byte at
  62  * all). If the chunk length is zero, then the pointer to the chunk data
  63  * may be `NULL`.
  64  */
  65 typedef struct {
  66         /**
  67          * \brief Pointer to the chunk data.
  68          */
  69         const void *data;
  70
  71         /**
  72          * \brief Chunk length (in bytes).
  73          */
  74         size_t len;
  75 } br_tls_prf_seed_chunk;
  76
  77 /**
  78  * \brief PRF implementation for TLS 1.0 and 1.1.
  79  *
  80  * This PRF is the one specified by TLS 1.0 and 1.1. It internally uses
  81  * MD5 and SHA-1.
  82  *
  83  * \param dst          destination buffer.
  84  * \param len          output length (in bytes).
  85  * \param secret       secret value (key) for this computation.
  86  * \param secret_len   length of "secret" (in bytes).
  87  * \param label        PRF label (zero-terminated ASCII string).
  88  * \param seed_num     number of seed chunks.
  89  * \param seed         seed chnks for this computation (usually non-secret).
  90  */
  91 void br_tls10_prf(void *dst, size_t len,
  92         const void *secret, size_t secret_len, const char *label,
  93         size_t seed_num, const br_tls_prf_seed_chunk *seed);
  94
  95 /**
  96  * \brief PRF implementation for TLS 1.2, with SHA-256.
  97  *
  98  * This PRF is the one specified by TLS 1.2, when the underlying hash
  99  * function is SHA-256.
 100  *
 101  * \param dst          destination buffer.
 102  * \param len          output length (in bytes).
 103  * \param secret       secret value (key) for this computation.
 104  * \param secret_len   length of "secret" (in bytes).
 105  * \param label        PRF label (zero-terminated ASCII string).
 106  * \param seed_num     number of seed chunks.
 107  * \param seed         seed chnks for this computation (usually non-secret).
 108  */
 109 void br_tls12_sha256_prf(void *dst, size_t len,
 110         const void *secret, size_t secret_len, const char *label,
 111         size_t seed_num, const br_tls_prf_seed_chunk *seed);
 112
 113 /**
 114  * \brief PRF implementation for TLS 1.2, with SHA-384.
 115  *
 116  * This PRF is the one specified by TLS 1.2, when the underlying hash
 117  * function is SHA-384.
 118  *
 119  * \param dst          destination buffer.
 120  * \param len          output length (in bytes).
 121  * \param secret       secret value (key) for this computation.
 122  * \param secret_len   length of "secret" (in bytes).
 123  * \param label        PRF label (zero-terminated ASCII string).
 124  * \param seed_num     number of seed chunks.
 125  * \param seed         seed chnks for this computation (usually non-secret).
 126  */
 127 void br_tls12_sha384_prf(void *dst, size_t len,
 128         const void *secret, size_t secret_len, const char *label,
 129         size_t seed_num, const br_tls_prf_seed_chunk *seed);
 130
 131 /**
 132  * brief A convenient type name for a PRF implementation.
 133  *
 134  * \param dst          destination buffer.
 135  * \param len          output length (in bytes).
 136  * \param secret       secret value (key) for this computation.
 137  * \param secret_len   length of "secret" (in bytes).
 138  * \param label        PRF label (zero-terminated ASCII string).
 139  * \param seed_num     number of seed chunks.
 140  * \param seed         seed chnks for this computation (usually non-secret).
 141  */
 142 typedef void (*br_tls_prf_impl)(void *dst, size_t len,
 143         const void *secret, size_t secret_len, const char *label,
 144         size_t seed_num, const br_tls_prf_seed_chunk *seed);
 145
 146 #ifdef __cplusplus
 147 }
 148 #endif
 149
 150 #endif