1 /* $OpenBSD: tls13_internal.h,v 1.67.4.1 2020/05/19 20:22:33 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 42 #define TLS13_ERR_VERIFY_FAILED 16 43 #define TLS13_ERR_HRR_FAILED 17 44 #define TLS13_ERR_TRAILING_DATA 18 45 #define TLS13_ERR_NO_SHARED_CIPHER 19 46 #define TLS13_ERR_NO_PEER_CERTIFICATE 21 47 48 typedef void (*tls13_alert_cb)(uint8_t _alert_desc, void *_cb_arg); 49 typedef ssize_t (*tls13_phh_recv_cb)(void *_cb_arg, CBS *_cbs); 50 typedef void (*tls13_phh_sent_cb)(void *_cb_arg); 51 typedef ssize_t (*tls13_read_cb)(void *_buf, size_t _buflen, void *_cb_arg); 52 typedef ssize_t (*tls13_write_cb)(const void *_buf, size_t _buflen, 53 void *_cb_arg); 54 typedef void (*tls13_handshake_message_cb)(void *_cb_arg); 55 56 /* 57 * Buffers. 58 */ 59 struct tls13_buffer; 60 61 struct tls13_buffer *tls13_buffer_new(size_t init_size); 62 int tls13_buffer_set_data(struct tls13_buffer *buf, CBS *data); 63 void tls13_buffer_free(struct tls13_buffer *buf); 64 ssize_t tls13_buffer_extend(struct tls13_buffer *buf, size_t len, 65 tls13_read_cb read_cb, void *cb_arg); 66 void tls13_buffer_cbs(struct tls13_buffer *buf, CBS *cbs); 67 int tls13_buffer_finish(struct tls13_buffer *buf, uint8_t **out, 68 size_t *out_len); 69 70 /* 71 * Secrets. 72 */ 73 struct tls13_secret { 74 uint8_t *data; 75 size_t len; 76 }; 77 78 /* RFC 8446 Section 7.1 Page 92 */ 79 struct tls13_secrets { 80 const EVP_MD *digest; 81 int resumption; 82 int init_done; 83 int early_done; 84 int handshake_done; 85 int schedule_done; 86 int insecure; /* Set by tests */ 87 struct tls13_secret zeros; 88 struct tls13_secret empty_hash; 89 struct tls13_secret extracted_early; 90 struct tls13_secret binder_key; 91 struct tls13_secret client_early_traffic; 92 struct tls13_secret early_exporter_master; 93 struct tls13_secret derived_early; 94 struct tls13_secret extracted_handshake; 95 struct tls13_secret client_handshake_traffic; 96 struct tls13_secret server_handshake_traffic; 97 struct tls13_secret derived_handshake; 98 struct tls13_secret extracted_master; 99 struct tls13_secret client_application_traffic; 100 struct tls13_secret server_application_traffic; 101 struct tls13_secret exporter_master; 102 struct tls13_secret resumption_master; 103 }; 104 105 struct tls13_secrets *tls13_secrets_create(const EVP_MD *digest, 106 int resumption); 107 void tls13_secrets_destroy(struct tls13_secrets *secrets); 108 109 int tls13_hkdf_expand_label(struct tls13_secret *out, const EVP_MD *digest, 110 const struct tls13_secret *secret, const char *label, 111 const struct tls13_secret *context); 112 113 int tls13_derive_early_secrets(struct tls13_secrets *secrets, uint8_t *psk, 114 size_t psk_len, const struct tls13_secret *context); 115 int tls13_derive_handshake_secrets(struct tls13_secrets *secrets, 116 const uint8_t *ecdhe, size_t ecdhe_len, const struct tls13_secret *context); 117 int tls13_derive_application_secrets(struct tls13_secrets *secrets, 118 const struct tls13_secret *context); 119 int tls13_update_client_traffic_secret(struct tls13_secrets *secrets); 120 int tls13_update_server_traffic_secret(struct tls13_secrets *secrets); 121 122 /* 123 * Key shares. 124 */ 125 struct tls13_key_share; 126 127 struct tls13_key_share *tls13_key_share_new(uint16_t group_id); 128 struct tls13_key_share *tls13_key_share_new_nid(int nid); 129 void tls13_key_share_free(struct tls13_key_share *ks); 130 131 uint16_t tls13_key_share_group(struct tls13_key_share *ks); 132 int tls13_key_share_peer_pkey(struct tls13_key_share *ks, EVP_PKEY *pkey); 133 int tls13_key_share_generate(struct tls13_key_share *ks); 134 int tls13_key_share_public(struct tls13_key_share *ks, CBB *cbb); 135 int tls13_key_share_peer_public(struct tls13_key_share *ks, uint16_t group, 136 CBS *cbs); 137 int tls13_key_share_derive(struct tls13_key_share *ks, uint8_t **shared_key, 138 size_t *shared_key_len); 139 140 /* 141 * Record Layer. 142 */ 143 struct tls13_record_layer; 144 145 struct tls13_record_layer *tls13_record_layer_new(tls13_read_cb wire_read, 146 tls13_write_cb wire_write, tls13_alert_cb alert_cb, 147 tls13_phh_recv_cb phh_recv_cb, 148 tls13_phh_sent_cb phh_sent_cb, void *cb_arg); 149 void tls13_record_layer_free(struct tls13_record_layer *rl); 150 void tls13_record_layer_allow_ccs(struct tls13_record_layer *rl, int allow); 151 void tls13_record_layer_allow_legacy_alerts(struct tls13_record_layer *rl, int allow); 152 void tls13_record_layer_rbuf(struct tls13_record_layer *rl, CBS *cbs); 153 void tls13_record_layer_set_aead(struct tls13_record_layer *rl, 154 const EVP_AEAD *aead); 155 void tls13_record_layer_set_hash(struct tls13_record_layer *rl, 156 const EVP_MD *hash); 157 void tls13_record_layer_set_legacy_version(struct tls13_record_layer *rl, 158 uint16_t version); 159 void tls13_record_layer_handshake_completed(struct tls13_record_layer *rl); 160 int tls13_record_layer_set_read_traffic_key(struct tls13_record_layer *rl, 161 struct tls13_secret *read_key); 162 int tls13_record_layer_set_write_traffic_key(struct tls13_record_layer *rl, 163 struct tls13_secret *write_key); 164 ssize_t tls13_record_layer_send_pending(struct tls13_record_layer *rl); 165 ssize_t tls13_record_layer_phh(struct tls13_record_layer *rl, CBS *cbs); 166 167 ssize_t tls13_read_handshake_data(struct tls13_record_layer *rl, uint8_t *buf, size_t n); 168 ssize_t tls13_write_handshake_data(struct tls13_record_layer *rl, const uint8_t *buf, 169 size_t n); 170 ssize_t tls13_pending_application_data(struct tls13_record_layer *rl); 171 ssize_t tls13_peek_application_data(struct tls13_record_layer *rl, uint8_t *buf, size_t n); 172 ssize_t tls13_read_application_data(struct tls13_record_layer *rl, uint8_t *buf, size_t n); 173 ssize_t tls13_write_application_data(struct tls13_record_layer *rl, const uint8_t *buf, 174 size_t n); 175 176 ssize_t tls13_send_alert(struct tls13_record_layer *rl, uint8_t alert_desc); 177 178 /* 179 * Handshake Messages. 180 */ 181 struct tls13_handshake_msg; 182 183 struct tls13_handshake_msg *tls13_handshake_msg_new(void); 184 void tls13_handshake_msg_free(struct tls13_handshake_msg *msg); 185 void tls13_handshake_msg_data(struct tls13_handshake_msg *msg, CBS *cbs); 186 int tls13_handshake_msg_set_buffer(struct tls13_handshake_msg *msg, CBS *cbs); 187 uint8_t tls13_handshake_msg_type(struct tls13_handshake_msg *msg); 188 int tls13_handshake_msg_content(struct tls13_handshake_msg *msg, CBS *cbs); 189 int tls13_handshake_msg_start(struct tls13_handshake_msg *msg, CBB *body, 190 uint8_t msg_type); 191 int tls13_handshake_msg_finish(struct tls13_handshake_msg *msg); 192 int tls13_handshake_msg_recv(struct tls13_handshake_msg *msg, 193 struct tls13_record_layer *rl); 194 int tls13_handshake_msg_send(struct tls13_handshake_msg *msg, 195 struct tls13_record_layer *rl); 196 197 struct tls13_handshake_stage { 198 uint8_t hs_type; 199 uint8_t message_number; 200 }; 201 202 struct ssl_handshake_tls13_st; 203 204 struct tls13_error { 205 int code; 206 int subcode; 207 int errnum; 208 const char *file; 209 int line; 210 char *msg; 211 }; 212 213 struct tls13_ctx { 214 struct tls13_error error; 215 216 SSL *ssl; 217 struct ssl_handshake_tls13_st *hs; 218 uint8_t mode; 219 struct tls13_handshake_stage handshake_stage; 220 int handshake_completed; 221 222 int close_notify_sent; 223 int close_notify_recv; 224 225 const EVP_AEAD *aead; 226 const EVP_MD *hash; 227 228 struct tls13_record_layer *rl; 229 struct tls13_handshake_msg *hs_msg; 230 uint8_t key_update_request; 231 uint8_t alert; 232 int phh_count; 233 time_t phh_last_seen; 234 235 tls13_handshake_message_cb handshake_message_sent_cb; 236 tls13_handshake_message_cb handshake_message_recv_cb; 237 }; 238 #ifndef TLS13_PHH_LIMIT_TIME 239 #define TLS13_PHH_LIMIT_TIME 3600 240 #endif 241 #ifndef TLS13_PHH_LIMIT 242 #define TLS13_PHH_LIMIT 100 243 #endif 244 245 struct tls13_ctx *tls13_ctx_new(int mode); 246 void tls13_ctx_free(struct tls13_ctx *ctx); 247 248 const EVP_AEAD *tls13_cipher_aead(const SSL_CIPHER *cipher); 249 const EVP_MD *tls13_cipher_hash(const SSL_CIPHER *cipher); 250 251 /* 252 * Legacy interfaces. 253 */ 254 int tls13_use_legacy_client(struct tls13_ctx *ctx); 255 int tls13_use_legacy_server(struct tls13_ctx *ctx); 256 int tls13_legacy_accept(SSL *ssl); 257 int tls13_legacy_connect(SSL *ssl); 258 int tls13_legacy_return_code(SSL *ssl, ssize_t ret); 259 ssize_t tls13_legacy_wire_read_cb(void *buf, size_t n, void *arg); 260 ssize_t tls13_legacy_wire_write_cb(const void *buf, size_t n, void *arg); 261 int tls13_legacy_pending(const SSL *ssl); 262 int tls13_legacy_read_bytes(SSL *ssl, int type, unsigned char *buf, int len, 263 int peek); 264 int tls13_legacy_write_bytes(SSL *ssl, int type, const void *buf, int len); 265 int tls13_legacy_shutdown(SSL *ssl); 266 267 /* 268 * Message Types - RFC 8446, Section B.3. 269 * 270 * Values listed as "_RESERVED" were used in previous versions of TLS and are 271 * listed here for completeness. TLS 1.3 implementations MUST NOT send them but 272 * might receive them from older TLS implementations. 273 */ 274 #define TLS13_MT_HELLO_REQUEST_RESERVED 0 275 #define TLS13_MT_CLIENT_HELLO 1 276 #define TLS13_MT_SERVER_HELLO 2 277 #define TLS13_MT_HELLO_VERIFY_REQUEST_RESERVED 3 278 #define TLS13_MT_NEW_SESSION_TICKET 4 279 #define TLS13_MT_END_OF_EARLY_DATA 5 280 #define TLS13_MT_HELLO_RETRY_REQUEST_RESERVED 6 281 #define TLS13_MT_ENCRYPTED_EXTENSIONS 8 282 #define TLS13_MT_CERTIFICATE 11 283 #define TLS13_MT_SERVER_KEY_EXCHANGE_RESERVED 12 284 #define TLS13_MT_CERTIFICATE_REQUEST 13 285 #define TLS13_MT_SERVER_HELLO_DONE_RESERVED 14 286 #define TLS13_MT_CERTIFICATE_VERIFY 15 287 #define TLS13_MT_CLIENT_KEY_EXCHANGE_RESERVED 16 288 #define TLS13_MT_FINISHED 20 289 #define TLS13_MT_CERTIFICATE_URL_RESERVED 21 290 #define TLS13_MT_CERTIFICATE_STATUS_RESERVED 22 291 #define TLS13_MT_SUPPLEMENTAL_DATA_RESERVED 23 292 #define TLS13_MT_KEY_UPDATE 24 293 #define TLS13_MT_MESSAGE_HASH 254 294 295 int tls13_handshake_msg_record(struct tls13_ctx *ctx); 296 int tls13_handshake_perform(struct tls13_ctx *ctx); 297 298 int tls13_client_init(struct tls13_ctx *ctx); 299 int tls13_server_init(struct tls13_ctx *ctx); 300 int tls13_client_connect(struct tls13_ctx *ctx); 301 int tls13_server_accept(struct tls13_ctx *ctx); 302 303 int tls13_client_hello_send(struct tls13_ctx *ctx, CBB *cbb); 304 int tls13_client_hello_sent(struct tls13_ctx *ctx); 305 int tls13_client_hello_recv(struct tls13_ctx *ctx, CBS *cbs); 306 int tls13_client_hello_retry_send(struct tls13_ctx *ctx, CBB *cbb); 307 int tls13_client_hello_retry_recv(struct tls13_ctx *ctx, CBS *cbs); 308 int tls13_client_end_of_early_data_send(struct tls13_ctx *ctx, CBB *cbb); 309 int tls13_client_end_of_early_data_recv(struct tls13_ctx *ctx, CBS *cbs); 310 int tls13_client_certificate_send(struct tls13_ctx *ctx, CBB *cbb); 311 int tls13_client_certificate_recv(struct tls13_ctx *ctx, CBS *cbs); 312 int tls13_client_certificate_verify_send(struct tls13_ctx *ctx, CBB *cbb); 313 int tls13_client_certificate_verify_recv(struct tls13_ctx *ctx, CBS *cbs); 314 int tls13_client_finished_recv(struct tls13_ctx *ctx, CBS *cbs); 315 int tls13_client_finished_send(struct tls13_ctx *ctx, CBB *cbb); 316 int tls13_client_finished_sent(struct tls13_ctx *ctx); 317 int tls13_server_hello_recv(struct tls13_ctx *ctx, CBS *cbs); 318 int tls13_server_hello_send(struct tls13_ctx *ctx, CBB *cbb); 319 int tls13_server_hello_sent(struct tls13_ctx *ctx); 320 int tls13_server_hello_retry_request_recv(struct tls13_ctx *ctx, CBS *cbs); 321 int tls13_server_hello_retry_request_send(struct tls13_ctx *ctx, CBB *cbb); 322 int tls13_server_encrypted_extensions_recv(struct tls13_ctx *ctx, CBS *cbs); 323 int tls13_server_encrypted_extensions_send(struct tls13_ctx *ctx, CBB *cbb); 324 int tls13_server_certificate_recv(struct tls13_ctx *ctx, CBS *cbs); 325 int tls13_server_certificate_send(struct tls13_ctx *ctx, CBB *cbb); 326 int tls13_server_certificate_request_recv(struct tls13_ctx *ctx, CBS *cbs); 327 int tls13_server_certificate_request_send(struct tls13_ctx *ctx, CBB *cbb); 328 int tls13_server_certificate_verify_send(struct tls13_ctx *ctx, CBB *cbb); 329 int tls13_server_certificate_verify_recv(struct tls13_ctx *ctx, CBS *cbs); 330 int tls13_server_finished_recv(struct tls13_ctx *ctx, CBS *cbs); 331 int tls13_server_finished_send(struct tls13_ctx *ctx, CBB *cbb); 332 int tls13_server_finished_sent(struct tls13_ctx *ctx); 333 334 void tls13_error_clear(struct tls13_error *error); 335 336 int tls13_cert_add(CBB *cbb, X509 *cert); 337 int tls13_synthetic_handshake_message(struct tls13_ctx *ctx); 338 339 int tls13_error_set(struct tls13_error *error, int code, int subcode, 340 const char *file, int line, const char *fmt, ...); 341 int tls13_error_setx(struct tls13_error *error, int code, int subcode, 342 const char *file, int line, const char *fmt, ...); 343 344 #define tls13_set_error(ctx, code, subcode, fmt, ...) \ 345 tls13_error_set(&(ctx)->error, (code), (subcode), __FILE__, __LINE__, \ 346 (fmt), __VA_ARGS__) 347 #define tls13_set_errorx(ctx, code, subcode, fmt, ...) \ 348 tls13_error_setx(&(ctx)->error, (code), (subcode), __FILE__, __LINE__, \ 349 (fmt), __VA_ARGS__) 350 351 extern const uint8_t tls13_downgrade_12[8]; 352 extern const uint8_t tls13_downgrade_11[8]; 353 extern const uint8_t tls13_hello_retry_request_hash[32]; 354 extern const uint8_t tls13_cert_verify_pad[64]; 355 extern const uint8_t tls13_cert_client_verify_context[]; 356 extern const uint8_t tls13_cert_server_verify_context[]; 357 358 __END_HIDDEN_DECLS 359 360 #endif 361