39d1c42661ae3ccaad2f221507f4bd568004c989
2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
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:
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
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
25 #ifndef BR_BEARSSL_PRF_H__
26 #define BR_BEARSSL_PRF_H__
35 /** \file bearssl_prf.h
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
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.
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.
52 * The PRF always uses as input three parameters: a "secret" (some
53 * bytes), a "label" (ASCII string), and a "seed" (again some bytes).
54 * An arbitrary output length can be produced.
57 /** \brief PRF implementation for TLS 1.0 and 1.1.
59 * This PRF is the one specified by TLS 1.0 and 1.1. It internally uses
62 * \param dst destination buffer.
63 * \param len output length (in bytes).
64 * \param secret secret value (key) for this computation.
65 * \param secret_len length of "secret" (in bytes).
66 * \param label PRF label (zero-terminated ASCII string).
67 * \param seed seed for this computation (usually non-secret).
68 * \param seed_len length of "seed" (in bytes).
70 void br_tls10_prf(void *dst
, size_t len
,
71 const void *secret
, size_t secret_len
,
72 const char *label
, const void *seed
, size_t seed_len
);
74 /** \brief PRF implementation for TLS 1.2, with SHA-256.
76 * This PRF is the one specified by TLS 1.2, when the underlying hash
77 * function is SHA-256.
79 * \param dst destination buffer.
80 * \param len output length (in bytes).
81 * \param secret secret value (key) for this computation.
82 * \param secret_len length of "secret" (in bytes).
83 * \param label PRF label (zero-terminated ASCII string).
84 * \param seed seed for this computation (usually non-secret).
85 * \param seed_len length of "seed" (in bytes).
87 void br_tls12_sha256_prf(void *dst
, size_t len
,
88 const void *secret
, size_t secret_len
,
89 const char *label
, const void *seed
, size_t seed_len
);
91 /** \brief PRF implementation for TLS 1.2, with SHA-384.
93 * This PRF is the one specified by TLS 1.2, when the underlying hash
94 * function is SHA-384.
96 * \param dst destination buffer.
97 * \param len output length (in bytes).
98 * \param secret secret value (key) for this computation.
99 * \param secret_len length of "secret" (in bytes).
100 * \param label PRF label (zero-terminated ASCII string).
101 * \param seed seed for this computation (usually non-secret).
102 * \param seed_len length of "seed" (in bytes).
104 void br_tls12_sha384_prf(void *dst
, size_t len
,
105 const void *secret
, size_t secret_len
,
106 const char *label
, const void *seed
, size_t seed_len
);
108 /** \brief A convenient type name for a PRF implementation.
110 * \param dst destination buffer.
111 * \param len output length (in bytes).
112 * \param secret secret value (key) for this computation.
113 * \param secret_len length of "secret" (in bytes).
114 * \param label PRF label (zero-terminated ASCII string).
115 * \param seed seed for this computation (usually non-secret).
116 * \param seed_len length of "seed" (in bytes).
118 typedef void (*br_tls_prf_impl
)(void *dst
, size_t len
,
119 const void *secret
, size_t secret_len
,
120 const char *label
, const void *seed
, size_t seed_len
);