GEP-3155: Complete Backend mutual TLS Configuration¶
- Issue: #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:
- Configuration for the client certificate Gateways should use when connecting to Backends
- Ability to specify SANs on BackendTLSPolicy
- 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
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
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:
// 2. Hostname MUST be used for authentication and MUST match the certificate
// served by the matching backend.
After:
// 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
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:
-
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
-
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, the memorandum GEP that provided the overall vision for where TLS configuration should fit throughout Gateway API.