Skip to content

Commit ff47627

Browse files
kl52752arkodg
kl52752
and
arkodg
authored
Gep-91: Address connection coalescing security issue (#3942)
* GEP 91: Update API Relates to #3760 (comment) Signed-off-by: Arko Dasgupta <[email protected]> * GEP-91: Address connection coalescing security issue * remove changes in API --------- Signed-off-by: Arko Dasgupta <[email protected]> Co-authored-by: Arko Dasgupta <[email protected]>
1 parent 222a1f8 commit ff47627

File tree

1 file changed

+175
-40
lines changed

1 file changed

+175
-40
lines changed

‎geps/gep-91/index.md

Lines changed: 175 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -10,24 +10,37 @@
1010
This GEP proposes a way to validate the TLS certificate presented by the frontend client to the server
1111
(Gateway in this case) during a [TLS Handshake Protocol][].
1212

13+
## Connection coalescing security issue
14+
15+
Gateway API standard defines a `Listener` as "the concept of a logical endpoint where a Gateway accepts network connections." This statement is incorrect because once the connection is established (this applies to both HTTP and TLS traffic) it can be reused across multiple listeners sharing the same port. This might lead to bypassing client certificate validation configuration for a given `Listener`. Those concerns were raised in [GEP-3567](). To provide the best experience for gateway users and secure their applications, client certificate configuration needs to be introduced with finer granularity per-port (binding to TCP connection).
16+
1317
## Goals
1418

1519
* Define an API field to specify the CA Certificate within the Gateway configuration that can be used as a trust anchor to validate the certificates presented by the client.
1620
This use case has been highlighted in the [TLS Configuration GEP][] under segment 1 and in the [Gateway API TLS Use Cases][] document under point 7.
21+
* Introduce explicit client certificate validation modes that reflect common TLS behaviors (e.g., optional vs. required client certs)
1722
* Ensure the configuration mitigates the authentication bypass risks associated with HTTP/2 connection coalesing as described in [GEP-3567](https://gateway-api.sigs.k8s.io/geps/gep-3567/#interaction-with-client-cert-validation).
18-
* Supporting a mode where validating client certificates is optional, useful for debugging and migrating to strict TLS.
1923

2024
## Non-Goals
2125
* Define other fields that can be used to verify the client certificate such as the Certificate Hash.
2226

2327
### API
2428

25-
* Introduce a `FrontendValidation` field of type `FrontendTLSValidation` within [GatewayTLSConfig][] that can be used to validate the peer (frontend) with which the TLS connection is being made.
29+
* Introduce two new structs `TLSConfig` and `FrontendTLSValidation` allowing for the definition of certificate validation used to authenticate the peer (frontend) in a TLS connection. A new `tls` field, storing an array of `TLSConfigs`, will be added to the gateway object.
30+
* This new field is separate from the existing [BackendTLSPolicy][] configuration. [BackendTLSPolicy][] controls TLS certificate validation for connections *from* the Gateway to the backend service.
31+
This proposal adds the ability to validate the TLS certificate presented by the *client* connecting to the Gateway (the frontend).
32+
These two validation mechanisms operate independently and can be used simultaneously.
2633
* Introduce a `caCertificateRefs` field within `FrontendTLSValidation` that can be used to specify a list of CA Certificates that can be used as a trust anchor to validate the certificates presented by the client.
27-
* This new field is separate from the existing [BackendTLSPolicy][] configuration. [BackendTLSPolicy][] controls TLS certificate validation for connections *from* the
28-
Gateway to the backend service. This proposal adds the ability to validate the TLS certificate presented by the *client* connecting to the Gateway (the
29-
frontend). These two validation mechanisms operate independently and can be used simultaneously.
30-
* Also introduce a `ObjectReference` structure that can be used to specify `caCertificateRefs` references.
34+
* Add a new `FrontendValidationModeType` enum within `FrontendTLSValidation` indicating how gateway should validate client certificates. As for now we support following values but it might change in the future:
35+
1) `AllowValidOnly`
36+
2) `AllowInvalidOrMissingCert`
37+
* Introduce a `ObjectReference` structure that can be used to specify `caCertificateRefs` references.
38+
* Introduce a `tls` field within the Gateway Spec to allow for a common TLS configuration to apply across all listeners.
39+
40+
### Impact on listeners
41+
42+
This proposal removes frontendTLSValidation from Listener's TLS configuration and introduces gateways level per port configuration. This is a breaking change for exisitng implementation which uses this feature from Experimental API.
43+
Once gateway level TLS is configured (either by default or for a specific port), the TLS settings will apply to all existing and newly created Listeners that match the configuration.
3144

3245
#### GO
3346

@@ -65,57 +78,131 @@ type ObjectReference struct {
6578
Namespace *Namespace `json:"namespace,omitempty"`
6679
}
6780

