design: backend TLS with client certificate (projectcontour#2338)

Signed-off-by: Tero Saarni <tero.saarni@est.tech>

design/tls-backend-client-authentication.md

@@ -0,0 +1,42 @@
+# Backend TLS: client authentication
+
+Status: Draft
+
+This proposal describes how to implement support for client certificate for Envoy for the TLS connection between Envoy and backend services.
+
+## Goals
+
+- Envoy shall be able authenticate itself to the backend
+- Backend service shall be able to request clients to present their client certificate
+
+## Non Goals
+
+- Configure several client certificates for Envoy e.g. different client certificate per each backend
+
+## Background
+
+It is already possible to use TLS for the connection between Envoy and the backend service.
+However only the backend is authenticated and the backend is not able to authenticate Envoy.
+Since the backend has no means to differentiate between clients, any client within the cluster network is able to access backend's resources.
+This could potentially include vulnerable software which might be running within the cluster and remotely exploited to access the backend.
+
+After external client certificate validation was introduced to Contour 1.4.0, it makes sense to allow configuring client certificates for the TLS connection between Envoy and backends.
+This completes securing the end-to-end connection all the way from the external client to the backend.
+
+Securing the connection between Envoy and backend can have similar importance as securing the xDS TLS connection between Contour and Envoy.
+
+## High-Level Design
+
+The client certificate and key is stored in Secret of type `tls`.
+New optional argument is added to `contour serve` named `--envoy-client-certificate` which refers to a Secret.
+The reference contains the namespace and the Secret name e.g. `namespace/name`.
+The same configuration is added to the Contour configuration file in the optional `tls.envoy-client-certificate` location.
+
+## Detailed Design
+
+New field is added to `dag.Cluster` that holds the client certificate for Envoy.
+Note that since only single client certificate is supported, the secret is the same for all instances of type `dag.Cluster`.
+When `CommonTlsContext` is constructed for the upstream connection, the client certificate is added using `SdsSecretConfig`, that is, the secret is streamed over SDS.
+
+When client certificate is defined in Contour configuration, it can be added to all Envoy clusters regardless if it will be used or not.
+Envoy will send the client certificate only when the backend requests the client to present its certificate during the TLS handshake.