1*0957b409SSimon J. Gerraty /* 2*0957b409SSimon J. Gerraty * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org> 3*0957b409SSimon J. Gerraty * 4*0957b409SSimon J. Gerraty * Permission is hereby granted, free of charge, to any person obtaining 5*0957b409SSimon J. Gerraty * a copy of this software and associated documentation files (the 6*0957b409SSimon J. Gerraty * "Software"), to deal in the Software without restriction, including 7*0957b409SSimon J. Gerraty * without limitation the rights to use, copy, modify, merge, publish, 8*0957b409SSimon J. Gerraty * distribute, sublicense, and/or sell copies of the Software, and to 9*0957b409SSimon J. Gerraty * permit persons to whom the Software is furnished to do so, subject to 10*0957b409SSimon J. Gerraty * the following conditions: 11*0957b409SSimon J. Gerraty * 12*0957b409SSimon J. Gerraty * The above copyright notice and this permission notice shall be 13*0957b409SSimon J. Gerraty * included in all copies or substantial portions of the Software. 14*0957b409SSimon J. Gerraty * 15*0957b409SSimon J. Gerraty * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 16*0957b409SSimon J. Gerraty * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 17*0957b409SSimon J. Gerraty * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 18*0957b409SSimon J. Gerraty * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 19*0957b409SSimon J. Gerraty * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 20*0957b409SSimon J. Gerraty * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 21*0957b409SSimon J. Gerraty * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 22*0957b409SSimon J. Gerraty * SOFTWARE. 23*0957b409SSimon J. Gerraty */ 24*0957b409SSimon J. Gerraty 25*0957b409SSimon J. Gerraty #ifndef BR_BEARSSL_PRF_H__ 26*0957b409SSimon J. Gerraty #define BR_BEARSSL_PRF_H__ 27*0957b409SSimon J. Gerraty 28*0957b409SSimon J. Gerraty #include <stddef.h> 29*0957b409SSimon J. Gerraty #include <stdint.h> 30*0957b409SSimon J. Gerraty 31*0957b409SSimon J. Gerraty #ifdef __cplusplus 32*0957b409SSimon J. Gerraty extern "C" { 33*0957b409SSimon J. Gerraty #endif 34*0957b409SSimon J. Gerraty 35*0957b409SSimon J. Gerraty /** \file bearssl_prf.h 36*0957b409SSimon J. Gerraty * 37*0957b409SSimon J. Gerraty * # The TLS PRF 38*0957b409SSimon J. Gerraty * 39*0957b409SSimon J. Gerraty * The "PRF" is the pseudorandom function used internally during the 40*0957b409SSimon J. Gerraty * SSL/TLS handshake, notably to expand negotiated shared secrets into 41*0957b409SSimon J. Gerraty * the symmetric encryption keys that will be used to process the 42*0957b409SSimon J. Gerraty * application data. 43*0957b409SSimon J. Gerraty * 44*0957b409SSimon J. Gerraty * TLS 1.0 and 1.1 define a PRF that is based on both MD5 and SHA-1. This 45*0957b409SSimon J. Gerraty * is implemented by the `br_tls10_prf()` function. 46*0957b409SSimon J. Gerraty * 47*0957b409SSimon J. Gerraty * TLS 1.2 redefines the PRF, using an explicit hash function. The 48*0957b409SSimon J. Gerraty * `br_tls12_sha256_prf()` and `br_tls12_sha384_prf()` functions apply that 49*0957b409SSimon J. Gerraty * PRF with, respectively, SHA-256 and SHA-384. Most standard cipher suites 50*0957b409SSimon J. Gerraty * rely on the SHA-256 based PRF, but some use SHA-384. 51*0957b409SSimon J. Gerraty * 52*0957b409SSimon J. Gerraty * The PRF always uses as input three parameters: a "secret" (some 53*0957b409SSimon J. Gerraty * bytes), a "label" (ASCII string), and a "seed" (again some bytes). An 54*0957b409SSimon J. Gerraty * arbitrary output length can be produced. The "seed" is provided as an 55*0957b409SSimon J. Gerraty * arbitrary number of binary chunks, that gets internally concatenated. 56*0957b409SSimon J. Gerraty */ 57*0957b409SSimon J. Gerraty 58*0957b409SSimon J. Gerraty /** 59*0957b409SSimon J. Gerraty * \brief Type for a seed chunk. 60*0957b409SSimon J. Gerraty * 61*0957b409SSimon J. Gerraty * Each chunk may have an arbitrary length, and may be empty (no byte at 62*0957b409SSimon J. Gerraty * all). If the chunk length is zero, then the pointer to the chunk data 63*0957b409SSimon J. Gerraty * may be `NULL`. 64*0957b409SSimon J. Gerraty */ 65*0957b409SSimon J. Gerraty typedef struct { 66*0957b409SSimon J. Gerraty /** 67*0957b409SSimon J. Gerraty * \brief Pointer to the chunk data. 68*0957b409SSimon J. Gerraty */ 69*0957b409SSimon J. Gerraty const void *data; 70*0957b409SSimon J. Gerraty 71*0957b409SSimon J. Gerraty /** 72*0957b409SSimon J. Gerraty * \brief Chunk length (in bytes). 73*0957b409SSimon J. Gerraty */ 74*0957b409SSimon J. Gerraty size_t len; 75*0957b409SSimon J. Gerraty } br_tls_prf_seed_chunk; 76*0957b409SSimon J. Gerraty 77*0957b409SSimon J. Gerraty /** 78*0957b409SSimon J. Gerraty * \brief PRF implementation for TLS 1.0 and 1.1. 79*0957b409SSimon J. Gerraty * 80*0957b409SSimon J. Gerraty * This PRF is the one specified by TLS 1.0 and 1.1. It internally uses 81*0957b409SSimon J. Gerraty * MD5 and SHA-1. 82*0957b409SSimon J. Gerraty * 83*0957b409SSimon J. Gerraty * \param dst destination buffer. 84*0957b409SSimon J. Gerraty * \param len output length (in bytes). 85*0957b409SSimon J. Gerraty * \param secret secret value (key) for this computation. 86*0957b409SSimon J. Gerraty * \param secret_len length of "secret" (in bytes). 87*0957b409SSimon J. Gerraty * \param label PRF label (zero-terminated ASCII string). 88*0957b409SSimon J. Gerraty * \param seed_num number of seed chunks. 89*0957b409SSimon J. Gerraty * \param seed seed chnks for this computation (usually non-secret). 90*0957b409SSimon J. Gerraty */ 91*0957b409SSimon J. Gerraty void br_tls10_prf(void *dst, size_t len, 92*0957b409SSimon J. Gerraty const void *secret, size_t secret_len, const char *label, 93*0957b409SSimon J. Gerraty size_t seed_num, const br_tls_prf_seed_chunk *seed); 94*0957b409SSimon J. Gerraty 95*0957b409SSimon J. Gerraty /** 96*0957b409SSimon J. Gerraty * \brief PRF implementation for TLS 1.2, with SHA-256. 97*0957b409SSimon J. Gerraty * 98*0957b409SSimon J. Gerraty * This PRF is the one specified by TLS 1.2, when the underlying hash 99*0957b409SSimon J. Gerraty * function is SHA-256. 100*0957b409SSimon J. Gerraty * 101*0957b409SSimon J. Gerraty * \param dst destination buffer. 102*0957b409SSimon J. Gerraty * \param len output length (in bytes). 103*0957b409SSimon J. Gerraty * \param secret secret value (key) for this computation. 104*0957b409SSimon J. Gerraty * \param secret_len length of "secret" (in bytes). 105*0957b409SSimon J. Gerraty * \param label PRF label (zero-terminated ASCII string). 106*0957b409SSimon J. Gerraty * \param seed_num number of seed chunks. 107*0957b409SSimon J. Gerraty * \param seed seed chnks for this computation (usually non-secret). 108*0957b409SSimon J. Gerraty */ 109*0957b409SSimon J. Gerraty void br_tls12_sha256_prf(void *dst, size_t len, 110*0957b409SSimon J. Gerraty const void *secret, size_t secret_len, const char *label, 111*0957b409SSimon J. Gerraty size_t seed_num, const br_tls_prf_seed_chunk *seed); 112*0957b409SSimon J. Gerraty 113*0957b409SSimon J. Gerraty /** 114*0957b409SSimon J. Gerraty * \brief PRF implementation for TLS 1.2, with SHA-384. 115*0957b409SSimon J. Gerraty * 116*0957b409SSimon J. Gerraty * This PRF is the one specified by TLS 1.2, when the underlying hash 117*0957b409SSimon J. Gerraty * function is SHA-384. 118*0957b409SSimon J. Gerraty * 119*0957b409SSimon J. Gerraty * \param dst destination buffer. 120*0957b409SSimon J. Gerraty * \param len output length (in bytes). 121*0957b409SSimon J. Gerraty * \param secret secret value (key) for this computation. 122*0957b409SSimon J. Gerraty * \param secret_len length of "secret" (in bytes). 123*0957b409SSimon J. Gerraty * \param label PRF label (zero-terminated ASCII string). 124*0957b409SSimon J. Gerraty * \param seed_num number of seed chunks. 125*0957b409SSimon J. Gerraty * \param seed seed chnks for this computation (usually non-secret). 126*0957b409SSimon J. Gerraty */ 127*0957b409SSimon J. Gerraty void br_tls12_sha384_prf(void *dst, size_t len, 128*0957b409SSimon J. Gerraty const void *secret, size_t secret_len, const char *label, 129*0957b409SSimon J. Gerraty size_t seed_num, const br_tls_prf_seed_chunk *seed); 130*0957b409SSimon J. Gerraty 131*0957b409SSimon J. Gerraty /** 132*0957b409SSimon J. Gerraty * brief A convenient type name for a PRF implementation. 133*0957b409SSimon J. Gerraty * 134*0957b409SSimon J. Gerraty * \param dst destination buffer. 135*0957b409SSimon J. Gerraty * \param len output length (in bytes). 136*0957b409SSimon J. Gerraty * \param secret secret value (key) for this computation. 137*0957b409SSimon J. Gerraty * \param secret_len length of "secret" (in bytes). 138*0957b409SSimon J. Gerraty * \param label PRF label (zero-terminated ASCII string). 139*0957b409SSimon J. Gerraty * \param seed_num number of seed chunks. 140*0957b409SSimon J. Gerraty * \param seed seed chnks for this computation (usually non-secret). 141*0957b409SSimon J. Gerraty */ 142*0957b409SSimon J. Gerraty typedef void (*br_tls_prf_impl)(void *dst, size_t len, 143*0957b409SSimon J. Gerraty const void *secret, size_t secret_len, const char *label, 144*0957b409SSimon J. Gerraty size_t seed_num, const br_tls_prf_seed_chunk *seed); 145*0957b409SSimon J. Gerraty 146*0957b409SSimon J. Gerraty #ifdef __cplusplus 147*0957b409SSimon J. Gerraty } 148*0957b409SSimon J. Gerraty #endif 149*0957b409SSimon J. Gerraty 150*0957b409SSimon J. Gerraty #endif 151