1 /* $OpenBSD: tls13_internal.h,v 1.104 2024/09/09 03:32:29 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 #include "tls_internal.h" 28 29 __BEGIN_HIDDEN_DECLS 30 31 #define TLS13_HS_CLIENT 1 32 #define TLS13_HS_SERVER 2 33 34 #define TLS13_IO_SUCCESS 1 35 #define TLS13_IO_EOF 0 36 #define TLS13_IO_FAILURE -1 37 #define TLS13_IO_ALERT -2 38 #define TLS13_IO_WANT_POLLIN -3 39 #define TLS13_IO_WANT_POLLOUT -4 40 #define TLS13_IO_WANT_RETRY -5 /* Retry the previous call immediately. */ 41 #define TLS13_IO_USE_LEGACY -6 42 #define TLS13_IO_RECORD_VERSION -7 43 #define TLS13_IO_RECORD_OVERFLOW -8 44 45 #define TLS13_ERR_VERIFY_FAILED 16 46 #define TLS13_ERR_HRR_FAILED 17 47 #define TLS13_ERR_TRAILING_DATA 18 48 #define TLS13_ERR_NO_SHARED_CIPHER 19 49 #define TLS13_ERR_NO_CERTIFICATE 20 50 #define TLS13_ERR_NO_PEER_CERTIFICATE 21 51 52 #define TLS13_ALERT_LEVEL_WARNING 1 53 #define TLS13_ALERT_LEVEL_FATAL 2 54 55 #define TLS13_ALERT_CLOSE_NOTIFY 0 56 #define TLS13_ALERT_UNEXPECTED_MESSAGE 10 57 #define TLS13_ALERT_BAD_RECORD_MAC 20 58 #define TLS13_ALERT_RECORD_OVERFLOW 22 59 #define TLS13_ALERT_HANDSHAKE_FAILURE 40 60 #define TLS13_ALERT_BAD_CERTIFICATE 42 61 #define TLS13_ALERT_UNSUPPORTED_CERTIFICATE 43 62 #define TLS13_ALERT_CERTIFICATE_REVOKED 44 63 #define TLS13_ALERT_CERTIFICATE_EXPIRED 45 64 #define TLS13_ALERT_CERTIFICATE_UNKNOWN 46 65 #define TLS13_ALERT_ILLEGAL_PARAMETER 47 66 #define TLS13_ALERT_UNKNOWN_CA 48 67 #define TLS13_ALERT_ACCESS_DENIED 49 68 #define TLS13_ALERT_DECODE_ERROR 50 69 #define TLS13_ALERT_DECRYPT_ERROR 51 70 #define TLS13_ALERT_PROTOCOL_VERSION 70 71 #define TLS13_ALERT_INSUFFICIENT_SECURITY 71 72 #define TLS13_ALERT_INTERNAL_ERROR 80 73 #define TLS13_ALERT_INAPPROPRIATE_FALLBACK 86 74 #define TLS13_ALERT_USER_CANCELED 90 75 #define TLS13_ALERT_MISSING_EXTENSION 109 76 #define TLS13_ALERT_UNSUPPORTED_EXTENSION 110 77 #define TLS13_ALERT_UNRECOGNIZED_NAME 112 78 #define TLS13_ALERT_BAD_CERTIFICATE_STATUS_RESPONSE 113 79 #define TLS13_ALERT_UNKNOWN_PSK_IDENTITY 115 80 #define TLS13_ALERT_CERTIFICATE_REQUIRED 116 81 #define TLS13_ALERT_NO_APPLICATION_PROTOCOL 120 82 83 #define TLS13_INFO_HANDSHAKE_STARTED SSL_CB_HANDSHAKE_START 84 #define TLS13_INFO_HANDSHAKE_COMPLETED SSL_CB_HANDSHAKE_DONE 85 #define TLS13_INFO_ACCEPT_LOOP SSL_CB_ACCEPT_LOOP 86 #define TLS13_INFO_CONNECT_LOOP SSL_CB_CONNECT_LOOP 87 #define TLS13_INFO_ACCEPT_EXIT SSL_CB_ACCEPT_EXIT 88 #define TLS13_INFO_CONNECT_EXIT SSL_CB_CONNECT_EXIT 89 90 typedef void (*tls13_alert_cb)(uint8_t _alert_level, uint8_t _alert_desc, 91 void *_cb_arg); 92 typedef ssize_t (*tls13_phh_recv_cb)(void *_cb_arg); 93 typedef void (*tls13_phh_sent_cb)(void *_cb_arg); 94 typedef void (*tls13_handshake_message_cb)(void *_cb_arg); 95 typedef void (*tls13_info_cb)(void *_cb_arg, int _state, int _ret); 96 typedef int (*tls13_ocsp_status_cb)(void *_cb_arg); 97 98 /* 99 * PSK support. 100 */ 101 102 /* 103 * Known PskKeyExchangeMode values. 104 * https://www.iana.org/assignments/tls-parameters/#tls-pskkeyexchangemode 105 */ 106 #define TLS13_PSK_KE 0 107 #define TLS13_PSK_DHE_KE 1 108 109 /* 110 * Secrets. 111 */ 112 struct tls13_secret { 113 uint8_t *data; 114 size_t len; 115 }; 116 117 /* RFC 8446 Section 7.1 Page 92 */ 118 struct tls13_secrets { 119 const EVP_MD *digest; 120 int resumption; 121 int init_done; 122 int early_done; 123 int handshake_done; 124 int schedule_done; 125 int insecure; /* Set by tests */ 126 struct tls13_secret zeros; 127 struct tls13_secret empty_hash; 128 struct tls13_secret extracted_early; 129 struct tls13_secret binder_key; 130 struct tls13_secret client_early_traffic; 131 struct tls13_secret early_exporter_master; 132 struct tls13_secret derived_early; 133 struct tls13_secret extracted_handshake; 134 struct tls13_secret client_handshake_traffic; 135 struct tls13_secret server_handshake_traffic; 136 struct tls13_secret derived_handshake; 137 struct tls13_secret extracted_master; 138 struct tls13_secret client_application_traffic; 139 struct tls13_secret server_application_traffic; 140 struct tls13_secret exporter_master; 141 struct tls13_secret resumption_master; 142 }; 143 144 int tls13_secret_init(struct tls13_secret *secret, size_t len); 145 void tls13_secret_cleanup(struct tls13_secret *secret); 146 struct tls13_secrets *tls13_secrets_create(const EVP_MD *digest, 147 int resumption); 148 void tls13_secrets_destroy(struct tls13_secrets *secrets); 149 150 int tls13_hkdf_expand_label(struct tls13_secret *out, const EVP_MD *digest, 151 const struct tls13_secret *secret, const char *label, 152 const struct tls13_secret *context); 153 int tls13_hkdf_expand_label_with_length(struct tls13_secret *out, 154 const EVP_MD *digest, const struct tls13_secret *secret, 155 const uint8_t *label, size_t label_len, const struct tls13_secret *context); 156 157 int tls13_derive_secret(struct tls13_secret *out, const EVP_MD *digest, 158 const struct tls13_secret *secret, const char *label, 159 const struct tls13_secret *context); 160 int tls13_derive_secret_with_label_length(struct tls13_secret *out, 161 const EVP_MD *digest, const struct tls13_secret *secret, 162 const uint8_t *label, size_t label_len, const struct tls13_secret *context); 163 164 int tls13_derive_early_secrets(struct tls13_secrets *secrets, uint8_t *psk, 165 size_t psk_len, const struct tls13_secret *context); 166 int tls13_derive_handshake_secrets(struct tls13_secrets *secrets, 167 const uint8_t *ecdhe, size_t ecdhe_len, const struct tls13_secret *context); 168 int tls13_derive_application_secrets(struct tls13_secrets *secrets, 169 const struct tls13_secret *context); 170 int tls13_update_client_traffic_secret(struct tls13_secrets *secrets); 171 int tls13_update_server_traffic_secret(struct tls13_secrets *secrets); 172 173 /* 174 * Record Layer. 175 */ 176 struct tls13_record_layer; 177 178 struct tls13_record_layer_callbacks { 179 /* Wire callbacks. */ 180 tls_read_cb wire_read; 181 tls_write_cb wire_write; 182 tls_flush_cb wire_flush; 183 184 /* Interceptors. */ 185 tls_handshake_read_cb handshake_read; 186 tls_handshake_write_cb handshake_write; 187 tls_traffic_key_cb set_read_traffic_key; 188 tls_traffic_key_cb set_write_traffic_key; 189 tls_alert_send_cb alert_send; 190 191 /* Notification callbacks. */ 192 tls13_alert_cb alert_recv; 193 tls13_alert_cb alert_sent; 194 tls13_phh_recv_cb phh_recv; 195 tls13_phh_sent_cb phh_sent; 196 }; 197 198 struct tls13_record_layer *tls13_record_layer_new( 199 const struct tls13_record_layer_callbacks *callbacks, void *cb_arg); 200 void tls13_record_layer_free(struct tls13_record_layer *rl); 201 void tls13_record_layer_set_callbacks(struct tls13_record_layer *rl, 202 const struct tls13_record_layer_callbacks *callbacks, void *cb_arg); 203 void tls13_record_layer_allow_ccs(struct tls13_record_layer *rl, int allow); 204 void tls13_record_layer_allow_legacy_alerts(struct tls13_record_layer *rl, int allow); 205 void tls13_record_layer_rcontent(struct tls13_record_layer *rl, CBS *cbs); 206 void tls13_record_layer_set_aead(struct tls13_record_layer *rl, 207 const EVP_AEAD *aead); 208 void tls13_record_layer_set_hash(struct tls13_record_layer *rl, 209 const EVP_MD *hash); 210 void tls13_record_layer_set_legacy_version(struct tls13_record_layer *rl, 211 uint16_t version); 212 void tls13_record_layer_set_retry_after_phh(struct tls13_record_layer *rl, int retry); 213 void tls13_record_layer_alert_sent(struct tls13_record_layer *rl, 214 uint8_t alert_level, uint8_t alert_desc); 215 void tls13_record_layer_handshake_completed(struct tls13_record_layer *rl); 216 int tls13_record_layer_set_read_traffic_key(struct tls13_record_layer *rl, 217 struct tls13_secret *read_key, enum ssl_encryption_level_t read_level); 218 int tls13_record_layer_set_write_traffic_key(struct tls13_record_layer *rl, 219 struct tls13_secret *write_key, enum ssl_encryption_level_t write_level); 220 ssize_t tls13_record_layer_send_pending(struct tls13_record_layer *rl); 221 ssize_t tls13_record_layer_phh(struct tls13_record_layer *rl, CBS *cbs); 222 ssize_t tls13_record_layer_flush(struct tls13_record_layer *rl); 223 224 ssize_t tls13_read_handshake_data(struct tls13_record_layer *rl, uint8_t *buf, size_t n); 225 ssize_t tls13_write_handshake_data(struct tls13_record_layer *rl, const uint8_t *buf, 226 size_t n); 227 ssize_t tls13_pending_application_data(struct tls13_record_layer *rl); 228 ssize_t tls13_peek_application_data(struct tls13_record_layer *rl, uint8_t *buf, size_t n); 229 ssize_t tls13_read_application_data(struct tls13_record_layer *rl, uint8_t *buf, size_t n); 230 ssize_t tls13_write_application_data(struct tls13_record_layer *rl, const uint8_t *buf, 231 size_t n); 232 233 ssize_t tls13_send_alert(struct tls13_record_layer *rl, uint8_t alert_desc); 234 ssize_t tls13_send_dummy_ccs(struct tls13_record_layer *rl); 235 236 /* 237 * Handshake Messages. 238 */ 239 struct tls13_handshake_msg; 240 241 struct tls13_handshake_msg *tls13_handshake_msg_new(void); 242 void tls13_handshake_msg_free(struct tls13_handshake_msg *msg); 243 void tls13_handshake_msg_data(struct tls13_handshake_msg *msg, CBS *cbs); 244 uint8_t tls13_handshake_msg_type(struct tls13_handshake_msg *msg); 245 int tls13_handshake_msg_content(struct tls13_handshake_msg *msg, CBS *cbs); 246 int tls13_handshake_msg_start(struct tls13_handshake_msg *msg, CBB *body, 247 uint8_t msg_type); 248 int tls13_handshake_msg_finish(struct tls13_handshake_msg *msg); 249 int tls13_handshake_msg_recv(struct tls13_handshake_msg *msg, 250 struct tls13_record_layer *rl); 251 int tls13_handshake_msg_send(struct tls13_handshake_msg *msg, 252 struct tls13_record_layer *rl); 253 254 struct tls13_handshake_stage { 255 uint8_t hs_type; 256 uint8_t message_number; 257 }; 258 259 struct ssl_handshake_tls13_st; 260 261 struct tls13_error { 262 int code; 263 int subcode; 264 int errnum; 265 const char *file; 266 int line; 267 char *msg; 268 }; 269 270 struct tls13_ctx { 271 struct tls13_error error; 272 273 SSL *ssl; 274 struct ssl_handshake_st *hs; 275 uint8_t mode; 276 struct tls13_handshake_stage handshake_stage; 277 int handshake_started; 278 int handshake_completed; 279 int need_flush; 280 int middlebox_compat; 281 int send_dummy_ccs; 282 int send_dummy_ccs_after; 283 284 int close_notify_sent; 285 int close_notify_recv; 286 287 const EVP_AEAD *aead; 288 const EVP_MD *hash; 289 290 struct tls13_record_layer *rl; 291 struct tls13_handshake_msg *hs_msg; 292 uint8_t key_update_request; 293 uint8_t alert; 294 int phh_count; 295 time_t phh_last_seen; 296 297 tls13_alert_cb alert_sent_cb; 298 tls13_alert_cb alert_recv_cb; 299 tls13_handshake_message_cb handshake_message_sent_cb; 300 tls13_handshake_message_cb handshake_message_recv_cb; 301 tls13_info_cb info_cb; 302 tls13_ocsp_status_cb ocsp_status_recv_cb; 303 }; 304 #ifndef TLS13_PHH_LIMIT_TIME 305 #define TLS13_PHH_LIMIT_TIME 3600 306 #endif 307 #ifndef TLS13_PHH_LIMIT 308 #define TLS13_PHH_LIMIT 100 309 #endif 310 311 struct tls13_ctx *tls13_ctx_new(int mode, SSL *ssl); 312 void tls13_ctx_free(struct tls13_ctx *ctx); 313 314 const EVP_AEAD *tls13_cipher_aead(const SSL_CIPHER *cipher); 315 const EVP_MD *tls13_cipher_hash(const SSL_CIPHER *cipher); 316 317 void tls13_alert_received_cb(uint8_t alert_level, uint8_t alert_desc, void *arg); 318 void tls13_alert_sent_cb(uint8_t alert_level, uint8_t alert_desc, void *arg); 319 ssize_t tls13_phh_received_cb(void *cb_arg); 320 void tls13_phh_done_cb(void *cb_arg); 321 322 int tls13_quic_init(struct tls13_ctx *ctx); 323 324 /* 325 * Legacy interfaces. 326 */ 327 int tls13_use_legacy_client(struct tls13_ctx *ctx); 328 int tls13_use_legacy_server(struct tls13_ctx *ctx); 329 int tls13_legacy_accept(SSL *ssl); 330 int tls13_legacy_connect(SSL *ssl); 331 ssize_t tls13_legacy_wire_read_cb(void *buf, size_t n, void *arg); 332 ssize_t tls13_legacy_wire_write_cb(const void *buf, size_t n, void *arg); 333 ssize_t tls13_legacy_wire_flush_cb(void *arg); 334 int tls13_legacy_pending(const SSL *ssl); 335 int tls13_legacy_read_bytes(SSL *ssl, int type, unsigned char *buf, int len, 336 int peek); 337 int tls13_legacy_write_bytes(SSL *ssl, int type, const void *buf, int len); 338 int tls13_legacy_shutdown(SSL *ssl); 339 int tls13_legacy_servername_process(struct tls13_ctx *ctx, uint8_t *alert); 340 341 /* 342 * Message Types - RFC 8446, Section B.3. 343 * 344 * Values listed as "_RESERVED" were used in previous versions of TLS and are 345 * listed here for completeness. TLS 1.3 implementations MUST NOT send them but 346 * might receive them from older TLS implementations. 347 */ 348 #define TLS13_MT_HELLO_REQUEST_RESERVED 0 349 #define TLS13_MT_CLIENT_HELLO 1 350 #define TLS13_MT_SERVER_HELLO 2 351 #define TLS13_MT_HELLO_VERIFY_REQUEST_RESERVED 3 352 #define TLS13_MT_NEW_SESSION_TICKET 4 353 #define TLS13_MT_END_OF_EARLY_DATA 5 354 #define TLS13_MT_HELLO_RETRY_REQUEST_RESERVED 6 355 #define TLS13_MT_ENCRYPTED_EXTENSIONS 8 356 #define TLS13_MT_CERTIFICATE 11 357 #define TLS13_MT_SERVER_KEY_EXCHANGE_RESERVED 12 358 #define TLS13_MT_CERTIFICATE_REQUEST 13 359 #define TLS13_MT_SERVER_HELLO_DONE_RESERVED 14 360 #define TLS13_MT_CERTIFICATE_VERIFY 15 361 #define TLS13_MT_CLIENT_KEY_EXCHANGE_RESERVED 16 362 #define TLS13_MT_FINISHED 20 363 #define TLS13_MT_CERTIFICATE_URL_RESERVED 21 364 #define TLS13_MT_CERTIFICATE_STATUS_RESERVED 22 365 #define TLS13_MT_SUPPLEMENTAL_DATA_RESERVED 23 366 #define TLS13_MT_KEY_UPDATE 24 367 #define TLS13_MT_MESSAGE_HASH 254 368 369 int tls13_handshake_msg_record(struct tls13_ctx *ctx); 370 int tls13_handshake_perform(struct tls13_ctx *ctx); 371 372 int tls13_client_init(struct tls13_ctx *ctx); 373 int tls13_server_init(struct tls13_ctx *ctx); 374 int tls13_client_connect(struct tls13_ctx *ctx); 375 int tls13_server_accept(struct tls13_ctx *ctx); 376 377 int tls13_client_hello_send(struct tls13_ctx *ctx, CBB *cbb); 378 int tls13_client_hello_sent(struct tls13_ctx *ctx); 379 int tls13_client_hello_recv(struct tls13_ctx *ctx, CBS *cbs); 380 int tls13_client_hello_retry_send(struct tls13_ctx *ctx, CBB *cbb); 381 int tls13_client_hello_retry_recv(struct tls13_ctx *ctx, CBS *cbs); 382 int tls13_client_end_of_early_data_send(struct tls13_ctx *ctx, CBB *cbb); 383 int tls13_client_end_of_early_data_recv(struct tls13_ctx *ctx, CBS *cbs); 384 int tls13_client_certificate_send(struct tls13_ctx *ctx, CBB *cbb); 385 int tls13_client_certificate_recv(struct tls13_ctx *ctx, CBS *cbs); 386 int tls13_client_certificate_verify_send(struct tls13_ctx *ctx, CBB *cbb); 387 int tls13_client_certificate_verify_recv(struct tls13_ctx *ctx, CBS *cbs); 388 int tls13_client_finished_recv(struct tls13_ctx *ctx, CBS *cbs); 389 int tls13_client_finished_send(struct tls13_ctx *ctx, CBB *cbb); 390 int tls13_client_finished_sent(struct tls13_ctx *ctx); 391 int tls13_server_hello_recv(struct tls13_ctx *ctx, CBS *cbs); 392 int tls13_server_hello_send(struct tls13_ctx *ctx, CBB *cbb); 393 int tls13_server_hello_sent(struct tls13_ctx *ctx); 394 int tls13_server_hello_retry_request_recv(struct tls13_ctx *ctx, CBS *cbs); 395 int tls13_server_hello_retry_request_send(struct tls13_ctx *ctx, CBB *cbb); 396 int tls13_server_hello_retry_request_sent(struct tls13_ctx *ctx); 397 int tls13_server_encrypted_extensions_recv(struct tls13_ctx *ctx, CBS *cbs); 398 int tls13_server_encrypted_extensions_send(struct tls13_ctx *ctx, CBB *cbb); 399 int tls13_server_certificate_recv(struct tls13_ctx *ctx, CBS *cbs); 400 int tls13_server_certificate_send(struct tls13_ctx *ctx, CBB *cbb); 401 int tls13_server_certificate_request_recv(struct tls13_ctx *ctx, CBS *cbs); 402 int tls13_server_certificate_request_send(struct tls13_ctx *ctx, CBB *cbb); 403 int tls13_server_certificate_verify_send(struct tls13_ctx *ctx, CBB *cbb); 404 int tls13_server_certificate_verify_recv(struct tls13_ctx *ctx, CBS *cbs); 405 int tls13_server_finished_recv(struct tls13_ctx *ctx, CBS *cbs); 406 int tls13_server_finished_send(struct tls13_ctx *ctx, CBB *cbb); 407 int tls13_server_finished_sent(struct tls13_ctx *ctx); 408 409 void tls13_error_clear(struct tls13_error *error); 410 int tls13_cert_add(struct tls13_ctx *ctx, CBB *cbb, X509 *cert, 411 int(*build_extensions)(SSL *s, uint16_t msg_type, CBB *cbb)); 412 413 int tls13_synthetic_handshake_message(struct tls13_ctx *ctx); 414 int tls13_clienthello_hash_init(struct tls13_ctx *ctx); 415 void tls13_clienthello_hash_clear(struct ssl_handshake_tls13_st *hs); 416 int tls13_clienthello_hash_update_bytes(struct tls13_ctx *ctx, void *data, 417 size_t len); 418 int tls13_clienthello_hash_update(struct tls13_ctx *ctx, CBS *cbs); 419 int tls13_clienthello_hash_finalize(struct tls13_ctx *ctx); 420 int tls13_clienthello_hash_validate(struct tls13_ctx *ctx); 421 422 int tls13_error_set(struct tls13_error *error, int code, int subcode, 423 const char *file, int line, const char *fmt, ...); 424 int tls13_error_setx(struct tls13_error *error, int code, int subcode, 425 const char *file, int line, const char *fmt, ...); 426 427 #define tls13_set_error(ctx, code, subcode, fmt, ...) \ 428 tls13_error_set(&(ctx)->error, (code), (subcode), __FILE__, __LINE__, \ 429 (fmt), __VA_ARGS__) 430 #define tls13_set_errorx(ctx, code, subcode, fmt, ...) \ 431 tls13_error_setx(&(ctx)->error, (code), (subcode), __FILE__, __LINE__, \ 432 (fmt), __VA_ARGS__) 433 434 int tls13_exporter(struct tls13_ctx *ctx, const uint8_t *label, size_t label_len, 435 const uint8_t *context_value, size_t context_value_len, uint8_t *out, 436 size_t out_len); 437 438 extern const uint8_t tls13_downgrade_12[8]; 439 extern const uint8_t tls13_downgrade_11[8]; 440 extern const uint8_t tls13_hello_retry_request_hash[32]; 441 extern const uint8_t tls13_cert_verify_pad[64]; 442 extern const uint8_t tls13_cert_client_verify_context[]; 443 extern const uint8_t tls13_cert_server_verify_context[]; 444 445 __END_HIDDEN_DECLS 446 447 #endif 448