crypto/tls: add server-side ECH

Adds support for server-side ECH.

We make a couple of implementation decisions that are not completely
in-line with the spec. In particular, we don't enforce that the SNI
matches the ECHConfig public_name, and we implement a hybrid
shared/backend mode (rather than shared or split mode, as described in
Section 7). Both of these match the behavior of BoringSSL.

The hybrid server mode will either act as a shared mode server, where-in
the server accepts "outer" client hellos and unwraps them before
processing the "inner" hello, or accepts bare "inner" hellos initially.
This lets the server operate either transparently as a shared mode
server, or a backend server, in Section 7 terminology. This seems like
the best implementation choice for a TLS library.

Fixes #68500

Change-Id: Ife69db7c1886610742e95e76b0ca92587e6d7ed4
Reviewed-on: https://go-review.googlesource.com/c/go/+/623576
Reviewed-by: Filippo Valsorda <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>
Reviewed-by: Daniel McCarney <[email protected]>
Auto-Submit: Roland Shoemaker <[email protected]>
Reviewed-by: Dmitri Shuralyov <[email protected]>

Author: rolandshoemaker

api/next/68500.txt

@@ -0,0 +1,5 @@
+pkg crypto/tls, type Config struct, EncryptedClientHelloKeys []EncryptedClientHelloKey #68500
+pkg crypto/tls, type EncryptedClientHelloKey struct #68500
+pkg crypto/tls, type EncryptedClientHelloKey struct, Config []uint8 #68500
+pkg crypto/tls, type EncryptedClientHelloKey struct, PrivateKey []uint8 #68500
+pkg crypto/tls, type EncryptedClientHelloKey struct, SendAsRetry bool #68500

doc/next/6-stdlib/99-minor/crypto/tls/68500.md

@@ -0,0 +1,2 @@
+The TLS server now supports Encrypted Client Hello (ECH). This feature can be
+enabled by populating the [Config.EncryptedClientHelloKeys] field.

src/crypto/tls/bogo_config.json

@@ -12,7 +12,7 @@
 
         "TLS-ECH-Client-Reject-ResumeInnerSession-TLS12": "We won't attempt to negotiate 1.2 if ECH is enabled (we could possibly test this if we had the ability to indicate not to send ECH on resumption?)",
 
-        "TLS-ECH-Client-Reject-EarlyDataRejected": "We don't support switiching out ECH configs with this level of granularity",
+        "TLS-ECH-Client-Reject-EarlyDataRejected": "Go does not support early (0-RTT) data",
 
         "TLS-ECH-Client-NoNPN": "We don't support NPN",
 
@@ -30,8 +30,12 @@
         "TLS-ECH-Client-NoSupportedConfigs": "We don't support fallback to cleartext when there are no valid ECH configs",
         "TLS-ECH-Client-SkipInvalidPublicName": "We don't support fallback to cleartext when there are no valid ECH configs",
 
+        "TLS-ECH-Server-EarlyData": "Go does not support early (0-RTT) data",
+        "TLS-ECH-Server-EarlyDataRejected": "Go does not support early (0-RTT) data",
+
+        "CurveTest-Client-Kyber-TLS13": "Temporarily disabled since the curve ID is not exposed and it cannot be correctly configured",
+        "CurveTest-Server-Kyber-TLS13": "Temporarily disabled since the curve ID is not exposed and it cannot be correctly configured",
 
-        "*ECH-Server*": "no ECH server support",
         "SendV2ClientHello*": "We don't support SSLv2",
         "*QUIC*": "No QUIC support",
         "Compliance-fips*": "No FIPS",
@@ -229,5 +233,11 @@
         "EarlyData-UnexpectedHandshake-Server-TLS13": "TODO: first pass, this should be fixed",
         "EarlyData-CipherMismatch-Client-TLS13": "TODO: first pass, this should be fixed",
         "Resume-Server-UnofferedCipher-TLS13": "TODO: first pass, this should be fixed"
-    }
+    },
+    "AllCurves": [
+        23,
+        24,
+        25,
+        29
+    ]
 }

src/crypto/tls/bogo_shim_test.go

