From 14c75e68bdba7cd67f8ea8260352e7536ce3cc82 Mon Sep 17 00:00:00 2001 From: Tero Saarni Date: Thu, 28 Nov 2019 10:55:22 +0200 Subject: [PATCH] design: TLS client validation doc updates after review * corrected misspellings * removed references to mutual TLS authentication and mTLS * corrected formatting Signed-off-by: Tero Saarni --- design/tls-client-verification.md | 93 +++++++++++-------------------- 1 file changed, 31 insertions(+), 62 deletions(-) diff --git a/design/tls-client-verification.md b/design/tls-client-verification.md index 3fc134f4b16..69620aaa2c1 100644 --- a/design/tls-client-verification.md +++ b/design/tls-client-verification.md @@ -1,59 +1,41 @@ -# External client certificate validation (mutual TLS authentication) +# External client certificate validation Status: Draft -This document outlines how to add support for authentication of external -clients by validating their client certificates. +This document outlines how to add support for authentication of external clients by validating their client certificates. ## Goals -- Allow Contour to be used to protect the backend services from access of - unauthorized external clients. -- Allow authentication of external clients by having Envoy validate that - client certificates are signed by trusted CA (Certificate Authority) -- Allow configuration of trusted CA certificate(s) for validating the client - certificates. +- Allow Contour to be used to protect the backend services from access of unauthorized external clients. +- Allow authentication of external clients by having Envoy validate that client certificates are signed by trusted CA (Certificate Authority). +- Allow configuration of trusted CA certificate(s) for validating the client certificates. ## Non Goals -- Fine grained authorization on level of individual request - (example of non-goal: only client X can access resource Y on backend - service Z) +- Fine grained authorization on level of individual request (example of non-goal: only client X can access resource Y on backend service Z). ## Background -In TLS (and HTTPS) often only the client authenticates the server. TLS -supports optional authentication of client which is referred to as -*mutual TLS authentication* or *mTLS*. Mutual TLS authentication is typically -used in machine-to-machine (M2M) communication e.g. to protect sensitive REST -APIs. The application acting as TLS client authenticates itself towards the -TLS server by using x509 certificate and by providing proof of posession of -the corresponding private key. - +In TLS (and HTTPS) often only the client authenticates the server. +TLS supports optional authentication of client. +Client certificate based authentication is typically used in machine-to-machine (M2M) communication e.g. to protect sensitive REST APIs. +The application acting as TLS client authenticates itself towards the TLS server by using x509 certificate and by providing proof of possession of the corresponding private key. ## High-Level Design Envoy supports following options for certificate based client authentication: -1. Verify that a chain of trust can be established from the presented client - certificate to the configured trusted root CA certificate (validation of - certificate) -2. In addition to 1, verify that the subject alternative name of the client is - one of the names listed in the configuration (validation of client identity) -3. Verify that the client certificate hash or subject public key hash matches - with configured hash (hash pinning) +1. Verify that a chain of trust can be established from the presented client certificate to the configured trusted root CA certificate (validation of certificate) +2. In addition to 1, verify that the subject alternative name of the client is one of the names listed in the configuration (validation of client identity) +3. Verify that the client certificate hash or subject public key hash matches with configured hash (hash pinning) -Option 1) is proposed to be implemented in this document. It is sufficient -for the very simplest mutual TLS authentication use cases. +Option 1) is proposed to be implemented in this document. +It is sufficient for the very simplest authentication use cases. At a high level following CRD change is proposed: -* A new record `clientValidation` is added in `spec.virtualhost.tls` - in the `HTTPProxy`. - -* The `clientValidation` contains parameter `caSecret` which is a reference - to a secret containing trusted CA certificate for validating client - certificates. +- A new record `clientValidation` is added in `spec.virtualhost.tls` in the `HTTPProxy`. +- The `clientValidation` contains parameter `caSecret` which is a reference to a secret containing trusted CA certificate for validating client certificates. Sample YAML @@ -61,7 +43,7 @@ Sample YAML apiVersion: projectcontour.io/v1 kind: HTTPProxy metadata: - name: mutual-tls-example + name: client-validation-example namespace: default spec: virtualhost: @@ -76,18 +58,15 @@ spec: port: 80 ``` - ### Trusted CAs in Secrets -The same approach shall be followed for configuring trusted CA certificates as -is used currently to store the CA certificates for backend (Envoy upstream) -validation: +The same approach shall be followed for configuring trusted CA certificates as is used currently to store the CA certificates for backend (Envoy upstream) validation: -The CA certificate is stored in an opaque Kubernetes secret. The secret will -be stored in the same namespace as the corresponding `HTTPProxy` object. -The secret object shall contain entry named `ca.crt`. The constents shall -be the CA certificate in PEM format. The file may contain "PEM bundle", -that is, a list of CA certificates concatenated in single file. +The CA certificate is stored in an opaque Kubernetes secret. +The secret will be stored in the same namespace as the corresponding `HTTPProxy` object. +The secret object shall contain entry named `ca.crt`. +The constents shall be the CA certificate in PEM format. +The file may contain "PEM bundle", that is, a list of CA certificates concatenated in single file. Example: ``` @@ -96,30 +75,20 @@ Example: TLS certificate delegation is not in scope for CA certificates. - ## Detailed Design -The new configuration item `spec.virtualhost.tls.clientValidation` must be -parsed and the CRD's must be updated to validate the new item. - -Client certificate validation is enabled in Envoy by setting -`auth.DownstreamTlsContext.RequireClientCertificate` value to `true` and by -adding trusted CA certificates to `auth.CommonTlsContext.ValidationContextType`. +The new configuration item `spec.virtualhost.tls.clientValidation` must be parsed and the CRD's must be updated to validate the new item. +Client certificate validation is enabled in Envoy by setting `auth.DownstreamTlsContext.RequireClientCertificate` value to `true` and by adding trusted CA certificates to `auth.CommonTlsContext.ValidationContextType`. ## Alternatives Considered -To use annotation in the `Ingress` object was considered to -clumsy. Annotation must on `Ingress` level and refer to an individual -virtual host. - +To use annotation in the `Ingress` object was considered to clumsy. +Annotation must on `Ingress` level and refer to an individual virtual host. ## Security Considerations -This proposal assumes that the API server is secure. If secret or CA -data stored in the API server is modified, verification will be -ineffective. +This proposal assumes that the API server is secure. +If secret or CA data stored in the API server is modified, verification will be ineffective. -This proposal also assumes that RBAC is in place and only the owners -of the Service, Secret, HTTPProxy documents in a namespace can -modify them. +This proposal also assumes that RBAC is in place and only the owners of the Service, Secret, HTTPProxy documents in a namespace can modify them.