xref: /openbsd-src/lib/libssl/tls13_internal.h (revision 505ee9ea3b177e2387d907a91ca7da069f3f14d8)
1 /* $OpenBSD: tls13_internal.h,v 1.85 2020/07/03 04:12:51 tb Exp $ */
2 /*
3  * Copyright (c) 2018 Bob Beck <beck@openbsd.org>
4  * Copyright (c) 2018 Theo Buehler <tb@openbsd.org>
5  * Copyright (c) 2018, 2019 Joel Sing <jsing@openbsd.org>
6  *
7  * Permission to use, copy, modify, and/or distribute this software for any
8  * purpose with or without fee is hereby granted, provided that the above
9  * copyright notice and this permission notice appear in all copies.
10  *
11  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
12  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
13  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
14  * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
15  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
16  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
17  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18  */
19 
20 #ifndef HEADER_TLS13_INTERNAL_H
21 #define HEADER_TLS13_INTERNAL_H
22 
23 #include <openssl/evp.h>
24 #include <openssl/ssl.h>
25 
26 #include "bytestring.h"
27 
28 __BEGIN_HIDDEN_DECLS
29 
30 #define TLS13_HS_CLIENT			1
31 #define TLS13_HS_SERVER			2
32 
33 #define TLS13_IO_SUCCESS		 1
34 #define TLS13_IO_EOF			 0
35 #define TLS13_IO_FAILURE		-1
36 #define TLS13_IO_ALERT			-2
37 #define TLS13_IO_WANT_POLLIN		-3
38 #define TLS13_IO_WANT_POLLOUT		-4
39 #define TLS13_IO_WANT_RETRY		-5 /* Retry the previous call immediately. */
40 #define TLS13_IO_USE_LEGACY		-6
41 #define TLS13_IO_RECORD_VERSION		-7
42 #define TLS13_IO_RECORD_OVERFLOW	-8
43 
44 #define TLS13_ERR_VERIFY_FAILED		16
45 #define TLS13_ERR_HRR_FAILED		17
46 #define TLS13_ERR_TRAILING_DATA		18
47 #define TLS13_ERR_NO_SHARED_CIPHER	19
48 #define TLS13_ERR_NO_CERTIFICATE	20
49 #define TLS13_ERR_NO_PEER_CERTIFICATE	21
50 
51 #define TLS13_ALERT_LEVEL_WARNING			1
52 #define TLS13_ALERT_LEVEL_FATAL				2
53 
54 #define TLS13_ALERT_CLOSE_NOTIFY			0
55 #define TLS13_ALERT_UNEXPECTED_MESSAGE			10
56 #define TLS13_ALERT_BAD_RECORD_MAC			20
57 #define TLS13_ALERT_RECORD_OVERFLOW			22
58 #define TLS13_ALERT_HANDSHAKE_FAILURE			40
59 #define TLS13_ALERT_BAD_CERTIFICATE			42
60 #define TLS13_ALERT_UNSUPPORTED_CERTIFICATE		43
61 #define TLS13_ALERT_CERTIFICATE_REVOKED			44
62 #define TLS13_ALERT_CERTIFICATE_EXPIRED			45
63 #define TLS13_ALERT_CERTIFICATE_UNKNOWN			46
64 #define TLS13_ALERT_ILLEGAL_PARAMETER			47
65 #define TLS13_ALERT_UNKNOWN_CA				48
66 #define TLS13_ALERT_ACCESS_DENIED			49
67 #define TLS13_ALERT_DECODE_ERROR			50
68 #define TLS13_ALERT_DECRYPT_ERROR			51
69 #define TLS13_ALERT_PROTOCOL_VERSION			70
70 #define TLS13_ALERT_INSUFFICIENT_SECURITY		71
71 #define TLS13_ALERT_INTERNAL_ERROR			80
72 #define TLS13_ALERT_INAPPROPRIATE_FALLBACK		86
73 #define TLS13_ALERT_USER_CANCELED			90
74 #define TLS13_ALERT_MISSING_EXTENSION			109
75 #define TLS13_ALERT_UNSUPPORTED_EXTENSION		110
76 #define TLS13_ALERT_UNRECOGNIZED_NAME			112
77 #define TLS13_ALERT_BAD_CERTIFICATE_STATUS_RESPONSE	113
78 #define TLS13_ALERT_UNKNOWN_PSK_IDENTITY		115
79 #define TLS13_ALERT_CERTIFICATE_REQUIRED		116
80 #define TLS13_ALERT_NO_APPLICATION_PROTOCOL		120
81 
82 typedef void (*tls13_alert_cb)(uint8_t _alert_desc, void *_cb_arg);
83 typedef ssize_t (*tls13_phh_recv_cb)(void *_cb_arg, CBS *_cbs);
84 typedef void (*tls13_phh_sent_cb)(void *_cb_arg);
85 typedef ssize_t (*tls13_read_cb)(void *_buf, size_t _buflen, void *_cb_arg);
86 typedef ssize_t (*tls13_write_cb)(const void *_buf, size_t _buflen,
87     void *_cb_arg);
88 typedef void (*tls13_handshake_message_cb)(void *_cb_arg);
89 typedef int (*tls13_ocsp_status_cb)(void *_cb_arg);
90 
91 /*
92  * Buffers.
93  */
94 struct tls13_buffer;
95 
96 struct tls13_buffer *tls13_buffer_new(size_t init_size);
97 int tls13_buffer_set_data(struct tls13_buffer *buf, CBS *data);
98 void tls13_buffer_free(struct tls13_buffer *buf);
99 ssize_t tls13_buffer_extend(struct tls13_buffer *buf, size_t len,
100     tls13_read_cb read_cb, void *cb_arg);
101 void tls13_buffer_cbs(struct tls13_buffer *buf, CBS *cbs);
102 int tls13_buffer_finish(struct tls13_buffer *buf, uint8_t **out,
103     size_t *out_len);
104 
105 /*
106  * Secrets.
107  */
108 struct tls13_secret {
109 	uint8_t *data;
110 	size_t len;
111 };
112 
113 /* RFC 8446 Section 7.1  Page 92 */
114 struct tls13_secrets {
115 	const EVP_MD *digest;
116 	int resumption;
117 	int init_done;
118 	int early_done;
119 	int handshake_done;
120 	int schedule_done;
121 	int insecure; /* Set by tests */
122 	struct tls13_secret zeros;
123 	struct tls13_secret empty_hash;
124 	struct tls13_secret extracted_early;
125 	struct tls13_secret binder_key;
126 	struct tls13_secret client_early_traffic;
127 	struct tls13_secret early_exporter_master;
128 	struct tls13_secret derived_early;
129 	struct tls13_secret extracted_handshake;
130 	struct tls13_secret client_handshake_traffic;
131 	struct tls13_secret server_handshake_traffic;
132 	struct tls13_secret derived_handshake;
133 	struct tls13_secret extracted_master;
134 	struct tls13_secret client_application_traffic;
135 	struct tls13_secret server_application_traffic;
136 	struct tls13_secret exporter_master;
137 	struct tls13_secret resumption_master;
138 };
139 
140 struct tls13_secrets *tls13_secrets_create(const EVP_MD *digest,
141     int resumption);
142 void tls13_secrets_destroy(struct tls13_secrets *secrets);
143 
144 int tls13_hkdf_expand_label(struct tls13_secret *out, const EVP_MD *digest,
145     const struct tls13_secret *secret, const char *label,
146     const struct tls13_secret *context);
147 
148 int tls13_derive_early_secrets(struct tls13_secrets *secrets, uint8_t *psk,
149     size_t psk_len, const struct tls13_secret *context);
150 int tls13_derive_handshake_secrets(struct tls13_secrets *secrets,
151     const uint8_t *ecdhe, size_t ecdhe_len, const struct tls13_secret *context);
152 int tls13_derive_application_secrets(struct tls13_secrets *secrets,
153     const struct tls13_secret *context);
154 int tls13_update_client_traffic_secret(struct tls13_secrets *secrets);
155 int tls13_update_server_traffic_secret(struct tls13_secrets *secrets);
156 
157 /*
158  * Key shares.
159  */
160 struct tls13_key_share;
161 
162 struct tls13_key_share *tls13_key_share_new(uint16_t group_id);
163 struct tls13_key_share *tls13_key_share_new_nid(int nid);
164 void tls13_key_share_free(struct tls13_key_share *ks);
165 
166 uint16_t tls13_key_share_group(struct tls13_key_share *ks);
167 int tls13_key_share_peer_pkey(struct tls13_key_share *ks, EVP_PKEY *pkey);
168 int tls13_key_share_generate(struct tls13_key_share *ks);
169 int tls13_key_share_public(struct tls13_key_share *ks, CBB *cbb);
170 int tls13_key_share_peer_public(struct tls13_key_share *ks, uint16_t group,
171     CBS *cbs);
172 int tls13_key_share_derive(struct tls13_key_share *ks, uint8_t **shared_key,
173     size_t *shared_key_len);
174 
175 /*
176  * Record Layer.
177  */
178 struct tls13_record_layer;
179 
180 struct tls13_record_layer_callbacks {
181 	tls13_read_cb wire_read;
182 	tls13_write_cb wire_write;
183 	tls13_alert_cb alert_recv;
184 	tls13_alert_cb alert_sent;
185 	tls13_phh_recv_cb phh_recv;
186 	tls13_phh_sent_cb phh_sent;
187 };
188 
189 struct tls13_record_layer *tls13_record_layer_new(
190     const struct tls13_record_layer_callbacks *callbacks, void *cb_arg);
191 void tls13_record_layer_free(struct tls13_record_layer *rl);
192 void tls13_record_layer_allow_ccs(struct tls13_record_layer *rl, int allow);
193 void tls13_record_layer_allow_legacy_alerts(struct tls13_record_layer *rl, int allow);
194 void tls13_record_layer_rbuf(struct tls13_record_layer *rl, CBS *cbs);
195 void tls13_record_layer_set_aead(struct tls13_record_layer *rl,
196     const EVP_AEAD *aead);
197 void tls13_record_layer_set_hash(struct tls13_record_layer *rl,
198     const EVP_MD *hash);
199 void tls13_record_layer_set_legacy_version(struct tls13_record_layer *rl,
200     uint16_t version);
201 void tls13_record_layer_set_retry_after_phh(struct tls13_record_layer *rl, int retry);
202 void tls13_record_layer_handshake_completed(struct tls13_record_layer *rl);
203 int tls13_record_layer_set_read_traffic_key(struct tls13_record_layer *rl,
204     struct tls13_secret *read_key);
205 int tls13_record_layer_set_write_traffic_key(struct tls13_record_layer *rl,
206     struct tls13_secret *write_key);
207 ssize_t tls13_record_layer_send_pending(struct tls13_record_layer *rl);
208 ssize_t tls13_record_layer_phh(struct tls13_record_layer *rl, CBS *cbs);
209 
210 ssize_t tls13_read_handshake_data(struct tls13_record_layer *rl, uint8_t *buf, size_t n);
211 ssize_t tls13_write_handshake_data(struct tls13_record_layer *rl, const uint8_t *buf,
212     size_t n);
213 ssize_t tls13_pending_application_data(struct tls13_record_layer *rl);
214 ssize_t tls13_peek_application_data(struct tls13_record_layer *rl, uint8_t *buf, size_t n);
215 ssize_t tls13_read_application_data(struct tls13_record_layer *rl, uint8_t *buf, size_t n);
216 ssize_t tls13_write_application_data(struct tls13_record_layer *rl, const uint8_t *buf,
217     size_t n);
218 
219 ssize_t tls13_send_alert(struct tls13_record_layer *rl, uint8_t alert_desc);
220 ssize_t tls13_send_dummy_ccs(struct tls13_record_layer *rl);
221 
222 /*
223  * Handshake Messages.
224  */
225 struct tls13_handshake_msg;
226 
227 struct tls13_handshake_msg *tls13_handshake_msg_new(void);
228 void tls13_handshake_msg_free(struct tls13_handshake_msg *msg);
229 void tls13_handshake_msg_data(struct tls13_handshake_msg *msg, CBS *cbs);
230 int tls13_handshake_msg_set_buffer(struct tls13_handshake_msg *msg, CBS *cbs);
231 uint8_t tls13_handshake_msg_type(struct tls13_handshake_msg *msg);
232 int tls13_handshake_msg_content(struct tls13_handshake_msg *msg, CBS *cbs);
233 int tls13_handshake_msg_start(struct tls13_handshake_msg *msg, CBB *body,
234     uint8_t msg_type);
235 int tls13_handshake_msg_finish(struct tls13_handshake_msg *msg);
236 int tls13_handshake_msg_recv(struct tls13_handshake_msg *msg,
237     struct tls13_record_layer *rl);
238 int tls13_handshake_msg_send(struct tls13_handshake_msg *msg,
239     struct tls13_record_layer *rl);
240 
241 struct tls13_handshake_stage {
242 	uint8_t	hs_type;
243 	uint8_t	message_number;
244 };
245 
246 struct ssl_handshake_tls13_st;
247 
248 struct tls13_error {
249 	int code;
250 	int subcode;
251 	int errnum;
252 	const char *file;
253 	int line;
254 	char *msg;
255 };
256 
257 struct tls13_ctx {
258 	struct tls13_error error;
259 
260 	SSL *ssl;
261 	struct ssl_handshake_tls13_st *hs;
262 	uint8_t	mode;
263 	struct tls13_handshake_stage handshake_stage;
264 	int handshake_completed;
265 	int middlebox_compat;
266 	int send_dummy_ccs;
267 	int send_dummy_ccs_after;
268 
269 	int close_notify_sent;
270 	int close_notify_recv;
271 
272 	const EVP_AEAD *aead;
273 	const EVP_MD *hash;
274 
275 	struct tls13_record_layer *rl;
276 	struct tls13_handshake_msg *hs_msg;
277 	uint8_t key_update_request;
278 	uint8_t alert;
279 	int phh_count;
280 	time_t phh_last_seen;
281 
282 	tls13_handshake_message_cb handshake_message_sent_cb;
283 	tls13_handshake_message_cb handshake_message_recv_cb;
284 	tls13_ocsp_status_cb ocsp_status_recv_cb;
285 };
286 #ifndef TLS13_PHH_LIMIT_TIME
287 #define TLS13_PHH_LIMIT_TIME 3600
288 #endif
289 #ifndef TLS13_PHH_LIMIT
290 #define TLS13_PHH_LIMIT 100
291 #endif
292 
293 struct tls13_ctx *tls13_ctx_new(int mode);
294 void tls13_ctx_free(struct tls13_ctx *ctx);
295 
296 const EVP_AEAD *tls13_cipher_aead(const SSL_CIPHER *cipher);
297 const EVP_MD *tls13_cipher_hash(const SSL_CIPHER *cipher);
298 
299 /*
300  * Legacy interfaces.
301  */
302 int tls13_use_legacy_client(struct tls13_ctx *ctx);
303 int tls13_use_legacy_server(struct tls13_ctx *ctx);
304 int tls13_legacy_accept(SSL *ssl);
305 int tls13_legacy_connect(SSL *ssl);
306 int tls13_legacy_return_code(SSL *ssl, ssize_t ret);
307 ssize_t tls13_legacy_wire_read_cb(void *buf, size_t n, void *arg);
308 ssize_t tls13_legacy_wire_write_cb(const void *buf, size_t n, void *arg);
309 int tls13_legacy_pending(const SSL *ssl);
310 int tls13_legacy_read_bytes(SSL *ssl, int type, unsigned char *buf, int len,
311     int peek);
312 int tls13_legacy_write_bytes(SSL *ssl, int type, const void *buf, int len);
313 int tls13_legacy_shutdown(SSL *ssl);
314 int tls13_legacy_servername_process(struct tls13_ctx *ctx, uint8_t *alert);
315 
316 /*
317  * Message Types - RFC 8446, Section B.3.
318  *
319  * Values listed as "_RESERVED" were used in previous versions of TLS and are
320  * listed here for completeness.  TLS 1.3 implementations MUST NOT send them but
321  * might receive them from older TLS implementations.
322  */
323 #define	TLS13_MT_HELLO_REQUEST_RESERVED		0
324 #define	TLS13_MT_CLIENT_HELLO			1
325 #define	TLS13_MT_SERVER_HELLO			2
326 #define	TLS13_MT_HELLO_VERIFY_REQUEST_RESERVED	3
327 #define	TLS13_MT_NEW_SESSION_TICKET		4
328 #define	TLS13_MT_END_OF_EARLY_DATA		5
329 #define	TLS13_MT_HELLO_RETRY_REQUEST_RESERVED	6
330 #define	TLS13_MT_ENCRYPTED_EXTENSIONS		8
331 #define	TLS13_MT_CERTIFICATE			11
332 #define	TLS13_MT_SERVER_KEY_EXCHANGE_RESERVED	12
333 #define	TLS13_MT_CERTIFICATE_REQUEST		13
334 #define	TLS13_MT_SERVER_HELLO_DONE_RESERVED	14
335 #define	TLS13_MT_CERTIFICATE_VERIFY		15
336 #define	TLS13_MT_CLIENT_KEY_EXCHANGE_RESERVED	16
337 #define	TLS13_MT_FINISHED			20
338 #define	TLS13_MT_CERTIFICATE_URL_RESERVED	21
339 #define	TLS13_MT_CERTIFICATE_STATUS_RESERVED	22
340 #define	TLS13_MT_SUPPLEMENTAL_DATA_RESERVED	23
341 #define	TLS13_MT_KEY_UPDATE			24
342 #define	TLS13_MT_MESSAGE_HASH			254
343 
344 int tls13_handshake_msg_record(struct tls13_ctx *ctx);
345 int tls13_handshake_perform(struct tls13_ctx *ctx);
346 
347 int tls13_client_init(struct tls13_ctx *ctx);
348 int tls13_server_init(struct tls13_ctx *ctx);
349 int tls13_client_connect(struct tls13_ctx *ctx);
350 int tls13_server_accept(struct tls13_ctx *ctx);
351 
352 int tls13_client_hello_send(struct tls13_ctx *ctx, CBB *cbb);
353 int tls13_client_hello_sent(struct tls13_ctx *ctx);
354 int tls13_client_hello_recv(struct tls13_ctx *ctx, CBS *cbs);
355 int tls13_client_hello_retry_send(struct tls13_ctx *ctx, CBB *cbb);
356 int tls13_client_hello_retry_recv(struct tls13_ctx *ctx, CBS *cbs);
357 int tls13_client_end_of_early_data_send(struct tls13_ctx *ctx, CBB *cbb);
358 int tls13_client_end_of_early_data_recv(struct tls13_ctx *ctx, CBS *cbs);
359 int tls13_client_certificate_send(struct tls13_ctx *ctx, CBB *cbb);
360 int tls13_client_certificate_recv(struct tls13_ctx *ctx, CBS *cbs);
361 int tls13_client_certificate_verify_send(struct tls13_ctx *ctx, CBB *cbb);
362 int tls13_client_certificate_verify_recv(struct tls13_ctx *ctx, CBS *cbs);
363 int tls13_client_finished_recv(struct tls13_ctx *ctx, CBS *cbs);
364 int tls13_client_finished_send(struct tls13_ctx *ctx, CBB *cbb);
365 int tls13_client_finished_sent(struct tls13_ctx *ctx);
366 int tls13_server_hello_recv(struct tls13_ctx *ctx, CBS *cbs);
367 int tls13_server_hello_send(struct tls13_ctx *ctx, CBB *cbb);
368 int tls13_server_hello_sent(struct tls13_ctx *ctx);
369 int tls13_server_hello_retry_request_recv(struct tls13_ctx *ctx, CBS *cbs);
370 int tls13_server_hello_retry_request_send(struct tls13_ctx *ctx, CBB *cbb);
371 int tls13_server_hello_retry_request_sent(struct tls13_ctx *ctx);
372 int tls13_server_encrypted_extensions_recv(struct tls13_ctx *ctx, CBS *cbs);
373 int tls13_server_encrypted_extensions_send(struct tls13_ctx *ctx, CBB *cbb);
374 int tls13_server_certificate_recv(struct tls13_ctx *ctx, CBS *cbs);
375 int tls13_server_certificate_send(struct tls13_ctx *ctx, CBB *cbb);
376 int tls13_server_certificate_request_recv(struct tls13_ctx *ctx, CBS *cbs);
377 int tls13_server_certificate_request_send(struct tls13_ctx *ctx, CBB *cbb);
378 int tls13_server_certificate_verify_send(struct tls13_ctx *ctx, CBB *cbb);
379 int tls13_server_certificate_verify_recv(struct tls13_ctx *ctx, CBS *cbs);
380 int tls13_server_finished_recv(struct tls13_ctx *ctx, CBS *cbs);
381 int tls13_server_finished_send(struct tls13_ctx *ctx, CBB *cbb);
382 int tls13_server_finished_sent(struct tls13_ctx *ctx);
383 
384 void tls13_error_clear(struct tls13_error *error);
385 int tls13_cert_add(struct tls13_ctx *ctx, CBB *cbb, X509 *cert,
386     int(*build_extensions)(SSL *s, uint16_t msg_type, CBB *cbb));
387 
388 int tls13_synthetic_handshake_message(struct tls13_ctx *ctx);
389 int tls13_clienthello_hash_init(struct tls13_ctx *ctx);
390 void tls13_clienthello_hash_clear(struct ssl_handshake_tls13_st *hs);
391 int tls13_clienthello_hash_update_bytes(struct tls13_ctx *ctx, void *data,
392     size_t len);
393 int tls13_clienthello_hash_update(struct tls13_ctx *ctx, CBS *cbs);
394 int tls13_clienthello_hash_finalize(struct tls13_ctx *ctx);
395 int tls13_clienthello_hash_validate(struct tls13_ctx *ctx);
396 
397 int tls13_error_set(struct tls13_error *error, int code, int subcode,
398     const char *file, int line, const char *fmt, ...);
399 int tls13_error_setx(struct tls13_error *error, int code, int subcode,
400     const char *file, int line, const char *fmt, ...);
401 
402 #define tls13_set_error(ctx, code, subcode, fmt, ...) \
403 	tls13_error_set(&(ctx)->error, (code), (subcode), __FILE__, __LINE__, \
404 	    (fmt), __VA_ARGS__)
405 #define tls13_set_errorx(ctx, code, subcode, fmt, ...) \
406 	tls13_error_setx(&(ctx)->error, (code), (subcode), __FILE__, __LINE__, \
407 	    (fmt), __VA_ARGS__)
408 
409 extern const uint8_t tls13_downgrade_12[8];
410 extern const uint8_t tls13_downgrade_11[8];
411 extern const uint8_t tls13_hello_retry_request_hash[32];
412 extern const uint8_t tls13_cert_verify_pad[64];
413 extern const uint8_t tls13_cert_client_verify_context[];
414 extern const uint8_t tls13_cert_server_verify_context[];
415 
416 __END_HIDDEN_DECLS
417 
418 #endif
419