From 0ec17ab67af27c9dad52fe34d5434d5859bc1206 Mon Sep 17 00:00:00 2001 From: Guy Daich Date: Mon, 15 Jul 2024 23:52:13 -0500 Subject: [PATCH] docs: add backend tls docs (#3843) * add backend tls docs Signed-off-by: Guy Daich * fix links Signed-off-by: Guy Daich * add gateway paramsref Signed-off-by: Guy Daich * nit Signed-off-by: Guy Daich --------- Signed-off-by: Guy Daich --- .../en/docs/tasks/security/backend-tls.md | 5 +- .../en/latest/tasks/security/backend-mtls.md | 200 ++++++++++++++++++ .../en/latest/tasks/security/backend-tls.md | 118 ++++++++++- .../en/v1.0/tasks/security/backend-tls.md | 5 +- 4 files changed, 321 insertions(+), 7 deletions(-) create mode 100644 site/content/en/latest/tasks/security/backend-mtls.md diff --git a/site/content/en/docs/tasks/security/backend-tls.md b/site/content/en/docs/tasks/security/backend-tls.md index 9eadf4dd9d8..1f84ea4db81 100644 --- a/site/content/en/docs/tasks/security/backend-tls.md +++ b/site/content/en/docs/tasks/security/backend-tls.md @@ -13,7 +13,7 @@ Envoy Gateway supports the Gateway-API defined [BackendTLSPolicy][]. ## Installation -Follow the steps from the [Quickstart](../../quickstart) to install Envoy Gateway and the example manifest. +Follow the steps from the [Quickstart][] to install Envoy Gateway and the example manifest. ## TLS Certificates @@ -28,7 +28,7 @@ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example In 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 req -out www.example.com.csr -newkey rsa:2048 -nodes -keyout www.example.com.key -subj "/CN=www.example.com/O=example organization" -addext "subjectAltName = DNS:www.example.com" openssl x509 -req -days 365 -CA ca.crt -CAkey ca.key -set_serial 0 -in www.example.com.csr -out www.example.com.crt ``` @@ -209,4 +209,5 @@ Inspect the output and see that the response contains the details of the TLS han } ``` +[Quickstart]: ../quickstart [BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/ diff --git a/site/content/en/latest/tasks/security/backend-mtls.md b/site/content/en/latest/tasks/security/backend-mtls.md new file mode 100644 index 00000000000..1d91c7a95f8 --- /dev/null +++ b/site/content/en/latest/tasks/security/backend-mtls.md @@ -0,0 +1,200 @@ +--- +title: "Backend Mutual TLS: Gateway to Backend" +--- + +This task demonstrates how mTLS can be achieved between the Gateway and a backend. +This task uses a self-signed CA, so it should be used for testing and demonstration purposes only. + +Envoy Gateway supports the Gateway-API defined [BackendTLSPolicy][] to establish TLS. For mTLS, the Gateway must authenticate by presenting a client certificate to the backend. + +## Prerequisites + +- OpenSSL to generate TLS assets. + +## Installation + +Follow the steps from the [Backend TLS][] to install Envoy Gateway and configure TLS to the backend server. + +## TLS Certificates + +Generate the certificates and keys used by the Gateway for authentication against the backend. + +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 clientca.key -out clientca.crt +``` + +Create a certificate and a private key for `www.example.com`: + +```shell +openssl req -new -newkey rsa:2048 -nodes -keyout client.key -out client.csr -subj "/CN=example-client/O=example organization" +openssl x509 -req -days 365 -CA clientca.crt -CAkey clientca.key -set_serial 0 -in client.csr -out client.crt +``` + +Store the cert/key in a Secret: + +```shell +kubectl -n envoy-gateway-system create secret tls example-client-cert --key=client.key --cert=client.crt +``` + +Store the CA Cert in another Secret: + +```shell +kubectl create configmap example-client-ca --from-file=clientca.crt +``` + +## Enforce Client Certificate Authentication on the backend + +Patch the existing quickstart backend to enforce Client Certificate Authentication. The patch will mount the server certificate and key required for TLS, and the CA certificate into the backend as volumes. + +```shell +kubectl patch deployment backend --type=json --patch ' + - op: add + path: /spec/template/spec/containers/0/volumeMounts + value: + - name: client-certs-volume + mountPath: /etc/client-certs + - name: secret-volume + mountPath: /etc/secret-volume + - op: add + path: /spec/template/spec/volumes + value: + - name: client-certs-volume + configMap: + name: example-client-ca + items: + - key: clientca.crt + path: crt + - name: secret-volume + secret: + secretName: example-cert + items: + - key: tls.crt + path: crt + - key: tls.key + path: key + - op: add + path: /spec/template/spec/containers/0/env/- + value: + name: TLS_CLIENT_CACERTS + value: /etc/client-certs/crt + ' +``` + +## Configure Envoy Proxy to use a client certificate + +In addition to enablement of backend TLS with the Gateway-API BackendTLSPolicy, Envoy Gateway supports customizing TLS parameters such as TLS Client Certificate. +To achieve this, the [EnvoyProxy][] resource can be used to specify a TLS Client Certificate. + +First, you need to add ParametersRef in GatewayClass, and refer to EnvoyProxy Config: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +## Testing mTLS + +Query the TLS-enabled backend through Envoy proxy: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:80:127.0.0.1" \ +http://www.example.com:80/get +``` + +Inspect the output and see that the response contains the details of the TLS handshake between Envoy and the backend. +The response now contains a "peerCertificates" attribute that reflects the client certificate used by the Gateway to establish mTLS with the backend. + +```shell +< HTTP/1.1 200 OK +[...] + "tls": { + "version": "TLSv1.2", + "serverName": "www.example.com", + "negotiatedProtocol": "http/1.1", + "cipherSuite": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" + "peerCertificates": ["-----BEGIN CERTIFICATE-----\n[...]-----END CERTIFICATE-----\n"] + } +``` + +[Backend TLS]: ./backend-tls +[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/ +[EnvoyProxy]: ../../api/extension_types#envoyproxy \ No newline at end of file diff --git a/site/content/en/latest/tasks/security/backend-tls.md b/site/content/en/latest/tasks/security/backend-tls.md index 93d155eb30e..53e9ccbd44a 100644 --- a/site/content/en/latest/tasks/security/backend-tls.md +++ b/site/content/en/latest/tasks/security/backend-tls.md @@ -13,7 +13,7 @@ Envoy Gateway supports the Gateway-API defined [BackendTLSPolicy][]. ## Installation -Follow the steps from the [Quickstart](../../quickstart) to install Envoy Gateway and the example manifest. +Follow the steps from the [Quickstart][] to install Envoy Gateway and the example manifest. ## TLS Certificates @@ -28,10 +28,12 @@ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example In 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 req -out www.example.com.csr -newkey rsa:2048 -nodes -keyout www.example.com.key -subj "/CN=www.example.com/O=example organization" -addext "subjectAltName = DNS:www.example.com" openssl x509 -req -days 365 -CA ca.crt -CAkey ca.key -set_serial 0 -in www.example.com.csr -out www.example.com.crt ``` +Note that the certificate must contain a DNS SAN for the relevant domain. + Store the cert/key in a Secret: ```shell @@ -206,7 +208,7 @@ Verify the HTTPRoute status: kubectl get HTTPRoute backend -o yaml ``` -## Testing +## Testing backend TLS {{< tabpane text=true >}} {{% tab header="With External LoadBalancer Support" %}} @@ -275,4 +277,114 @@ Inspect the output and see that the response contains the details of the TLS han {{% /tab %}} {{< /tabpane >}} +## Customize backend TLS Parameters + +In addition to enablement of backend TLS with the Gateway-API BackendTLSPolicy, Envoy Gateway supports customizing TLS parameters. +To achieve this, the [EnvoyProxy][] resource can be used to specify TLS parameters. We will customize the TLS version in this example. + +First, you need to add ParametersRef in GatewayClass, and refer to EnvoyProxy Config: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +You can customize the EnvoyProxy Backend TLS Parameters via EnvoyProxy Config like: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +## Testing TLS Parameters + +Query the TLS-enabled backend through Envoy proxy: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:80:127.0.0.1" \ +http://www.example.com:80/get +``` + +Inspect the output and see that the response contains the details of the TLS handshake between Envoy and the backend. +The TLS version is now TLS1.3, as configured in the EnvoyProxy resource. The TLS cipher is also changed, since TLS1.3 supports different ciphers from TLS1.2. + +```shell +< HTTP/1.1 200 OK +[...] + "tls": { + "version": "TLSv1.3", + "serverName": "www.example.com", + "negotiatedProtocol": "http/1.1", + "cipherSuite": "TLS_AES_128_GCM_SHA256" + } +``` + +[Quickstart]: ../quickstart [BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/ +[EnvoyProxy]: ../../api/extension_types#envoyproxy \ No newline at end of file diff --git a/site/content/en/v1.0/tasks/security/backend-tls.md b/site/content/en/v1.0/tasks/security/backend-tls.md index 9eadf4dd9d8..1f84ea4db81 100644 --- a/site/content/en/v1.0/tasks/security/backend-tls.md +++ b/site/content/en/v1.0/tasks/security/backend-tls.md @@ -13,7 +13,7 @@ Envoy Gateway supports the Gateway-API defined [BackendTLSPolicy][]. ## Installation -Follow the steps from the [Quickstart](../../quickstart) to install Envoy Gateway and the example manifest. +Follow the steps from the [Quickstart][] to install Envoy Gateway and the example manifest. ## TLS Certificates @@ -28,7 +28,7 @@ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example In 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 req -out www.example.com.csr -newkey rsa:2048 -nodes -keyout www.example.com.key -subj "/CN=www.example.com/O=example organization" -addext "subjectAltName = DNS:www.example.com" openssl x509 -req -days 365 -CA ca.crt -CAkey ca.key -set_serial 0 -in www.example.com.csr -out www.example.com.crt ``` @@ -209,4 +209,5 @@ Inspect the output and see that the response contains the details of the TLS han } ``` +[Quickstart]: ../quickstart [BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/