Documentation for Support TLS 1.3 ciphers in load balancer configuration

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]```<br>```client_max_body_size="250"``` |
-| nginx['ssl_protocols']                          | TLSv1.2                                   | TLSv1.2                             | ```[cs_nginx.v1.sys.ngx.http]```<br>```ssl_protocols="TLSv1.2"```      |
+| nginx['ssl_protocols']                          | TLSv1.2 TLSv1.3                           | TLSv1.2 TLSv1.3                     | ```[cs_nginx.v1.sys.ngx.http]```<br>```ssl_protocols="TLSv1.2 TLSv1.3"```<br>**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]```<br>```worker_connections=10240``` |
 | nginx['worker_processes']                       | 4                                         | 2                                   | ```[cs_nginx.v1.sys.ngx.main]```<br>```worker_processes=4```     |
 | nginx['gzip']                                   | ON                                        |ON                                   |```[cs_nginz.v1.sys.ngx.http]```<br>```gzip= "on"```              |
@@ -31,6 +31,7 @@ The list of parameters are as follows:
 | nginx['keepalive_timeout']                      |65                                         |65                                   |```[cs_nginz.v1.sys.ngx.http]```<br>```keepalive_timeout=65```      |
 | nginx['sendfile']                               |ON                                         |ON                                   |```[cs_nginz.v1.sys.ngx.http]```<br>```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]```<br>```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]```<br>```ssl_ciphersuites=""```<br>**Note:** TLS 1.3 cipher suites only. |
 | opscode_erchef['s3_url_ttl']                    | 900                                       | 28800                               | ```[erchef.v1.sys.api]```<br>```s3_url_ttl=900```                  |
 | opscode_erchef['auth_skew']                     | 900                                       | 900                                 | ```[erchef.v1.sys.api]```<br>```auth_skew=900```                   |
 | opscode_erchef['authz_fanout']                  | 20                                        | 20                                  | ```[erchef.v1.sys.authz]```<br>```fanout=20```               |

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<your load balancer private key>\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 </path/to/your-file.toml>` 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:

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.