Mbed OS Reference
Loading...
Searching...
No Matches
ssl_tls13_keys.h
1/*
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/* This requires MBEDTLS_SSL_TLS1_3_LABEL( idx, name, string ) to be defined at
23 * the point of use. See e.g. the definition of mbedtls_ssl_tls1_3_labels_union
24 * below. */
25#define MBEDTLS_SSL_TLS1_3_LABEL_LIST \
26 MBEDTLS_SSL_TLS1_3_LABEL( finished , "finished" ) \
27 MBEDTLS_SSL_TLS1_3_LABEL( resumption , "resumption" ) \
28 MBEDTLS_SSL_TLS1_3_LABEL( traffic_upd , "traffic upd" ) \
29 MBEDTLS_SSL_TLS1_3_LABEL( exporter , "exporter" ) \
30 MBEDTLS_SSL_TLS1_3_LABEL( key , "key" ) \
31 MBEDTLS_SSL_TLS1_3_LABEL( iv , "iv" ) \
32 MBEDTLS_SSL_TLS1_3_LABEL( c_hs_traffic, "c hs traffic" ) \
33 MBEDTLS_SSL_TLS1_3_LABEL( c_ap_traffic, "c ap traffic" ) \
34 MBEDTLS_SSL_TLS1_3_LABEL( c_e_traffic , "c e traffic" ) \
35 MBEDTLS_SSL_TLS1_3_LABEL( s_hs_traffic, "s hs traffic" ) \
36 MBEDTLS_SSL_TLS1_3_LABEL( s_ap_traffic, "s ap traffic" ) \
37 MBEDTLS_SSL_TLS1_3_LABEL( s_e_traffic , "s e traffic" ) \
38 MBEDTLS_SSL_TLS1_3_LABEL( e_exp_master, "e exp master" ) \
39 MBEDTLS_SSL_TLS1_3_LABEL( res_master , "res master" ) \
40 MBEDTLS_SSL_TLS1_3_LABEL( exp_master , "exp master" ) \
41 MBEDTLS_SSL_TLS1_3_LABEL( ext_binder , "ext binder" ) \
42 MBEDTLS_SSL_TLS1_3_LABEL( res_binder , "res binder" ) \
43 MBEDTLS_SSL_TLS1_3_LABEL( derived , "derived" )
44
45#define MBEDTLS_SSL_TLS1_3_LABEL( name, string ) \
46 const unsigned char name [ sizeof(string) - 1 ];
47
49{
50 MBEDTLS_SSL_TLS1_3_LABEL_LIST
51};
53{
54 MBEDTLS_SSL_TLS1_3_LABEL_LIST
55};
56#undef MBEDTLS_SSL_TLS1_3_LABEL
57
58extern const struct mbedtls_ssl_tls1_3_labels_struct mbedtls_ssl_tls1_3_labels;
59
60#define MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( LABEL ) \
61 mbedtls_ssl_tls1_3_labels.LABEL, \
62 sizeof(mbedtls_ssl_tls1_3_labels.LABEL)
63
64#define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_LABEL_LEN \
65 sizeof( union mbedtls_ssl_tls1_3_labels_union )
66
67/* The maximum length of HKDF contexts used in the TLS 1.3 standard.
68 * Since contexts are always hashes of message transcripts, this can
69 * be approximated from above by the maximum hash size. */
70#define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_CONTEXT_LEN \
71 MBEDTLS_MD_MAX_SIZE
72
73/* Maximum desired length for expanded key material generated
74 * by HKDF-Expand-Label.
75 *
76 * Warning: If this ever needs to be increased, the implementation
77 * ssl_tls1_3_hkdf_encode_label() in ssl_tls13_keys.c needs to be
78 * adjusted since it currently assumes that HKDF key expansion
79 * is never used with more than 255 Bytes of output. */
80#define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_EXPANSION_LEN 255
81
82/**
83 * \brief The \c HKDF-Expand-Label function from
84 * the TLS 1.3 standard RFC 8446.
85 *
86 * <tt>
87 * HKDF-Expand-Label( Secret, Label, Context, Length ) =
88 * HKDF-Expand( Secret, HkdfLabel, Length )
89 * </tt>
90 *
91 * \param hash_alg The identifier for the hash algorithm to use.
92 * \param secret The \c Secret argument to \c HKDF-Expand-Label.
93 * This must be a readable buffer of length \p slen Bytes.
94 * \param slen The length of \p secret in Bytes.
95 * \param label The \c Label argument to \c HKDF-Expand-Label.
96 * This must be a readable buffer of length \p llen Bytes.
97 * \param llen The length of \p label in Bytes.
98 * \param ctx The \c Context argument to \c HKDF-Expand-Label.
99 * This must be a readable buffer of length \p clen Bytes.
100 * \param clen The length of \p context in Bytes.
101 * \param buf The destination buffer to hold the expanded secret.
102 * This must be a writable buffer of length \p blen Bytes.
103 * \param blen The desired size of the expanded secret in Bytes.
104 *
105 * \returns \c 0 on success.
106 * \return A negative error code on failure.
107 */
108
109int mbedtls_ssl_tls1_3_hkdf_expand_label(
110 mbedtls_md_type_t hash_alg,
111 const unsigned char *secret, size_t slen,
112 const unsigned char *label, size_t llen,
113 const unsigned char *ctx, size_t clen,
114 unsigned char *buf, size_t blen );
115
116/**
117 * \brief This function is part of the TLS 1.3 key schedule.
118 * It extracts key and IV for the actual client/server traffic
119 * from the client/server traffic secrets.
120 *
121 * From RFC 8446:
122 *
123 * <tt>
124 * [sender]_write_key = HKDF-Expand-Label(Secret, "key", "", key_length)
125 * [sender]_write_iv = HKDF-Expand-Label(Secret, "iv", "", iv_length)*
126 * </tt>
127 *
128 * \param hash_alg The identifier for the hash algorithm to be used
129 * for the HKDF-based expansion of the secret.
130 * \param client_secret The client traffic secret.
131 * This must be a readable buffer of size \p slen Bytes
132 * \param server_secret The server traffic secret.
133 * This must be a readable buffer of size \p slen Bytes
134 * \param slen Length of the secrets \p client_secret and
135 * \p server_secret in Bytes.
136 * \param key_len The desired length of the key to be extracted in Bytes.
137 * \param iv_len The desired length of the IV to be extracted in Bytes.
138 * \param keys The address of the structure holding the generated
139 * keys and IVs.
140 *
141 * \returns \c 0 on success.
142 * \returns A negative error code on failure.
143 */
144
145int mbedtls_ssl_tls1_3_make_traffic_keys(
146 mbedtls_md_type_t hash_alg,
147 const unsigned char *client_secret,
148 const unsigned char *server_secret,
149 size_t slen, size_t key_len, size_t iv_len,
150 mbedtls_ssl_key_set *keys );
151
152
153#define MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED 0
154#define MBEDTLS_SSL_TLS1_3_CONTEXT_HASHED 1
155
156/**
157 * \brief The \c Derive-Secret function from the TLS 1.3 standard RFC 8446.
158 *
159 * <tt>
160 * Derive-Secret( Secret, Label, Messages ) =
161 * HKDF-Expand-Label( Secret, Label,
162 * Hash( Messages ),
163 * Hash.Length ) )
164 * </tt>
165 *
166 * \param hash_alg The identifier for the hash function used for the
167 * applications of HKDF.
168 * \param secret The \c Secret argument to the \c Derive-Secret function.
169 * This must be a readable buffer of length \p slen Bytes.
170 * \param slen The length of \p secret in Bytes.
171 * \param label The \c Label argument to the \c Derive-Secret function.
172 * This must be a readable buffer of length \p llen Bytes.
173 * \param llen The length of \p label in Bytes.
174 * \param ctx The hash of the \c Messages argument to the
175 * \c Derive-Secret function, or the \c Messages argument
176 * itself, depending on \p context_already_hashed.
177 * \param clen The length of \p hash.
178 * \param ctx_hashed This indicates whether the \p ctx contains the hash of
179 * the \c Messages argument in the application of the
180 * \c Derive-Secret function
181 * (value MBEDTLS_SSL_TLS1_3_CONTEXT_HASHED), or whether
182 * it is the content of \c Messages itself, in which case
183 * the function takes care of the hashing
184 * (value MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED).
185 * \param dstbuf The target buffer to write the output of
186 * \c Derive-Secret to. This must be a writable buffer of
187 * size \p buflen Bytes.
188 * \param buflen The length of \p dstbuf in Bytes.
189 *
190 * \returns \c 0 on success.
191 * \returns A negative error code on failure.
192 */
193int mbedtls_ssl_tls1_3_derive_secret(
194 mbedtls_md_type_t hash_alg,
195 const unsigned char *secret, size_t slen,
196 const unsigned char *label, size_t llen,
197 const unsigned char *ctx, size_t clen,
198 int ctx_hashed,
199 unsigned char *dstbuf, size_t buflen );
200
201/**
202 * \brief Compute the next secret in the TLS 1.3 key schedule
203 *
204 * The TLS 1.3 key schedule proceeds as follows to compute
205 * the three main secrets during the handshake: The early
206 * secret for early data, the handshake secret for all
207 * other encrypted handshake messages, and the master
208 * secret for all application traffic.
209 *
210 * <tt>
211 * 0
212 * |
213 * v
214 * PSK -> HKDF-Extract = Early Secret
215 * |
216 * v
217 * Derive-Secret( ., "derived", "" )
218 * |
219 * v
220 * (EC)DHE -> HKDF-Extract = Handshake Secret
221 * |
222 * v
223 * Derive-Secret( ., "derived", "" )
224 * |
225 * v
226 * 0 -> HKDF-Extract = Master Secret
227 * </tt>
228 *
229 * Each of the three secrets in turn is the basis for further
230 * key derivations, such as the derivation of traffic keys and IVs;
231 * see e.g. mbedtls_ssl_tls1_3_make_traffic_keys().
232 *
233 * This function implements one step in this evolution of secrets:
234 *
235 * <tt>
236 * old_secret
237 * |
238 * v
239 * Derive-Secret( ., "derived", "" )
240 * |
241 * v
242 * input -> HKDF-Extract = new_secret
243 * </tt>
244 *
245 * \param hash_alg The identifier for the hash function used for the
246 * applications of HKDF.
247 * \param secret_old The address of the buffer holding the old secret
248 * on function entry. If not \c NULL, this must be a
249 * readable buffer whose size matches the output size
250 * of the hash function represented by \p hash_alg.
251 * If \c NULL, an all \c 0 array will be used instead.
252 * \param input The address of the buffer holding the additional
253 * input for the key derivation (e.g., the PSK or the
254 * ephemeral (EC)DH secret). If not \c NULL, this must be
255 * a readable buffer whose size \p input_len Bytes.
256 * If \c NULL, an all \c 0 array will be used instead.
257 * \param input_len The length of \p input in Bytes.
258 * \param secret_new The address of the buffer holding the new secret
259 * on function exit. This must be a writable buffer
260 * whose size matches the output size of the hash
261 * function represented by \p hash_alg.
262 * This may be the same as \p secret_old.
263 *
264 * \returns \c 0 on success.
265 * \returns A negative error code on failure.
266 */
267
268int mbedtls_ssl_tls1_3_evolve_secret(
269 mbedtls_md_type_t hash_alg,
270 const unsigned char *secret_old,
271 const unsigned char *input, size_t input_len,
272 unsigned char *secret_new );
273
274#endif /* MBEDTLS_SSL_TLS1_3_KEYS_H */
mbedtls_md_type_t
Supported message digests.
Definition: md.h:64
The data structure holding the cryptographic material (key and IV) used for record protection in TLS ...
Definition: ssl_internal.h:407