Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
+1,291 −509
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6c7e1ed
GEP-91: Address connection coalescing security issue - API updates
kl52752 Jul 22, 2025
d94294e
review
kl52752 Aug 6, 2025
5cf5c4e
rename GatewayTLSConfig to ListenerTLSConfig
kl52752 Aug 7, 2025
a1d2106
validation mode
kl52752 Aug 8, 2025
e003d67
gateway tls config
kl52752 Aug 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 122 additions & 19 deletions apis/v1/gateway_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -295,6 +295,13 @@
//
// +optional
AllowedListeners *AllowedListeners `json:"allowedListeners,omitempty"`
// GatewayTLSConfig specifies frontend tls configuration for gateway.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// GatewayTLSConfig specifies frontend tls configuration for gateway.
// GatewayTLSConfig specifies frontend tls configuration for gateway.

//
// Support: Extended
//
// +optional
// <gateway:experimental>
TLS *GatewayTLSConfig `json:"tls,omitempty"`
}

// AllowedListeners defines which ListenerSets can be attached to this Gateway.
Expand Down Expand Up @@ -414,7 +421,7 @@
// the Protocol field is "HTTPS" or "TLS". It is invalid to set this field
// if the Protocol field is "HTTP", "TCP", or "UDP".
//
// The association of SNIs to Certificate defined in GatewayTLSConfig is
// The association of SNIs to Certificate defined in ListenerTLSConfig is
// defined based on the Hostname field for this listener.
//
// The GatewayClass MUST use the longest matching SNI out of all
Expand All @@ -423,7 +430,7 @@
// Support: Core
//
// +optional
TLS *GatewayTLSConfig `json:"tls,omitempty"`
TLS *ListenerTLSConfig `json:"tls,omitempty"`

// AllowedRoutes defines the types of routes that MAY be attached to a
// Listener and the trusted namespaces where those Route resources MAY be
Expand Down Expand Up @@ -526,10 +533,10 @@
ClientCertificateRef *SecretObjectReference `json:"clientCertificateRef,omitempty"`
}

// GatewayTLSConfig describes a TLS configuration.
// ListenerTLSConfig describes a TLS configuration for a listener.
//
// +kubebuilder:validation:XValidation:message="certificateRefs or options must be specified when mode is Terminate",rule="self.mode == 'Terminate' ? size(self.certificateRefs) > 0 || size(self.options) > 0 : true"
type GatewayTLSConfig struct {
type ListenerTLSConfig struct {
// Mode defines the TLS behavior for the TLS session initiated by the client.
// There are two possible modes:
//
Expand Down Expand Up @@ -578,18 +585,6 @@
// +kubebuilder:validation:MaxItems=64
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
// 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"`

// Options are a list of key/value pairs to enable extended TLS
// configuration for each implementation. For example, configuring the
// minimum TLS version or supported cipher suites.
Expand All @@ -606,6 +601,31 @@
Options map[AnnotationKey]AnnotationValue `json:"options,omitempty"`
}

// GatewayTLSConfig specifies frontend tls configuration for gateway.
type GatewayTLSConfig struct {
// default specifies the default client certificate validation configuration
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While I think we eventually want to move to json names in field descriptions, we're currently using go types, so Default would be more appropriate here.

Suggested change
// default specifies the default client certificate validation configuration
// Default specifies the default client certificate validation configuration

// for all Listeners handling HTTPS traffic, unless a per-port configuration
// is defined.
//
// support: Core
//
// +required
// <gateway:experimental>
Default TLSConfig `json:"default"`

// PerPort specifies tls configuration assigned per port.
// Per port configuration is optional. Once set this configuration overrides
// the default configuration for all Listeners handling HTTPS traffic
// that match this port.
// Each override port requires a unique TLS configuration.
//
// support: Core
//
// +optional
// <gateway:experimental>
PerPort []TLSPortConfig `json:"perport,omitempty"`

Check failure on line 626 in apis/v1/gateway_types.go

View workflow job for this annotation

GitHub Actions / kube-api-lint 

ssatags: PerPort should have a listType marker for proper Server-Side Apply behavior (atomic, set, or map) (kubeapilinter)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
PerPort []TLSPortConfig `json:"perport,omitempty"`
PerPort []TLSPortConfig `json:"perPort,omitempty"`

}

// TLSModeType type defines how a Gateway handles TLS sessions.
//
// +kubebuilder:validation:Enum=Terminate;Passthrough
Expand All @@ -624,6 +644,42 @@
TLSModePassthrough TLSModeType = "Passthrough"
)

// TLSConfig describes a TLS configuration. Currently, it stores only the client
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// TLSConfig describes a TLS configuration. Currently, it stores only the client
// TLSConfig describes TLS configuration that can apply to multiple Listeners within this Gateway. Currently, it stores only the client

// certificate validation configuration, but this may be extended in the future.
type TLSConfig struct {
// 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: Core
//
// +required
// <gateway:experimental>
FrontendValidation FrontendTLSValidation `json:"frontendValidation"`
}

