GEP-91: Address connection coalescing security issue - API updates

Author: kl52752

apis/v1/gateway_types.go

@@ -295,6 +295,15 @@ type GatewaySpec struct {
 	//
 	// +optional
 	AllowedListeners *AllowedListeners `json:"allowedListeners,omitempty"`
+
+	// TLSConfigs stores TLS configurations for a Gateway.
+	//
+	// GatewayTLSConfigs will impact all existing and newly added Listeners.
+	//
+	// Support: Core
+	//
+	// +optional
+	TLSConfigs GatewayTLSConfigs `json:"tlsConfigs,omitempty"`
 }
 
 // AllowedListeners defines which ListenerSets can be attached to this Gateway.
@@ -579,8 +588,7 @@ type GatewayTLSConfig struct {
 	CertificateRefs []SecretObjectReference `json:"certificateRefs,omitempty"`
 
 	// FrontendValidation holds configuration information for validating the frontend (client).
-	// Setting this field will require clients to send a client certificate
-	// required for validation during the TLS handshake. In browsers this may result in a dialog appearing
+	// Setting this field will result in mutual authentication when connecting to the gateway. In browsers this may result in a dialog appearing
 	// that requests a user to specify the client certificate.
 	// The maximum depth of a certificate chain accepted in verification is Implementation specific.
 	//
@@ -624,6 +632,31 @@ const (
 	TLSModePassthrough TLSModeType = "Passthrough"
 )
 
+// TLSConfig describes a TLS configuration that can be applied to all Gateway
+// Listeners or to all Listeners matching the Port if set.
+type TLSConfig struct {
+	// The Port indicates the Port Number to which the TLS configuration will be
+	// applied. If the field is not set the TLS Configuration will be applied to
+	// all Listeners.
+	//
+	// Support: Extended
+	//
+	// +optional
+	// <gateway:experimental>
+	Port *PortNumber `json:"port,omitempty"`
+	// FrontendValidation holds configuration information for validating the frontend (client).
+	// Setting this field will result in mutual authentication when connecting to the gateway.
+	// In browsers this may result in a dialog appearing
+	// that requests a user to specify the client certificate.
+	// The maximum depth of a certificate chain accepted in verification is Implementation specific.
+	//
+	// Support: Extended
+	//
+	// +optional
+	// <gateway:experimental>
+	FrontendValidation *FrontendTLSValidation `json:"frontendValidation,omitempty"`
+}
+
 // FrontendTLSValidation holds configuration information that can be used to validate
 // the frontend initiating the TLS connection
 type FrontendTLSValidation struct {
@@ -640,8 +673,8 @@ type FrontendTLSValidation struct {
 	// Support: Core - A single reference to a Kubernetes ConfigMap
 	// with the CA certificate in a key named `ca.crt`.
 	//
-	// Support: Implementation-specific (More than one reference, or other kinds
-	// of resources).
+	// Support: Implementation-specific (More than one certificate in a ConfigMap
+	// with different keys or more than one reference, or other kinds of resources).
 	//
 	// References to a resource in a different namespace are invalid UNLESS there
 	// is a ReferenceGrant in the target namespace that allows the certificate
@@ -654,8 +687,53 @@ type FrontendTLSValidation struct {
 	// +kubebuilder:validation:MaxItems=8
 	// +kubebuilder:validation:MinItems=1
 	CACertificateRefs []ObjectReference `json:"caCertificateRefs,omitempty"`
+
+	// FrontendValidationMode defines the mode for validating the client certificate.
+	// There are two possible modes:
+	//
+	// - AllowValidOnly: In this mode, the gateway will accept connections only if
+	//   the client presents a valid certificate. This certificate must successfully
+	//   pass validation against the CA certificates specified in `CACertificateRefs`.
+	// - AllowInvalidOrMissingCert: In this mode, the gateway will accept
+	//   connections even if the client certificate is not presented or fails verification.
+	//
+	// Defaults to AllowValidOnly.
+	//
+	// Support: Core
+	//
+	// +optional
+	// +kubebuilder:default=AllowValidOnly
+	Mode FrontendValidationModeType `json:"mode,omitempty"`
 }
 
+// GatewayTLSConfigs stores TLS configurations for a Gateway.
+//
+//   - If the `port` field in `TLSConfig` is not set, the TLS configuration applies
+//     to all listeners in the gateway. We call this `default` configuration.
+//   - If the `port` field in `TLSConfig` is set, the TLS configuration applies
+//     only to listeners with a matching port. Each port requires a unique TLS configuration.
+//   - Per-port configurations can override the `default` configuration.
+//   - The `default` configuration is optional. Clients can apply TLS configuration
+//     to a subset of listeners by creating only per-port configurations.
+//     Listeners with a port that does not match any TLS configuration will
+//     not have `frontendValidation` set.
+type GatewayTLSConfigs = []TLSConfig
+
+// FrontendValidationModeType type defines how a Gateway validates client certificates.
+//
+// +kubebuilder:validation:Enum=AllowValidOnly;AllowInvalidOrMissingCert
+type FrontendValidationModeType string
+
+const (
+	// AllowValidOnly indicates that a client certificate is required
+	// during the TLS handshake and MUST pass validation.
+	AllowValidOnly FrontendValidationModeType = "AllowValidOnly"
+
+	// AllowInvalidOrMissingCert indicates that a client certificate may not be
+	// presented during the handshake or the validation against CA certificates may fail.
+	AllowInvalidOrMissingCert FrontendValidationModeType = "AllowInvalidOrMissingCert"
+)
+
 // AllowedRoutes defines which Routes may be attached to this Listener.
 type AllowedRoutes struct {
 	// Namespaces indicates namespaces from which Routes may be attached to this

geps/gep-91/index.md

@@ -102,14 +102,12 @@ type TLSConfig struct {
 	//
 	// +optional
 	// <gateway:experimental>
-	Port *PortNumber
+	Port *PortNumber `json:"port,omitempty"`
 	// FrontendValidation holds configuration information for validating the frontend (client).
 	// Setting this field will result in mutual authentication when connecting to the gateway. In browsers this may result in a dialog appearing
 	// that requests a user to specify the client certificate.
 	// The maximum depth of a certificate chain accepted in verification is Implementation specific.
 	//
-	// Each field may be overidden by an equivalent setting applied at the Listener level.
-	//
 	// Support: Extended
 	//
 	// +optional
@@ -156,14 +154,14 @@ type FrontendTLSValidation struct {
 	//
 	// Defaults to AllowValidOnly.
 	//
-	// Support: Extended
+	// Support: Core
 	//
 	// +optional
 	// +kubebuilder:default=AllowValidOnly
-	Mode *FrontendValidationModeType `json:"mode,omitempty"`
+	Mode FrontendValidationModeType `json:"mode,omitempty"`
 }
 
-// FrontendValidationModeType type defines how a Gateway or Listener validates client certificates.
+// FrontendValidationModeType type defines how a Gateway validates client certificates.
 //
 // +kubebuilder:validation:Enum=AllowValidOnly;AllowInvalidOrMissingCert
 type FrontendValidationModeType string