From 54fffe52660d0dac8c16f0aaada6ab24cbde5f4e Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Thu, 8 Jul 2021 17:51:12 -0400 Subject: [PATCH 1/4] docs: fix example of TLS config To actually enable TLS --- website/content/docs/agent/options.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/website/content/docs/agent/options.mdx b/website/content/docs/agent/options.mdx index 04e42a035b..6648c4a211 100644 --- a/website/content/docs/agent/options.mdx +++ b/website/content/docs/agent/options.mdx @@ -555,6 +555,8 @@ definitions support being updated during a reload. #### Example Configuration File, with TLS +~> **Security Note:** three verify options must be set to `true` to enable TLS. + ```javascript { "datacenter": "east-aws", @@ -570,7 +572,10 @@ definitions support being updated during a reload. }, "key_file": "/etc/pki/tls/private/my.key", "cert_file": "/etc/pki/tls/certs/my.crt", - "ca_file": "/etc/pki/tls/certs/ca-bundle.crt" + "ca_file": "/etc/pki/tls/certs/ca-bundle.crt", + "verify_incoming": true, + "verify_outgoing": true, + "verify_server_hostname": true } ``` From d906ddb218b573583d6a1a529e7239f421a2c7e2 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Thu, 8 Jul 2021 18:01:04 -0400 Subject: [PATCH 2/4] docs: group all agent tls settings together. To make it easier to see all of the related settings in one place. Also add some context about how these settings are applied. --- website/content/docs/agent/options.mdx | 88 ++++++++++++++------------ 1 file changed, 48 insertions(+), 40 deletions(-) diff --git a/website/content/docs/agent/options.mdx b/website/content/docs/agent/options.mdx index 6648c4a211..a91752c16f 100644 --- a/website/content/docs/agent/options.mdx +++ b/website/content/docs/agent/options.mdx @@ -555,7 +555,9 @@ definitions support being updated during a reload. #### Example Configuration File, with TLS -~> **Security Note:** three verify options must be set to `true` to enable TLS. +See [TLS Configuration Reference](#tls-configuration-reference) for more information about Agent TLS settings. + +~> **Security Note:** the three verify options must be set to `true` to enable TLS. ```javascript { @@ -1168,19 +1170,6 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr The default value is "No limit" and should be tuned on large clusters to avoid performing too many RPCs on entries changing a lot. -- `ca_file` This provides a file path to a PEM-encoded certificate - authority. The certificate authority is used to check the authenticity of client - and server connections with the appropriate [`verify_incoming`](#verify_incoming) - or [`verify_outgoing`](#verify_outgoing) flags. - -- `ca_path` This provides a path to a directory of PEM-encoded - certificate authority files. These certificate authorities are used to check the - authenticity of client and server connections with the appropriate [`verify_incoming`](#verify_incoming) or [`verify_outgoing`](#verify_outgoing) flags. - -- `cert_file` This provides a file path to a PEM-encoded - certificate. The certificate is provided to clients or servers to verify the agent's - authenticity. It must be provided along with [`key_file`](#key_file). - - `check_update_interval` ((#check_update_interval)) This interval controls how often check output from checks in a steady state is synchronized with the server. By default, this is set to 5 minutes ("5m"). Many @@ -1607,10 +1596,6 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr part of the cluster before declaring it dead, giving that suspect node more time to refute if it is indeed still alive. The default is 6. -- `key_file` This provides a the file path to a PEM-encoded - private key. The key is used with the certificate to verify the agent's authenticity. - This must be provided along with [`cert_file`](#cert_file). - - `http_config` This object allows setting options for the HTTP API and UI. The following sub-keys are available: @@ -1900,10 +1885,6 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr - `read_replica` - Equivalent to the [`-read-replica` command-line flag](#_read_replica). -- `server_name` When provided, this overrides the [`node_name`](#_node) - for the TLS certificate. It can be used to ensure that the certificate name matches - the hostname we declare. - - `session_ttl_min` The minimum allowed session TTL. This ensures sessions are not created with TTL's shorter than the specified limit. It is recommended to keep this limit at or above the default to encourage clients to send infrequent heartbeats. Defaults to 10s. @@ -2063,19 +2044,6 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr is provided, this controls to which facility messages are sent. By default, `LOCAL0` will be used. -- `tls_min_version` Added in Consul 0.7.4, this specifies - the minimum supported version of TLS. Accepted values are "tls10", "tls11", "tls12", - or "tls13". This defaults to "tls12". WARNING: TLS 1.1 and lower are generally - considered less secure; avoid using these if possible. - -- `tls_cipher_suites` Added in Consul 0.8.2, this specifies the list of - supported ciphersuites as a comma-separated-list. The list of all supported - ciphersuites is available through - [this search](https://github.com/hashicorp/consul/search?q=cipherMap+%3A%3D+map&unscoped_q=cipherMap+%3A%3D+map). - -- `tls_prefer_server_cipher_suites` Added in Consul 0.8.2, this - will cause Consul to prefer the server's ciphersuite over the client ciphersuites. - - `translate_wan_addrs` If set to true, Consul will prefer a node's configured [WAN address](#_advertise-wan) when servicing DNS and HTTP requests for a node in a remote datacenter. This allows @@ -2250,6 +2218,51 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr streaming. All servers must have [`rpc.enable_streaming`](#rpc_enable_streaming) enabled before any client can enable `use_streaming_backend`. +- `watches` - Watches is a list of watch specifications which + allow an external process to be automatically invoked when a particular data view + is updated. See the [watch documentation](/docs/agent/watches) for more detail. + Watches can be modified when the configuration is reloaded. + +### TLS Configuration Reference + +This section documents all of the configuration settings that apply to Agent TLS. Agent +TLS is used by the HTTP API, server RPC, and xDS interfaces. Some of these settings may also be +applied automatically by [auto_config](#auto_config) or [auto_encrypt](#auto_encrypt). + +- `ca_file` This provides a file path to a PEM-encoded certificate + authority. The certificate authority is used to check the authenticity of client + and server connections with the appropriate [`verify_incoming`](#verify_incoming) + or [`verify_outgoing`](#verify_outgoing) flags. + +- `ca_path` This provides a path to a directory of PEM-encoded + certificate authority files. These certificate authorities are used to check the + authenticity of client and server connections with the appropriate [`verify_incoming`](#verify_incoming) or [`verify_outgoing`](#verify_outgoing) flags. + +- `cert_file` This provides a file path to a PEM-encoded + certificate. The certificate is provided to clients or servers to verify the agent's + authenticity. It must be provided along with [`key_file`](#key_file). + +- `key_file` This provides a the file path to a PEM-encoded + private key. The key is used with the certificate to verify the agent's authenticity. + This must be provided along with [`cert_file`](#cert_file). + +- `server_name` When provided, this overrides the [`node_name`](#_node) + for the TLS certificate. It can be used to ensure that the certificate name matches + the hostname we declare. + +- `tls_min_version` Added in Consul 0.7.4, this specifies + the minimum supported version of TLS. Accepted values are "tls10", "tls11", "tls12", + or "tls13". This defaults to "tls12". WARNING: TLS 1.1 and lower are generally + considered less secure; avoid using these if possible. + +- `tls_cipher_suites` Added in Consul 0.8.2, this specifies the list of + supported ciphersuites as a comma-separated-list. The list of all supported + ciphersuites is available through + [this search](https://github.com/hashicorp/consul/search?q=cipherMap+%3A%3D+map&unscoped_q=cipherMap+%3A%3D+map). + +- `tls_prefer_server_cipher_suites` Added in Consul 0.8.2, this + will cause Consul to prefer the server's ciphersuite over the client ciphersuites. + - `verify_incoming` - If set to true, Consul requires that all incoming connections make use of TLS and that the client provides a certificate signed by a Certificate Authority from the @@ -2303,11 +2316,6 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr [CVE-2018-19653](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-19653) for more details. For those versions you **must also set `verify_outgoing = true`** to ensure encrypted RPC connections. -- `watches` - Watches is a list of watch specifications which - allow an external process to be automatically invoked when a particular data view - is updated. See the [watch documentation](/docs/agent/watches) for more detail. - Watches can be modified when the configuration is reloaded. - ## Ports Used Consul requires up to 6 different ports to work properly, some on From 7e681b142814670a1edcb1e327ec261e625bee62 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Mon, 12 Jul 2021 13:03:32 -0400 Subject: [PATCH 3/4] Update website/content/docs/agent/options.mdx Co-authored-by: Kent 'picat' Gruber --- website/content/docs/agent/options.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/agent/options.mdx b/website/content/docs/agent/options.mdx index a91752c16f..a33f3f0293 100644 --- a/website/content/docs/agent/options.mdx +++ b/website/content/docs/agent/options.mdx @@ -557,7 +557,7 @@ definitions support being updated during a reload. See [TLS Configuration Reference](#tls-configuration-reference) for more information about Agent TLS settings. -~> **Security Note:** the three verify options must be set to `true` to enable TLS. +~> **Security Note:** all three verify options should be set as `true` to enable secure mTLS communication, enabling both encryption and authentication. Failing to set [`verify_incoming`](#verify_incoming) or [`verify_outgoing`](#verify_outgoing) can result in TLS not being enabled at all, even when specifying a [`ca_file`](#ca_file), [`cert_file`](#cert_file), and [`key_file`](#key_file). ```javascript { From c69a3fa760ee46d7cc2de370677e88f005ccde57 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Mon, 12 Jul 2021 13:08:02 -0400 Subject: [PATCH 4/4] docs: move TLS example next to field reference --- website/content/docs/agent/options.mdx | 82 +++++++++++++------------- 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/website/content/docs/agent/options.mdx b/website/content/docs/agent/options.mdx index a33f3f0293..ac86c1a775 100644 --- a/website/content/docs/agent/options.mdx +++ b/website/content/docs/agent/options.mdx @@ -553,46 +553,6 @@ definitions support being updated during a reload. } ``` -#### Example Configuration File, with TLS - -See [TLS Configuration Reference](#tls-configuration-reference) for more information about Agent TLS settings. - -~> **Security Note:** all three verify options should be set as `true` to enable secure mTLS communication, enabling both encryption and authentication. Failing to set [`verify_incoming`](#verify_incoming) or [`verify_outgoing`](#verify_outgoing) can result in TLS not being enabled at all, even when specifying a [`ca_file`](#ca_file), [`cert_file`](#cert_file), and [`key_file`](#key_file). - -```javascript -{ - "datacenter": "east-aws", - "data_dir": "/opt/consul", - "log_level": "INFO", - "node_name": "foobar", - "server": true, - "addresses": { - "https": "0.0.0.0" - }, - "ports": { - "https": 8501 - }, - "key_file": "/etc/pki/tls/private/my.key", - "cert_file": "/etc/pki/tls/certs/my.crt", - "ca_file": "/etc/pki/tls/certs/ca-bundle.crt", - "verify_incoming": true, - "verify_outgoing": true, - "verify_server_hostname": true -} -``` - -See, especially, the use of the `ports` setting: - -```javascript -"ports": { - "https": 8501 -} -``` - -Consul will not enable TLS for the HTTP API unless the `https` port has been -assigned a port number `> 0`. We recommend using `8501` for `https` as this -default will automatically work with some tooling. - #### Configuration Key Reference -> **Note:** All the TTL values described below are parsed by Go's `time` package, and have the following @@ -2223,7 +2183,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr is updated. See the [watch documentation](/docs/agent/watches) for more detail. Watches can be modified when the configuration is reloaded. -### TLS Configuration Reference +## TLS Configuration Reference This section documents all of the configuration settings that apply to Agent TLS. Agent TLS is used by the HTTP API, server RPC, and xDS interfaces. Some of these settings may also be @@ -2316,6 +2276,46 @@ applied automatically by [auto_config](#auto_config) or [auto_encrypt](#auto_enc [CVE-2018-19653](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-19653) for more details. For those versions you **must also set `verify_outgoing = true`** to ensure encrypted RPC connections. +### Example Configuration File, with TLS + +~> **Security Note:** all three verify options should be set as `true` to enable secure mTLS communication, enabling both +encryption and authentication. Failing to set [`verify_incoming`](#verify_incoming) or [`verify_outgoing`](#verify_outgoing) +will result in TLS not being enabled at all, even when specifying a [`ca_file`](#ca_file), [`cert_file`](#cert_file), and [`key_file`](#key_file). + +```javascript +{ + "datacenter": "east-aws", + "data_dir": "/opt/consul", + "log_level": "INFO", + "node_name": "foobar", + "server": true, + "addresses": { + "https": "0.0.0.0" + }, + "ports": { + "https": 8501 + }, + "key_file": "/etc/pki/tls/private/my.key", + "cert_file": "/etc/pki/tls/certs/my.crt", + "ca_file": "/etc/pki/tls/certs/ca-bundle.crt", + "verify_incoming": true, + "verify_outgoing": true, + "verify_server_hostname": true +} +``` + +See, especially, the use of the `ports` setting: + +```javascript +"ports": { + "https": 8501 +} +``` + +Consul will not enable TLS for the HTTP API unless the `https` port has been +assigned a port number `> 0`. We recommend using `8501` for `https` as this +default will automatically work with some tooling. + ## Ports Used Consul requires up to 6 different ports to work properly, some on