blob: a35e08597d243c0c785ed3d81c8cd8d523b1b02f [file] [log] [blame]
Hanno Beckerbe9d6642020-08-21 13:20:06 +01001/*
2 * TLS 1.3 key schedule
3 *
4 * Copyright The Mbed TLS Contributors
5 * SPDX-License-Identifier: Apache-2.0
6 *
7 * Licensed under the Apache License, Version 2.0 ( the "License" ); you may
8 * not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
15 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
18 */
19#if !defined(MBEDTLS_SSL_TLS1_3_KEYS_H)
20#define MBEDTLS_SSL_TLS1_3_KEYS_H
21
22#if defined(MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL)
23#define MBEDTLS_SSL_TLS1_3_LABEL_LIST \
24 const unsigned char finished [ sizeof("finished") - 1 ]; \
25 const unsigned char resumption [ sizeof("resumption") - 1 ]; \
26 const unsigned char traffic_upd [ sizeof("traffic upd") - 1 ]; \
27 const unsigned char export [ sizeof("exporter") - 1 ]; \
28 const unsigned char key [ sizeof("key") - 1 ]; \
29 const unsigned char iv [ sizeof("iv") - 1 ]; \
30 const unsigned char sn [ sizeof("sn") - 1 ]; \
31 const unsigned char c_hs_traffic[ sizeof("c hs traffic") - 1 ]; \
32 const unsigned char c_ap_traffic[ sizeof("c ap traffic") - 1 ]; \
33 const unsigned char c_e_traffic [ sizeof("c e traffic") - 1 ]; \
34 const unsigned char s_hs_traffic[ sizeof("s hs traffic") - 1 ]; \
35 const unsigned char s_ap_traffic[ sizeof("s ap traffic") - 1 ]; \
36 const unsigned char s_e_traffic [ sizeof("s e traffic") - 1 ]; \
37 const unsigned char exp_master [ sizeof("exp master") - 1 ]; \
38 const unsigned char res_master [ sizeof("res master") - 1 ]; \
39 const unsigned char ext_binder [ sizeof("ext binder") - 1 ]; \
40 const unsigned char res_binder [ sizeof("res binder") - 1 ]; \
41 const unsigned char derived [ sizeof("derived") - 1 ]; \
42
43union mbedtls_ssl_tls1_3_labels_union
44{
45 MBEDTLS_SSL_TLS1_3_LABEL_LIST
46};
47struct mbedtls_ssl_tls1_3_labels_struct
48{
49 MBEDTLS_SSL_TLS1_3_LABEL_LIST
50};
51extern const struct mbedtls_ssl_tls1_3_labels_struct mbedtls_ssl_tls1_3_labels;
52
53#define MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( LABEL ) \
54 mbedtls_ssl_tls1_3_labels.LABEL, \
55 sizeof(mbedtls_ssl_tls1_3_labels.LABEL)
56
57#define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_LABEL_LEN \
58 sizeof( union mbedtls_ssl_tls1_3_labels_union )
59
60/* The maximum length of HKDF contexts used in the TLS 1.3 standad.
61 * Since contexts are always hashes of message transcripts, this can
62 * be approximated from above by the maximum hash size. */
63#define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_CONTEXT_LEN \
64 MBEDTLS_MD_MAX_SIZE
65
66/* Maximum desired length for expanded key material generated
67 * by HKDF-Expand-Label. */
68#define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_EXPANSION_LEN 255
69
70/**
71 * \brief The \c HKDF-Expand-Label function from
72 * the TLS 1.3 standard RFC 8446.
73 *
74 * <tt>
75 * HKDF-Expand-Label( Secret, Label, Context, Length ) =
76 * HKDF-Expand( Secret, HkdfLabel, Length )
77 * </tt>
78 *
79 * \param hash_alg The identifier for the hash algorithm to use.
80 * \param secret The \c Secret argument to \c HKDF-Expand-Label.
81 * This must be a readable buffer of length \p slen Bytes.
82 * \param slen The length of \p secret in Bytes.
83 * \param label The \c Label argument to \c HKDF-Expand-Label.
84 * This must be a readable buffer of length \p llen Bytes.
85 * \param llen The length of \p label in Bytes.
86 * \param ctx The \c Context argument to \c HKDF-Expand-Label.
87 * This must be a readable buffer of length \p clen Bytes.
88 * \param clen The length of \p context in Bytes.
89 * \param buf The destination buffer to hold the expanded secret.
90 * This must be a writable buffe of length \p blen Bytes.
91 * \param blen The desired size of the expanded secret in Bytes.
92 *
93 * \returns \c 0 on success.
94 * \return A negative error code on failure.
95 */
96
97int mbedtls_ssl_tls1_3_hkdf_expand_label(
98 mbedtls_md_type_t hash_alg,
99 const unsigned char *secret, size_t slen,
100 const unsigned char *label, size_t llen,
101 const unsigned char *ctx, size_t clen,
102 unsigned char *buf, size_t blen );
103
Hanno Becker3385a4d2020-08-21 13:03:34 +0100104/**
105 * \brief This function is part of the TLS 1.3 key schedule.
106 * It extracts key and IV for the actual client/server traffic
107 * from the client/server traffic secrets.
108 *
109 * From RFC 8446:
110 *
111 * <tt>
112 * [sender]_write_key = HKDF-Expand-Label(Secret, "key", "", key_length)
113 * [sender]_write_iv = HKDF-Expand-Label(Secret, "iv", "", iv_length)*
114 * </tt>
115 *
116 * \param hash_alg The identifier for the hash algorithm to be used
117 * for the HKDF-based expansion of the secret.
118 * \param client_secret The client traffic secret.
119 * This must be a readable buffer of size \p slen Bytes
120 * \param server_secret The server traffic secret.
121 * This must be a readable buffer of size \p slen Bytes
122 * \param slen Length of the secrets \p client_secret and
123 * \p server_secret in Bytes.
124 * \param keyLen The desired length of the key to be extracted in Bytes.
125 * \param ivLen The desired length of the IV to be extracted in Bytes.
126 * \param keys The address of the structure holding the generated
127 * keys and IVs.
128 *
129 * \returns \c 0 on success.
130 * \returns A negative error code on failure.
131 */
132
133int mbedtls_ssl_tls1_3_make_traffic_keys(
134 mbedtls_md_type_t hash_alg,
135 const unsigned char *client_secret,
136 const unsigned char *server_secret,
137 size_t slen, size_t keyLen, size_t ivLen,
138 mbedtls_ssl_key_set *keys );
139
Hanno Beckerb35d5222020-08-21 13:27:44 +0100140/**
141 * \brief The \c Derive-Secret function from the TLS 1.3 standard RFC 8446.
142 *
143 * <tt>
144 * Derive-Secret( Secret, Label, Messages ) =
145 * HKDF-Expand-Label( Secret, Label,
146 * Hash( Messages ),
147 * Hash.Length ) )
148 * </tt>
149 *
150 * Note: In this implementation of the function we assume that
151 * the parameter message contains the already hashed value and
152 * the Derive-Secret function does not need to hash it again.
153 *
154 * \param hash_alg The identifier for the hash function used for the
155 * applications of HKDF.
156 * \param secret The \c Secret argument to the \c Derive-Secret function.
157 * This must be a readable buffer of length \p slen Bytes.
158 * \param slen The length of \p secret in Bytes.
159 * \param label The \c Label argument to the \c Derive-Secret function.
160 * This must be a readable buffer of length \p llen Bytes.
161 * \param llen The length of \p label in Bytes.
162 * \param hash The hash of the \c Messages argument to the \c Derive-Secret
163 * function. This must be a readable buffer of length \p mlen
164 * hlen Bytes.
165 * \param hlen The length of \p hash.
166 * \param dstbuf The target buffer to write the output of \c Derive-Secret to.
167 * This must be a writable buffer of size \p buflen Bytes.
168 * \param buflen The length of \p dstbuf in Bytes.
169 *
170 * \returns \c 0 on success.
171 * \returns A negative error code on failure.
172 */
173
174#define MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED 0
175#define MBEDTLS_SSL_TLS1_3_CONTEXT_HASHED 1
176
177int mbedtls_ssl_tls1_3_derive_secret(
178 mbedtls_md_type_t hash_alg,
179 const unsigned char *secret, size_t slen,
180 const unsigned char *label, size_t llen,
181 const unsigned char *ctx, size_t clen,
182 int context_already_hashed,
183 unsigned char *dstbuf, size_t buflen );
184
Hanno Beckere9cccb42020-08-20 13:42:46 +0100185/**
186 * \brief Compute the next secret in the TLS 1.3 key schedule
187 *
188 * The TLS 1.3 key schedule proceeds as follows to compute
189 * the three main secrets during the handshake: The early
190 * secret for early data, the handshake secret for all
191 * other encrypted handshake messages, and the master
192 * secret for all application traffic.
193 *
194 * <tt>
195 * 0
196 * |
197 * v
198 * PSK -> HKDF-Extract = Early Secret
199 * |
200 * v
201 * Derive-Secret( ., "derived", "" )
202 * |
203 * v
204 * (EC)DHE -> HKDF-Extract = Handshake Secret
205 * |
206 * v
207 * Derive-Secret( ., "derived", "" )
208 * |
209 * v
210 * 0 -> HKDF-Extract = Master Secret
211 * </tt>
212 *
213 * Each of the three secrets in turn is the basis for further
214 * key derivations, such as the derivation of traffic keys and IVs;
215 * see e.g. mbedtls_ssl_tls1_3_make_traffic_keys().
216 *
217 * This function implements one step in this evolution of secrets:
218 *
219 * <tt>
220 * old_secret
221 * |
222 * v
223 * Derive-Secret( ., "derived", "" )
224 * |
225 * v
226 * input -> HKDF-Extract = new_secret
227 * </tt>
228 *
229 * \param hash_alg The identifier for the hash function used for the
230 * applications of HKDF.
231 * \param secret_old The address of the buffer holding the old secret
232 * on function entry. If not \c NULL, this must be a
233 * readable buffer whose size matches the output size
234 * of the hash function represented by \p hash_alg.
235 * If \c NULL, an all \c 0 array will be used instead.
236 * \param input The address of the buffer holding the additional
237 * input for the key derivation (e.g., the PSK or the
238 * ephemeral (EC)DH secret). If not \c NULL, this must be
239 * a readable buffer whose size \p input_len Bytes.
240 * If \c NULL, an all \c 0 array will be used instead.
241 * \param input_len The length of \p input in Bytes.
242 * \param secret_new The address of the buffer holding the new secret
243 * on function exit. This must be a writable buffer
244 * whose size matches the output size of the hash
245 * function represented by \p hash_alg.
246 * This may be the same as \p secret_old.
247 *
248 * \returns \c 0 on success.
249 * \returns A negative error code on failure.
250 */
251
252int mbedtls_ssl_tls1_3_evolve_secret(
253 mbedtls_md_type_t hash_alg,
254 const unsigned char *secret_old,
255 const unsigned char *input, size_t input_len,
256 unsigned char *secret_new );
257
Hanno Beckerbe9d6642020-08-21 13:20:06 +0100258#endif /* MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL */
259
260#endif /* MBEDTLS_SSL_TLS1_3_KEYS_H */