forked from kubernetes-sigs/gateway-api
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add GEP-3155: Complete Backend mTLS Configuration (kubernetes-sigs#3180)
* Initial commit * Pending changes exported from your codespace * Update geps/gep-3155/index.md Co-authored-by: Mike Morris <mikemorris@users.noreply.github.com> * Initial commit * Initial commit * Initial commit * Initial commit * Fix enum values * Initial commit * Pending changes exported from your codespace * Fix indentation * Fix indentation * Update geps/gep-3155/index.md Co-authored-by: Nick Young <inocuo@gmail.com> * Update geps/gep-3155/index.md Co-authored-by: Nick Young <inocuo@gmail.com> * Removed per-service override from the proposal * - Reverted back changes necessary for the GatewaySpec - Added clarifications * Update geps/gep-3155/index.md Co-authored-by: Rob Scott <rob.scott87@gmail.com> * Update geps/gep-3155/index.md Co-authored-by: Rob Scott <rob.scott87@gmail.com> * Update geps/gep-3155/index.md Co-authored-by: Rob Scott <rob.scott87@gmail.com> * Update geps/gep-3155/index.md Co-authored-by: Rob Scott <rob.scott87@gmail.com> --------- Co-authored-by: Mike Morris <mikemorris@users.noreply.github.com> Co-authored-by: Nick Young <inocuo@gmail.com> Co-authored-by: Rob Scott <rob.scott87@gmail.com>
- Loading branch information
Showing
3 changed files
with
212 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,198 @@ | ||
# GEP-3155: Complete Backend mutual TLS Configuration | ||
|
||
* Issue: [#3155](https://github.com/kubernetes-sigs/gateway-api/issues/3155) | ||
* Status: Implementable | ||
|
||
## TLDR | ||
|
||
This GEP aims to complete the configuration required for Backend mutual TLS in Gateway | ||
API. This includes the following new capabilities: | ||
|
||
1. Configuration for the client certificate Gateways should use when connecting | ||
to Backends | ||
1. Ability to specify SANs on BackendTLSPolicy | ||
1. Add TLS options to BackendTLSPolicy to mirror TLS config on Gateways | ||
|
||
## Goals | ||
|
||
* Add sufficient configuration that basic mutual TLS is possible between Gateways and | ||
Backends | ||
* Enable the optional use of SPIFFE for Backend mutual TLS | ||
|
||
## Non-Goals | ||
|
||
* Define how automatic mTLS should be implemented with Gateway API | ||
|
||
## Introduction | ||
|
||
This is a wide ranging GEP intending to cover three additions to the API that all | ||
have a shared goal - enabling backend mutual TLS with Gateway API. Although this | ||
specific GEP focuses on manual configuration across the board, the hope is that | ||
it will also enable higher level automation to simplify this process for users. | ||
|
||
## API | ||
|
||
### Client Certs on Gateways | ||
|
||
A key requirement of mutual TLS is that the Gateway can provide a client cert to the | ||
backend. This adds that configuration to both Gateway and Service (via | ||
BackendTLSPolicy). | ||
|
||
#### Gateway-level (Core support) | ||
Specifying credentials at the gateway level is the default operation mode, where all | ||
backends will be presented with a single gateway certificate. Per-service overrides are | ||
subject for consideration as the future work. | ||
|
||
**1. Add a new `BackendTLS` field at the top level of Gateways** | ||
|
||
```go | ||
type GatewaySpec struct { | ||
// BackendTLS configures TLS settings for when this Gateway is connecting to | ||
// backends with TLS. | ||
BackendTLS GatewayBackendTLS `json:"backendTLS,omitempty"' | ||
} | ||
type GatewayBackendTLS struct { | ||
// ClientCertificateRef is a reference to an object that contains a Client | ||
// Certificate and the associated private key. | ||
// | ||
// References to a resource in 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. | ||
// | ||
// ClientCertificateRef can reference to standard Kubernetes resources, i.e. | ||
// Secret, or implementation-specific custom resources. | ||
// | ||
// This setting can be overriden on the service level by use of BackendTLSPolicy. | ||
ClientCertificateRef SecretObjectReference `json:"clientCertificateRef,omitempty"` | ||
} | ||
``` | ||
|
||
### SANs on BackendTLSPolicy | ||
|
||
This change enables the backend certificate to have a different identity than the SNI | ||
(both are currently tied to the hostname field). This is particularly useful | ||
when using SPIFFE, which relies on URI Subject Names which are not valid SNIs | ||
as per https://www.rfc-editor.org/rfc/rfc6066.html#section-3. | ||
|
||
In such case either connection properties or an arbitrary SNI, like cluster-local | ||
service name could be used for certificate selection, while the identity validation | ||
will be done based on SubjectAltNames field. | ||
|
||
When specified, the certificate served from the backend MUST have at least one Subject | ||
Alternate Name matching one of the specified SubjectAltNames. | ||
|
||
|
||
|
||
**1. Add a new `SubjectAltNames` field to `BackendTLSPolicyValidation`** | ||
|
||
```go | ||
type BackendTLSPolicyValidation struct { | ||
// SubjectAltNames contains one or more Subject Alternative Names. | ||
// When specified, the certificate served from the backend MUST have at least one | ||
// Subject Alternate Name matching one of the specified SubjectAltNames. | ||
// +kubebuilder:validation:MaxItems=5 | ||
SubjectAltNames []SubjectAltName `json:"subjectAltNames,omitempty"` | ||
} | ||
// +kubebuilder:validation:Enum=Cookie;Header | ||
type SubjectAltNameType string | ||
const ( | ||
// HostnameSubjectAltNameType specifies hostname-based SAN. | ||
// | ||
// Support: Core | ||
HostnameSubjectAltNameType SubjectAltNameType = "Hostname" | ||
// URISubjectAltNameType specifies URI-based SAN, e.g. SPIFFE id. | ||
// | ||
// Support: Core | ||
URISubjectAltNameType SubjectAltNameType = "URI" | ||
) | ||
type SubjectAltName struct { | ||
// Type determines the format of the Subject Alternative Name. Always required. | ||
Type SubjectAltNameType `json:"type"` | ||
// Hostname contains Subject Alternative Name specified in DNS name format. Required when Type is set to Hostname, ignored otherwise. | ||
Hostname v1.PreciseHostname `json:"hostname,omitempty"` | ||
// URI contains Subject Alternative Name specified in URI format. Required when Type is set to URI, ignored otherwise. | ||
URI string `json:"uri,omitempty"` | ||
} | ||
``` | ||
|
||
**2. Modify Spec for `BackendTLSPolicyValidation` `Hostname`** | ||
|
||
Before: | ||
```go | ||
// 2. Hostname MUST be used for authentication and MUST match the certificate | ||
// served by the matching backend. | ||
``` | ||
|
||
After: | ||
```go | ||
// 2. Only if SubjectAltNames is not specified, Hostname MUST be used for | ||
// authentication and MUST match the certificate served by the matching | ||
// backend. | ||
``` | ||
|
||
### Allow per-service TLS settings BackendTLSPolicy | ||
|
||
Gateway level TLS configuration already includes an `options` field. This has | ||
been helpful for implementation-specific TLS configurations, or simply features | ||
that have not made it to the core API yet. It would be similarly useful to have | ||
an identical field on BackendTLSPolicy. | ||
|
||
Examples: | ||
- configuration options for vendor-specific mTLS automation | ||
- restrictions on the minimum supported TLS version or supported cipher suites | ||
|
||
```go | ||
type BackendTLSPolicySpec struct { | ||
// Options are a list of key/value pairs to enable extended TLS | ||
// configuration for each implementation. For example, configuring the | ||
// minimum TLS version or supported cipher suites. | ||
// | ||
// A set of common keys MAY be defined by the API in the future. To avoid | ||
// any ambiguity, implementation-specific definitions MUST use | ||
// domain-prefixed names, such as `example.com/my-custom-option`. | ||
// Un-prefixed names are reserved for key names defined by Gateway API. | ||
// | ||
// Support: Implementation-specific | ||
// | ||
// +optional | ||
// +kubebuilder:validation:MaxProperties=16 | ||
Options map[AnnotationKey]AnnotationValue `json:"options,omitempty"` | ||
} | ||
``` | ||
|
||
## Conformance Details | ||
|
||
Conformance tests will be written to ensure the following: | ||
|
||
1. When SubjectAltNames are specified in BackendTLSPolicy: | ||
|
||
- The hostname field is still used as SNI, if specified | ||
- A certificate with at least one matching SubjectAltName is accepted | ||
- A certificate without a matching SubjectAltName is rejected | ||
|
||
2. When a Client Certificate is specified on a Gateway: | ||
|
||
- It is applied to all services. | ||
- The appropriate status condition is populated if the reference is invalid | ||
|
||
## Future work | ||
This GEP does not cover per-service overrides for client certificate. This is mostly for two reasons: | ||
|
||
- it supports only the niche use cases - it should be reconsidered in future | ||
- in current model, where BackendTLSPolicy shares namespace with the service instead of the Gateway, there are non-trivial security implications to adding client certificate configuration at this level - therefore ownership and colocation of BackendTLSPolicy (Service vs Gateway) needs to be figured out first | ||
|
||
## References | ||
|
||
This is a natural continuation of | ||
[GEP-2907](https://gateway-api.sigs.k8s.io/geps/gep-2907/), the memorandum GEP | ||
that provided the overall vision for where TLS configuration should fit | ||
throughout Gateway API. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,13 @@ | ||
apiVersion: internal.gateway.networking.k8s.io/v1alpha1 | ||
kind: GEPDetails | ||
number: 3155 | ||
name: Complete Backend mutual TLS Configuration | ||
status: Implementable | ||
authors: | ||
- mkosieradzki | ||
- robscott | ||
relationships: | ||
seeAlso: | ||
- number: 2907 | ||
name: TLS Configuration Placement and Terminology | ||
description: Will use some of the terminology defined by this GEP. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters