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