-
Notifications
You must be signed in to change notification settings - Fork 18
DOCS-3469 Added info about SSL/TLS certificates #1849
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
egoverdovskaya-wallarm
wants to merge
3
commits into
master
Choose a base branch
from
feature/docs-2204-SSL-termination-2
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| --8<-- "latest/admin-en/ssl-certificates.md" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,100 @@ | ||
| [nginx-sidecar]: ../installation/kubernetes/sidecar-proxy/deployment.md | ||
| [ssl-termination]: ../installation/kubernetes/sidecar-proxy/customization.md#ssltls-termination | ||
| [nginx-aio]: ../installation/inline/compute-instances/linux/all-in-one.md | ||
| [nginx-docker]: ../admin-en/installation-docker-en.md | ||
| [nginx-node]: ../installation/nginx-native-node-internals.md#nginx-node | ||
| [native-node]: ../installation/nginx-native-node-internals.md#native-node | ||
| [security-edge]: ../installation/security-edge/overview.md | ||
| [aws-ami]: ../installation/inline/compute-instances/aws/aws-ami.md | ||
| [gcp]: ../installation/inline/compute-instances/gcp/machine-image.md | ||
|
|
||
|
|
||
| # TLS Termination and Certificate Management (Self-Hosted Nodes) | ||
|
|
||
| This article describes how TLS termination and certificate management work in self-hosted Wallarm nodes (including NGINX and Native Nodes), and how HTTPS traffic is processed for analysis. | ||
|
|
||
|
egoverdovskaya-wallarm marked this conversation as resolved.
|
||
| Wallarm analyzes HTTP traffic only after TLS decryption. TLS termination can occur on an upstream component or on the Wallarm Node, which determines HTTPS traffic flow and whether certificates must be managed on the Wallarm side. | ||
|
|
||
| ## HTTPS traffic flow and TLS termination | ||
|
|
||
| HTTPS traffic is encrypted and cannot be inspected in its encrypted form. To analyze requests, the traffic must be decrypted at the point of TLS termination. | ||
|
|
||
| In Wallarm deployments, TLS termination can be performed either by an upstream component (e.g., a load balancer or Ingress Controller) or by a Wallarm Node. | ||
|
|
||
|
egoverdovskaya-wallarm marked this conversation as resolved.
|
||
| * If TLS is terminated upstream, Wallarm receives already decrypted traffic and does not require certificates. | ||
| * If a Wallarm NGINX Node terminates TLS, certificates must be issued, configured, and maintained on the Wallarm side. | ||
|
|
||
| ## TLS termination in the NGINX Node | ||
|
|
||
| The way TLS termination is handled in the NGINX Node depends on the deployment artifact (Sidecar, all-in-one installer, Docker image, or AWS/GCP cloud image). You can see each case described below. | ||
|
|
||
| ### Sidecar | ||
|
|
||
| By default, [Wallarm Sidecar][nginx-sidecar] does not terminate TLS. It expects an upstream component (e.g., Ingress or Application Gateway) to handle HTTPS, while the Sidecar receives decrypted HTTP traffic. | ||
|
|
||
| In this case, the Wallarm Node doesn't need certificates because TLS is terminated upstream. However, if your infrastructure cannot terminate TLS upstream, you can [enable TLS termination directly in Wallarm Sidecar][ssl-termination]. | ||
|
|
||
| ### [All-in-one installer][nginx-aio], [Docker image][nginx-docker], and [AWS][aws-ami]/[GCP][gcp] cloud images | ||
|
|
||
| The NGINX Node handles TLS termination. To configure it, you must issue an TLS certificate for the protected resource, upload the certificate and private key to the NGINX Node, and edit the [NGINX configuration](https://nginx.org/en/docs/http/configuring_https_servers.html). | ||
|
|
||
| Because the NGINX Node terminates TLS directly, certificate provisioning and lifecycle management are the clients' responsibility. Wallarm does not issue, manage, or automatically renew certificates. | ||
|
|
||
| You need to: | ||
|
|
||
| 1. Issue a certificate from a trusted Certificate Authority (CA) for a Wallarm Node instance. | ||
|
|
||
| The certificate must meet the following requirements: | ||
|
|
||
| * Supported format: PEM for both certificate and private key files. | ||
| * Key types and sizes: Any key size supported by OpenSSL/NGINX, including 2048-bit, 4096-bit, and ECDSA keys. | ||
| * Cipher suites: Defined and managed through standard NGINX/OpenSSL configuration. | ||
|
|
||
| 1. Upload the certificate file and private key to the host or container running the Wallarm NGINX Node. | ||
| 1. Edit the [NGINX configuration](https://nginx.org/en/docs/http/configuring_https_servers.html) of the Wallarm Node: | ||
|
|
||
| * [`ssl_certificate`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate) - specifies the PEM-format certificate file, including the full certificate chain. | ||
| * [`ssl_certificate_key`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate_key) - specifies the PEM-format private key file. | ||
|
|
||
| ??? info "Show sample NGINX configuration" | ||
|
|
||
| ``` | ||
| server { | ||
| listen 80; | ||
| server_name test.com; | ||
| return 301 https://$server_name$request_uri; | ||
| } | ||
|
|
||
| server { | ||
| listen 443 ssl; | ||
| listen [::]:443 ssl; | ||
| server_name test.com; | ||
|
|
||
| ssl_certificate /etc/ssl/certs/example_public.crt; | ||
| ssl_certificate_key /etc/ssl/key/private_example.key; | ||
|
|
||
| set_real_ip_from 11.11.11.11; # Replace with the IP address of the proxy in front of NGINX | ||
| real_ip_header X-Forwarded-For; | ||
| real_ip_recursive on; | ||
|
|
||
| wallarm_mode monitoring; | ||
| wallarm_application 100; | ||
|
|
||
| location / { | ||
| proxy_pass https://10.100.100.30; # Replace with the IP address of the origin server | ||
| proxy_set_header Host $host; | ||
| proxy_set_header X-Forwarded-For $remote_addr; | ||
| proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| 1. Monitor the certificate's validity and renew it before expiration. | ||
|
|
||
| To automate these actions, you can use external tools, e.g., [Certbot](https://certbot.eff.org/), [HashiCorp Vault](https://developer.hashicorp.com/vault), [Kubernetes cert-manager](https://cert-manager.io/), [Ansible playbooks](https://docs.ansible.com/projects/ansible/devel/playbook_guide/playbooks_intro.html), or others. | ||
|
|
||
| ## TLS termination in the Native Node | ||
|
|
||
| The Native Node **does not handle TLS termination** and never acts as an inline traffic endpoint. It analyzes a copy of traffic, not the original client connection. | ||
|
|
||
| HTTPS traffic must be decrypted by an upstream or adjacent component (e.g., load balancer, reverse proxy, ADC, Ingress Controller, or connector), which then sends a decrypted copy to the Native Node for analysis. Refer to the component's documentation for configuration details. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,6 @@ | ||
| Update targets of your load balancer to send traffic to the Wallarm instance. For details, please refer to the documentation on your load balancer. | ||
| 1. If you have secured communications between clients and the Wallarm Node with an SSL/TLS certificate, edit the [NGINX configuration ](https://nginx.org/en/docs/http/configuring_https_servers.html) to set up [TLS termination][ssl-certificates]: | ||
|
|
||
| * [`ssl_certificate`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate) - specifies the PEM-format certificate file, including the full certificate chain. | ||
| * [`ssl_certificate_key`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate_key) - specifies the PEM-format private key file. | ||
|
|
||
| 1. Update targets of your load balancer to send traffic to the Wallarm instance. For details, refer to the documentation on your load balancer. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.