Implementation of GEP-3567 - TLS Updates for Connection Coalescing (#3630)

* Implementation of GEP-3567 - TLS Updates for Connection Coalescing

* Responses to PR feedback

Author: robscott

apis/v1/gateway_types.go

@@ -336,10 +336,31 @@ type Listener struct {
 	//
 	// * TLS: The Listener Hostname MUST match the SNI.
 	// * HTTP: The Listener Hostname MUST match the Host header of the request.
-	// * HTTPS: The Listener Hostname SHOULD match at both the TLS and HTTP
-	//   protocol layers as described above. If an implementation does not
-	//   ensure that both the SNI and Host header match the Listener hostname,
-	//   it MUST clearly document that.
+	// * HTTPS: The Listener Hostname SHOULD match both the SNI and Host header.
+	//   Note that this does not require the SNI and Host header to be the same.
+	//   The semantics of this are described in more detail below.
+	//
+	// To ensure security, Section 11.1 of RFC-6066 emphasizes that server
+	// implementations that rely on SNI hostname matching MUST also verify
+	// hostnames within the application protocol.
+	//
+	// Section 9.1.2 of RFC-7540 provides a mechanism for servers to reject the
+	// reuse of a connection by responding with the HTTP 421 Misdirected Request
+	// status code. This indicates that the origin server has rejected the
+	// request because it appears to have been misdirected.
+	//
+	// To detect misdirected requests, Gateways SHOULD match the authority of
+	// the requests with all the SNI hostname(s) configured across all the
+	// Gateway Listeners on the same port and protocol:
+	//
+	// * If another Listener has an exact match or more specific wildcard entry,
+	//   the Gateway SHOULD return a 421.
+	// * If the current Listener (selected by SNI matching during ClientHello)
+	//   does not match the Host:
+	//     * If another Listener does match the Host the Gateway SHOULD return a
+	//       421.
+	//     * If no other Listener matches the Host, the Gateway MUST return a
+	//       404.
 	//
 	// For HTTPRoute and TLSRoute resources, there is an interaction with the
 	// `spec.hostnames` array. When both listener and route specify hostnames,
@@ -1268,6 +1289,62 @@ const (
 	ListenerReasonPending ListenerConditionReason = "Pending"
 )
 
+const (
+	// This condition indicates that TLS configuration within this Listener
+	// conflicts with TLS configuration in another Listener on the same port.
+	// This could happen for two reasons:
+	//
+	// 1) Overlapping Hostnames: Listener A matches *.example.com while Listener
+	//    B matches foo.example.com.
+	// B) Overlapping Certificates: Listener A contains a certificate with a
+	//    SAN for *.example.com, while Listener B contains a certificate with a
+	//    SAN for foo.example.com.
+	//
+	// This overlapping TLS configuration can be particularly problematic when
+	// combined with HTTP connection coalescing. When clients reuse connections
+	// using this technique, it can have confusing interactions with Gateway
+	// API, such as TLS configuration for one Listener getting used for a
+	// request reusing an existing connection that would not be used if the same
+	// request was initiating a new connection.
+	//
+	// Controllers MUST detect the presence of overlapping hostnames and MAY
+	// detect the presence of overlapping certificates.
+	//
+	// This condition MUST be set on all Listeners with overlapping TLS config.
+	// For example, consider the following listener - hostname mapping:
+	//
+	// A: foo.example.com
+	// B: foo.example.org
+	// C: *.example.com
+	//
+	// In the above example, Listeners A and C would have overlapping hostnames
+	// and therefore this condition should be set for Listeners A and C, but not
+	// B.
+	//
+	// Possible reasons for this condition to be True are:
+	//
+	// * "OverlappingHostnames"
+	// * "OverlappingCertificates"
+	//
+	// If a controller supports checking for both possible reasons and finds
+	// that both are true, it SHOULD set the "OverlappingCertificates" Reason.
+	//
+	// This is a negative polarity condition and MUST NOT be set when it is
+	// False.
+	//
+	// Controllers may raise this condition with other reasons, but should
+	// prefer to use the reasons listed above to improve interoperability.
+	ListenerConditionOverlappingTLSConfig ListenerConditionType = "OverlappingTLSConfig"
+
+	// This reason is used with the "OverlappingTLSConfig" condition when the
+	// condition is true.
+	ListenerReasonOverlappingHostnames ListenerConditionReason = "OverlappingHostnames"
+
+	// This reason is used with the "OverlappingTLSConfig" condition when the
+	// condition is true.
+	ListenerReasonOverlappingCertificates ListenerConditionReason = "OverlappingCertificates"
+)
+
 const (
 	// "Ready" is a condition type reserved for future use. It should not be used by implementations.
 	// Note: This condition is not really "deprecated", but rather "reserved"; however, deprecated triggers Go linters

config/crd/experimental/gateway.networking.k8s.io_gateways.yaml

@@ -1,7 +1,7 @@
 # GEP-3567: Gateway TLS Updates for HTTP/2 Connection Coalescing
 
 * Issue: [#3567](https://github.com/kubernetes-sigs/gateway-api/issues/3567)
-* Status: Implementable
+* Status: Experimental
 
 ## TLDR
 
@@ -40,7 +40,9 @@ the client sends.
 
 Gateway API deals with this situation imprecisely, stating:
 
-    The Listener Hostname SHOULD match at both the TLS and HTTP protocol layers as described above. If an implementation does not ensure that both the SNI and Host header match the Listener hostname, it MUST clearly document that.
+    The Listener Hostname SHOULD match at both the TLS and HTTP protocol layers
+    as described above. If an implementation does not ensure that both the SNI
+    and Host header match the Listener hostname, it MUST clearly document that.
 
 In practice we can end up with an implementation that misroutes requests when a
 Gateway is configured using certificates that use multiple or wildcard SANs.
@@ -119,7 +121,7 @@ A new condition will be added to Gateways: `OverlappingTLSConfig`.
 Implementations MUST add this condition to status when a Gateway is configured
 with TLS configuration across multiple Listeners. Implementations MAY add this
 condition to status when a Gateway is configured with overlapping TLS
-certifications. Note that since this is a negative polarity condition, it would
+certificates. Note that since this is a negative polarity condition, it would
 only be populated when it is true.
 
 ### B) Modify API Spec to recommend sending 421s

config/crd/standard/gateway.networking.k8s.io_gateways.yaml

@@ -141,6 +141,7 @@ nav:
       - geps/gep-2649/index.md
       - geps/gep-3155/index.md
       - geps/gep-3171/index.md
+      - geps/gep-3567/index.md
     - Standard:
       - geps/gep-709/index.md
       - geps/gep-718/index.md