From 50a5b1d6bb5b54b6247a6159ab9c1367ff2d41da Mon Sep 17 00:00:00 2001 From: Aishwarya2001A Date: Sat, 1 Nov 2025 10:28:11 +0530 Subject: [PATCH] Documentation for Support TLS 1.3 ciphers in load balancer configuration Signed-off-by: Aishwarya2001A --- .../automate/chef_infra_in_chef_automate.md | 3 +- .../content/automate/configuration.md | 171 +++++++++++++++++- .../automate/security_best_practices.md | 129 +++++++++++++ 3 files changed, 301 insertions(+), 2 deletions(-) diff --git a/components/docs-chef-io/content/automate/chef_infra_in_chef_automate.md b/components/docs-chef-io/content/automate/chef_infra_in_chef_automate.md index b5ea4489be..5c51ab52ec 100644 --- a/components/docs-chef-io/content/automate/chef_infra_in_chef_automate.md +++ b/components/docs-chef-io/content/automate/chef_infra_in_chef_automate.md @@ -21,7 +21,7 @@ The list of parameters are as follows: | Chef Infra Server Key | Default Values In Automate (Having Infra Server Package) | Default Values In Automate HA | Automate Configuration | | ----------------------------------------------- | ----------------------------------------- | ----------------------------------- | ---------------------------------------------------------- | | nginx['client_max_body_size'] | 250 | 250 | ```[cs_nginx.v1.sys.ngx.http]```
```client_max_body_size="250"``` | -| nginx['ssl_protocols'] | TLSv1.2 | TLSv1.2 | ```[cs_nginx.v1.sys.ngx.http]```
```ssl_protocols="TLSv1.2"``` | +| nginx['ssl_protocols'] | TLSv1.2 TLSv1.3 | TLSv1.2 TLSv1.3 | ```[cs_nginx.v1.sys.ngx.http]```
```ssl_protocols="TLSv1.2 TLSv1.3"```
**Note:** Supports TLS 1.2 and 1.3. SSLv2, SSLv3, TLSv1, and TLSv1.1 are deprecated. | | nginx['worker_connections'] | 10240 | 10240 | ```[cs_nginx.v1.sys.ngx.events]```
```worker_connections=10240``` | | nginx['worker_processes'] | 4 | 2 | ```[cs_nginx.v1.sys.ngx.main]```
```worker_processes=4``` | | nginx['gzip'] | ON |ON |```[cs_nginz.v1.sys.ngx.http]```
```gzip= "on"``` | @@ -31,6 +31,7 @@ The list of parameters are as follows: | nginx['keepalive_timeout'] |65 |65 |```[cs_nginz.v1.sys.ngx.http]```
```keepalive_timeout=65``` | | nginx['sendfile'] |ON |ON |```[cs_nginz.v1.sys.ngx.http]```
```sendfile ="on"``` | | nginx['ssl_ciphers'] | Refer [nginx[ssl_ciphers]](https://docs.chef.io/server/config_rb_server/#nginx-ssl-protocols-14) | Refer [nginx[ssl_ciphers]](https://docs.chef.io/server/config_rb_server/#nginx-ssl-protocols-14) |```[cs_nginz.v1.sys.ngx.http]```
```ssl_ciphers=""``` | +| nginx['ssl_ciphersuites'] | Refer [nginx[ssl_ciphersuites]](https://docs.chef.io/automate/configuration/#tlsssl-protocol-and-cipher-configuration) | Refer [nginx[ssl_ciphersuites]](https://docs.chef.io/automate/configuration/#tlsssl-protocol-and-cipher-configuration) |```[cs_nginz.v1.sys.ngx.http]```
```ssl_ciphersuites=""```
**Note:** TLS 1.3 cipher suites only. | | opscode_erchef['s3_url_ttl'] | 900 | 28800 | ```[erchef.v1.sys.api]```
```s3_url_ttl=900``` | | opscode_erchef['auth_skew'] | 900 | 900 | ```[erchef.v1.sys.api]```
```auth_skew=900``` | | opscode_erchef['authz_fanout'] | 20 | 20 | ```[erchef.v1.sys.authz]```
```fanout=20``` | diff --git a/components/docs-chef-io/content/automate/configuration.md b/components/docs-chef-io/content/automate/configuration.md index aeed02a47f..ec61322da6 100644 --- a/components/docs-chef-io/content/automate/configuration.md +++ b/components/docs-chef-io/content/automate/configuration.md @@ -341,7 +341,8 @@ Uncomment and change settings as needed, and then run `chef-automate config patc # large_client_header_buffers_number = 4 # sendfile = "on" # ssl_ciphers = "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:!aNULL:!eNULL:!EXPORT:AES256-GCM-SHA384" -# ssl_protocols = "TLSv1.2" +# ssl_ciphersuites = "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256" +# ssl_protocols = "TLSv1.2 TLSv1.3" # tcp_nodelay = "on" # tcp_nopush = "on" # enable_csp_header = false @@ -360,6 +361,174 @@ Uncomment and change settings as needed, and then run `chef-automate config patc # key = "-----BEGIN RSA PRIVATE KEY-----\n\n-----END RSA PRIVATE KEY-----\n" ``` +#### TLS/SSL Protocol and Cipher Configuration + +Chef Automate supports TLS 1.2 and TLS 1.3 protocols for secure communication. You can configure both protocols and their respective ciphers. + +##### Supported TLS Versions + +- **TLSv1.2** (Recommended for compatibility) +- **TLSv1.3** (Recommended for maximum security) + +{{< warning >}} +**Deprecated Protocols**: SSLv2, SSLv3, TLSv1, and TLSv1.1 are deprecated and non-functional. These protocols are not supported by modern OpenSSL versions (1.1.0+) and will not work even if configured. Use only TLSv1.2 and TLSv1.3. +{{< /warning >}} + +##### TLS 1.3 Cipher Suites + +TLS 1.3 uses the `ssl_ciphersuites` directive (separate from TLS 1.2's `ssl_ciphers`). When TLS 1.3 is enabled, you must specify cipher suites. + +**Default TLS 1.3 Cipher Suites:** + +```toml +[load_balancer.v1.sys.ngx.http] +ssl_protocols = "TLSv1.3" +ssl_ciphersuites = "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256" +``` + +**Supported TLS 1.3 Cipher Suites:** + +- `TLS_AES_256_GCM_SHA384` - AES-256 with GCM mode (most secure) +- `TLS_CHACHA20_POLY1305_SHA256` - ChaCha20-Poly1305 (optimized for mobile devices) +- `TLS_AES_128_GCM_SHA256` - AES-128 with GCM mode (faster performance) + +{{< note >}} +TLS 1.3 cipher suites use underscores in their names (e.g., `TLS_AES_256_GCM_SHA384`) and are separated by colons. Do not use hyphens or spaces. +{{< /note >}} + +##### TLS 1.2 Ciphers + +TLS 1.2 uses the `ssl_ciphers` directive (separate from TLS 1.3's `ssl_ciphersuites`). + +**Default TLS 1.2 Ciphers:** + +```toml +[load_balancer.v1.sys.ngx.http] +ssl_protocols = "TLSv1.2" +ssl_ciphers = "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256" +``` + +{{< note >}} +TLS 1.2 ciphers use hyphens in their names (e.g., `ECDHE-RSA-AES256-GCM-SHA384`) and are separated by colons. Do not use semicolons or spaces. +{{< /note >}} + +##### Dual TLS 1.2 and TLS 1.3 Configuration (Recommended) + +For maximum compatibility and security, enable both protocols: + +```toml +[load_balancer.v1.sys.ngx.http] +ssl_protocols = "TLSv1.2 TLSv1.3" +ssl_ciphers = "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305" +ssl_ciphersuites = "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256" +``` + +Then run `chef-automate config patch ` to deploy your change. + +##### Configuration Examples + +**Example 1: TLS 1.3 Only (Maximum Security)** + +```toml +[load_balancer.v1.sys.ngx.http] +ssl_protocols = "TLSv1.3" +ssl_ciphersuites = "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256" +``` + +**Example 2: TLS 1.2 Only (Legacy Compatibility)** + +```toml +[load_balancer.v1.sys.ngx.http] +ssl_protocols = "TLSv1.2" +ssl_ciphers = "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384" +``` + +**Example 3: Both Protocols (Production - Recommended)** + +```toml +[load_balancer.v1.sys.ngx.http] +ssl_protocols = "TLSv1.2 TLSv1.3" +ssl_ciphers = "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305" +ssl_ciphersuites = "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256" +``` + +##### Configuration Validation + +Chef Automate validates TLS/SSL configuration and provides error messages for common issues: + +**Common Configuration Errors:** + +1. **Empty ciphers when TLS 1.2 is enabled:** + ``` + Error: ssl_ciphers cannot be empty when TLSv1.2 is enabled + ``` + +2. **Empty cipher suites when TLS 1.3 is enabled:** + ``` + Error: ssl_ciphersuites cannot be empty when TLSv1.3 is enabled + ``` + +3. **Invalid protocol format:** + ``` + Error: 'TLS1.3' contains invalid protocol versions. Use 'TLSv1.3' + ``` + +4. **Invalid separator in ciphers:** + ``` + Error: ssl_ciphers should not contain spaces. Use colons (:) to separate cipher names + ``` + +5. **Wrong format for TLS 1.3 cipher suites:** + ``` + Error: 'TLS-AES-256-GCM-SHA384' contains invalid characters. Use underscores: TLS_AES_256_GCM_SHA384 + ``` + +**Configuration Warnings:** + +Chef Automate issues warnings for suboptimal configurations: + +1. **Deprecated protocols configured:** + ``` + WARNING: ssl_protocols 'TLSv1.1 TLSv1.2' contains deprecated and non-functional protocol versions (SSLv2, SSLv3, TLSv1, TLSv1.1). These protocols are not supported by OpenSSL 1.1.0+ and will not work. Use only TLSv1.2 and TLSv1.3. + ``` + +2. **Cipher suites configured without TLS 1.3:** + ``` + WARNING: ssl_ciphersuites is configured, but ssl_protocols does not include TLSv1.3. The ssl_ciphersuites directive will be ignored by NGINX. + ``` + +3. **TLS 1.2 ciphers configured without TLS 1.2:** + ``` + WARNING: ssl_ciphers is configured, but ssl_protocols does not include TLSv1.2. The ssl_ciphers directive will be ignored by NGINX. + ``` + +##### Testing TLS Configuration + +After applying TLS configuration, verify it's working correctly: + +**Test TLS 1.3 connection:** + +```bash +openssl s_client -connect your-automate-fqdn:443 -tls1_3 +``` + +**Test TLS 1.2 connection:** + +```bash +openssl s_client -connect your-automate-fqdn:443 -tls1_2 +``` + +**Check negotiated cipher:** + +```bash +openssl s_client -connect your-automate-fqdn:443 -tls1_3 | grep "Cipher" +``` + +Expected output for TLS 1.3: +``` +New, TLSv1.3, Cipher is TLS_AES_256_GCM_SHA384 +``` + #### Buffer Size Configure message buffer ingest size: diff --git a/components/docs-chef-io/content/automate/security_best_practices.md b/components/docs-chef-io/content/automate/security_best_practices.md index 460c68b049..31cf111873 100644 --- a/components/docs-chef-io/content/automate/security_best_practices.md +++ b/components/docs-chef-io/content/automate/security_best_practices.md @@ -12,6 +12,135 @@ gh_repo = "automate" weight = 50 +++ +## TLS/SSL Security Best Practices + +### Use Modern TLS Protocols + +Chef Automate supports TLS 1.2 and TLS 1.3. For optimal security, use the following configuration: + +#### Recommended Configuration (Production) + +```toml +[load_balancer.v1.sys.ngx.http] +ssl_protocols = "TLSv1.2 TLSv1.3" +ssl_ciphers = "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256" +ssl_ciphersuites = "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256" +``` + +This configuration: +- Supports both TLS 1.2 (for legacy clients) and TLS 1.3 (for modern clients) +- Prioritizes strongest ciphers +- Provides forward secrecy with ECDHE key exchange +- Disables weak and deprecated protocols + +#### High Security Configuration (TLS 1.3 Only) + +For environments where all clients support TLS 1.3: + +```toml +[load_balancer.v1.sys.ngx.http] +ssl_protocols = "TLSv1.3" +ssl_ciphersuites = "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256" +``` + +### Deprecated and Insecure Protocols + +{{< warning >}} +**NEVER use the following protocols in production:** + +- **SSLv2** - Critically insecure, not supported by modern OpenSSL +- **SSLv3** - Multiple vulnerabilities (POODLE), not supported by modern OpenSSL +- **TLSv1** - Deprecated, not supported by modern OpenSSL (1.1.0+) +- **TLSv1.1** - Deprecated by major browsers and standards, not supported by modern OpenSSL + +These protocols are non-functional even if configured, as they are not supported by OpenSSL 1.1.0 and newer. +{{< /warning >}} + +### TLS Cipher Selection Guidelines + +#### TLS 1.3 Cipher Suites (Priority Order) + +1. **`TLS_AES_256_GCM_SHA384`** (Highest Security) + - AES-256 encryption with GCM mode + - 384-bit SHA hash + - Best for environments requiring maximum security + +2. **`TLS_CHACHA20_POLY1305_SHA256`** (Mobile Optimized) + - ChaCha20 stream cipher with Poly1305 MAC + - Optimized for ARM processors (mobile devices) + - Excellent performance without AES hardware acceleration + +3. **`TLS_AES_128_GCM_SHA256`** (High Performance) + - AES-128 encryption with GCM mode + - Lower computational overhead + - Still provides strong security + +#### TLS 1.2 Ciphers (Priority Order) + +1. **ECDHE-ECDSA-AES256-GCM-SHA384** / **ECDHE-RSA-AES256-GCM-SHA384** + - Elliptic Curve Diffie-Hellman Ephemeral (forward secrecy) + - AES-256-GCM (strongest symmetric encryption) + - Preferred for high-security environments + +2. **ECDHE-ECDSA-CHACHA20-POLY1305** / **ECDHE-RSA-CHACHA20-POLY1305** + - Forward secrecy with ECDHE + - ChaCha20-Poly1305 (optimized for non-AES-hardware) + - Excellent for mobile and IoT devices + +3. **ECDHE-ECDSA-AES128-GCM-SHA256** / **ECDHE-RSA-AES128-GCM-SHA256** + - Forward secrecy with ECDHE + - AES-128-GCM (high performance, strong security) + - Good balance of security and performance + +### Testing TLS Configuration + +#### Verify TLS 1.3 Support + +```bash +# Test TLS 1.3 connection +openssl s_client -connect your-automate-fqdn:443 -tls1_3 + +# Expected output should show: +# - Protocol: TLSv1.3 +# - Cipher: TLS_AES_256_GCM_SHA384 (or configured cipher) +``` + +#### Verify TLS 1.2 Support + +```bash +# Test TLS 1.2 connection +openssl s_client -connect your-automate-fqdn:443 -tls1_2 + +# Expected output should show: +# - Protocol: TLSv1.2 +# - Cipher: ECDHE-RSA-AES256-GCM-SHA384 (or configured cipher) +``` + +#### Verify Weak Protocols are Disabled + +```bash +# These should fail with connection errors: +openssl s_client -connect your-automate-fqdn:443 -ssl3 # Should fail +openssl s_client -connect your-automate-fqdn:443 -tls1 # Should fail +openssl s_client -connect your-automate-fqdn:443 -tls1_1 # Should fail +``` + +### Security Compliance + +#### Compliance Checklist + +Use this checklist to verify TLS/SSL security compliance: + +- [ ] TLS 1.2 and/or TLS 1.3 enabled +- [ ] SSLv2, SSLv3, TLSv1, and TLSv1.1 explicitly disabled +- [ ] Strong ciphers configured +- [ ] Weak ciphers excluded +- [ ] Forward secrecy enabled +- [ ] Valid certificate from trusted CA +- [ ] Certificate key size >= 2048-bit RSA or 256-bit ECDSA +- [ ] Certificate expiration monitoring in place + + ## Ensuring autocomplete remains disabled on the login screen. A configuration maintained in Chef Automate's nginx.conf file determines the autocomplete functionality.