68-
type GatewayTLSConfig struct {
69-
......
70-
// FrontendValidation holds configuration information for validating the frontend (client).
71-
// Setting this field will require clients to send a client certificate
72-
// required for validation during the TLS handshake. In browsers this may result in a dialog appearing
73-
// that requests a user to specify the client certificate.
74-
// The maximum depth of a certificate chain accepted in verification is Implementation specific.
75-
FrontendValidation *FrontendTLSValidation `json:"frontendValidation,omitempty"`
81+
// GatewayTLSConfigs stores TLS configurations for a Gateway.
82+
//
83+
// * If the `port` field in `TLSConfig` is not set, the TLS configuration applies
84+
// to all listeners in the gateway. We call this `default` configuration.
85+
// * If the `port` field in `TLSConfig` is set, the TLS configuration applies
86+
// only to listeners with a matching port. Each port requires a unique TLS configuration.
87+
// * Per-port configurations can override the `default` configuration.
88+
// * The `default` configuration is optional. Clients can apply TLS configuration
89+
// to a subset of listeners by creating only per-port configurations. Listeners
90+
// with a port that does not match any TLS configuration will not have
91+
// `frontendValidation` set.
92+
type GatewayTLSConfigs = []TLSConfig
93+
94+
// TLSConfig describes a TLS configuration that can be applied to all Gateway
95+
// Listeners or to all Listeners matching the Port if set.
96+
type TLSConfig struct {
97+
// The Port indicates the Port Number to which the TLS configuration will be
98+
// applied. If the field is not set the TLS Configuration will be applied to
99+
// all Listeners.
100+
//
101+
// Support: Extended
102+
//
103+
// +optional
104+
// <gateway:experimental>
105+
Port *PortNumber
106+
// FrontendValidation holds configuration information for validating the frontend (client).
107+
// Setting this field will result in mutual authentication when connecting to the gateway. In browsers this may result in a dialog appearing
108+
// that requests a user to specify the client certificate.
109+
// The maximum depth of a certificate chain accepted in verification is Implementation specific.
110+
//
111+
// Each field may be overidden by an equivalent setting applied at the Listener level.
112+
//
113+
// Support: Extended
114+
//
115+
// +optional
116+
// <gateway:experimental>
117+
FrontendValidation *FrontendTLSValidation `json:"frontendValidation,omitempty"`
76118
}
77119

78120
// FrontendTLSValidation holds configuration information that can be used to validate
79121
// the frontend initiating the TLS connection
80122
type FrontendTLSValidation struct {
81-
// CACertificateRefs contains one or more references to
82-
// Kubernetes objects that contain TLS certificates of
83-
// the Certificate Authorities that can be used
84-
// as a trust anchor to validate the certificates presented by the client.
85-
//
86-
// A single CA certificate reference to a Kubernetes ConfigMap
87-
// has "Core" support.
88-
// Implementations MAY choose to support attaching multiple CA certificates to
89-
// a Listener, but this behavior is implementation-specific.
90-
//
91-
// Support: Core - A single reference to a Kubernetes ConfigMap
92-
// with the CA certificate in a key named `ca.crt`.
93-
//
94-
// Support: Implementation-specific (More than one reference, or other kinds
95-
// of resources).
96-
//
97-
// References to a resource in a different namespace are invalid UNLESS there
98-
// is a ReferenceGrant in the target namespace that allows the certificate
99-
// to be attached. If a ReferenceGrant does not allow this reference, the
100-
// "ResolvedRefs" condition MUST be set to False for this listener with the
101-
// "RefNotPermitted" reason.
102-
//
103-
// +kubebuilder:validation:MaxItems=8
104-
// +kubebuilder:validation:MinItems=1
105-
CACertificateRefs []ObjectReference `json:"caCertificateRefs,omitempty"`
123+
// CACertificateRefs contains one or more references to
124+
// Kubernetes objects that contain TLS certificates of
125+
// the Certificate Authorities that can be used
126+
// as a trust anchor to validate the certificates presented by the client.
127+
//
128+
// A single CA certificate reference to a Kubernetes ConfigMap
129+
// has "Core" support.
130+
// Implementations MAY choose to support attaching multiple CA certificates to
131+
// a Listener, but this behavior is implementation-specific.
132+
//
133+
// Support: Core - A single reference to a Kubernetes ConfigMap
134+
// with the CA certificate in a key named `ca.crt`.
135+
//
136+
// Support: Implementation-specific (More than one certificate in a ConfigMap with different keys or more than one reference, or other kinds of resources).
137+
//
138+
// References to a resource in a different namespace are invalid UNLESS there
139+
// is a ReferenceGrant in the target namespace that allows the certificate
140+
// to be attached. If a ReferenceGrant does not allow this reference, the
141+
// "ResolvedRefs" condition MUST be set to False for this listener with the
142+
// "RefNotPermitted" reason.
143+
//
144+
// +kubebuilder:validation:MaxItems=8
145+
// +kubebuilder:validation:MinItems=1
146+
CACertificateRefs []ObjectReference `json:"caCertificateRefs,omitempty"`
147+
148+
// FrontendValidationMode defines the mode for validating the client certificate.
149+
// There are two possible modes:
150+
//
151+
// - AllowValidOnly: In this mode, the gateway will accept connections only if
152+
// the client presents a valid certificate. This certificate must successfully
153+
// pass validation against the CA certificates specified in `CACertificateRefs`.
154+
// - AllowInvalidOrMissingCert: In this mode, the gateway will accept
155+
// connections even if the client certificate is not presented or fails verification.
156+
//
157+
// Defaults to AllowValidOnly.
158+
//
159+
// Support: Extended
160+
//
161+
// +optional
162+
// +kubebuilder:default=AllowValidOnly
163+
Mode *FrontendValidationModeType `json:"mode,omitempty"`
164+
}
165+
166+
// FrontendValidationModeType type defines how a Gateway or Listener validates client certificates.
167+
//
168+
// +kubebuilder:validation:Enum=AllowValidOnly;AllowInvalidOrMissingCert
169+
type FrontendValidationModeType string
170+
171+
const (
172+
// AllowValidOnly indicates that a client certificate is required
173+
// during the TLS handshake and MUST pass validation.
174+
AllowValidOnly FrontendValidationModeType = "AllowValidOnly"
175+
176+
// AllowInvalidOrMissingCert indicates that a client certificate may not be
177+
// presented during the handshake or the validation against CA certificates may fail.
178+
AllowInvalidOrMissingCert FrontendValidationModeType = "AllowInvalidOrMissingCert"
179+
)
180+
181+
type GatewaySpec struct {
182+
...
183+
// TLSConfigs stores TLS configurations for a Gateway.
184+
TLSConfigs GatewayTLSConfigs
106185
}
107186

108187
```
109188

110189
#### YAML
111190

191+
1. Setting default `frontendValidation` config.
192+
112193
```yaml
113194
apiVersion: gateway.networking.k8s.io/v1beta1
114195
kind: Gateway
115196
metadata:
116197
name: client-validation-basic
117198
spec:
118199
gatewayClassName: acme-lb
200+
tls:
201+
- frontendValidation:
202+
caCertificateRefs:
203+
- kind: ConfigMap
204+
group: ""
205+
name: default-cert
119206
listeners:
120207
- name: foo-https
121208
protocol: HTTPS
@@ -126,11 +213,58 @@ spec:
126213
- kind: Secret
127214
group: ""
128215
name: foo-example-com-cert
216+
- name: bar-https
217+
protocol: HTTPS
218+
port: 8443
219+
hostname: bar.example.com
220+
tls:
221+
certificateRefs:
222+
- kind: Secret
223+
group: ""
224+
name: bar-example-com-cert
225+
```
226+
227+
2. Setting default and per port `frontendValidation` configs.
228+
229+
```yaml
230+
apiVersion: gateway.networking.k8s.io/v1beta1
231+
kind: Gateway
232+
metadata:
233+
name: client-validation-basic
234+
spec:
235+
gatewayClassName: acme-lb
236+
tls:
237+
- port: 443
129238
frontendValidation:
130239
caCertificateRefs:
131240
- kind: ConfigMap
132241
group: ""
133242
name: foo-example-com-ca-cert
243+
- frontendValidation:
244+
caCertificateRefs:
245+
- kind: ConfigMap
246+
group: ""
247+
name: default-cert
248+
mode: AllowInvalidOrMissingCert
249+
listeners:
250+
- name: foo-https
251+
protocol: HTTPS
252+
port: 443
253+
hostname: foo.example.com
254+
tls:
255+
certificateRefs:
256+
- kind: Secret
257+
group: ""
258+
name: foo-example-com-cert
259+
- name: bar-https
260+
protocol: HTTPS
261+
port: 8443
262+
hostname: bar.example.com
263+
tls:
264+
certificateRefs:
265+
- kind: Secret
266+
group: ""
267+
name: bar-example-com-cert
134268
```
135269

136270
## Deferred
@@ -143,7 +277,7 @@ This section highlights use cases that may be covered in a future iteration of t
143277

144278
## Existing support in Implementations
145279

146-
This feature is already widely supported by implementations that conform to the Gateway API.
280+
This feature is already widely supported by implementations that conform to the Gateway API.
147281
The table below summarizes current support. Please feel free to add any implementations that are missing.
148282
This GEP aims to standardize this behavior as an official part of the upstream specification.
149283

@@ -191,3 +325,4 @@ This GEP aims to standardize this behavior as an official part of the upstream s
191325
[BackendTLSPolicy]: ../../api-types/backendtlspolicy.md
192326
[TLS Configuration GEP]: ../gep-2907/index.md
193327
[Gateway API TLS Use Cases]: https://docs.google.com/document/d/17sctu2uMJtHmJTGtBi_awGB0YzoCLodtR6rUNmKMCs8/edit?pli=1#heading=h.cxuq8vo8pcxm
328+
[GEP-3567]: https://gateway-api.sigs.k8s.io/geps/gep-3567/

0 commit comments

Comments
 (0)