mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-10-30 02:02:43 +00:00
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 <jfinnigan@hashicorp.com> * Update website/content/docs/configuration/listener/tcp-tls.mdx Co-authored-by: Jamie Finnigan <jfinnigan@hashicorp.com> * Update website/content/docs/configuration/listener/tcp-tls.mdx Co-authored-by: Jamie Finnigan <jfinnigan@hashicorp.com> * Update website/content/docs/configuration/listener/tcp-tls.mdx Co-authored-by: Jamie Finnigan <jfinnigan@hashicorp.com> * Update website/content/docs/configuration/listener/tcp-tls.mdx Co-authored-by: Jamie Finnigan <jfinnigan@hashicorp.com> * Update website/content/docs/configuration/listener/tcp-tls.mdx Co-authored-by: Jamie Finnigan <jfinnigan@hashicorp.com> * Suggestions for TCP-TLS docs (#27335) * recreating edits * Fix nav entry --------- Co-authored-by: Jamie Finnigan <jfinnigan@hashicorp.com> Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>
This commit is contained in:
Jonathan Frappier
committed by
GitHub
GitHub
parent
b9a2f83019
commit
ef10c1a2a4
@@ -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.
|
||||
|
||||
@@ -303,6 +341,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"
|
||||
}
|
||||
@@ -566,4 +605,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
|
||||
208
website/content/docs/configuration/listener/tcp/tcp-tls.mdx
Normal file
208
website/content/docs/configuration/listener/tcp/tcp-tls.mdx
Normal file
@@ -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>
|
||||
@@ -376,7 +376,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",
|
||||
|
||||
Reference in New Issue
Block a user