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",