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