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 negotiated 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 151