Added stricter rule on input for RSA private key operation (mathematically correct...
[BearSSL] / 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