@@ -76,6 +76,9 @@ var (
 	onResumeExpectECHAccepted  = flag.Bool("on-resume-expect-ech-accept", false, "")
 	_                          = flag.Bool("on-resume-expect-no-ech-name-override", false, "")
 	expectedServerName         = flag.String("expect-server-name", "", "")
+	echServerConfig            = flagStringSlice("ech-server-config", "")
+	echServerKey               = flagStringSlice("ech-server-key", "")
+	echServerRetryConfig       = flagStringSlice("ech-is-retry-config", "")
 
 	expectSessionMiss = flag.Bool("expect-session-miss", false, "")
 
@@ -105,12 +108,12 @@ func flagStringSlice(name, usage string) *stringSlice {
 	return f
 }
 
-func (saf stringSlice) String() string {
-	return strings.Join(saf, ",")
+func (saf *stringSlice) String() string {
+	return strings.Join(*saf, ",")
 }
 
-func (saf stringSlice) Set(s string) error {
-	saf = append(saf, s)
+func (saf *stringSlice) Set(s string) error {
+	*saf = append(*saf, s)
 	return nil
 }
 
@@ -248,6 +251,29 @@ func bogoShim() {
 		}
 	}
 
+	if len(*echServerConfig) != 0 {
+		if len(*echServerConfig) != len(*echServerKey) || len(*echServerConfig) != len(*echServerRetryConfig) {
+			log.Fatal("-ech-server-config, -ech-server-key, and -ech-is-retry-config mismatch")
+		}
+
+		for i, c := range *echServerConfig {
+			configBytes, err := base64.StdEncoding.DecodeString(c)
+			if err != nil {
+				log.Fatalf("parse ech-server-config err: %s", err)
+			}
+			privBytes, err := base64.StdEncoding.DecodeString((*echServerKey)[i])
+			if err != nil {
+				log.Fatalf("parse ech-server-key err: %s", err)
+			}
+
+			cfg.EncryptedClientHelloKeys = append(cfg.EncryptedClientHelloKeys, EncryptedClientHelloKey{
+				Config:      configBytes,
+				PrivateKey:  privBytes,
+				SendAsRetry: (*echServerRetryConfig)[i] == "1",
+			})
+		}
+	}
+
 	for i := 0; i < *resumeCount+1; i++ {
 		if i > 0 && (*onResumeECHConfigListB64 != "") {
 			echConfigList, err := base64.StdEncoding.DecodeString(*onResumeECHConfigListB64)
@@ -446,8 +472,11 @@ func TestBogoSuite(t *testing.T) {
 	// are present in the output. They are only checked if -bogo-filter
 	// was not passed.
 	assertResults := map[string]string{
-		"CurveTest-Client-Kyber-TLS13": "PASS",
-		"CurveTest-Server-Kyber-TLS13": "PASS",
+		// TODO: these tests are temporarily disabled, since we don't expose the
+		// necessary curve ID, and it's currently not possible to correctly
+		// configure it.
+		// "CurveTest-Client-Kyber-TLS13": "PASS",
+		// "CurveTest-Server-Kyber-TLS13": "PASS",
 	}
 
 	for name, result := range results.Tests {

src/crypto/tls/common.go

@@ -791,8 +791,10 @@ type Config struct {
 
 	// EncryptedClientHelloConfigList is a serialized ECHConfigList. If
 	// provided, clients will attempt to connect to servers using Encrypted
-	// Client Hello (ECH) using one of the provided ECHConfigs. Servers
-	// currently ignore this field.
+	// Client Hello (ECH) using one of the provided ECHConfigs.
+	//
+	// Servers do not use this field. In order to configure ECH for servers, see
+	// the EncryptedClientHelloKeys field.
 	//
 	// If the list contains no valid ECH configs, the handshake will fail
 	// and return an error.
@@ -810,9 +812,11 @@ type Config struct {
 	EncryptedClientHelloConfigList []byte
 
 	// EncryptedClientHelloRejectionVerify, if not nil, is called when ECH is
-	// rejected, in order to verify the ECH provider certificate in the outer
-	// Client Hello. If it returns a non-nil error, the handshake is aborted and
-	// that error results.
+	// rejected by the remote server, in order to verify the ECH provider
+	// certificate in the outer Client Hello. If it returns a non-nil error, the
+	// handshake is aborted and that error results.
+	//
+	// On the server side this field is not used.
 	//
 	// Unlike VerifyPeerCertificate and VerifyConnection, normal certificate
 	// verification will not be performed before calling
@@ -824,6 +828,20 @@ type Config struct {
 	// when ECH is rejected, even if set, and InsecureSkipVerify is ignored.
 	EncryptedClientHelloRejectionVerify func(ConnectionState) error
 
+	// EncryptedClientHelloKeys are the ECH keys to use when a client
+	// attempts ECH.
+	//
+	// If EncryptedClientHelloKeys is set, MinVersion, if set, must be
+	// VersionTLS13.
+	//
+	// If a client attempts ECH, but it is rejected by the server, the server
+	// will send a list of configs to retry based on the set of
+	// EncryptedClientHelloKeys which have the SendAsRetry field set.
+	//
+	// On the client side, this field is ignored. In order to configure ECH for
+	// clients, see the EncryptedClientHelloConfigList field.
+	EncryptedClientHelloKeys []EncryptedClientHelloKey
+
 	// mutex protects sessionTicketKeys and autoSessionTicketKeys.
 	mutex sync.RWMutex
 	// sessionTicketKeys contains zero or more ticket keys. If set, it means
@@ -837,6 +855,24 @@ type Config struct {
 	autoSessionTicketKeys []ticketKey
 }
 
+// EncryptedClientHelloKey holds a private key that is associated
+// with a specific ECH config known to a client.
+type EncryptedClientHelloKey struct {
+	// Config should be a marshalled ECHConfig associated with PrivateKey. This
+	// must match the config provided to clients byte-for-byte. The config
+	// should only specify the DHKEM(X25519, HKDF-SHA256) KEM ID (0x0020), the
+	// HKDF-SHA256 KDF ID (0x0001), and a subset of the following AEAD IDs:
+	// AES-128-GCM (0x0000), AES-256-GCM (0x0001), ChaCha20Poly1305 (0x0002).
+	Config []byte
+	// PrivateKey should be a marshalled private key. Currently, we expect
+	// this to be the output of [ecdh.PrivateKey.Bytes].
+	PrivateKey []byte
+	// SendAsRetry indicates if Config should be sent as part of the list of
+	// retry configs when ECH is requested by the client but rejected by the
+	// server.
+	SendAsRetry bool
+}
+
 const (
 	// ticketKeyLifetime is how long a ticket key remains valid and can be used to
 	// resume a client connection.
@@ -913,6 +949,7 @@ func (c *Config) Clone() *Config {
 		KeyLogWriter:                        c.KeyLogWriter,
 		EncryptedClientHelloConfigList:      c.EncryptedClientHelloConfigList,
 		EncryptedClientHelloRejectionVerify: c.EncryptedClientHelloRejectionVerify,
+		EncryptedClientHelloKeys:            c.EncryptedClientHelloKeys,
 		sessionTicketKeys:                   c.sessionTicketKeys,
 		autoSessionTicketKeys:               c.autoSessionTicketKeys,
 	}