From 02b247ea5b593d36cfefb4bab6579b329cd314a5 Mon Sep 17 00:00:00 2001 From: Steve Wagner Date: Thu, 31 Aug 2023 09:23:04 -0700 Subject: [PATCH] Add documentation for TLS configuration of NLK- better titles - tweaks - Add Under Development notice - prefer References section over inline links to external documentation --- docs/tls/CA-MTLS.md | 87 ++++++++++++++++++++ docs/tls/CA-TLS.md | 77 +++++++++++++++++ docs/tls/CERTIFICATE-AUTHORITY.md | 44 ++++++++++ docs/tls/CLIENT-CERTIFICATE.md | 50 +++++++++++ docs/tls/DOCUMENT-HIERARCHY.md | 51 ++++++++++++ docs/tls/KUBERNETES-SECRETS.md | 71 ++++++++++++++++ docs/tls/NGINX-PLUS-CONFIGURATION.md | 82 ++++++++++++++++++ docs/tls/NO-TLS.md | 57 +++++++++++++ docs/tls/README.md | 119 +++++++++++++++++++++++++++ docs/tls/SERVER-CERTIFICATE.md | 70 ++++++++++++++++ docs/tls/SS-MTLS.md | 91 ++++++++++++++++++++ docs/tls/SS-TLS.md | 83 +++++++++++++++++++ 12 files changed, 882 insertions(+) create mode 100644 docs/tls/CA-MTLS.md create mode 100644 docs/tls/CA-TLS.md create mode 100644 docs/tls/CERTIFICATE-AUTHORITY.md create mode 100644 docs/tls/CLIENT-CERTIFICATE.md create mode 100644 docs/tls/DOCUMENT-HIERARCHY.md create mode 100644 docs/tls/KUBERNETES-SECRETS.md create mode 100644 docs/tls/NGINX-PLUS-CONFIGURATION.md create mode 100644 docs/tls/NO-TLS.md create mode 100644 docs/tls/README.md create mode 100644 docs/tls/SERVER-CERTIFICATE.md create mode 100644 docs/tls/SS-MTLS.md create mode 100644 docs/tls/SS-TLS.md diff --git a/docs/tls/CA-MTLS.md b/docs/tls/CA-MTLS.md new file mode 100644 index 0000000..1e72dda --- /dev/null +++ b/docs/tls/CA-MTLS.md @@ -0,0 +1,87 @@ +# Mutual TLS with Certificate Authority (CA) certificates + +This mode allows NLK to verify it is connecting to the correct NGINX Plus instance, allows NGINX Plus to verify it is connecting to the correct NLK, and encrypts the data between NLK and NGINX Plus. + +## Overview + +Mutual TLS is used to encrypt the traffic between NLK and NGINX Plus, to ensure NLK verifies the NGINX Plus server, and to ensure NGINX Plus verifies NLK. + +## Certificates + +To configure this mode, the following certificates are required: + +- Server Certificate +- Client Certificate + +See the following sections for instructions on how to create these certificates. + +### Certificate Authority (CA) + +Provided by the user. + +### Server Certificate (NGINX Plus) + +Use your own certificate authority (CA) to generate a server certificate and key. + +### Client Certificate (NLK) + +Use your own certificate authority (CA) to generate a client certificate and key. + +## Kubernetes Secrets + +NLK accesses the necessary certificates for each mode from Kubernetes Secrets. For this mode, the following Kubernetes Secret(s) are required: +- Client Certificate + +To create the Kubernetes Secret containing the CA certificate, refer to the [Kubernetes Secrets](./KUBERNETES-SECRETS.md) guide; +the name and location of the certificate(s) created above should be used. The name of the Secret will be needed for the ConfigMap (discussed below). + +## ConfigMap + + +NLK is configured via a ConfigMap. The ConfigMap is named `nlk-config` and is located in the `nlk` namespace. + +Depending on which mode is chosen, certain fields will need to be updated in the NLK ConfigMap. + +For this mode, the `mode` and `clientCertificate` fields need to be included. The `mode` field should be set to `ca-mtls` +and the `clientCertificate` field should be set to the name of the Kubernetes Secret containing the Client certificate created above. + +The following is an example of a ConfigMap for this mode (be sure to update the `nginx-hosts` field with the correct NGINX Plus API endpoints): + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: nlk-config + namespace: nlk +data: + nginx-hosts: "http://10.1.1.4:9000/api,http://10.1.1.5:9000/api" + mode: "ca-mtls" + clientCertificate: "nlk-tls-client-secret" +``` + +## Deployment + +Save the above ConfigMap definition to a file named `ca-mtls-configmap.yaml`, then deploy the ConfigMap using the following command: + +```bash +kubectl apply -f docs/tls/ca-mtls-configmap.yaml +``` + +## Configuring NGINX Plus + +Refer to the [NGINX Plus Configuration](./NGINX-PLUS-CONFIGURATION.md) guide for instructions on configuring NGINX Plus to use the certificates created above. + +The steps in both the ["One-way TLS"](./NGINX-PLUS-CONFIGURATION.md#one-way-tls) section and the ["Mutual TLS"](./NGINX-PLUS-CONFIGURATION.md#mutual-tls) section are required for this mode. + +## Verification + +To verify the ConfigMap was deployed correctly, run the following command: + +```bash +kubectl get configmap -n nlk nlk-config -o yaml +``` + +The output should match the ConfigMap above. + +To verify NLK is running, follow the instructions in either the [TCP](../tcp/tcp-installation-guide.md) or [HTTP](../http/http-installation-guide.md) guides. + diff --git a/docs/tls/CA-TLS.md b/docs/tls/CA-TLS.md new file mode 100644 index 0000000..3429ed5 --- /dev/null +++ b/docs/tls/CA-TLS.md @@ -0,0 +1,77 @@ +# One-way TLS with Certificate Authority (CA) certificates + +This mode allows NLK to verify it is connecting to the correct NGINX Plus instance, and encrypts the data between NLK and NGINX Plus. + +## Overview + +One-way TLS is used to encrypt the traffic between NLK and NGINX Plus, and to ensure NLK verifies the NGINX Plus server; +however, the NGINX Plus server _does not_ validate NLK. + +## Certificates + +To configure this mode, the following certificates are required: + +- Server Certificate + +See the following sections for instructions on how to create these certificates. + +### Certificate Authority (CA) + +Provided by the user. + +### Server Certificate (NGINX Plus) + +Use your certificate authority (CA) to generate a server certificate and key. + +## Kubernetes Secrets + +No Kubernetes Secrets are required for this mode. + +## ConfigMap + +NLK is configured via a ConfigMap. The ConfigMap is named `nlk-config` and is located in the `nlk` namespace. + +Depending on which mode is chosen, certain fields will need to be updated in the NLK ConfigMap. + +For this mode, only the `mode` fields needs to be included. The `mode` field should be set to `ca-tls`. + +The following is an example of a ConfigMap for this mode (be sure to update the `nginx-hosts` field with the correct NGINX Plus API endpoints): + + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: nlk-config + namespace: nlk +data: + nginx-hosts: "http://10.1.1.4:9000/api,http://10.1.1.5:9000/api" + mode: "ca-tls" +``` + +## Deployment + +Save the above ConfigMap definition to a file named `ca-tls-configmap.yaml`, then deploy the ConfigMap using the following command: + +```bash +kubectl apply -f docs/tls/ca-tls-configmap.yaml +``` + +## Configuring NGINX Plus + +Refer to the [NGINX Plus Configuration](./NGINX-PLUS-CONFIGURATION.md) guide for instructions on configuring NGINX Plus to use the certificates created above. + +Only the steps in the ["One-way TLS"](./NGINX-PLUS-CONFIGURATION.md#one-way-tls) section are required for this mode. +Use the certificate and key from your CA to configure NGINX Plus. + +## Verification + +To verify the ConfigMap was deployed correctly, run the following command: + +```bash +kubectl get configmap -n nlk nlk-config -o yaml +``` + +The output should match the ConfigMap above. + +To verify NLK is running, follow the instructions in either the [TCP](../tcp/tcp-installation-guide.md) or [HTTP](../http/http-installation-guide.md) guides. diff --git a/docs/tls/CERTIFICATE-AUTHORITY.md b/docs/tls/CERTIFICATE-AUTHORITY.md new file mode 100644 index 0000000..fe44fe8 --- /dev/null +++ b/docs/tls/CERTIFICATE-AUTHORITY.md @@ -0,0 +1,44 @@ +# Generate a Certificate Authority (CA) + +When using self-signed certificates, the first step is to generate the Certificate Authority (CA). + +The following commands will generate the CA certificate and key: + +```bash +openssl req -newkey rsa:2048 -nodes -x509 -out ca.crt -keyout ca.key +``` + +You will be prompted to enter the Distinguished Name (DN) information for the CA. + +Alternatively, you can provide the DN information in a file, an example is shown below: + +```bash +[ req ] +distinguished_name = dn +prompt = no +req_extensions = req_ext + +[ req_ext ] +basicConstraints = CA:TRUE +keyUsage = critical, keyCertSign, cRLSign + +[ dn ] +C=[COUNTRY] +ST=[STATE] +L=[LOCALITY] +O=[ORGANIZATION] +OU=[ORGANIZATION_UNIT] +``` + +Create a file using the above as a template and update the values in the `[ dn ]` section; then use following command to generate the CA certificate and key: + +```bash +openssl req -newkey rsa:2048 -nodes -x509 -config ca.cnf -out ca.crt -keyout ca.key +``` + +The output of the above command will be the CA certificate (`ca.crt`) and key (`ca.key`). + +## References + +- [Distinguished Name reference](http://certificate.fyicenter.com/2098_OpenSSL_req_-distinguished_name_Configuration_Section.html) + diff --git a/docs/tls/CLIENT-CERTIFICATE.md b/docs/tls/CLIENT-CERTIFICATE.md new file mode 100644 index 0000000..4ff86c9 --- /dev/null +++ b/docs/tls/CLIENT-CERTIFICATE.md @@ -0,0 +1,50 @@ +# Generate a client certificate + +When using self-signed certificates in the `ss-mtls` mode, a certificate needs to be generated for NLK. + +The certificate has the same basic field as the CA certificate, with the addition of `clientAuth` in the `extendedKeyUsage` field: + +```bash +[ req ] +distinguished_name = dn +prompt = no + +[ dn ] +C=[COUNTRY] +ST=[STATE] +L=[LOCALITY] +O=[ORGANIZATION] +OU=[ORGANIZATION_UNIT] + +[ client ] +extendedKeyUsage = clientAuth +``` + +Create a file using the above as a template and update the values in the `[ dn ]` section; then use following command to generate the certificate request and key: + +```bash +openssl genrsa -out client.key 2048 +openssl req -new -key client.key -config client.cnf -out client.csr +``` + +The output of the above commands will be the client certificate request (`client.csr`) and key (`client.key`). + +##### Sign the client certificate + +```bash +openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt -days 365 -sha256 -extfile client.cnf -extensions client +``` + +The output of the above command will be the client certificate (`client.crt`). + +#### Verify the Client Certificate has the correct extendedKeyUsage + +```bash +openssl x509 -in client.crt -noout -purpose | grep 'SSL client :' +``` + +Look for `SSL client : Yes` in the output. + +## References + +- [Distinguished Name reference](http://certificate.fyicenter.com/2098_OpenSSL_req_-distinguished_name_Configuration_Section.html) \ No newline at end of file diff --git a/docs/tls/DOCUMENT-HIERARCHY.md b/docs/tls/DOCUMENT-HIERARCHY.md new file mode 100644 index 0000000..2d3deb2 --- /dev/null +++ b/docs/tls/DOCUMENT-HIERARCHY.md @@ -0,0 +1,51 @@ +```mermaid +graph LR + README[README.md] + SS-TLS[SS-TLS.md] + SS-MTLS[SS-MTLS.md] + CA-TLS[CA-TLS.md] + CA-MTLS[CA-MTLS.md] + NO-TLS[NO-TLS.md] + CERTIFICATE-AUTHORITY[CERTIFICATE-AUTHORITY.md] + CLIENT-CERTIFICATE[CLIENT-CERTIFICATE.md] + SERVER-CERTIFICATE[SERVER-CERTIFICATE.md] + KUBERNETES-SECRETS[KUBERNETES-SECRETS.md] + NGINX-PLUS-CONFIGURATION[NGINX-PLUS-CONFIGURATION.md] + KUBERNETES-SECRETS[KUBERNETES-SECRETS.md] + + subgraph "README.md" + README + end + + subgraph "NO-TLS links" + README --> NO-TLS + end + + subgraph "SS-TLS links" + README --> SS-TLS + SS-TLS --> CERTIFICATE-AUTHORITY + SS-TLS --> SERVER-CERTIFICATE + SS-TLS --> KUBERNETES-SECRETS + SS-TLS --> NGINX-PLUS-CONFIGURATION + end + + subgraph "SS-MTLS links" + README --> SS-MTLS + SS-MTLS --> CERTIFICATE-AUTHORITY + SS-MTLS --> SERVER-CERTIFICATE + SS-MTLS --> CLIENT-CERTIFICATE + SS-MTLS --> KUBERNETES-SECRETS + SS-MTLS --> NGINX-PLUS-CONFIGURATION + end + + subgraph "CA-TLS links" + README --> CA-TLS + CA-TLS --> NGINX-PLUS-CONFIGURATION + end + + subgraph "CA-MTLS links" + README --> CA-MTLS + CA-MTLS --> KUBERNETES-SECRETS + CA-MTLS --> NGINX-PLUS-CONFIGURATION + end +``` \ No newline at end of file diff --git a/docs/tls/KUBERNETES-SECRETS.md b/docs/tls/KUBERNETES-SECRETS.md new file mode 100644 index 0000000..1f998dd --- /dev/null +++ b/docs/tls/KUBERNETES-SECRETS.md @@ -0,0 +1,71 @@ +# Kubernetes Secrets + +## Overview + +Kubernetes Secrets are used to provide the required certificates to NLK. There are two ways to create the Secrets: +- Using `kubectl` +- Using yaml files + +The filenames for the certificates created previously are required for both methods. The examples below assume the certificates were generated in `/tmp` +and follow the naming conventions in the documentation. + +## Using `kubectl` + +The easiest way to create the secret is by using `kubectl`: + +```bash +kubectl create secret tls -n nlk nlk-tls-{ca,server,client}-secret --cert=/tmp/{ca,server,client}.crt --key=/tmp/{ca,server,client}.key +``` + +## Using yaml files + +The Secrets can also be created using yaml files. The following is an example of a yaml file for the Client Secret (note that the `data` values are truncated): + +```yaml +apiVersion: v1 +data: + tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVCVEN... + tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2Z0l... +kind: Secret +metadata: + name: nlk-tls-client-secret +type: kubernetes.io/tls +``` + +Note: While it is possible to generate the values for `tls.crt` and `tls.key` manually, the above yaml can be generated using the following command: + +```bash +kubectl create secret tls -n nlk nlk-tls-{ca,server,client}-secret --cert=/tmp/{ca,server,client}.crt --key=/tmp/{ca,server,client}.key --dry-run=client -o yaml > {ca,server,client}-secret.yaml +``` + +**Warning: it is important that these files do not make their way into a public repository or other storage location where they can be accessed by unauthorized users.** + + +Once the yaml files are generated they can be applied using `kubectl`: + +```bash +kubectl apply -f {ca,server,client}-secret.yaml +``` + +# Verification + +The Secrets can be verified using `kubectl`: + +```bash +kubectl describe secret -n nlk nlk-tls-{ca,server,client}-secret +``` + +The output should look similar to the example above. + +To see the actual values of the certificates, the following command can be used: + +```bash +kubectl get secret -n nlk nlk-tls-ca-secret -o json | jq -r '.data["tls.crt"], .data["tls.key"]' | base64 -d +``` + +Note that this requires `jq` to be installed. + +## References + +- [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) +- [kubectl dry run flags](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#-em-dry-run-em-) \ No newline at end of file diff --git a/docs/tls/NGINX-PLUS-CONFIGURATION.md b/docs/tls/NGINX-PLUS-CONFIGURATION.md new file mode 100644 index 0000000..e622c83 --- /dev/null +++ b/docs/tls/NGINX-PLUS-CONFIGURATION.md @@ -0,0 +1,82 @@ +# Configuring NGINX Plus + +## Configuring the server certificate + +Depending on the mode chosen, some files will need to be copied to the NGINX Plus host. The following table shows which files are required for each mode: + +| Mode | Server Certificate | CA Certificate | +| ---- | ------------------ |--------------------| +| no-tls | | | | +| ss-tls | :heavy_check_mark: | :heavy_check_mark: | +| ss-mtls | :heavy_check_mark: | :heavy_check_mark: | +| ca-tls | :heavy_check_mark: | | +| ca-mtls | :heavy_check_mark: | | + + +Copy the necessary server files for the chosen mode to the NGINX host; place them in the `/etc/ssl/certs/nginx` directory. + +### One-way TLS + +The following applies to modes `ss-tls`, `ss-mtls`, `ca-tls`, and `ca-mtls`. + +To configure NGINX Plus to use the `server.crt` and `server.key` files for TLS, +add the following to the `http` or `server` context in the `/etc/nginx/nginx.conf` file: + +```bash +http { + ssl_certificate /etc/ssl/certs/nginx/server.crt; + ssl_certificate_key /etc/ssl/certs/nginx/server.key; +} +``` + +Reload the NGINX Plus configuration to apply the changes. + +```bash +nginx -s reload +``` + +### Mutual TLS + +In the `/etc/nginx/nginx.conf` file, add the following to the `http` or `server` context: + +#### Self-signed certificates + +When using `ss-mtls` mode, the CA certificate must be provided to NGINX Plus: + +```bash +http { + ssl_client_certificate /etc/ssl/certs/nginx/ca.crt; + ssl_verify_client on; + ssl_verify_depth 3; +} +``` + +This will configure NGINX Plus to use the `ca.crt` file for client authentication. + +#### CA-signed certificates + +When using `ca-mtls` mode, the `ssl_client_certificate` directive is not required: + +```bash +http { + ssl_verify_client on; + ssl_verify_depth 3; +} +``` + +Reload the NGINX Plus configuration to apply the changes. + +```bash +nginx -s reload +``` + +Test with curl: + +```bash +curl --cert client.crt --key client.key --cacert ca.crt https:///api +``` + +## References + +- [NGINX `ssl_certificate` directive](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate) +- [NGINX `ssl_client_certificate` directive](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_client_certificate) \ No newline at end of file diff --git a/docs/tls/NO-TLS.md b/docs/tls/NO-TLS.md new file mode 100644 index 0000000..e4aacd3 --- /dev/null +++ b/docs/tls/NO-TLS.md @@ -0,0 +1,57 @@ +# No TLS Mode + +This mode is the easiest to configure, but provides no security. Choose this for development environments, or test +environments where security is not strictly necessary. + +Note: you should test with one of the TLS / mTLS modes before deploying to production to ensure familiarity with the configuration and process. + +## Overview + +This is the default mode of operation for NLK. It offers no verification of either side of the connection, nor any encryption of the data. + +## Certificates + +No certificates are required for this mode. + +## Kubernetes Secrets + +No Kubernetes Secrets are required for this mode. + +## ConfigMap + +NLK is configured via a ConfigMap. The ConfigMap is named `nlk-config` and is located in the `nlk` namespace. Depending on which mode is chosen, certain fields will need to be updated in the NLK ConfigMap. + +For this mode, only the `mode` field needs to be included, and should be set to `no-tls` (or omitted altogether as this is the default mode). + +The following is an example of a ConfigMap for this mode (be sure to update the `nginx-hosts` field with the correct NGINX Plus API endpoints) + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: nlk-config + namespace: nlk +data: + nginx-hosts: "http://10.1.1.4:9000/api,http://10.1.1.5:9000/api" + mode: "no-tls" +``` + +## Deployment + +Save the above ConfigMap definition to a file named `no-tls-configmap.yaml`, then deploy the ConfigMap using the following command: + +```bash +kubectl apply -f docs/tls/no-tls-configmap.yaml +``` + +## Verification + +To verify the ConfigMap was deployed correctly, run the following command: + +```bash +kubectl get configmap -n nlk nlk-config -o yaml +``` + +The output should match the ConfigMap above. + +To verify NLK is running, follow the instructions in either the [TCP](../tcp/tcp-installation-guide.md) or [HTTP](../http/http-installation-guide.md) guides. diff --git a/docs/tls/README.md b/docs/tls/README.md new file mode 100644 index 0000000..9f537e9 --- /dev/null +++ b/docs/tls/README.md @@ -0,0 +1,119 @@ +# Securing communication between NLK and NGINX Plus with TLS / mTLS + +THIS FEATURE IS IN DEVELOPMENT. THIS NOTICE WILL BE REMOVED WHEN THE IMPLEMENTATION IS COMPLETE. + +This document describes how to configure TLS / mTLS to secure communication between NLK and NGINX Plus. + +For development and test environments, using secure communication may not be necessary; however, in production environments +communications should be encrypted. More importantly, communications should be restricted to known actors. + +Using TLS / mTLS provides the following benefits: +- Confidentiality: communications are encrypted +- Integrity: communications are protected from tampering +- Authentication: communications are restricted to known actors + +NLK supports three options for securing communications between the NLK and NGINX Plus: + +1. No TLS +2. TLS with self-signed certificates +3. TLS with certificates signed by a Certificate Authority (CA) + +Within the TLS options there are two sub-options: + +1. One-way TLS +2. Mutual TLS + +The following diagram shows a visual representation of the One-way and Mutual TLS options +(the "CA Certificate" can be either self-signed or signed by a well-known CA): + +```mermaid +graph LR + CACertificate[CA Certificate] + + subgraph "One-way TLS" + NGINXPlusCert[NGINX Plus Certificate] + NLK[nginx-loadbalancer-kubernetes] + NGINXPlus[NGINX Plus] + NGINXPlusCert -->|Used by| NLK + NLK -->|Verifies| NGINXPlus + end + + subgraph "Mutual TLS" + NLKCert[NLK Certificate] + MNGINXPlusCert[NGINX Plus Certificate] + MNLK[nginx-loadbalancer-kubernetes] + MNGINXPlus[NGINX Plus] + NLKCert -->|Used by| MNGINXPlus + MNGINXPlus -->|Verifies| MNLK + MNGINXPlusCert -->|Used by| MNLK + MNLK -->|Verifies| MNGINXPlus + end + +CACertificate -->|Used for Signing| NLKCert +CACertificate -->|Used for Signing| NGINXPlusCert +CACertificate -->|Used for Signing| MNGINXPlusCert +``` + + +## No TLS + +This option, denoted as `no-tls`, is the easiest to configure, but provides no security. It is not recommended for production environments. + +This is the default mode of operation for NLK. + +## TLS with self-signed certificates + +This option is more secure than no TLS. With this option the certificates are self-signed, and therefore not trusted by default. +This means that NGINX Plus and NLK will need to be configured to trust the certificates. + +### One-way TLS + +In this mode, denoted as `ss-tls`, NLK will trust the server certificate, but NLK presents no certificate to be validated. +Since self-signed certificates are used, NLK will need to be configured to trust the server certificate. +This is done by adding the CA certificate to NLK's trust store. In order to do this, +the CA certificate will need to be provided to NLK via a Kubernetes Secret. + +Instructions for configuring One-way TLS with self-signed certificates can be found [here](SS-TLS.md). + +### Mutual TLS + +In this mode, denoted as `ss-mtls`, NLK will trust the server certificate, and the server will trust the NLK certificate. +Since self-signed certificates are used, NLK will need to be configured to trust the server certificate. Additionally, +the server will need to be configured to trust the NLK certificate. In order to do this, the CA certificate will need to be +provided to NLK via a Kubernetes Secret, and to the server by copying the CA certificate to the NGINX Plus host. + +Instructions for configuring Mutual TLS with self-signed certificates can be found [here](SS-MTLS.md). + +## TLS with certificates signed by a Certificate Authority (CA) + +This is the most secure option. With this option the certificates are signed by a CA, and therefore trusted by default. + +### One-way TLS + +In this mode, denoted as `ca-tls`, NLK will trust the server certificate, but NLK presents no certificate and cannot be verified by the server. + +Instructions for configuring One-way TLS with a CA-signed certificate can be found [here](CA-TLS.md). + +### Mutual TLS + +In this mode, denoted as `ca-mtls`, NLK will trust the server certificate, and the server will trust the NLK certificate. + +Instructions for configuring Mutual TLS with a CA-signed certificate can be found [here](CA-MTLS.md). + +## Considerations + +No TLS may be acceptable for development and testing, but is not recommended for production environments. + +If the highest level of trust and security is not required, but secure communication is, then mutual TLS with self-signed certificates is recommended. +This option provides a reasonable level of security, especially when the environments are sufficiently hardened and access is controlled. + +If the highest level of trust and security is required then Mutual TLS with certificates signed by a CA is recommended. + +## Next Steps + +Follow the guide appropriate for your preferred mode: +- [No TLS](NO-TLS.md) +- [One-way TLS with self-signed certificates](SS-TLS.md) +- [Mutual TLS with self-signed certificates](SS-MTLS.md) +- [One-way TLS with certificates signed by a Certificate Authority (CA)](CA-TLS.md) +- [Mutal TLS with certificates signed by a Certificate Authority (CA)](CA-MTLS.md) diff --git a/docs/tls/SERVER-CERTIFICATE.md b/docs/tls/SERVER-CERTIFICATE.md new file mode 100644 index 0000000..4102541 --- /dev/null +++ b/docs/tls/SERVER-CERTIFICATE.md @@ -0,0 +1,70 @@ +# Generate a server certificate + +When using self-signed certificates in the `ss-tls` and `ss-mtls` modes, a certificate needs to be generated for the NGINX Plus server. + +The certificate has the same basic fields as the CA certificate, but with a few additional fields. + +The following is an example of a configuration file for server certificates: + +```bash +[ req ] +distinguished_name = dn +req_extensions = req_ext +prompt = no + +[ dn ] +C=[COUNTRY] +ST=[STATE] +L=[LOCALITY] +O=[ORGANIZATION] +OU=[ORGANIZATION_UNIT] +CN=[COMMON_NAME] + +[ req_ext ] +basicConstraints = CA:FALSE +keyUsage = nonRepudiation, digitalSignature, keyEncipherment +subjectAltName = @alt_names +extendedKeyUsage = serverAuth + +[ alt_names ] +DNS.1 = mydomain.com +DNS.2 = server.mydomain.com +DNS.3 = *.mydomain.com +IP.1 = 10.0.0.10 +IP.2 = 10.0.0.11 +``` + +Create a file using this as a template, the following example commands use the name `server.cnf`. + +Be sure to update the Distinguished Name (DN) information and the SAN information (DNS / IP entries in the `alt_names` section) as appropriate. +Doing so ensures that the certificate is valid for the server by providing an unambiguous match between the server (IP addresses and/or domain names) and the certificate. + +The following commands will generate the server certificate request and key: + +```bash +openssl genrsa -out server.key 2048 +openssl req -new -key server.key -config server.cnf -out server.csr +``` + +The output of the above commands will be the server certificate request (`server.csr`) and key (`server.key`). + +##### Sign the server certificate + +```bash +openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 365 -sha256 -extensions req_ext -extfile server.cnf +``` + +The output of the above command will be the server certificate (`server.crt`). + +##### Verify the Server Certificate has the SAN + +```bash +openssl x509 -in server.crt -text -noout | grep -A 1 "Subject Alternative Name" +``` + +Look for the DNS / IP entries in the `Subject Alternative Name` section in the output; the values entered in the `alt_names` section of the `server.cnf` file should be present. + +## References + +- [OpenSSL extensions documentation](https://www.openssl.org/docs/manmaster/man5/x509v3_config.html) +- [Distinguished Name reference](http://certificate.fyicenter.com/2098_OpenSSL_req_-distinguished_name_Configuration_Section.html) diff --git a/docs/tls/SS-MTLS.md b/docs/tls/SS-MTLS.md new file mode 100644 index 0000000..ba62dd3 --- /dev/null +++ b/docs/tls/SS-MTLS.md @@ -0,0 +1,91 @@ +# Mutual TLS with self-signed certificates + +This mode allows NLK to verify it is connecting to the correct NGINX Plus instance, allows NGINX Plus to verify it is connecting to the correct NLK, and encrypts the data between NLK and NGINX Plus. + + +## Overview + +Mutual TLS is used to encrypt the traffic between NLK and NGINX Plus, to ensure NLK verifies the NGINX Plus server, and to ensure NGINX Plus verifies NLK. + + +## Certificates + +To configure this mode, the following certificates are required: + +- CA Certificate +- Server Certificate +- Client Certificate + +See the following sections for instructions on how to create these certificates. + +### Certificate Authority (CA) + +Follow the instructions in the [Certificate Authority](./CERTIFICATE-AUTHORITY.md) guide to create a self-signed CA certificate and key. + +### Server Certificate (NGINX Plus) + +Follow the instructions in the [Server Certificate](./SERVER-CERTIFICATE.md) guide to create a self-signed server certificate and key. + +### Client Certificate (NLK) + +Follow the instructions in the [Client Certificate](./CLIENT-CERTIFICATE.md) guide to create a self-signed client certificate and key. + +## Kubernetes Secrets + +NLK accesses the necessary certificates for each mode from Kubernetes Secrets. For this mode, the following Kubernetes Secret(s) are required: +- CA Certificate +- Client Certificate + +To create the Kubernetes Secret containing the CA certificate, refer to the [Kubernetes Secrets](./KUBERNETES-SECRETS.md) guide; +the name and location of the certificate(s) created above should be used. The name of the Secret will be needed for the ConfigMap (discussed below). + +## ConfigMap + +NLK is configured via a ConfigMap. The ConfigMap is named `nlk-config` and is located in the `nlk` namespace. + +Depending on which mode is chosen, certain fields will need to be updated in the NLK ConfigMap. + +For this mode, the `mode`, `caCertificates`, and `clientCertificate` fields need to be included. The `mode` field should be set to `ss-mtls`, +the `caCertificates` field should be set to the name of the Kubernetes Secret containing the CA certificate created above, +and the `clientCertificate` field should be set to the name of the Kubernetes Secret containing the Client certificate created above. + +The following is an example of a ConfigMap for this mode (be sure to update the `nginx-hosts` field with the correct NGINX Plus API endpoints): + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: nlk-config + namespace: nlk +data: + nginx-hosts: "http://10.1.1.4:9000/api,http://10.1.1.5:9000/api" + mode: "ss-mtls" + caCertificate: "nlk-tls-ca-secret" + clientCertificate: "nlk-tls-client-secret" +``` + +## Deployment + +Save the above ConfigMap definition to a file named `ss-mtls-configmap.yaml`, then deploy the ConfigMap using the following command: + +```bash +kubectl apply -f docs/tls/ss-mtls-configmap.yaml +``` + +## Configuring NGINX Plus + +Refer to the [NGINX Plus Configuration](./NGINX-PLUS-CONFIGURATION.md) guide for instructions on configuring NGINX Plus to use the certificates created above. + +The steps in both the ["One-way TLS"](./NGINX-PLUS-CONFIGURATION.md#one-way-tls) section and the ["Mutual TLS"](./NGINX-PLUS-CONFIGURATION.md#mutual-tls) section are required for this mode. + +## Verification + +To verify the ConfigMap was deployed correctly, run the following command: + +```bash +kubectl get configmap -n nlk nlk-config -o yaml +``` + +The output should match the ConfigMap above. + +To verify NLK is running, follow the instructions in either the [TCP](../tcp/tcp-installation-guide.md) or [HTTP](../http/http-installation-guide.md) guides. diff --git a/docs/tls/SS-TLS.md b/docs/tls/SS-TLS.md new file mode 100644 index 0000000..aeee4a0 --- /dev/null +++ b/docs/tls/SS-TLS.md @@ -0,0 +1,83 @@ +# One-way TLS with self-signed certificates + +This mode allows NLK to verify it is connecting to the correct NGINX Plus instance, and encrypts the data between NLK and NGINX Plus. + +## Overview + +One-way TLS is used to encrypt the traffic between NLK and NGINX Plus, and to ensure NLK verifies the NGINX Plus server; +however, the NGINX Plus server _does not_ validate NLK. + +## Certificates + +To configure this mode, the following certificates are required: + +- CA Certificate +- Server Certificate + +See the following sections for instructions on how to create these certificates. + +### Certificate Authority (CA) + +Follow the instructions in the [Certificate Authority](./CERTIFICATE-AUTHORITY.md) guide to create a self-signed CA certificate and key. + +### Server Certificate (NGINX Plus) + +Follow the instructions in the [Server Certificate](./SERVER-CERTIFICATE.md) guide to create a self-signed server certificate and key. + +## Kubernetes Secrets + +NLK accesses the necessary certificates for each mode from Kubernetes Secrets. For this mode, the following Kubernetes Secret(s) are required: +- CA Certificate + +To create the Kubernetes Secret containing the CA certificate, refer to the [Kubernetes Secrets](./KUBERNETES-SECRETS.md) guide; +the name and location of the certificate(s) created above should be used. The name of the Secret will be needed for the ConfigMap (discussed below). + +## ConfigMap + +NLK is configured via a ConfigMap. The ConfigMap is named `nlk-config` and is located in the `nlk` namespace. + +Depending on which mode is chosen, certain fields will need to be updated in the NLK ConfigMap. + +For this mode, both the `mode` and `caCertificates` fields need to be included. The `mode` field should be set to `ss-tls`, +and the `caCertificates` field should be set to the name of the Kubernetes Secret containing the CA certificate created above. + +The following is an example of a ConfigMap for this mode (be sure to update the `nginx-hosts` field with the correct NGINX Plus API endpoints): + + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: nlk-config + namespace: nlk +data: + nginx-hosts: "http://10.1.1.4:9000/api,http://10.1.1.5:9000/api" + mode: "ss-tls" + caCertificate: "nlk-tls-ca-secret" +``` + +## Deployment + +Save the above ConfigMap definition to a file named `ss-tls-configmap.yaml`, then deploy the ConfigMap using the following command: + +```bash +kubectl apply -f docs/tls/ss-tls-configmap.yaml +``` + +## Configuring NGINX Plus + +Refer to the [NGINX Plus Configuration](./NGINX-PLUS-CONFIGURATION.md) guide for instructions on configuring NGINX Plus to use the certificates created above. + +Only the steps in the ["One-way TLS"](./NGINX-PLUS-CONFIGURATION.md#one-way-tls) section are required for this mode. + +## Verification + +To verify the ConfigMap was deployed correctly, run the following command: + +```bash +kubectl get configmap -n nlk nlk-config -o yaml +``` + +The output should match the ConfigMap above. + +To verify NLK is running, follow the instructions in either the [TCP](../tcp/tcp-installation-guide.md) or [HTTP](../http/http-installation-guide.md) guides.