Add initial, experimental support for split handshakes.
Split handshakes allows the handshaking of a TLS connection to be
performed remotely. This encompasses not just the private-key and ticket
operations – support for that was already available – but also things
such as selecting the certificates and cipher suites.
The the comment block in ssl.h for details. This is highly experimental
and will change significantly before its settled.
Change-Id: I337bdfa4c3262169e9b79dd4e70b57f0d380fcad
Reviewed-on: https://boringssl-review.googlesource.com/25387
Reviewed-by: Adam Langley <agl@google.com>
Commit-Queue: Adam Langley <agl@google.com>
diff --git a/include/openssl/ssl.h b/include/openssl/ssl.h
index 17709bc..a1b6fa7 100644
--- a/include/openssl/ssl.h
+++ b/include/openssl/ssl.h
@@ -534,6 +534,8 @@
// See also |SSL_CTX_set_custom_verify|.
#define SSL_ERROR_WANT_CERTIFICATE_VERIFY 16
+#define SSL_ERROR_HANDOFF 17
+
// SSL_set_mtu sets the |ssl|'s MTU in DTLS to |mtu|. It returns one on success
// and zero on failure.
OPENSSL_EXPORT int SSL_set_mtu(SSL *ssl, unsigned mtu);
@@ -3918,6 +3920,7 @@
#define SSL_PENDING_TICKET 10
#define SSL_EARLY_DATA_REJECTED 11
#define SSL_CERTIFICATE_VERIFY 12
+#define SSL_HANDOFF 13
// SSL_want returns one of the above values to determine what the most recent
// operation on |ssl| was blocked on. Use |SSL_get_error| instead.
@@ -4453,6 +4456,53 @@
Span<uint8_t> out, Span<uint8_t> out_suffix,
Span<const uint8_t> in);
+
+// *** EXPERIMENTAL — DO NOT USE WITHOUT CHECKING ***
+//
+// Split handshakes.
+//
+// Split handshakes allows the handshake part of a TLS connection to be
+// performed in a different process (or on a different machine) than the data
+// exchange. This only applies to servers.
+//
+// In the first part of a split handshake, an |SSL| (where the |SSL_CTX| has
+// been configured with |SSL_CTX_set_handoff_mode|) is used normally. Once the
+// ClientHello message has been received, the handshake will stop and
+// |SSL_get_error| will indicate |SSL_ERROR_HANDOFF|. At this point (and only
+// at this point), |SSL_serialize_handoff| can be called to write the “handoff”
+// state of the connection.
+//
+// Elsewhere, a fresh |SSL| can be used with |SSL_apply_handoff| to continue
+// the connection. The connection from the client is fed into this |SSL| until
+// the handshake completes normally. At this point (and only at this point),
+// |SSL_serialize_handback| can be called to serialize the result of the
+// handshake.
+//
+// Back at the first location, a fresh |SSL| can be used with
+// |SSL_apply_handback|. Then the client's connection can be processed mostly
+// as normal.
+//
+// Lastly, when a connection is in the handoff state, whether or not
+// |SSL_serialize_handoff| is called, |SSL_decline_handoff| will move it back
+// into a normal state where the connection can procede without impact.
+//
+// WARNING: Currently only works with TLS 1.0–1.2.
+// WARNING: The serialisation formats are not yet stable: version skew may be
+// fatal.
+// WARNING: The handback data contains sensitive key material and must be
+// protected.
+// WARNING: Some calls on the final |SSL| will not work. Just as an example,
+// calls like |SSL_get0_session_id_context| and |SSL_get_privatekey| won't
+// work because the certificate used for handshaking isn't available.
+// WARNING: |SSL_apply_handoff| may trigger “msg” callback calls.
+
+OPENSSL_EXPORT void SSL_CTX_set_handoff_mode(SSL_CTX *ctx, bool on);
+OPENSSL_EXPORT bool SSL_serialize_handoff(const SSL *ssl, CBB *out);
+OPENSSL_EXPORT bool SSL_decline_handoff(SSL *ssl);
+OPENSSL_EXPORT bool SSL_apply_handoff(SSL *ssl, Span<const uint8_t> handoff);
+OPENSSL_EXPORT bool SSL_serialize_handback(const SSL *ssl, CBB *out);
+OPENSSL_EXPORT bool SSL_apply_handback(SSL *ssl, Span<const uint8_t> handback);
+
} // namespace bssl
} // extern C++
diff --git a/ssl/CMakeLists.txt b/ssl/CMakeLists.txt
index 35288e1..3eab0b5 100644
--- a/ssl/CMakeLists.txt
+++ b/ssl/CMakeLists.txt
@@ -11,6 +11,7 @@
d1_srtp.cc
dtls_method.cc
dtls_record.cc
+ handoff.cc
handshake.cc
handshake_client.cc
handshake_server.cc
diff --git a/ssl/handoff.cc b/ssl/handoff.cc
new file mode 100644
index 0000000..b19d443
--- /dev/null
+++ b/ssl/handoff.cc
@@ -0,0 +1,285 @@
+/* Copyright (c) 2018, Google Inc.
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+ * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+ * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+ * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
+
+#include <openssl/ssl.h>
+
+#include <openssl/bytestring.h>
+
+#include "internal.h"
+
+
+namespace bssl {
+
+constexpr int kHandoffVersion = 0;
+constexpr int kHandbackVersion = 0;
+
+bool SSL_serialize_handoff(const SSL *ssl, CBB *out) {
+ const SSL3_STATE *const s3 = ssl->s3;
+ if (!ssl->server ||
+ s3->hs == nullptr ||
+ s3->rwstate != SSL_HANDOFF) {
+ return false;
+ }
+
+ CBB seq;
+ Span<const uint8_t> transcript = s3->hs->transcript.buffer();
+ if (!CBB_add_asn1(out, &seq, CBS_ASN1_SEQUENCE) ||
+ !CBB_add_asn1_uint64(&seq, kHandoffVersion) ||
+ !CBB_add_asn1_octet_string(&seq, transcript.data(), transcript.size()) ||
+ !CBB_add_asn1_octet_string(&seq,
+ reinterpret_cast<uint8_t *>(s3->hs_buf->data),
+ s3->hs_buf->length) ||
+ !CBB_flush(out)) {
+ return false;
+ }
+
+ return true;
+}
+
+bool SSL_decline_handoff(SSL *ssl) {
+ const SSL3_STATE *const s3 = ssl->s3;
+ if (!ssl->server ||
+ s3->hs == nullptr ||
+ s3->rwstate != SSL_HANDOFF) {
+ return false;
+ }
+
+ ssl->handoff = false;
+ return true;
+}
+
+bool SSL_apply_handoff(SSL *ssl, Span<const uint8_t> handoff) {
+ if (ssl->method->is_dtls) {
+ return false;
+ }
+
+ CBS seq, handoff_cbs(handoff);
+ uint64_t handoff_version;
+ if (!CBS_get_asn1(&handoff_cbs, &seq, CBS_ASN1_SEQUENCE) ||
+ !CBS_get_asn1_uint64(&seq, &handoff_version) ||
+ handoff_version != kHandoffVersion) {
+ return false;
+ }
+
+ CBS transcript, hs_buf;
+ if (!CBS_get_asn1(&seq, &transcript, CBS_ASN1_OCTETSTRING) ||
+ !CBS_get_asn1(&seq, &hs_buf, CBS_ASN1_OCTETSTRING)) {
+ return false;
+ }
+
+ SSL_set_accept_state(ssl);
+
+ SSL3_STATE *const s3 = ssl->s3;
+ s3->v2_hello_done = true;
+ s3->has_message = true;
+
+ s3->hs_buf.reset(BUF_MEM_new());
+ if (!s3->hs_buf ||
+ !BUF_MEM_append(s3->hs_buf.get(), CBS_data(&hs_buf), CBS_len(&hs_buf))) {
+ return false;
+ }
+
+ if (CBS_len(&transcript) != 0) {
+ s3->hs->transcript.Update(transcript);
+ s3->is_v2_hello = true;
+ ssl_do_msg_callback(ssl, 0 /* read */, 0 /* V2ClientHello */, transcript);
+ }
+
+ return true;
+}
+
+bool SSL_serialize_handback(const SSL *ssl, CBB *out) {
+ if (!ssl->server ||
+ !ssl->s3->initial_handshake_complete ||
+ ssl->method->is_dtls ||
+ ssl->version < TLS1_VERSION) {
+ return false;
+ }
+
+ const SSL3_STATE *const s3 = ssl->s3;
+ size_t hostname_len = 0;
+ if (s3->hostname) {
+ hostname_len = strlen(s3->hostname.get());
+ }
+
+ size_t iv_len = 0;
+ const uint8_t *read_iv = nullptr, *write_iv = nullptr;
+ if (ssl->version == TLS1_VERSION &&
+ SSL_CIPHER_is_block_cipher(s3->aead_read_ctx->cipher()) &&
+ (!s3->aead_read_ctx->GetIV(&read_iv, &iv_len) ||
+ !s3->aead_write_ctx->GetIV(&write_iv, &iv_len))) {
+ return false;
+ }
+
+ CBB seq;
+ if (!CBB_add_asn1(out, &seq, CBS_ASN1_SEQUENCE) ||
+ !CBB_add_asn1_uint64(&seq, kHandbackVersion) ||
+ !CBB_add_asn1_uint64(&seq, ssl->version) ||
+ !CBB_add_asn1_uint64(&seq, ssl->conf_max_version) ||
+ !CBB_add_asn1_uint64(&seq, ssl->conf_min_version) ||
+ !CBB_add_asn1_uint64(&seq, ssl->max_send_fragment) ||
+ !CBB_add_asn1_octet_string(&seq, s3->read_sequence,
+ sizeof(s3->read_sequence)) ||
+ !CBB_add_asn1_octet_string(&seq, s3->write_sequence,
+ sizeof(s3->write_sequence)) ||
+ !CBB_add_asn1_octet_string(&seq, s3->server_random,
+ sizeof(s3->server_random)) ||
+ !CBB_add_asn1_octet_string(&seq, s3->client_random,
+ sizeof(s3->client_random)) ||
+ !CBB_add_asn1_octet_string(&seq, read_iv, iv_len) ||
+ !CBB_add_asn1_octet_string(&seq, write_iv, iv_len) ||
+ !CBB_add_asn1_bool(&seq, s3->session_reused) ||
+ !CBB_add_asn1_bool(&seq, s3->send_connection_binding) ||
+ !CBB_add_asn1_bool(&seq, s3->tlsext_channel_id_valid) ||
+ !ssl_session_serialize(s3->established_session.get(), &seq) ||
+ !CBB_add_asn1_octet_string(&seq, s3->next_proto_negotiated.data(),
+ s3->next_proto_negotiated.size()) ||
+ !CBB_add_asn1_octet_string(&seq, s3->alpn_selected.data(),
+ s3->alpn_selected.size()) ||
+ !CBB_add_asn1_octet_string(
+ &seq, reinterpret_cast<uint8_t *>(s3->hostname.get()),
+ hostname_len) ||
+ !CBB_add_asn1_octet_string(&seq, s3->tlsext_channel_id,
+ sizeof(s3->tlsext_channel_id)) ||
+ !CBB_add_asn1_uint64(&seq, ssl->options) ||
+ !CBB_add_asn1_uint64(&seq, ssl->mode) ||
+ !CBB_add_asn1_uint64(&seq, ssl->max_cert_list) ||
+ !CBB_add_asn1_bool(&seq, ssl->quiet_shutdown) ||
+ !CBB_add_asn1_bool(&seq, ssl->tlsext_channel_id_enabled) ||
+ !CBB_add_asn1_bool(&seq, ssl->retain_only_sha256_of_client_certs) ||
+ !CBB_flush(out)) {
+ return false;
+ }
+
+ return true;
+}
+
+bool SSL_apply_handback(SSL *ssl, Span<const uint8_t> handback) {
+ if (ssl->do_handshake != nullptr ||
+ ssl->method->is_dtls) {
+ return false;
+ }
+
+ SSL3_STATE *const s3 = ssl->s3;
+ uint64_t handback_version, version, conf_max_version, conf_min_version,
+ max_send_fragment, options, mode, max_cert_list;
+ CBS seq, read_seq, write_seq, server_rand, client_rand, read_iv, write_iv,
+ next_proto, alpn, hostname, channel_id;
+ int session_reused, send_connection_binding, channel_id_valid,
+ quiet_shutdown, channel_id_enabled, retain_only_sha256;
+
+ CBS handback_cbs(handback);
+ if (!CBS_get_asn1(&handback_cbs, &seq, CBS_ASN1_SEQUENCE) ||
+ !CBS_get_asn1_uint64(&seq, &handback_version) ||
+ handback_version != kHandbackVersion) {
+ return false;
+ }
+
+ if (!CBS_get_asn1_uint64(&seq, &version) ||
+ !CBS_get_asn1_uint64(&seq, &conf_max_version) ||
+ !CBS_get_asn1_uint64(&seq, &conf_min_version) ||
+ !CBS_get_asn1_uint64(&seq, &max_send_fragment) ||
+ !CBS_get_asn1(&seq, &read_seq, CBS_ASN1_OCTETSTRING) ||
+ CBS_len(&read_seq) != sizeof(s3->read_sequence) ||
+ !CBS_get_asn1(&seq, &write_seq, CBS_ASN1_OCTETSTRING) ||
+ CBS_len(&write_seq) != sizeof(s3->write_sequence) ||
+ !CBS_get_asn1(&seq, &server_rand, CBS_ASN1_OCTETSTRING) ||
+ CBS_len(&server_rand) != sizeof(s3->server_random) ||
+ !CBS_copy_bytes(&server_rand, s3->server_random,
+ sizeof(s3->server_random)) ||
+ !CBS_get_asn1(&seq, &client_rand, CBS_ASN1_OCTETSTRING) ||
+ CBS_len(&client_rand) != sizeof(s3->client_random) ||
+ !CBS_copy_bytes(&client_rand, s3->client_random,
+ sizeof(s3->client_random)) ||
+ !CBS_get_asn1(&seq, &read_iv, CBS_ASN1_OCTETSTRING) ||
+ !CBS_get_asn1(&seq, &write_iv, CBS_ASN1_OCTETSTRING) ||
+ !CBS_get_asn1_bool(&seq, &session_reused) ||
+ !CBS_get_asn1_bool(&seq, &send_connection_binding) ||
+ !CBS_get_asn1_bool(&seq, &channel_id_valid)) {
+ return false;
+ }
+
+ s3->established_session =
+ SSL_SESSION_parse(&seq, ssl->ctx->x509_method, ssl->ctx->pool);
+
+ if (!s3->established_session ||
+ !CBS_get_asn1(&seq, &next_proto, CBS_ASN1_OCTETSTRING) ||
+ !CBS_get_asn1(&seq, &alpn, CBS_ASN1_OCTETSTRING) ||
+ !CBS_get_asn1(&seq, &hostname, CBS_ASN1_OCTETSTRING) ||
+ !CBS_get_asn1(&seq, &channel_id, CBS_ASN1_OCTETSTRING) ||
+ CBS_len(&channel_id) != sizeof(s3->tlsext_channel_id) ||
+ !CBS_copy_bytes(&channel_id, s3->tlsext_channel_id,
+ sizeof(s3->tlsext_channel_id)) ||
+ !CBS_get_asn1_uint64(&seq, &options) ||
+ !CBS_get_asn1_uint64(&seq, &mode) ||
+ !CBS_get_asn1_uint64(&seq, &max_cert_list) ||
+ !CBS_get_asn1_bool(&seq, &quiet_shutdown) ||
+ !CBS_get_asn1_bool(&seq, &channel_id_enabled) ||
+ !CBS_get_asn1_bool(&seq, &retain_only_sha256)) {
+ return false;
+ }
+
+ ssl->version = version;
+ ssl->conf_max_version = conf_max_version;
+ ssl->conf_min_version = conf_min_version;
+ ssl->max_send_fragment = max_send_fragment;
+ ssl->do_handshake = ssl_server_handshake;
+ ssl->server = true;
+ ssl->options = options;
+ ssl->mode = mode;
+ ssl->max_cert_list = max_cert_list;
+
+ s3->hs.reset();
+ s3->have_version = true;
+ s3->initial_handshake_complete = true;
+ s3->session_reused = session_reused;
+ s3->send_connection_binding = send_connection_binding;
+ s3->tlsext_channel_id_valid = channel_id_valid;
+ s3->next_proto_negotiated.CopyFrom(next_proto);
+ s3->alpn_selected.CopyFrom(alpn);
+
+ const size_t hostname_len = CBS_len(&hostname);
+ if (hostname_len == 0) {
+ s3->hostname.reset();
+ } else {
+ char *hostname_str = nullptr;
+ if (!CBS_strdup(&hostname, &hostname_str)) {
+ return false;
+ }
+ s3->hostname.reset(hostname_str);
+ }
+
+ ssl->quiet_shutdown = quiet_shutdown;
+ ssl->tlsext_channel_id_enabled = channel_id_enabled;
+ ssl->retain_only_sha256_of_client_certs = retain_only_sha256;
+
+ Array<uint8_t> key_block;
+ if (!tls1_configure_aead(ssl, evp_aead_open, &key_block,
+ s3->established_session->cipher, read_iv) ||
+ !tls1_configure_aead(ssl, evp_aead_seal, &key_block,
+ s3->established_session->cipher, write_iv)) {
+ return false;
+ }
+
+ if (!CBS_copy_bytes(&read_seq, s3->read_sequence,
+ sizeof(s3->read_sequence)) ||
+ !CBS_copy_bytes(&write_seq, s3->write_sequence,
+ sizeof(s3->write_sequence))) {
+ return false;
+ }
+
+ return true;
+}
+
+} // namespace bssl
diff --git a/ssl/handshake.cc b/ssl/handshake.cc
index 43afc6c..6432424 100644
--- a/ssl/handshake.cc
+++ b/ssl/handshake.cc
@@ -560,6 +560,11 @@
hs->wait = ssl_hs_ok;
return -1;
+ case ssl_hs_handoff:
+ ssl->s3->rwstate = SSL_HANDOFF;
+ hs->wait = ssl_hs_ok;
+ return -1;
+
case ssl_hs_x509_lookup:
ssl->s3->rwstate = SSL_X509_LOOKUP;
hs->wait = ssl_hs_ok;
diff --git a/ssl/handshake_server.cc b/ssl/handshake_server.cc
index bcbd7e2..fa8a241 100644
--- a/ssl/handshake_server.cc
+++ b/ssl/handshake_server.cc
@@ -441,6 +441,10 @@
return ssl_hs_error;
}
+ if (ssl->handoff) {
+ return ssl_hs_handoff;
+ }
+
SSL_CLIENT_HELLO client_hello;
if (!ssl_client_hello_init(ssl, &client_hello, msg)) {
OPENSSL_PUT_ERROR(SSL, SSL_R_DECODE_ERROR);
diff --git a/ssl/internal.h b/ssl/internal.h
index f2b2f6d..937c9fe 100644
--- a/ssl/internal.h
+++ b/ssl/internal.h
@@ -1257,6 +1257,7 @@
ssl_hs_read_message,
ssl_hs_flush,
ssl_hs_certificate_selection_pending,
+ ssl_hs_handoff,
ssl_hs_x509_lookup,
ssl_hs_channel_id_lookup,
ssl_hs_private_key_operation,
@@ -2173,6 +2174,11 @@
// false_start_allowed_without_alpn is whether False Start (if
// |SSL_MODE_ENABLE_FALSE_START| is enabled) is allowed without ALPN.
bool false_start_allowed_without_alpn:1;
+
+ // handoff indicates that a server should stop after receiving the
+ // ClientHello and pause the handshake in such a way that |SSL_get_error|
+ // returns |SSL_HANDOFF|.
+ bool handoff:1;
};
// An ssl_shutdown_t describes the shutdown state of one end of the connection,
@@ -2537,8 +2543,8 @@
// session info
- // client cert?
- // This is used to hold the server certificate used
+ // This is used to hold the local certificate used (i.e. the server
+ // certificate for a server or the client certificate for a client).
CERT *cert;
// initial_timeout_duration_ms is the default DTLS timeout duration in
@@ -2658,6 +2664,12 @@
// hash of the peer's certificate and then discard it to save memory and
// session space. Only effective on the server side.
bool retain_only_sha256_of_client_certs:1;
+
+ // handoff indicates that a server should stop after receiving the
+ // ClientHello and pause the handshake in such a way that |SSL_get_error|
+ // returns |SSL_HANDOFF|. This is copied in |SSL_new| from the |SSL_CTX|
+ // element of the same name and may be cleared if the handoff is declined.
+ bool handoff:1;
};
// From draft-ietf-tls-tls13-18, used in determining PSK modes.
@@ -2847,6 +2859,16 @@
void dtls1_next_message(SSL *ssl);
int dtls1_dispatch_alert(SSL *ssl);
+// tls1_configure_aead configures either the read or write direction AEAD (as
+// determined by |direction|) using the keys generated by the TLS KDF. The
+// |key_block_cache| argument is used to store the generated key block, if
+// empty. Otherwise it's assumed that the key block is already contained within
+// it. Returns one on success or zero on error.
+int tls1_configure_aead(SSL *ssl, evp_aead_direction_t direction,
+ Array<uint8_t> *key_block_cache,
+ const SSL_CIPHER *cipher,
+ Span<const uint8_t> iv_override);
+
int tls1_change_cipher_state(SSL_HANDSHAKE *hs, evp_aead_direction_t direction);
int tls1_generate_master_secret(SSL_HANDSHAKE *hs, uint8_t *out,
Span<const uint8_t> premaster);
diff --git a/ssl/ssl_lib.cc b/ssl/ssl_lib.cc
index d05e613..2fd3beb 100644
--- a/ssl/ssl_lib.cc
+++ b/ssl/ssl_lib.cc
@@ -465,6 +465,10 @@
#endif
}
+void SSL_CTX_set_handoff_mode(SSL_CTX *ctx, bool on) {
+ ctx->handoff = on;
+}
+
} // namespace bssl
using namespace bssl;
@@ -736,6 +740,7 @@
ssl->signed_cert_timestamps_enabled = ctx->signed_cert_timestamps_enabled;
ssl->ocsp_stapling_enabled = ctx->ocsp_stapling_enabled;
+ ssl->handoff = ctx->handoff;
return ssl;
@@ -1269,6 +1274,9 @@
case SSL_CERTIFICATE_SELECTION_PENDING:
return SSL_ERROR_PENDING_CERTIFICATE;
+ case SSL_HANDOFF:
+ return SSL_ERROR_HANDOFF;
+
case SSL_READING: {
BIO *bio = SSL_get_rbio(ssl);
if (BIO_should_read(bio)) {
diff --git a/ssl/t1_enc.cc b/ssl/t1_enc.cc
index d1fb710..5947627 100644
--- a/ssl/t1_enc.cc
+++ b/ssl/t1_enc.cc
@@ -239,10 +239,10 @@
return true;
}
-static int tls1_configure_aead(SSL *ssl, evp_aead_direction_t direction,
- Array<uint8_t> *key_block_cache,
- const SSL_CIPHER *cipher,
- Span<const uint8_t> iv_override) {
+int tls1_configure_aead(SSL *ssl, evp_aead_direction_t direction,
+ Array<uint8_t> *key_block_cache,
+ const SSL_CIPHER *cipher,
+ Span<const uint8_t> iv_override) {
size_t mac_secret_len, key_len, iv_len;
if (!get_key_block_lengths(ssl, &mac_secret_len, &key_len, &iv_len, cipher)) {
return 0;
