Skip to content

Commit fde94f2

Browse files
snorwinsnorwin
authored
gep: refine CACertificateRefs description for frontend TLS (#4183)
* gep: refine CACertificateRefs description for frontend TLS Signed-off-by: Norwin Schnyder <norwin.schnyder+github@gmail.com> * apply PR feedback Signed-off-by: Norwin Schnyder <norwin.schnyder+github@gmail.com> --------- Signed-off-by: Norwin Schnyder <norwin.schnyder+github@gmail.com>
1 parent a356293 commit fde94f2

File tree

1 file changed

+56
-21
lines changed

1 file changed

+56
-21
lines changed

‎geps/gep-91/index.md‎

Lines changed: 56 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -35,21 +35,30 @@ This proposal adds the ability to validate the TLS certificate presented by the
3535
These two validation mechanisms operate independently and can be used simultaneously.
3636
* 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.
3737
* 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:
38-
1) `AllowValidOnly` (Core Support)
39-
2) `AllowInsecureFallback` (Extended Support)
38+
1. `AllowValidOnly` (Core Support)
39+
2. `AllowInsecureFallback` (Extended Support)
4040

41-
`AllowInsecureFallback` mode indicates the gateway will accept connections even if the client certificate is not presented or fails verification.
41+
`AllowInsecureFallback` mode indicates the gateway will accept connections even if the client certificate is not presented or fails verification.
4242
This approach delegates client authorization to the backend and introduce a significant security risk. It should be used in testing environments or
4343
on a temporary basis in non-testing environments.
4444
When `FrontendValidationModeType` is changed from `AllowValidOnly` to `AllowInsecureFallback` the `InsecureFrontendValidationMode` condition MUST be set to `True` with Reason `ConfigurationChanged` on gateway.
45+
This condition is removed as soon as `FrontendValidationModeType` is changed back to `AllowValidOnly`.
46+
4547
* Introduce a `ObjectReference` structure that can be used to specify `caCertificateRefs` references.
48+
* Invalid `caCertificateRefs` directly affect the `ResolvedRefs` and `Accepted` conditions of the targeted listeners.
49+
* **For a `perPort` configuration**: A listener is considered targeted if and only if it serves HTTPS and its port
50+
matches the port specified in the per-port configuration.
51+
* **For the `default` configuration**: A listener is considered targeted if and only if it serves HTTPS and its port
52+
does not match any of the per-port configurations.
53+
This behavior is important to ensure that when all CA certificates are invalid, listeners do not implicitly fall
54+
back to skipping client certificate verification.
4655

4756
### Impact on listeners
4857

4958
This proposal removes frontendTLSValidation from Listener's TLS configuration and introduces gateways level per port configuration. This is a breaking change for existing implementation which uses this feature from Experimental API.
5059
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 serving HTTPS that match the configuration.
5160

52-
#### GO
61+
#### Go
5362

5463
```go
5564
// ObjectReference identifies an API object including its namespace.
@@ -142,27 +151,51 @@ type TLSPortConfig struct {
142151
// FrontendTLSValidation holds configuration information that can be used to validate
143152
// the frontend initiating the TLS connection
144153
type FrontendTLSValidation struct {
145-
// CACertificateRefs contains one or more references to
146-
// Kubernetes objects that contain TLS certificates of
147-
// the Certificate Authorities that can be used
148-
// as a trust anchor to validate the certificates presented by the client.
154+
// CACertificateRefs contains one or more references to Kubernetes
155+
// objects that contain a PEM-encoded TLS CA certificate bundle, which
156+
// is used as a trust anchor to validate the certificates presented by
157+
// the client.
158+
//
159+
// A CACertificateRef is invalid if:
149160
//
150-
// A single CA certificate reference to a Kubernetes ConfigMap
151-
// has "Core" support.
152-
// Implementations MAY choose to support attaching multiple CA certificates to
153-
// a Listener, but this behavior is implementation-specific.
161+
// * It refers to a resource that cannot be resolved (e.g., the
162+
// referenced resource does not exist) or is misconfigured (e.g., a
163+
// ConfigMap does not contain a key named `ca.crt`). In this case, the
164+
// Reason must be set to `InvalidCACertificateRef` and the Message of
165+
// the Condition must indicate which reference is invalid and why.
154166
//
155-
// Support: Core - A single reference to a Kubernetes ConfigMap
156-
// with the CA certificate in a key named `ca.crt`.
167+
// * It refers to an unknown or unsupported kind of resource. In this
168+
// case, the Reason must be set to `InvalidKind` and the Message of
169+
// the Condition must explain which kind of resource is unknown or
170+
// unsupported.
171+
//
172+
// * It refers to a resource in another namespace UNLESS there is a
173+
// ReferenceGrant in the target namespace that allows the CA
174+
// certificate to be attached. If a ReferenceGrant does not allow this
175+
// reference, the `ResolvedRefs` condition MUST be set with
176+
// the Reason `RefNotPermitted`.
177+
//
178+
// Implementations MAY choose to perform further validation of the
179+
// certificate content (e.g., checking expiry or enforcing specific formats).
180+
// In such cases, an implementation-specific Reason and Message MUST be set.
157181
//
158-
// Support: Implementation-specific (More than one certificate in a ConfigMap with different keys or more than one reference, or other kinds of resources).
182+
// In all cases, the implementation MUST ensure that the `ResolvedRefs`
183+
// condition is set to `status: False` on all targeted listeners (i.e.,
184+
// listeners serving HTTPS on a matching port). The condition MUST
185+
// include a Reason and Message that indicate the cause of the error. If
186+
// ALL CACertificateRefs are invalid, the implementation MUST also ensure
187+
// the `Accepted` condition on the listener is set to `status: False`, with
188+
// the Reason `NoValidCACertificate`.
189+
// Implementations MAY choose to support attaching multiple CA certificates
190+
// to a listener, but this behavior is implementation-specific.
159191
//
160-
// References to a resource in a different namespace are invalid UNLESS there
161-
// is a ReferenceGrant in the target namespace that allows the certificate
162-
// to be attached. If a ReferenceGrant does not allow this reference, the
163-
// "ResolvedRefs" condition MUST be set to False for this listener with the
164-
// "RefNotPermitted" reason.
192+
// Support: Core - A single reference to a Kubernetes ConfigMap, with the
193+
// CA certificate in a key named `ca.crt`.
165194
//
195+
// Support: Implementation-specific - More than one reference, other kinds
196+
// of resources, or a single reference that includes multiple certificates.
197+
//
198+
// +listType=atomic
166199
// +kubebuilder:validation:MaxItems=8
167200
// +kubebuilder:validation:MinItems=1
168201
CACertificateRefs []ObjectReference `json:"caCertificateRefs,omitempty"`
@@ -182,7 +215,9 @@ type FrontendTLSValidation struct {
182215
//
183216
// Defaults to AllowValidOnly.
184217
//
185-
// Support: Core
218+
// Support: Core - AllowValidOnly
219+
//
220+
// Support: Extended - AllowInsecureFallback
186221
//
187222
// +optional
188223
// +kubebuilder:default=AllowValidOnly

0 commit comments

Comments
 (0)