From 888feb2af4989d24e04fc2638febb784ef183dc5 Mon Sep 17 00:00:00 2001 From: Sarah Chavis <62406755+schavis@users.noreply.github.com> Date: Wed, 5 Jun 2024 12:48:13 -0700 Subject: [PATCH] Add TCP TLS guide (#27318) (#27373) * Add TCP TLS guide * Apply Suggestions for TCP-TLS docs (#27335) --------- Co-authored-by: Jonathan Frappier <92055993+jonathanfrappier@users.noreply.github.com> Co-authored-by: Jamie Finnigan --- .../listener/{tcp.mdx => tcp/index.mdx} | 45 +++- .../configuration/listener/tcp/tcp-tls.mdx | 208 ++++++++++++++++++ website/data/docs-nav-data.json | 11 +- 3 files changed, 260 insertions(+), 4 deletions(-) rename website/content/docs/configuration/listener/{tcp.mdx => tcp/index.mdx} (89%) create mode 100644 website/content/docs/configuration/listener/tcp/tcp-tls.mdx diff --git a/website/content/docs/configuration/listener/tcp.mdx b/website/content/docs/configuration/listener/tcp/index.mdx similarity index 89% rename from website/content/docs/configuration/listener/tcp.mdx rename to website/content/docs/configuration/listener/tcp/index.mdx index 6c814a5cf5b2..f9a1425dba6b 100644 --- a/website/content/docs/configuration/listener/tcp.mdx +++ b/website/content/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. --- @@ -21,6 +21,44 @@ multiple interfaces. If you configure multiple listeners you also need to specify [`api_addr`][api-addr] and [`cluster_addr`][cluster-addr] so Vault will advertise the correct address to other nodes. +## 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 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. + + + +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/*`). @@ -93,7 +131,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. @@ -243,6 +281,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" } @@ -372,4 +411,4 @@ cluster_addr = "https://[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8201" [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 \ No newline at end of file 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..90b356bec14e --- /dev/null +++ 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: + + + +```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,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" +} +``` + + + +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 5dbdfc7cb70f..9a9f9bb54c69 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -313,7 +313,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",