From 3385054478bfc640966d6ffd59aed4012f85c014 Mon Sep 17 00:00:00 2001 From: Norwin Schnyder Date: Wed, 10 Sep 2025 07:35:47 +0000 Subject: [PATCH 1/3] gep: provisional GEP for certificate pinning (#4078) Signed-off-by: Norwin Schnyder --- geps/gep-4078/index.md | 25 +++++++++++++++++++++++++ geps/gep-4078/metadata.yaml | 35 +++++++++++++++++++++++++++++++++++ geps/gep-91/metadata.yaml | 26 ++++++++++++++++++++++++++ 3 files changed, 86 insertions(+) create mode 100644 geps/gep-4078/index.md create mode 100644 geps/gep-4078/metadata.yaml diff --git a/geps/gep-4078/index.md b/geps/gep-4078/index.md new file mode 100644 index 0000000000..71e485642a --- /dev/null +++ b/geps/gep-4078/index.md @@ -0,0 +1,25 @@ +# GEP-4078: Certificate Pinning for Client Certificate Validation + +* Issue: [#4078](https://github.com/kubernetes-sigs/gateway-api/issues/4078) +* Status: Provisional + +(See [status definitions](../overview.md#gep-states).) + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this +document are to be interpreted as described in BCP 14 ([RFC8174]) when, and +only when, they appear in all capitals, as shown here. + +[RFC8174]: https://www.rfc-editor.org/rfc/rfc8174 + +## What +Enhance the existing Client Certificate Validation defined in [GEP-91](../gep-91/index.md) by introducing support for certificate pinning. This allows specifying one or more certificate or public key hashes (SPKI) that are considered valid for client connections. During TLS client authentication, the Gateway will validate not only against the configured CAs, but also against the pinned certificates or keys. This provides a mechanism to restrict allowed clients to a narrowly defined set of certificates, even if the CA trust domain is broad. + +## Why +While [GEP-91](../gep-91/index.md) enables client certificate validation against a CA, in practice many operators rely on large organizational CAs or even on public CAs. These often cover many certificates and, as a result, unintentionally expand the trust boundary. This limitation becomes particularly significant when client certificates are used not only for encryption but also for authentication. In these cases, operators may want to restrict access to an explicit set of identities, rather than the entire population served by a CA. +In addition, certificate pinning strengthens security by reducing exposure to rogue certificates and mitigating the risk of man-in-the-middle (MITM) attacks. + +## Who: Beneficiaries +* **Application Developers**: Can use certificate pinning as a lightweight alternative to JWTs or other token systems, authenticating users or devices directly through TLS without additional infrastructure. +* **Platform Operators/Administrators**: Gain a standardized way to enforce fine-grained client restrictions, even when using broad or public CAs, which improves security. +* **Security and Compliance Teams**: Benefit from a certificate-bound authentication mechanism that limits access to explicitly approved identities, aligning with regulatory and organizational policies. \ No newline at end of file diff --git a/geps/gep-4078/metadata.yaml b/geps/gep-4078/metadata.yaml new file mode 100644 index 0000000000..45abc8686e --- /dev/null +++ b/geps/gep-4078/metadata.yaml @@ -0,0 +1,35 @@ +apiVersion: internal.gateway.networking.k8s.io/v1alpha1 +kind: GEPDetails +number: 4078 +name: Certificate Pinning for Client Certificate Validation +status: Provisional +# Any authors who contribute to the GEP in any way should be listed here using +# their GitHub handle. +authors: + - snorwin +relationships: + # obsoletes indicates that a GEP makes the linked GEP obsolete, and completely + # replaces that GEP. The obsoleted GEP MUST have its obsoletedBy field + # set back to this GEP, and MUST be moved to Declined. + obsoletes: {} + obsoletedBy: {} + # extends indicates that a GEP extends the linked GEP, adding more detail + # or additional implementation. The extended GEP MUST have its extendedBy + # field set back to this GEP. + extends: + - number: 91 + name: Client Certificate Validation for TLS terminating at the Gateway Listener + extendedBy: {} + # seeAlso indicates other GEPs that are relevant in some way without being + # covered by an existing relationship. + seeAlso: {} +# references is a list of hyperlinks to relevant external references. +# It's intended to be used for storing GitHub discussions, Google docs, etc. +references: {} +# featureNames is a list of the feature names introduced by the GEP, if there +# are any. This will allow us to track which feature was introduced by which GEP. +# This is the value added to supportedFeatures and the conformance tests, in string form. +featureNames: {} +# changelog is a list of hyperlinks to PRs that make changes to the GEP, in +# ascending date order. +changelog: {} diff --git a/geps/gep-91/metadata.yaml b/geps/gep-91/metadata.yaml index 409fd393e1..6cf638b4bd 100644 --- a/geps/gep-91/metadata.yaml +++ b/geps/gep-91/metadata.yaml @@ -5,3 +5,29 @@ name: Client Certificate Validation for TLS terminating at the Gateway Listener status: Provisional authors: - arkodg +relationships: + # obsoletes indicates that a GEP makes the linked GEP obsolete, and completely + # replaces that GEP. The obsoleted GEP MUST have its obsoletedBy field + # set back to this GEP, and MUST be moved to Declined. + obsoletes: {} + obsoletedBy: {} + # extends indicates that a GEP extends the linked GEP, adding more detail + # or additional implementation. The extended GEP MUST have its extendedBy + # field set back to this GEP. + extends: {} + extendedBy: + - number: 4078 + name: Certificate Pinning for Client Certificate Validation + # seeAlso indicates other GEPs that are relevant in some way without being + # covered by an existing relationship. + seeAlso: {} +# references is a list of hyperlinks to relevant external references. +# It's intended to be used for storing GitHub discussions, Google docs, etc. +references: {} +# featureNames is a list of the feature names introduced by the GEP, if there +# are any. This will allow us to track which feature was introduced by which GEP. +# This is the value added to supportedFeatures and the conformance tests, in string form. +featureNames: {} +# changelog is a list of hyperlinks to PRs that make changes to the GEP, in +# ascending date order. +changelog: {} From da724f14f03421b0b07f33046278bf054f182350 Mon Sep 17 00:00:00 2001 From: Norwin Schnyder Date: Wed, 10 Sep 2025 13:40:12 +0000 Subject: [PATCH 2/3] fix GEP metadata Signed-off-by: Norwin Schnyder --- geps/gep-4078/metadata.yaml | 14 +++++++------- geps/gep-91/metadata.yaml | 22 ---------------------- 2 files changed, 7 insertions(+), 29 deletions(-) diff --git a/geps/gep-4078/metadata.yaml b/geps/gep-4078/metadata.yaml index 45abc8686e..53015c03f1 100644 --- a/geps/gep-4078/metadata.yaml +++ b/geps/gep-4078/metadata.yaml @@ -11,25 +11,25 @@ relationships: # obsoletes indicates that a GEP makes the linked GEP obsolete, and completely # replaces that GEP. The obsoleted GEP MUST have its obsoletedBy field # set back to this GEP, and MUST be moved to Declined. - obsoletes: {} - obsoletedBy: {} + obsoletes: [] + obsoletedBy: [] # extends indicates that a GEP extends the linked GEP, adding more detail # or additional implementation. The extended GEP MUST have its extendedBy # field set back to this GEP. extends: - number: 91 name: Client Certificate Validation for TLS terminating at the Gateway Listener - extendedBy: {} + extendedBy: [] # seeAlso indicates other GEPs that are relevant in some way without being # covered by an existing relationship. - seeAlso: {} + seeAlso: [] # references is a list of hyperlinks to relevant external references. # It's intended to be used for storing GitHub discussions, Google docs, etc. -references: {} +references: [] # featureNames is a list of the feature names introduced by the GEP, if there # are any. This will allow us to track which feature was introduced by which GEP. # This is the value added to supportedFeatures and the conformance tests, in string form. -featureNames: {} +featureNames: [] # changelog is a list of hyperlinks to PRs that make changes to the GEP, in # ascending date order. -changelog: {} +changelog: [] diff --git a/geps/gep-91/metadata.yaml b/geps/gep-91/metadata.yaml index 6cf638b4bd..d577cf9171 100644 --- a/geps/gep-91/metadata.yaml +++ b/geps/gep-91/metadata.yaml @@ -6,28 +6,6 @@ status: Provisional authors: - arkodg relationships: - # obsoletes indicates that a GEP makes the linked GEP obsolete, and completely - # replaces that GEP. The obsoleted GEP MUST have its obsoletedBy field - # set back to this GEP, and MUST be moved to Declined. - obsoletes: {} - obsoletedBy: {} - # extends indicates that a GEP extends the linked GEP, adding more detail - # or additional implementation. The extended GEP MUST have its extendedBy - # field set back to this GEP. - extends: {} extendedBy: - number: 4078 name: Certificate Pinning for Client Certificate Validation - # seeAlso indicates other GEPs that are relevant in some way without being - # covered by an existing relationship. - seeAlso: {} -# references is a list of hyperlinks to relevant external references. -# It's intended to be used for storing GitHub discussions, Google docs, etc. -references: {} -# featureNames is a list of the feature names introduced by the GEP, if there -# are any. This will allow us to track which feature was introduced by which GEP. -# This is the value added to supportedFeatures and the conformance tests, in string form. -featureNames: {} -# changelog is a list of hyperlinks to PRs that make changes to the GEP, in -# ascending date order. -changelog: {} From 32e9adaf158647fb3c200352a92394467c8d20bd Mon Sep 17 00:00:00 2001 From: Norwin Schnyder Date: Tue, 23 Sep 2025 12:16:03 +0000 Subject: [PATCH 3/3] apply PR feedback Signed-off-by: Norwin Schnyder --- geps/gep-4078/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/geps/gep-4078/index.md b/geps/gep-4078/index.md index 71e485642a..79c09da76a 100644 --- a/geps/gep-4078/index.md +++ b/geps/gep-4078/index.md @@ -13,7 +13,7 @@ only when, they appear in all capitals, as shown here. [RFC8174]: https://www.rfc-editor.org/rfc/rfc8174 ## What -Enhance the existing Client Certificate Validation defined in [GEP-91](../gep-91/index.md) by introducing support for certificate pinning. This allows specifying one or more certificate or public key hashes (SPKI) that are considered valid for client connections. During TLS client authentication, the Gateway will validate not only against the configured CAs, but also against the pinned certificates or keys. This provides a mechanism to restrict allowed clients to a narrowly defined set of certificates, even if the CA trust domain is broad. +Enhance the existing Client Certificate Validation defined in [GEP-91](../gep-91/index.md) by introducing support for certificate pinning. This allows specifying one or more certificate or public key hashes (SPKI) that are considered valid for client connections. During TLS client authentication, the Gateway can validate client certificates either against the configured CAs or against the pinned certificates. This provides a mechanism to restrict allowed clients to a narrowly defined set of certificates, in cases where the CA trust domain is too broad. ## Why While [GEP-91](../gep-91/index.md) enables client certificate validation against a CA, in practice many operators rely on large organizational CAs or even on public CAs. These often cover many certificates and, as a result, unintentionally expand the trust boundary. This limitation becomes particularly significant when client certificates are used not only for encryption but also for authentication. In these cases, operators may want to restrict access to an explicit set of identities, rather than the entire population served by a CA.