Skip to content

GEP 91: Update Goals and Prior Art #3838

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

Merged
merged 4 commits into from
Jun 16, 2025
Merged

GEP 91: Update Goals and Prior Art #3838

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
18b1b58
GEP 91: Update Goals and Prior Art
arkodg Jun 6, 2025
c690fe9
fix table
arkodg Jun 6, 2025
4311be3
moves prior art to the end of the file
arkodg Jun 16, 2025
44a2b48
rewrite prior art section description
arkodg Jun 16, 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
67 changes: 47 additions & 20 deletions geps/gep-91/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# GEP-91: Client Certificate Validation for TLS terminating at the Gateway Listener
# GEP-91: Client Certificate Validation for TLS terminating at the Gateway

* Issue: [#91](https://github.com/kubernetes-sigs/gateway-api/issues/91)
* Status: Implementable
Expand All @@ -8,31 +8,18 @@
## TLDR

This GEP proposes a way to validate the TLS certificate presented by the frontend client to the server
(Gateway Listener in this case) during a [TLS Handshake Protocol][].
(Gateway in this case) during a [TLS Handshake Protocol][].

## Goals

* Define an API field to specify the CA Certificate within the Gateway Listener configuration that can be used as a trust anchor to validate the certificates presented by the client. 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.
* 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.
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.
Copy link
Member

Choose a reason for hiding this comment

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

We should fix these links while we're here.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

all these links work for me

Copy link
Contributor Author

Choose a reason for hiding this comment

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

https://gateway-api.sigs.k8s.io/geps/gep-91/

Copy link
Contributor

Choose a reason for hiding this comment

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

I hadn't seen this link syntax before, that's probably where the confusion comes from. (the links are in the Reference section at the end.)

* 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).
* Supporting a mode where validating client certificates is optional, useful for debugging and migrating to strict TLS.

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

## Existing support in Implementations

This feature is widely supported in implementations that support Gateway API.
This table highlights the support. Please feel free to add any missing implementations not mentioned below.

