Merge pull request #10579 from hashicorp/dnephin/improve-config-docs-tls

docs: Improve TLS user documentation

website/content/docs/agent/options.mdx

@@ -553,39 +553,6 @@ definitions support being updated during a reload.
 }
 ```
 
-#### Example Configuration File, with TLS
-
-```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"
-}
-```
-
-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
@@ -1163,19 +1130,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
@@ -1602,10 +1556,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:
@@ -1895,10 +1845,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.
@@ -2058,19 +2004,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
@@ -2245,6 +2178,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
@@ -2298,10 +2276,45 @@ 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
+### Example Configuration File, with TLS
-  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.
+~> **Security Note:** all three verify options should be set as `true` to enable secure mTLS communication, enabling both
-  Watches can be modified when the configuration is reloaded.
+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