Skip to content

Commit a1161fd

Browse files
robscottrobscott
authored
Adding GEP-3567: Gateway TLS Updates for HTTP/2 Connection Coalescing (#3572)
1 parent 7ca7d50 commit a1161fd

File tree

2 files changed

+193
-0
lines changed

2 files changed

+193
-0
lines changed

‎geps/gep-3567/index.md

+160
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# GEP-3567: Gateway TLS Updates for HTTP/2 Connection Coalescing
2+
3+
* Issue: [#3567](https://github.com/kubernetes-sigs/gateway-api/issues/3567)
4+
* Status: Implementable
5+
6+
## TLDR
7+
8+
As described in the [previous
9+
doc](https://docs.google.com/document/d/1g_TNN8eOaVDC3xesO9JFdvQbPFdSTHp1vb70TD3-Vrs/edit?tab=t.0#heading=h.qiz1tfw67tbp),
10+
the current state of TLS configuration on Gateways can lead to confusing
11+
behavior when combined with HTTP/2 connection coalescing. This GEP proposes a
12+
series of changes to the API to address these problems.
13+
14+
## Goals
15+
16+
* Take steps that will make it less likely for users to encounter these problems
17+
* Warn when users have configuration that is prone to these issues
18+
* Provide central source of documentation explaining both the problem and
19+
potential solutions
20+
21+
## Non-Goals
22+
23+
* Breaking or significantly disruptive changes to the existing API surface
24+
25+
## Introduction
26+
27+
Gateway API creates situations where clients might be able to send requests
28+
through a Listener that, according to the Gateway’s configuration, is not
29+
supposed to receive these requests. This can cause requests to be apparently
30+
mis-routed.
31+
32+
The problem here is an inherent conflict between the API and the mechanics of
33+
HTTPS. Gateway API uses the “hostname” field in the Listener to constrain both
34+
the TLS certificate selection and the host header of requests. But when a server
35+
presents a TLS certificate that is valid for multiple domains, a client is free
36+
to reuse its TLS connection for requests sent to any of those domains (for
37+
HTTP2, see RFC). The SNI hostname, which the client presents only with the
38+
initial TLS handshake, doesn’t constrain the host header of the requests that
39+
the client sends.
40+
41+
Gateway API deals with this situation imprecisely, stating:
42+
43+
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.
44+
45+
In practice we can end up with an implementation that misroutes requests when a
46+
Gateway is configured using certificates that use multiple or wildcard SANs.
47+
48+
### Example
49+
50+
The following configuration ([from the Gateway API
51+
documentation](https://gateway-api.sigs.k8s.io/guides/tls/#wildcard-tls-listeners))
52+
illustrates the problem:
53+
54+
55+
```
56+
apiVersion: gateway.networking.k8s.io/v1
57+
kind: Gateway
58+
metadata:
59+
name: wildcard-tls-gateway
60+
spec:
61+
gatewayClassName: example
62+
listeners:
63+
- name: foo-https
64+
protocol: HTTPS
65+
port: 443
66+
hostname: foo.example.com
67+
tls:
68+
certificateRefs:
69+
- kind: Secret
70+
group: ""
71+
name: foo-example-com-cert # SAN: foo.example.com
72+
- name: wildcard-https
73+
protocol: HTTPS
74+
port: 443
75+
hostname: "*.example.com"
76+
tls:
77+
certificateRefs:
78+
- kind: Secret
79+
group: ""
80+
name: wildcard-example-com-cert # SAN: *.example.com
81+
```
82+
83+
84+
The Gateway API definition requires requests to `foo.example.com` to be
85+
associated with the `foo-https` listener, on connections negotiated with
86+
`foo-example-com-cert`.
87+
88+
Suppose a client sends a request to `bar.example.com`, specifying that as the
89+
SNI hostname, and establishes a TLS connection attached to the `wildcard-https`
90+
Listener. And then it sends a subsequent request to `foo.example.com`. The
91+
client can correctly reuse its existing TLS connection for the second request,
92+
because the `wildcard-example-com-cert` is valid also for `foo.example.com`. But
93+
now the Gateway has a problem: Routing the request via the `wildcard-https`
94+
Listener violates the intent of the configuration, and routing via the
95+
`foo-https` Listener is inconsistent with the connection’s having been
96+
negotiated with the other Listener’s certificate.
97+
98+
Mapping a request to a Listener matters if the Gateway configuration has
99+
different
100+
[HTTPRoutes](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRoute)
101+
bound to the different Listeners. It also matters if the Listeners have
102+
different
103+
[GatewayTlsConfigs](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.GatewayTLSConfig)
104+
attached, for example if one Listener uses mutual TLS and the other does not.
105+
106+
107+
### Interaction with Client Cert Validation
108+
109+
[GEP-91](https://gateway-api.sigs.k8s.io/geps/gep-91/) introduced Client
110+
Certificate Validation to Gateway Listeners as a new experimental concept. If an
111+
implementation is unable to properly isolate HTTPS listeners, this could result
112+
in this Client Cert Validation being bypassed. Before this feature can graduate
113+
beyond experimental, we’ll need to resolve this underlying issue.
114+
115+
## Proposal
116+
117+
### A) Add Warning in Gateway Status
118+
A new condition will be added to Gateways: `OverlappingTLSConfig`.
119+
Implementations MUST add this condition to status when a Gateway is configured
120+
with TLS configuration across multiple Listeners. Implementations MAY add this
121+
condition to status when a Gateway is configured with overlapping TLS
122+
certifications. Note that since this is a negative polarity condition, it would
123+
only be populated when it is true.
124+
125+
### B) Modify API Spec to recommend sending 421s
126+
The Gateway spec for `listener.hostname` will be updated to recommend returning
127+
a 421 when this problem occurs.
128+
129+
### C) Top Level Gateway TLS Config for Client Cert Validation
130+
131+
A follow up discussion for GEP-91 will consider if Client Cert Validation should
132+
be moved or copied to a new top level Gateway TLS config instead of
133+
per-listener.
134+
135+
## Conformance Details
136+
137+
#### Feature Names
138+
139+
A) None, this will be required for any implementations that support HTTP +
140+
Gateways.
141+
142+
B) `GatewayReturn421`
143+
144+
C) Will be covered in GEP-91
145+
146+
### Conformance tests
147+
148+
A) A new conformance test will be added to ensure that the new status condition
149+
is populated when a Gateway is configured with overlapping TLS configuration.
150+
151+
B) A new conformance test will be added to ensure that implementations return a
152+
421 when a connection is reused for a different listener with an overlapping
153+
SNI.
154+
155+
C) Will be covered in GEP-91
156+
157+
## Alternatives
158+
159+
Discussed in more detail the [original
160+
doc](https://docs.google.com/document/d/1g_TNN8eOaVDC3xesO9JFdvQbPFdSTHp1vb70TD3-Vrs/edit?tab=t.0#heading=h.qiz1tfw67tbp)

‎geps/gep-3567/metadata.yaml

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
apiVersion: internal.gateway.networking.k8s.io/v1alpha1
2+
kind: GEPDetails
3+
number: 3567
4+
name: Gateway TLS Updates for HTTP/2 Connection Coalescing
5+
status: Implementable
6+
# Any authors who contribute to the GEP in any way should be listed here using
7+
# their Github handle.
8+
authors:
9+
- robscott
10+
relationships:
11+
# obsoletes indicates that a GEP makes the linked GEP obsolete, and completely
12+
# replaces that GEP. The obsoleted GEP MUST have its obsoletedBy field
13+
# set back to this GEP, and MUST be moved to Declined.
14+
obsoletes: {}
15+
obsoletedBy: {}
16+
# extends indicates that a GEP extends the linkned GEP, adding more detail
17+
# or additional implementation. The extended GEP MUST have its extendedBy
18+
# field set back to this GEP.
19+
extends: {}
20+
extendedBy: {}
21+
# seeAlso indicates other GEPs that are relevant in some way without being
22+
# covered by an existing relationship.
23+
seeAlso: {}
24+
# references is a list of hyperlinks to relevant external references.
25+
# It's intended to be used for storing Github discussions, Google docs, etc.
26+
references: {}
27+
# featureNames is a list of the feature names introduced by the GEP, if there
28+
# are any. This will allow us to track which feature was introduced by which GEP.
29+
featureNames:
30+
- GatewayReturn421
31+
# changelog is a list of hyperlinks to PRs that make changes to the GEP, in
32+
# ascending date order.
33+
changelog: {}

0 commit comments

Comments
 (0)