Skip to content

Commit

Permalink
design: TLS client validation doc updates after review
Browse files Browse the repository at this point in the history 
* corrected misspellings
* removed references to mutual TLS authentication and mTLS
* corrected formatting

Signed-off-by: Tero Saarni <tero.saarni@est.tech>
  • Loading branch information
@tsaarni
tsaarni committed Nov 28, 2019
1 parent 206f949 commit 14c75e6
Showing 1 changed file with 31 additions and 62 deletions.
93 changes: 31 additions & 62 deletions design/tls-client-verification.md
View file
Original file line number Diff line number Diff line change
@@ -1,67 +1,49 @@
# 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

```
apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
name: mutual-tls-example
name: client-validation-example
namespace: default
spec:
virtualhost:
Expand All @@ -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:
```
Expand All @@ -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.

0 comments on commit 14c75e6

Please sign in to comment.