| Implementation | Support |
|----------------|------------|
| Apache APISIX | [ApisixTls.Client.CASecret](https://apisix.apache.org/docs/ingress-controller/tutorials/mtls/#mutual-authentication) |
| Contour | [HTTPProxy.Spec.VirtualHost.Tls.ClientValidation.CASecret](https://projectcontour.io/docs/v1.17.1/config/tls-termination/) |
| Emissary Ingress| [TlSContext.Spec.Secret](https://www.getambassador.io/docs/emissary/latest/topics/running/tls/mtls) |
| Gloo Edge | [VirtualService.Spec.SSLConfig.SecretRef](https://docs.solo.io/gloo-edge/latest/guides/security/tls/server_tls/#configuring-downstream-mtls-in-a-virtual-service) |
| Istio | [Gateway.Spec.Servers.TLS.Mode](https://istio.io/latest/docs/tasks/traffic-management/ingress/secure-ingress/#configure-a-mutual-tls-ingress-gateway) |
| Kong | [mTLS Plugin](https://docs.konghq.com/hub/kong-inc/mtls-auth/) |
| Traefik | [TLSOption.Spec.ClientAuth](https://doc.traefik.io/traefik/https/tls/#client-authentication-mtls) |
| NGINX Ingress Controller | [ingressMTLS](https://docs.nginx.com/nginx-ingress-controller/configuration/policy-resource/#ingressmtls) |

### API

* 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.
Expand Down Expand Up @@ -151,10 +138,50 @@ spec:
This section highlights use cases that may be covered in a future iteration of this GEP

* Using system CA certificates as the trust anchor to validate the certificates presented by the frontend client.
* Supporting a mode where validating client certificates is optional, useful for debugging and migrating to strict TLS.
* Supporting an optional `subjectAltNames` field within `FrontendTLSValidation` that can be used to specify one or more alternate names to verify the subject identity in the certificate presented by the client. This field falls under Authorization, the initial focus here is on Client Authentication and will be revisited when Authorization is tackled as a whole in the project.
* Specifying the verification depth in the client certificate chain. This is being deferred because the default verification depth differs across implementations.

## Existing support in Implementations

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

| Implementation | Support | Granularity | Inline vs Policy |
|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|------------------|
| Acnodal EPIC | | | |
| Airlock Microgateway | [SidecarGateway.spec.applications[].downstream.tls.clientCertificate](https://docs.airlock.com/microgateway/latest/index/api/crds/sidecar-gateway/v1alpha1/index.html#sidecargatewayspecapplicationsdownstreamtls) | Per Listener | Inline |
| Amazon Elastic Kubernetes Service | | | |
| Apache APISIX | [ApisixTls.Client.CASecret](https://apisix.apache.org/docs/ingress-controller/tutorials/mtls/#mutual-authentication) | Per SNI | |
| Avi Kubernetes Operator | | | |
| Azure Application Gateway for Containers | [FrontendTLSPolicy](https://learn.microsoft.com/en-us/azure/application-gateway/for-containers/api-specification-kubernetes#alb.networking.azure.io/v1.FrontendTLSPolicy) | Per Gateway & Per Listener | Policy |
| Cilium | | | |
| Contour | [HTTPProxy.Spec.VirtualHost.Tls.ClientValidation.CASecret](https://projectcontour.io/docs/v1.17.1/config/tls-termination/) | Per SNI | Inline |
| Easegress | | | |
| Emissary Ingress | [TlSContext.Spec.CASecret](https://www.getambassador.io/docs/emissary/latest/howtos/client-cert-validation) | Per SNI | Policy |
| Envoy Gateway | [ClientTrafficPolicy.Spec.TLS.ClientValidation](https://gateway.envoyproxy.io/docs/api/extension_types/#clientvalidationcontext) | Per Gateway & Per Listener | Policy |
| Flomesh Service Mesh | | | |
| Gloo Gateway | [VirtualService.Spec.SSLConfig.SecretRef](https://docs.solo.io/gloo-edge/latest/guides/security/tls/server_tls/#configuring-downstream-mtls-in-a-virtual-service) | Per SNI | Inline |
| Google Cloud Service Mesh | | | |
| Google Kubernetes Engine | | | |
| HAProxy Ingress | | | |
| HAProxy Kubernetes Ingress Controller | [ca-file](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/security/authentication/client-certificate-authentication/#sidebar) | Per SNI | Inline |
| HashiCorp Consul | [file-system-certificate](https://developer.hashicorp.com/consul/docs/north-south/api-gateway/secure-traffic/encrypt) | Per Listener | Policy |
| Istio | [Gateway.Spec.Servers.TLS.Mode](https://istio.io/latest/docs/tasks/traffic-management/ingress/secure-ingress/#configure-a-mutual-tls-ingress-gateway) | Per Server | Inline |
| kgateway | | | |
| Kong Kubernetes Ingress Controller | [mTLS Plugin](https://docs.konghq.com/hub/kong-inc/mtls-auth/) | Per HTTP Proxy (Host/Port) | Policy |
| Kong Gateway Operator | [mTLS Plugin](https://docs.konghq.com/hub/kong-inc/mtls-auth/) | Per HTTP Proxy (Host/Port) | Policy |
| Kuma | | | |
| Linkerd | | | |
| LiteSpeed Ingress Controller | | | |
| LoxiLB | | | |
| NGINX Gateway Fabric | [ingressMTLS](https://docs.nginx.com/nginx-ingress-controller/configuration/policy-resource/#ingressmtls) | Per Listener | Policy |
| ngrok Kubernetes Operator | [TrafficPolicy.Terminate-TLS.Config.MutualTLSCertificateAuthorities](https://ngrok.com/docs/traffic-policy/actions/terminate-tls/#configuration-reference) | Per Endpoint (Host:Port) | Policy |
| STUNner | | | |
| Traefik Proxy | [TLSOption.Spec.ClientAuth](https://doc.traefik.io/traefik/https/tls/#client-authentication-mtls) | Per EntryPoint | Inline |
| Tyk | [Enable Client Certificate](https://tyk.io/docs/basic-config-and-security/security/mutual-tls/client-mtls/#why-use-mutual-tls) | Per Gateway | Policy |
| WSO2 APK | [Authentication.Spec.Default.AuthTypes.MTLS](https://apk.docs.wso2.com/en/latest/catalogs/crds/authentication_types/#dp.wso2.com/v1alpha2.MutualSSLConfig) | Per API | Policy |
| Ingress-NGINX | [nginx.ingress.kubernetes.io/auth-tls-verify-client](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#client-certificate-authentication) | Per Ingress | Inline |

## References

Expand Down