Update the warnings on split handshakes and handshake hints Handshake hints work fine with TLS 1.2 resumption now. Also split handshakes is really really dangerous, and I think hints has survived long enough that we can just declare it the successor. Change-Id: Ib5fe5e1b030034b853a96c3404608c56d7b7a7c7 Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/62925 Reviewed-by: Adam Langley <agl@google.com> Auto-Submit: David Benjamin <davidben@google.com> Commit-Queue: Adam Langley <agl@google.com>
diff --git a/include/openssl/ssl.h b/include/openssl/ssl.h index 995d05e..e8ef56e 100644 --- a/include/openssl/ssl.h +++ b/include/openssl/ssl.h
@@ -4056,12 +4056,15 @@ // Handshake hints. // -// *** EXPERIMENTAL — DO NOT USE WITHOUT CHECKING *** +// WARNING: Contact the BoringSSL team before using this API. While this +// mechanism was designed to gracefully recover from version skew and +// configuration mismatch, splitting a single TLS server into multiple services +// is complex. // // Some server deployments make asynchronous RPC calls in both ClientHello // dispatch and private key operations. In TLS handshakes where the private key // operation occurs in the first round-trip, this results in two consecutive RPC -// round-trips. Handshake hints allow the RPC service to predicte a signature. +// round-trips. Handshake hints allow the RPC service to predict a signature. // If correctly predicted, this can skip the second RPC call. // // First, the server installs a certificate selection callback (see @@ -4087,10 +4090,6 @@ // the private key in later round-trips, such as TLS 1.3 HelloRetryRequest. In // those cases, BoringSSL will not predict a signature as there is no benefit. // Callers must allow for handshakes to complete without a predicted signature. -// -// Handshake hints are supported for TLS 1.3 and partially supported for -// TLS 1.2. TLS 1.2 resumption handshakes are not yet fully hinted. They will -// still work, but may not be as efficient. // SSL_serialize_capabilities writes an opaque byte string to |out| describing // some of |ssl|'s capabilities. It returns one on success and zero on error. @@ -5532,10 +5531,18 @@ BORINGSSL_MAKE_UP_REF(SSL_SESSION, SSL_SESSION_up_ref) -// *** EXPERIMENTAL — DO NOT USE WITHOUT CHECKING *** +// *** DEPRECATED EXPERIMENT — DO NOT USE *** // // Split handshakes. // +// WARNING: This mechanism is deprecated and should not be used. It is very +// fragile and difficult to use correctly. The relationship between +// configuration options across the two halves is ill-defined and not +// self-consistent. Additionally, version skew across the two halves risks +// unusual behavior and connection failure. New development should use the +// handshake hints API. Existing deployments should migrate to handshake hints +// to reduce the risk of service outages. +// // 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.