From 50b5e49823cb191ed6f62d5710962f786c844dcd Mon Sep 17 00:00:00 2001
From: Sarah Chavis <62406755+schavis@users.noreply.github.com>
Date: Fri, 31 May 2024 15:24:13 -0700
Subject: [PATCH] Suggestions for TCP-TLS docs
---
.../docs/configuration/listener/tcp-tls.mdx | 293 ------------------
.../listener/{tcp.mdx => tcp/index.mdx} | 37 +++
.../configuration/listener/tcp/tcp-tls.mdx | 207 +++++++++++++
website/data/docs-nav-data.json | 15 +-
4 files changed, 254 insertions(+), 298 deletions(-)
delete mode 100644 website/content/docs/configuration/listener/tcp-tls.mdx
rename website/content/docs/configuration/listener/{tcp.mdx => tcp/index.mdx} (93%)
create mode 100644 website/content/docs/configuration/listener/tcp/tcp-tls.mdx
diff --git a/website/content/docs/configuration/listener/tcp-tls.mdx b/website/content/docs/configuration/listener/tcp-tls.mdx
deleted file mode 100644
index f68f0ccbf511..000000000000
--- a/website/content/docs/configuration/listener/tcp-tls.mdx
+++ /dev/null
@@ -1,293 +0,0 @@
----
-layout: docs
-page_title: TCP TLS - Listeners - Configuration
-description: |-
- Configure the TCP listener with TLS to encrypt
- traffic in-transit from Vault Clients to your Vault cluster.
----
-
-# Configure TLS for TCP listener
-
-Encryption of data in transit using TLS is an important part of a secure Vault
-deployment.
-
-This guide provides a basic Vault TLS configuration in alignment with client support
-needs, modern cryptography standards, and environment-specific security
-requirements.
-
-## Background
-
-Vault enables TLS for inbound TCP connections with a reasonably secure set of
-defaults, inherited from those provided by the [Go crypto/tls
-package](https://pkg.go.dev/crypto/tls). The Go team has developed an
-[opinionated approach to TLS
-configuration](https://go.dev/blog/tls-cipher-suites) and particularly
-ciphersuite selection, which Vault inherits through use of this package.
-
-## Requirements
-
-- A valid TLS certificate file, secret key, and (if required) CA file.
-
-## Default Vault TLS configuration
-
-A default Vault [TCP
-listener](/vault/docs/configuration/listener/tcp)
-configuration accepts TLS 1.2 or 1.3 connections. Attempts to connect using
-TLS 1.0 and 1.1 are dropped.
-
-The ciphersuites used for **TLS 1.2** depends on whether Vault has been
-configured with a RSA or ECDSA certificate. The TLS configuration may include
-any ciphers supported by Go’s TLS package and Vault’s [ciphersuite configuration
-parser](https://github.com/hashicorp/go-secure-stdlib/blob/main/tlsutil/tlsutil.go#L31-L57).
-
-
-
-While the Go team believes this set of ciphers are appropriate for modern secure
-usage, and HashiCorp agrees, some vulnerability scanners may flag issues with
-this 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.
-
-The Go team did not believe this attack was sufficient to remove existing client
-compatibility by deprecating 3DES support (per the researcher’s vulnerability
-disclosure it took a single HTTPS session with 785 GB of traffic to break the
-encryption). Go did deprioritize 3DES in favor of AES-based ciphers.
-
-
-
-The ciphersuites used for **TLS 1.3** are `TLS_AES_128_GCM_SHA256`,
-`TLS_AES_256_GCM_SHA384`, and `TLS_CHACHA20_POLY1305_SHA256`.
-
-## Configure TLS for a Vault TCP listener
-
-To run Vault with the default TLS configuration, add the TLS certficate to the
-Vault configuration files `listener` stanza and start Vault.
-
-
-
-If the TLS configuration is added after your Vault cluster is running, you must
-restart the cluster gracefully. A sighup will not reload the TLS configuration.
-
-Refer to the [HashiCorp support knowledge
-base](https://support.hashicorp.com/hc/en-us/articles/17169701076371-A-Step-by-Step-Guide-to-Restarting-a-Vault-Cluster)
-for more information.
-
-
-
-**Example configuration:**
-
-
-
-```plaintext
-listener "tcp" {
- address = "127.0.0.1:8200"
- tls_cert_file = "cert.pem"
- tls_key_file = "key.pem"
-}
-```
-
-
-
-You can verify the TLS configuration using an SSL scanner such as
-[`sslscan`](https://github.com/rbsec/sslscan) or similar tools.
-
-**Example sslscan output:**
-
-
-
-
-
-
-```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
-```
-
-
-
-
-
-
-
-
-```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
-```
-
-
-
-
-
-
-## Customize Vault TLS configuration
-
-If this default TLS protocol and ciphersuite support is not suitable, Vault’s
-TLS configuration can be customized using various parameters within the
-[listener](/vault/docs/configuration/listener/tcp) configuration stanza.
-
-### Configure TLS 1.2
-
-If you require TLS 1.2, but with a non-default set of ciphersuites, you can
-explicitly define the ciphersuites.
-
-Add the `tls_min_version`, `tls_max_version`, and `tls_ciper_suites` parameters
-to the `listner` stanza.
-
-**Example configuration:**
-
-
-
-```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"}
-```
-
-
-
-Both `tls_min_version` and `tls_max_version` are set to `tls12` to disable usage
-of TLS 1.3, as suggested in the [tcp listener
-documentation](/vault/docs/configuration/listener/tcp#tls_cipher_suites).
-
-The ciphersuites used in `tls_cipher_suites` are taken from the list supported by
-Vault’s ciphersuite configuration parser. The ordering of `tls_cipher_suites` does
-not matter, as Go will determine the ordering.
-
-This configuration excludes any 3DES ciphers to avoid potential exposure to the
-Sweet32 attack (CVE-2016-2183) described earlier. You can customize this example
-to meet environment-specific security requirements.
-
-### Configure TLS 1.3
-
-If a reasonably modern set of clients are connecting to a Vault instance, you
-can be configure the tcp listener stanza to accept just TLS 1.3.
-
-Set the `tls_min_version` parameter to `tls13`.
-
-**Example configuration:**
-
-
-
-```plaintext
-listener "tcp" {
- address = "127.0.0.1:8200"
- tls_cert_file = "cert.pem"
- tls_key_file = "key.pem"
- tls_min_version = "tls13"
-}
-```
-
-
-
-Ciphersuite configuration is not supported in this mode. A select set of ciphers
-has been selected by the Go team and aligned with the [modern
-configuration](https://wiki.mozilla.org/Security/Server_Side_TLS#Modern_compatibility)
-in the broadly-accepted Mozilla Security/Server Side TLS guidance.
-
-## Next steps
-
-- [Vault security model](/vault/docs/internals/security)
-- [Vault production hardening tutorial](/vault/tutorials/operations/production-hardening)
-- [Vault with integrated storage reference architecture](/vault/tutorials/day-one-raft/raft-reference-architecture)
\ No newline at end of file
diff --git a/website/content/docs/configuration/listener/tcp.mdx b/website/content/docs/configuration/listener/tcp/index.mdx
similarity index 93%
rename from website/content/docs/configuration/listener/tcp.mdx
rename to website/content/docs/configuration/listener/tcp/index.mdx
index 089a12b0419f..8607fe6eade9 100644
--- a/website/content/docs/configuration/listener/tcp.mdx
+++ b/website/content/docs/configuration/listener/tcp/index.mdx
@@ -47,6 +47,42 @@ 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.
+## 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.
+
+
+
+ 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 vulnerability disclosures, 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 .
+
+
+
+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/*`).
@@ -303,6 +339,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"
}
diff --git a/website/content/docs/configuration/listener/tcp/tcp-tls.mdx b/website/content/docs/configuration/listener/tcp/tcp-tls.mdx
new file mode 100644
index 000000000000..0515af4ee281
--- /dev/null
+++ b/website/content/docs/configuration/listener/tcp/tcp-tls.mdx
@@ -0,0 +1,207 @@
+---
+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:
+
+
+
+```plaintext
+listener "tcp" {
+ address = "127.0.0.1:8200"
+ tls_cert_file = "cert.pem"
+ tls_key_file = "key.pem"
+ tls_min_version = "tls13"
+}
+```
+
+
+
+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:
+
+
+
+```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"}
+```
+
+
+
+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.
+
+
+
+ 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.
+
+
+
+## Verify your TLS configuration
+
+You can verify your TLS configuration using an SSL scanner such as
+[`sslscan`](https://github.com/rbsec/sslscan).
+
+
+
+
+
+
+```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
+```
+
+
+
+
+
+
+
+
+```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
+```
+
+
+
+
+
\ No newline at end of file
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index b0470b833df2..340e86a49868 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -376,11 +376,16 @@
},
{
"title": "TCP",
- "path": "configuration/listener/tcp"
- },
- {
- "title": "Configure TLS for TCP listener",
- "path": "configuration/listener/tcp-tls"
+ "routes": [
+ {
+ "title": "Overview",
+ "path": "configuration/listener/tcp"
+ },
+ {
+ "title": "Configure TLS",
+ "path": "configuration/listener/tcp/tcp-tls"
+ }
+ ]
},
{
"title": "Unix",