type TLSPortConfig struct {
// The Port indicates the Port Number to which the TLS configuration will be
// applied. This configuration will be applied to all Listeners handling HTTPS
// traffic that match this port.
//
// Support: Core
//
// +required
// <gateway:experimental>
Port PortNumber `json:"port"`
// TLS store the configuration that will be applied to all Listeners handling
Comment on lines +672 to +673
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Port PortNumber `json:"port"`
// TLS store the configuration that will be applied to all Listeners handling
Port PortNumber `json:"port"`
// TLS stores the configuration that will be applied to all Listeners handling

// HTTPS traffic and matching given port.
//
// Support: Core
//
// +required
// <gateway:experimental>
TLS TLSConfig `json:"tls"`
}

// FrontendTLSValidation holds configuration information that can be used to validate
// the frontend initiating the TLS connection
type FrontendTLSValidation struct {
Expand All @@ -640,8 +696,8 @@
// 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
Expand All @@ -653,9 +709,49 @@
// +listType=atomic
// +kubebuilder:validation:MaxItems=8
// +kubebuilder:validation:MinItems=1
CACertificateRefs []ObjectReference `json:"caCertificateRefs,omitempty"`
CACertificateRefs []ObjectReference `json:"caCertificateRefs"`

// 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`.
// - AllowInsecureFallback: In this mode, the gateway will accept connections
// even if the client certificate is not presented or fails verification.
//
// This approach delegates client authorization to the backend and introduce
// a significant security risk. It should be used in testing environments or
// on a temporary basis in non-testing environments.
//
// Defaults to AllowValidOnly.
//
// Support: Core
//
// +optional
// +kubebuilder:default=AllowValidOnly
Mode FrontendValidationModeType `json:"mode,omitempty"`
}

// FrontendValidationModeType type defines how a Gateway validates client certificates.
//
// +kubebuilder:validation:Enum=AllowValidOnly;AllowInsecureFallback
type FrontendValidationModeType string

const (
// AllowValidOnly indicates that a client certificate is required
// during the TLS handshake and MUST pass validation.
//
// Support: Core
AllowValidOnly FrontendValidationModeType = "AllowValidOnly"

// AllowInsecureFallback indicates that a client certificate may not be
// presented during the handshake or the validation against CA certificates may fail.
//
// Support: Extended
AllowInsecureFallback FrontendValidationModeType = "AllowInsecureFallback"
)

// AllowedRoutes defines which Routes may be attached to this Listener.
type AllowedRoutes struct {
// Namespaces indicates namespaces from which Routes may be attached to this
Expand Down Expand Up @@ -993,6 +1089,13 @@
// information on which address is causing the problem and how to resolve it
// in the condition message.
GatewayReasonAddressNotUsable GatewayConditionReason = "AddressNotUsable"
// This condition indicates `FrontendValidationModeType` changed from
// `AllowValidOnly` to `AllowInsecureFallback`.
GatewayConditionInsecureFrontendValidationMode GatewayConditionReason = "InsecureFrontendValidationMode"
// This reason MUST be set for GatewayConditionInsecureFrontendValidationMode
// when client change FrontendValidationModeType for a Gateway or per port override
// to `AllowInsecureFallback`.
GatewayReasonConfigurationChanged GatewayConditionReason = "ConfigurationChanged"
)

const (
Expand Down
97 changes: 76 additions & 21 deletions apis/v1/zz_generated.deepcopy.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions apis/v1beta1/gateway_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,9 +88,9 @@ type Listener = v1.Listener
// +k8s:deepcopy-gen=false
type ProtocolType = v1.ProtocolType

// GatewayTLSConfig describes a TLS configuration.
// ListenerTLSConfig describes a TLS configuration.
// +k8s:deepcopy-gen=false
type GatewayTLSConfig = v1.GatewayTLSConfig
type ListenerTLSConfig = v1.ListenerTLSConfig

// TLSModeType type defines how a Gateway handles TLS sessions.
//
Expand Down
2 changes: 1 addition & 1 deletion apisx/v1alpha1/shared_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ type (
// +k8s:deepcopy-gen=false
AllowedRoutes = v1.AllowedRoutes
// +k8s:deepcopy-gen=false
GatewayTLSConfig = v1.GatewayTLSConfig
ListenerTLSConfig = v1.ListenerTLSConfig
// +k8s:deepcopy-gen=false
Group = v1.Group
// +k8s:deepcopy-gen=false
Expand Down
4 changes: 2 additions & 2 deletions apisx/v1alpha1/xlistenerset_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,14 +179,14 @@ type ListenerEntry struct {
// the Protocol field is "HTTPS" or "TLS". It is invalid to set this field
// if the Protocol field is "HTTP", "TCP", or "UDP".
//
// The association of SNIs to Certificate defined in GatewayTLSConfig is
// The association of SNIs to Certificate defined in ListenerTLSConfig is
// defined based on the Hostname field for this listener.
//
// The GatewayClass MUST use the longest matching SNI out of all
// available certificates for any TLS handshake.
//
// +optional
TLS *GatewayTLSConfig `json:"tls,omitempty"`
TLS *ListenerTLSConfig `json:"tls,omitempty"`

// AllowedRoutes defines the types of routes that MAY be attached to a
// Listener and the trusted namespaces where those Route resources MAY be
Expand Down
2 changes: 1 addition & 1 deletion apisx/v1alpha1/zz_generated.deepcopy.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading