Skip to content

gep: refine CACertificateRefs description for frontend TLS #4183

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 2 commits into
base: main
Choose a base branch
from
+56 −21
Open

gep: refine CACertificateRefs description for frontend TLS #4183

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
37efe3a
gep: refine CACertificateRefs description for frontend TLS
snorwin Oct 17, 2025
6a188d6
apply PR feedback
snorwin Oct 24, 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
77 changes: 56 additions & 21 deletions geps/gep-91/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,21 +35,30 @@ This proposal adds the ability to validate the TLS certificate presented by the
These two validation mechanisms operate independently and can be used simultaneously.
* 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.
* 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:
1) `AllowValidOnly` (Core Support)
2) `AllowInsecureFallback` (Extended Support)
1. `AllowValidOnly` (Core Support)
2. `AllowInsecureFallback` (Extended Support)

`AllowInsecureFallback` mode indicates the gateway will accept connections even if the client certificate is not presented or fails verification.
`AllowInsecureFallback` mode indicates 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.
When `FrontendValidationModeType` is changed from `AllowValidOnly` to `AllowInsecureFallback` the `InsecureFrontendValidationMode` condition MUST be set to `True` with Reason `ConfigurationChanged` on gateway.
This condition is removed as soon as `FrontendValidationModeType` is changed back to `AllowValidOnly`.

* Introduce a `ObjectReference` structure that can be used to specify `caCertificateRefs` references.
* Invalid `caCertificateRefs` directly affect the `ResolvedRefs` and `Accepted` conditions of the targeted listeners.
* **For a `perPort` configuration**: A listener is considered targeted if and only if it serves HTTPS and its port
matches the port specified in the per-port configuration.
* **For the `default` configuration**: A listener is considered targeted if and only if it serves HTTPS and its port
does not match any of the per-port configurations.
This behavior is important to ensure that when all CA certificates are invalid, listeners do not implicitly fall
back to skipping client certificate verification.

### Impact on listeners

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.
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.

#### GO
#### Go

```go
// ObjectReference identifies an API object including its namespace.
Expand Down Expand Up @@ -142,27 +151,51 @@ type TLSPortConfig struct {
// FrontendTLSValidation holds configuration information that can be used to validate
// the frontend initiating the TLS connection
type FrontendTLSValidation struct {
// CACertificateRefs contains one or more references to
// Kubernetes objects that contain TLS certificates of
// the Certificate Authorities that can be used
// as a trust anchor to validate the certificates presented by the client.
// CACertificateRefs contains one or more references to Kubernetes
// objects that contain a PEM-encoded TLS CA certificate bundle, which
// is used as a trust anchor to validate the certificates presented by
// the client.
//
// A CACertificateRef is invalid if:
//
// A single CA certificate reference to a Kubernetes ConfigMap
// has "Core" support.
// Implementations MAY choose to support attaching multiple CA certificates to
// a Listener, but this behavior is implementation-specific.
// * It refers to a resource that cannot be resolved (e.g., the
// referenced resource does not exist) or is misconfigured (e.g., a
// ConfigMap does not contain a key named `ca.crt`). In this case, the
// Reason must be set to `InvalidCACertificateRef` and the Message of
// the Condition must indicate which reference is invalid and why.
//
// Support: Core - A single reference to a Kubernetes ConfigMap
// with the CA certificate in a key named `ca.crt`.
// * It refers to an unknown or unsupported kind of resource. In this
// case, the Reason must be set to `InvalidKind` and the Message of
// the Condition must explain which kind of resource is unknown or
// unsupported.
//
// * It refers to a resource in another namespace UNLESS there is a
// ReferenceGrant in the target namespace that allows the CA
// certificate to be attached. If a ReferenceGrant does not allow this
// reference, the `ResolvedRefs` condition MUST be set with
// the Reason `RefNotPermitted`.
//
// Implementations MAY choose to perform further validation of the
// certificate content (e.g., checking expiry or enforcing specific formats).
// In such cases, an implementation-specific Reason and Message MUST be set.
//
// Support: Implementation-specific (More than one certificate in a ConfigMap with different keys or more than one reference, or other kinds of resources).
// In all cases, the implementation MUST ensure that the `ResolvedRefs`
// condition is set to `status: False` on all targeted listeners (i.e.,
// listeners serving HTTPS on a matching port). The condition MUST
// include a Reason and Message that indicate the cause of the error. If
// ALL CACertificateRefs are invalid, the implementation MUST also ensure
// the `Accepted` condition on the listener is set to `status: False`, with
// the Reason `NoValidCACertificate`.
// Implementations MAY choose to support attaching multiple CA certificates
// to a listener, but this behavior is implementation-specific.
//
// References to a resource in a different namespace are invalid UNLESS there
// is a ReferenceGrant in the target namespace that allows the certificate
// to be attached. If a ReferenceGrant does not allow this reference, the
// "ResolvedRefs" condition MUST be set to False for this listener with the
// "RefNotPermitted" reason.
// 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, other kinds
// of resources, or a single reference that includes multiple certificates.
//
// +listType=atomic
// +kubebuilder:validation:MaxItems=8
// +kubebuilder:validation:MinItems=1
Copy link
Member Author

@snorwin snorwin Oct 24, 2025

Choose a reason for hiding this comment

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

@kl52752 I’m wondering if cACertificateRefs should be optional when using the AllowInsecureFallback mode, or if that case would justify adding a separate mode.

Copy link
Contributor

@kl52752 kl52752 Oct 24, 2025

Choose a reason for hiding this comment

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

Well Insecure mode is design for validating the setup (fg. using mtl headers) not to bypass it (fg in testing env). Why would some wants to have mTLS enalbed without CA set?

Copy link
Member Author

@snorwin snorwin Oct 27, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I tried to summarize all the different cases and how we interpreted the specification and how we’ve implemented it so far.

Mode Client certificate presented Response of the Gateway
AllowInsecureFallback No certificate (TLS) Accepted
AllowInsecureFallback Certificate not signed by the trusted CA Accepted
AllowInsecureFallback Certificate signed by the trusted CA Accepted
AllowValidOnly No certificate (TLS) Rejected (TLS handshake fails)
AllowValidOnly Certificate not signed by the trusted CA Rejected (TLS handshake fails)
AllowValidOnly Certificate signed by the trusted CA Accepted

@kl52752 could you please check if this table matches your expectations?
If it looks good, I’ll probably include it (or a similar version) in the GEP.

According to the cases described in the table, in my opinion the Gateway’s behavior wouldn’t change depending on whether client CA certificates are configured when using AllowInsecureFallback.

This raises the question, why do we enforce configuring CA certificates for AllowInsecureFallback if it doesn’t directly affect the Gateway’s behavior?
However, it does have a noticeable impact on the client side, the client behaves quite differently when the Gateway presents the client certificate CA during negotiation, e.g., without additional workarounds, it’s not possible to connect with a browser or the Go HTTP client to a Gateway with AllowInsecureFallback using a self-signed client certificate.

Copy link
Contributor

@kl52752 kl52752 Oct 27, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

yes this table summarized it all 👍

This raises the question, why do we enforce configuring CA certificates for AllowInsecureFallback if it doesn’t directly affect the Gateway’s behavior?

The purpose for AllowInsecureFallback is for testing purposes (or for a short period of time when credentials need to be rotated). This should be used either on testing environments or together with mTLS custom headers where the information about tls handshakes are passed. That's why I don't think that we should allow for empty CA cert list because this mode is not meant for bypassing the validation but move the "decision" for allowing the traffic to backend.

Copy link
Member Author

@snorwin snorwin Oct 28, 2025

Choose a reason for hiding this comment

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

I'm happy to leave it as it is, but before resolving the discussion, I would appreciate some input from others as well.

/cc @howardjohn @shaneutt @youngnick

CACertificateRefs []ObjectReference `json:"caCertificateRefs,omitempty"`
Expand All @@ -182,7 +215,9 @@ type FrontendTLSValidation struct {
//
// Defaults to AllowValidOnly.
//
// Support: Core
// Support: Core - AllowValidOnly
//
// Support: Extended - AllowInsecureFallback
//
// +optional
// +kubebuilder:default=AllowValidOnly
Expand Down