Feature: mtls filters (#4044)

Author: szuecs

AGENTS.md

@@ -22,6 +22,7 @@ Backend is the thing to which skipper should proxy, for example:
 - Start example proxy with one route: `./bin/skipper -inline-routes='r: * -> latency("1ms") -> status(201) -> <shunt>' -address :9001`
   Call the proxy: curl http://localhost:9001/
 - Run tests by package for example proxy: `go test ./proxy`
+- Run linter: `make lint`
 - Run all tests: `make check`
 - Run all tests with race detector: `make check-race`
 
@@ -32,6 +33,7 @@ Backend is the thing to which skipper should proxy, for example:
 - package docs in doc.go
 - no comments in code if they are not critical
 - no kubernetes client-go dependencies
+- run linter `make lint` and fix all findings
 
 ## Testing instructions
 

Makefile

@@ -4,8 +4,8 @@ CURRENT_VERSION     = $(shell git describe --tags --always --dirty)
 VERSION            ?= $(CURRENT_VERSION)
 COMMIT_HASH         = $(shell git rev-parse --short HEAD)
 LIMIT_FDS           = $(shell ulimit -n)
-TEST_ETCD_VERSION  ?= v3.5.11
-TEST_ETCD_CHECKSUM ?= 4fb304f384dd4d6e491e405fed8375a09ea1c6c2596b93f97cb31844202e620df160f87f18611e84f17675e7b7245e40d1aa23571ecdb507cb094ba04d378171
+TEST_ETCD_VERSION  ?= v3.6.12
+TEST_ETCD_CHECKSUM ?= d2564bb50b58e52fbaf3bde4a9561a1d04e20cdc761f795580e4d615d5d41355
 TEST_PLUGINS       = _test_plugins/filter_noop.so \
 		     _test_plugins/predicate_match_none.so \
 		     _test_plugins/dataclient_noop.so \

config/config.go

@@ -2,6 +2,7 @@ package config
 
 import (
 	"crypto/tls"
+	"crypto/x509"
 	"flag"
 	"fmt"
 	"net/http"
@@ -256,6 +257,9 @@ type Config struct {
 	ClientCertRefreshInterval time.Duration     `yaml:"client-tls-cert-refresh-interval"`
 	Certificates              []tls.Certificate `yaml:"-"`
 	EnableMTLS                bool              `yaml:"enable-mtls"`
+	MtlsAuthnAppendCA         bool              `yaml:"mtls-authn-append-ca"`
+	MtlsAuthnCaFile           string            `yaml:"mtls-authn-ca"`
+	MtlsAuthnCA               *x509.CertPool    `yaml:"-"`
 
 	// TLS version
 	TLSMinVersion string             `yaml:"tls-min-version"`
@@ -633,6 +637,8 @@ func NewConfig() *Config {
 	flag.StringVar(&cfg.ClientCertFile, "client-tls-cert", "", "TLS certificate files for backend connections, multiple keys may be given comma separated - the order must match the keys")
 	flag.DurationVar(&cfg.ClientCertRefreshInterval, "client-tls-cert-refresh-interval", 0, "How often to reload client TLS certificate and key files for backend connections. Defaults to 5 minutes if certificate files are set.")
 	// MTLS
+	flag.StringVar(&cfg.MtlsAuthnCaFile, "mtls-authn-ca", "", "PEM encoded CA files to use in mtlsAuthn() filter to validate client certificates, multiple files may be given comma separated")
+	flag.BoolVar(&cfg.MtlsAuthnAppendCA, "mtls-authn-append-ca", false, "If set to true -mtls-authn-ca will load system CAs, too.")
 	flag.BoolVar(&cfg.EnableMTLS, "enable-mtls", false, "Enables MTLS support in the proxy. It uses -client-tls-cert and -client-tls-key as files and rotates the client cert every -client-tls-cert-refresh-interval time.Duration. It only supports one cert and one key file!")
 
 	// TLS version
@@ -861,6 +867,28 @@ func (c *Config) ParseArgs(progname string, args []string) error {
 		c.Certificates = certificates
 	}
 
+	if c.MtlsAuthnAppendCA {
+		pool, err := x509.SystemCertPool()
+		if err != nil {
+			return fmt.Errorf("failed to load system cert pool: %v", err)
+		} else {
+			c.MtlsAuthnCA = pool
+		}
+	} else {
+		c.MtlsAuthnCA = x509.NewCertPool()
+	}
+	if c.MtlsAuthnCaFile != "" {
+		for f := range strings.SplitSeq(c.MtlsAuthnCaFile, ",") {
+			pem, err := os.ReadFile(f)
+			if err != nil {
+				return fmt.Errorf("failed to read %q: %v", f, err)
+			}
+			if !c.MtlsAuthnCA.AppendCertsFromPEM(pem) {
+				return fmt.Errorf("failed to append CA cert %q", f)
+			}
+		}
+	}
+
 	if c.NormalizeHost || c.KubernetesIngress {
 		c.HostPatch = net.HostPatch{
 			ToLower:           true,
@@ -1209,6 +1237,7 @@ func (c *Config) ToOptions() skipper.Options {
 	options.ClientCertFile = c.ClientCertFile
 	options.ClientKeyFile = c.ClientKeyFile
 	options.ClientCertRefreshInterval = c.ClientCertRefreshInterval
+	options.MtlsAuthnCA = c.MtlsAuthnCA
 
 	var wrappers []func(handler http.Handler) http.Handler
 	options.CustomHttpHandlerWrap = func(handler http.Handler) http.Handler {

config/config_test.go

@@ -2,6 +2,7 @@ package config
 
 import (
 	"crypto/tls"
+	"crypto/x509"
 	"errors"
 	"fmt"
 	"os"
@@ -190,6 +191,9 @@ func defaultConfig(with func(*Config)) *Config {
 		ProxyAllowListCIDRs:                     commaListFlag(),
 		ProxyDenyListCIDRs:                      commaListFlag(),
 		ProxySkipListCIDRs:                      commaListFlag(),
+		MtlsAuthnAppendCA:                       false,
+		MtlsAuthnCaFile:                         "",
+		MtlsAuthnCA:                             x509.NewCertPool(),
 	}
 	with(cfg)
 	return cfg

docs/operation/operation.md

@@ -191,6 +191,63 @@ addresses.
 
 ## Authentication and Authorization
 
+### mTLS
+
+Skipper as a proxy supports mTLS as authentication and authorization
+method as client and as server and per route via filters to check the
+data in the validated X509 certificate.
+
+#### proxy client to backend
+
+To enable proxy client to backend authentication, skipper will create
+an mTLS connection sending its client certificate as its identity to
+the backend such that backends can verify the connection is ok to
+trust.
+
+To enable this you need to use `-enable-mtls`, `-client-tls-cert` and
+`-client-tls-key`.  Skipper supports only one identity, so only one
+cert+key in the mTLS case.  The provided file paths for cert and key
+can be used to rotate cert and key. Skipper will automatically detect
+new data in these files and will reload the TLS client configuration
+to use the new cert and key. Rotation will happen every
+`-client-tls-cert-refresh-interval`, which defaults to `5m`.
+
+This configuration will enable mTLS for all connections to all
+backends of the proxy. More advanced configurations are work in
+progress:
+
+- https://github.com/zalando/skipper/issues/4072
+- https://github.com/zalando/skipper/issues/4042
+
+#### client to proxy server
+
+For mTLS to be able to work you need to terminate TLS in skipper.  If
+you want to validate client certificates for mTLS connections in
+skipper, it is possible to do so per route.
+
+Global configuration is not needed if the system CAs are enough to
+validate all client certificates.  If you want to add your own CAs,
+you can use `-mtls-authn-ca="pem1,pem2"` to add your PEM encoded CA
+bundles. If you also want to add the system CAs, too, you can use
+`-mtls-authn-append-ca=true` to load also system bundles.
+
+How mTLS authentication and authorization works per route:
+
+The client presents the client certificate and Go passes it to the
+http.Request.TLS object that we can process in filters. For example in
+the [`mtlsAuthn()`](../reference/filters.md#mtlsauthn) filter to
+validate client certificates. In order to check more details for authorization, you can add the other mtls filters after the `mtlsAuthn()` filter, like:
+
+- [`mtlsIssuerDN()`](../reference/filters.md#mtlsissuerdn)
+- [`mtlsSanCIDR()`](../reference/filters.md#mtlssancidr)
+- [`mtlsSanDNS()`](../reference/filters.md#mtlssandns)
+- [`mtlsSanIP()`](../reference/filters.md#mtlssanip)
+- [`mtlsSanURI()`](../reference/filters.md#mtlssanuri)
+
+Features are also work in progress:
+
+- https://github.com/zalando/skipper/issues/4073
+
 ### OAuth2 Tokeninfo
 
 OAuth2 filters integrate with external services and have their own

docs/reference/filters.md

@@ -561,6 +561,109 @@ Example:
 * -> tlsPassClientCertificates() -> "http://10.2.5.21:8080";
 ```
 
+### mtlsAuthn
+
+This filter validates the client certificate provided by verifying
+with the configured system CA certificates.
+
+Example:
+
+```
+* -> mtlsAuthn() -> "http://10.2.5.21:8080";
+```
+
+### mtlsIssuerDN
+
+This authz filter checks the DN value of the issuer of the provided certificate. You have
+to use `mtlsAuthn()` to verify validity.
+
+Parameters:
+
+* DN (string)
+
+Example:
+
+```
+* -> mtlsAuthn() ->  mtlsIssuerDN("CN=My CA,O=My Org,C=DE") -> "http://10.2.5.21:8080";
+```
+
+### mtlsCN
+
+This authz filter checks the CN value of the subject of the provided
+certificate. You have to use `mtlsAuthn()` to verify validity.
+
+Parameters:
+
+* CN (string)
+
+Example:
+
+```
+* -> mtlsAuthn() ->  mtlsCN("My CA") -> "http://10.2.5.21:8080";
+```
+
+### mtlsSanCIDR
+
+This authz filter checks CIDRs of the SAN value of the provided certificate. You have
+to use `mtlsAuthn()` to verify validity.
+
+Parameters are one or more:
+
+* CIDR (string)
+
+Example:
+
+```
+* -> mtlsAuthn() ->  mtlsSanCIDR("2a05:aec0::/29", "10.0.5.0/15") -> "http://10.2.5.21:8080";
+```
+
+### mtlsSanDNS
+
+This authz filter checks DNS of the SAN value of the provided certificate. You have
+to use `mtlsAuthn()` to verify validity.
+
+Parameters are one or more:
+
+* DNS hostnames (string)
+
+Example:
+
+```
+* -> mtlsAuthn() ->  mtlsSanDNS("my.host.example") -> "http://10.2.5.21:8080";
+```
+
+### mtlsSanIP
+
+This authz filter checks IPs of the SAN value of the provided certificate. You have
+to use `mtlsAuthn()` to verify validity.
+
+Parameters are one or more:
+
+* IP (string)
+
+Example:
+
+```
+* -> mtlsAuthn() ->  mtlsSanIP("2a05:aec0::5", "10.0.5.10") -> "http://10.2.5.21:8080";
+```
+
+### mtlsSanURI
+
+This authz filter checks URIs of the SAN value of the provided certificate. You have
+to use `mtlsAuthn()` to verify validity.
+
+Parameters are one or more:
+
+* URI (string)
+
+Example:
+
+```
+* -> mtlsAuthn() ->  mtlsSanURI("spiffe://my-service.example/app1") -> "http://10.2.5.21:8080";
+```
+
+
+
 ## Diagnostics
 
 These filters are meant for diagnostic or load testing purposes.

etcd/install.sh

@@ -22,7 +22,7 @@ mkdir -p .bin
 
 curl -LsSfo ./.bin/etcd.tar.gz "${ETCD_URL}"
 
-echo ${ETCD_CHECKSUM} ./.bin/etcd.tar.gz | sha512sum --check - 
+echo ${ETCD_CHECKSUM} ./.bin/etcd.tar.gz | sha256sum --check -
 
 tar -xzf .bin/etcd.tar.gz --strip-components=1 \
     -C ./.bin "etcd-${ETCD_VERSION}-linux-amd64/etcd"

filters/builtin/builtin.go

@@ -243,6 +243,12 @@ func Filters() []filters.Spec {
 		consistenthash.NewConsistentHashKey(),
 		consistenthash.NewConsistentHashBalanceFactor(),
 		tls.New(),
+		tls.NewMtlsCN(),
+		tls.NewMtlsIssuerDN(),
+		tls.NewMtlsSanCIDR(),
+		tls.NewMtlsSanDNS(),
+		tls.NewMtlsSanIP(),
+		tls.NewMtlsSanURI(),
 	}
 }
 

filters/filters.go

@@ -377,6 +377,13 @@ const (
 	OpaServeResponseName                       = "opaServeResponse"
 	OpaServeResponseWithReqBodyName            = "opaServeResponseWithReqBody"
 	TLSName                                    = "tlsPassClientCertificates"
+	MtlsIssuerDN                               = "mtlsIssuerDN"
+	MtlsSanCIDR                                = "mtlsSanCIDR"
+	MtlsSanDNS                                 = "mtlsSanDNS"
+	MtlsSanIP                                  = "mtlsSanIP"
+	MtlsSanURI                                 = "mtlsSanURI"
+	MtlsCN                                     = "mtlsCN"
+	MtlsAuthn                                  = "mtlsAuthn"
 	AWSSigV4Name                               = "awsSigv4"
 	LoopbackIfStatus                           = "loopbackIfStatus"
 	CacheName                                  = "cache"