diff --git a/site/content/en/latest/user/security/mutual-tls.md b/site/content/en/latest/user/security/mutual-tls.md new file mode 100644 index 00000000000..e24562ca45e --- /dev/null +++ b/site/content/en/latest/user/security/mutual-tls.md @@ -0,0 +1,153 @@ +--- +title: "Mutual TLS: External Clients to the Gateway" +--- + +This guide demonstrates how mutual TLS can be achieved between external clients and the Gateway. The guide uses a self-signed CA, so it should be used for +testing and demonstration purposes only. + +## Prerequisites + +- OpenSSL to generate TLS assets. + +## Installation + +Follow the steps from the [Quickstart Guide](../../quickstart) to install Envoy Gateway and the example manifest. +Before proceeding, you should be able to query the example backend using HTTP. + +## TLS Certificates + +Generate the certificates and keys used by the Gateway to terminate client TLS connections. + +Create a root certificate and private key to sign certificates: + +```shell +openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example Inc./CN=example.com' -keyout example.com.key -out example.com.crt +``` + +Create a certificate and a private key for `www.example.com`: + +```shell +openssl req -out www.example.com.csr -newkey rsa:2048 -nodes -keyout www.example.com.key -subj "/CN=www.example.com/O=example organization" +openssl x509 -req -days 365 -CA example.com.crt -CAkey example.com.key -set_serial 0 -in www.example.com.csr -out www.example.com.crt +``` + +Store the cert/key in a Secret: + +```shell +kubectl create secret tls example-cert --key=www.example.com.key --cert=www.example.com.crt --certificate-authority=example.com.crt +``` + +Store the CA Cert in another Secret: + +```shell +kubectl create secret generic example-ca-cert --from-file=ca.crt=example.com.crt +``` + +Create a certificate and a private key for the client `client.example.com`: + +```shell +openssl req -out client.example.com.csr -newkey rsa:2048 -nodes -keyout client.example.com.key -subj "/CN=client.example.com/O=example organization" +openssl x509 -req -days 365 -CA example.com.crt -CAkey example.com.key -set_serial 0 -in client.example.com.csr -out client.example.com.crt +``` + +Update the Gateway from the Quickstart guide to include an HTTPS listener that listens on port `443` and references the +`example-cert` Secret: + +```shell +kubectl patch gateway eg --type=json --patch '[{ + "op": "add", + "path": "/spec/listeners/-", + "value": { + "name": "https", + "protocol": "HTTPS", + "port": 443, + "tls": { + "mode": "Terminate", + "certificateRefs": [{ + "kind": "Secret", + "group": "", + "name": "example-cert", + }], + }, + }, +}]' +``` + +Verify the Gateway status: + +```shell +kubectl get gateway/eg -o yaml +``` + +Create a [ClientTrafficPolicy][] to enforce client validation using the CA Certificate as a trusted anchor. + +```shell +cat <