Add TCP TLS guide (#27318)

* Add TCP TLS guide * Fix example listener stanza missing } * Update website/content/docs/configuration/listener/tcp-tls.mdx Co-authored-by: Jamie Finnigan <[email protected]> * Update website/content/docs/configuration/listener/tcp-tls.mdx Co-authored-by: Jamie Finnigan <[email protected]> * Update website/content/docs/configuration/listener/tcp-tls.mdx Co-authored-by: Jamie Finnigan <[email protected]> * Update website/content/docs/configuration/listener/tcp-tls.mdx Co-authored-by: Jamie Finnigan <[email protected]> * Update website/content/docs/configuration/listener/tcp-tls.mdx Co-authored-by: Jamie Finnigan <[email protected]> * Update website/content/docs/configuration/listener/tcp-tls.mdx Co-authored-by: Jamie Finnigan <[email protected]> * Suggestions for TCP-TLS docs (#27335) * recreating edits * Fix nav entry --------- Co-authored-by: Jamie Finnigan <[email protected]> Co-authored-by: Sarah Chavis <[email protected]>
hashicorp · Jun 5, 2024 · 58a9338 · 58a9338
1 parent 7c893dc
commit 58a9338
Show file tree

Hide file tree

Showing 3 changed files with 260 additions and 4 deletions.
diff --git a/...ntent/docs/configuration/listener/tcp.mdx → ...docs/configuration/listener/tcp/index.mdx b/...ntent/docs/configuration/listener/tcp.mdx → ...docs/configuration/listener/tcp/index.mdx
@@ -1,7 +1,7 @@
 ---
 layout: docs
 page_title: TCP - Listeners - Configuration
-description: |-
+description: >-
   The TCP listener configures Vault to listen on the specified TCP address and
   port.
 ---
@@ -47,6 +47,44 @@ also omit keys from the response when the corresponding value is empty (`""`).
   settings will apply to CLI and UI output in addition to direct API calls.
 </Note>
 
+## Default TLS configuration
+
+By default, Vault TCP listeners only accept TLS 1.2 or 1.3 connections and will
+drop connection requests from clients using TLS 1.0 or 1.1.
+
+Vault uses the following ciphersuites by default:
+
+- **TLS 1.3** - `TLS_AES_128_GCM_SHA256`, `TLS_AES_256_GCM_SHA384`, or `TLS_CHACHA20_POLY1305_SHA256`.
+- **TLS 1.2** - depends on whether you configure Vault with a RSA or ECDSA certificate. 
+
+You can configure Vault with any cipher supported by the
+[`tls`](https://pkg.go.dev/crypto/tls) and
+[`tlsutil`](https://github.com/hashicorp/go-secure-stdlib/blob/main/tlsutil/tlsutil.go#L31-L57)
+Go packages. Vault uses the `tlsutil` package to parse ciphersuite configurations.
+
+<Note title="Sweet32 and 3DES">
+
+  The Go team and HashiCorp believe that the set of cyphers supported by `tls`
+  and `tlsutil` is appropriate for modern, secure usage. However, some
+  vulnerability scanners may flag issues with your configuration.
+
+  In particular, Sweet32 (CVE-2016-2183) is an attack against 64-bit block size
+  ciphers including 3DES that may allow an attacker to break the encryption of
+  long lived connections. According to the
+  [vulnerability disclosure](https://sweet32.info/), Sweet32 took a
+  single HTTPS session with 785 GB of traffic to break the encryption.
+
+  As of May 2024, the Go team does not believe the risk of Sweet32 is sufficient
+  to remove existing client compatibility by deprecating 3DES support, however,
+  the team did [de-prioritize 3DES](https://github.com/golang/go/issues/45430)
+  in favor of AES-based ciphers.
+
+</Note>
+
+Before overriding Vault defaults, we recommend reviewing the recommended Go team
+[approach to TLS configuration](https://go.dev/blog/tls-cipher-suites) with
+particular attention to their ciphersuite selections.
+
 ## Listener's custom response headers
 
 As of version 1.9, Vault supports defining custom HTTP response headers for the root path (`/`) and also on API endpoints (`/v1/*`).
@@ -119,7 +157,7 @@ default value in the `"/sys/config/ui"` [API endpoint](/vault/api-docs/system/co
   request size, in bytes. Defaults to 32 MB if not set or set to `0`.
   Specifying a number less than `0` turns off limiting altogether.
 
-- `max_request_duration` `(string: "90s")` – Specifies the maximum
+- `max_request_duration` `(string: "90s")` – Specifies the maximum
   request duration allowed before Vault cancels the request. This overrides
   `default_max_request_duration` for this listener.
 
@@ -283,6 +321,7 @@ This example shows enabling a TLS listener.
 
 ```hcl
 listener "tcp" {
+  address = "127.0.0.1:8200"
   tls_cert_file = "/etc/certs/vault.crt"
   tls_key_file  = "/etc/certs/vault.key"
 }
@@ -546,4 +585,4 @@ Raft Applied Index      219
 [golang-tls]: https://golang.org/src/crypto/tls/cipher_suites.go
 [api-addr]: /vault/docs/configuration#api_addr
 [cluster-addr]: /vault/docs/configuration#cluster_addr
-[go-tls-blog]: https://go.dev/blog/tls-cipher-suites
+[go-tls-blog]: https://go.dev/blog/tls-cipher-suites
diff --git a/website/content/docs/configuration/listener/tcp/tcp-tls.mdx b/website/content/docs/configuration/listener/tcp/tcp-tls.mdx
@@ -0,0 +1,208 @@
+---
+layout: docs
+page_title: Configure TLS for your Vault TCP listener
+description: >-
+  Example TCP listener configuration with TLS encryption.
+---
+
+# Configure TLS for your Vault TCP listener
+
+You can configure your TCP listener to use specific versions of TLS and specific
+ciphersuites.
+
+## Assumptions
+
+- **Your Vault instance is not currently running**. If your Vault cluster is
+  running, you must
+  [restart the cluster gracefully](https://support.hashicorp.com/hc/en-us/articles/17169701076371-A-Step-by-Step-Guide-to-Restarting-a-Vault-Cluster)
+  to apply changes to your TCP listener. SIGHIP will not reload your TLS
+  configuration.
+- **You have a valid TLS certificate file**.
+- **You have a valid TLS key file**.
+- **You have a valid CA file (if required)**.
+
+## Example TLS 1.3 configuration
+
+If a reasonably modern set of clients are connecting to a Vault instance, you
+can configure the `tcp` listener stanza to only accept TLS 1.3 with the
+`tls_min_version` parameter:
+
+<CodeBlockConfig hideClipboard highlight="5">
+
+```plaintext
+listener "tcp" {
+  address = "127.0.0.1:8200"
+  tls_cert_file = "cert.pem"
+  tls_key_file  = "key.pem"
+  tls_min_version = "tls13"
+}
+```
+
+</CodeBlockConfig>
+
+Vault does not accept explicit ciphersuite configuration for TLS 1.3 because the
+Go team has already designated a select set of ciphers that align with the
+broadly-accepted Mozilla Security/Server Side TLS guidance for [modern TLS
+configuration](https://wiki.mozilla.org/Security/Server_Side_TLS#Modern_compatibility).
+
+## Example TLS 1.2 configuration
+
+To use TLS 1.2 with a non-default set of ciphersuites, you can set 1.2 as the
+minimum and maximum allowed TLS version and explicitly define your preferred
+ciphersuites with `tls_ciper_suites` and one or more of the ciphersuite
+constants from the ciphersuite configuration parser. For example:
+
+<CodeBlockConfig hideClipboard highlight="5-7">
+
+```plaintext
+listener "tcp" {
+  address = "127.0.0.1:8200"
+  tls_cert_file = "cert.pem"
+  tls_key_file  = "key.pem"
+  tls_min_version = "tls12"
+  tls_max_version = "tls12"
+  tls_cipher_suites = "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256"
+}
+```
+
+</CodeBlockConfig>
+
+You must set the minimum and maximum TLS version to disable TLS 1.3, which does
+not support explicit cipher selection. The priority order of the ciphersuites
+in `tls_cipher_suites` is determined by the `tls` Go package.
+
+<Note>
+
+  The TLS 1.2 configuration example excludes any 3DES ciphers to avoid potential
+  exposure to the Sweet32 attack (CVE-2016-2183). You should customize the
+  ciphersuite list as needed to meet your environment-specific security
+  requirements.
+
+</Note>
+
+## Verify your TLS configuration
+
+You can verify your TLS configuration using an SSL scanner such as
+[`sslscan`](https://github.com/rbsec/sslscan). 
+
+<Tabs>
+<Tab heading="Example scan with ECDSA certificate">
+
+<CodeBlockConfig hideClipboard>
+
+```shell-session
+$ sslscan 127.0.0.1:8200
+Version: 2.1.3
+OpenSSL 3.2.1 30 Jan 2024
+
+Connected to 127.0.0.1
+
+Testing SSL server 127.0.0.1 on port 8200 using SNI name 127.0.0.1
+
+  SSL/TLS Protocols:
+SSLv2     disabled
+SSLv3     disabled
+TLSv1.0   disabled
+TLSv1.1   disabled
+TLSv1.2   enabled
+TLSv1.3   enabled
+
+  TLS Fallback SCSV:
+Server supports TLS Fallback SCSV
+
+  TLS renegotiation:
+Session renegotiation not supported
+
+  TLS Compression:
+Compression disabled
+
+  Heartbleed:
+TLSv1.3 not vulnerable to heartbleed
+TLSv1.2 not vulnerable to heartbleed
+
+  Supported Server Cipher(s):
+Preferred TLSv1.3  128 bits  TLS_AES_128_GCM_SHA256        Curve 25519 DHE 253
+Accepted  TLSv1.3  256 bits  TLS_AES_256_GCM_SHA384        Curve 25519 DHE 253
+Accepted  TLSv1.3  256 bits  TLS_CHACHA20_POLY1305_SHA256  Curve 25519 DHE 253
+Preferred TLSv1.2  128 bits  ECDHE-ECDSA-AES128-GCM-SHA256 Curve 25519 DHE 253
+Accepted  TLSv1.2  256 bits  ECDHE-ECDSA-AES256-GCM-SHA384 Curve 25519 DHE 253
+Accepted  TLSv1.2  256 bits  ECDHE-ECDSA-CHACHA20-POLY1305 Curve 25519 DHE 253
+Accepted  TLSv1.2  128 bits  ECDHE-ECDSA-AES128-SHA        Curve 25519 DHE 253
+Accepted  TLSv1.2  256 bits  ECDHE-ECDSA-AES256-SHA        Curve 25519 DHE 253
+
+  Server Key Exchange Group(s):
+TLSv1.3  128 bits  secp256r1 (NIST P-256)
+TLSv1.3  192 bits  secp384r1 (NIST P-384)
+TLSv1.3  260 bits  secp521r1 (NIST P-521)
+TLSv1.3  128 bits  x25519
+TLSv1.2  128 bits  secp256r1 (NIST P-256)
+TLSv1.2  192 bits  secp384r1 (NIST P-384)
+TLSv1.2  260 bits  secp521r1 (NIST P-521)
+TLSv1.2  128 bits  x25519
+
+  SSL Certificate:
+Signature Algorithm: ecdsa-with-SHA256
+ECC Curve Name:      prime256v1
+ECC Key Strength:    128
+
+Subject:  localhost
+Issuer:   localhost
+
+Not valid before: May 17 17:27:29 2024 GMT
+Not valid after:  Jun 16 17:27:29 2024 GMT
+```
+
+</CodeBlockConfig>
+
+</Tab>
+<Tab heading="Example scan with RSA certificate">
+
+<CodeBlockConfig hideClipboard>
+
+```shell-session
+sslscan 127.0.0.1:8200
+Testing SSL server 127.0.0.1 on port 8200 using SNI name 127.0.0.1
+
+  SSL/TLS Protocols:
+SSLv2     disabled
+SSLv3     disabled
+TLSv1.0   disabled
+TLSv1.1   disabled
+TLSv1.2   enabled
+TLSv1.3   enabled
+
+  Supported Server Cipher(s):
+Preferred TLSv1.3  128 bits  TLS_AES_128_GCM_SHA256        Curve 25519 DHE 253
+Accepted  TLSv1.3  256 bits  TLS_AES_256_GCM_SHA384        Curve 25519 DHE 253
+Accepted  TLSv1.3  256 bits  TLS_CHACHA20_POLY1305_SHA256  Curve 25519 DHE 253
+Preferred TLSv1.2  128 bits  ECDHE-RSA-AES128-GCM-SHA256   Curve 25519 DHE 253
+Accepted  TLSv1.2  256 bits  ECDHE-RSA-AES256-GCM-SHA384   Curve 25519 DHE 253
+Accepted  TLSv1.2  256 bits  ECDHE-RSA-CHACHA20-POLY1305   Curve 25519 DHE 253
+Accepted  TLSv1.2  128 bits  ECDHE-RSA-AES128-SHA          Curve 25519 DHE 253
+Accepted  TLSv1.2  256 bits  ECDHE-RSA-AES256-SHA          Curve 25519 DHE 253
+Accepted  TLSv1.2  128 bits  AES128-GCM-SHA256
+Accepted  TLSv1.2  256 bits  AES256-GCM-SHA384
+Accepted  TLSv1.2  128 bits  AES128-SHA
+Accepted  TLSv1.2  256 bits  AES256-SHA
+Accepted  TLSv1.2  112 bits  TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
+Accepted  TLSv1.2  112 bits  TLS_RSA_WITH_3DES_EDE_CBC_SHA
+
+  Server Key Exchange Group(s):
+TLSv1.3  128 bits  secp256r1 (NIST P-256)
+TLSv1.3  192 bits  secp384r1 (NIST P-384)
+TLSv1.3  260 bits  secp521r1 (NIST P-521)
+TLSv1.3  128 bits  x25519
+TLSv1.2  128 bits  secp256r1 (NIST P-256)
+TLSv1.2  192 bits  secp384r1 (NIST P-384)
+TLSv1.2  260 bits  secp521r1 (NIST P-521)
+TLSv1.2  128 bits  x25519
+
+  SSL Certificate:
+Signature Algorithm: sha256WithRSAEncryption
+RSA Key Strength:    4096
+```
+
+</CodeBlockConfig>
+
+</Tab>
+</Tabs>
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
@@ -357,7 +357,16 @@
           },
           {
             "title": "TCP",
-            "path": "configuration/listener/tcp"
+            "routes": [  
+              {
+                "title": "Overview",
+                "path": "configuration/listener/tcp"
+              },
+              {
+                "title": "Configure TLS",
+                "path": "configuration/listener/tcp/tcp-tls"
+              }
+            ]
           },
           {
             "title": "Unix",