TLS Documentation Changes (#12940)

* Add note to TLS cipher suite configuration Ordering is no longer respected and the tls_max_version flag must be used for this list to be relevant (as TLSv1.3 will ignore the cipher suite list entirely). See blog post linked in the docs for more information. Signed-off-by: Alexander Scheel <[email protected]> * Note that server cipher suite flag is ignored Signed-off-by: Alexander Scheel <[email protected]> * Add upgrade note about TLS cipher suites Signed-off-by: Alexander Scheel <[email protected]>
hashicorp · Nov 1, 2021 · 759f94f · 759f94f
1 parent 9701bdf
commit 759f94f
Show file tree

Hide file tree

Showing 2 changed files with 19 additions and 0 deletions.
diff --git a/website/content/docs/configuration/listener/tcp.mdx b/website/content/docs/configuration/listener/tcp.mdx
@@ -133,9 +133,17 @@ default value in the `"/sys/config/ui"` [API endpoint](/api/system/config-ui).
   ciphersuites as a comma-separated-list. The list of all available ciphersuites
   is available in the [Golang TLS documentation][golang-tls].
 
+  ~> **Note**: Go only consults this list for TLSv1.2 and earlier; the order of
+  ciphers is not important. For this parameter to be effective, the
+  `tls_max_version` property must be set to `tls12` to prevent negotiation of
+  TLSv1.3, which is not recommended. See the [Go blog post][go-tls-blog] for
+  more information.
+
 - `tls_prefer_server_cipher_suites` `(string: "false")` – Specifies to prefer the
   server's ciphersuite over the client ciphersuites.
 
+  ~> **Warning**: This parameter is deprecated. Setting it has no effect.
+
 - `tls_require_and_verify_client_cert` `(string: "false")` – Turns on client
   authentication for this listener; the listener will require a presented
   client cert that successfully validates against system CAs.
@@ -331,3 +339,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]: /docs/configuration#api_addr
 [cluster-addr]: /docs/configuration#cluster_addr
+[go-tls-blog]: https://go.dev/blog/tls-cipher-suites
diff --git a/website/content/docs/upgrading/upgrade-to-1.9.0.mdx b/website/content/docs/upgrading/upgrade-to-1.9.0.mdx
@@ -65,3 +65,13 @@ should prepare to [migrate](/docs/commands/operator/migrate) Vault storage to
 an Etcd v3 cluster prior to upgrading to Vault 1.10. All storage migrations
 should have [backups](/docs/concepts/storage#backing-up-vault-s-persisted-data)
 taken prior to migration.
+
+## TLS Cipher Suites Changes
+
+In Vault 1.9, due to changes in Go 1.17, the `tls_prefer_server_cipher_suites`
+TCP configuration parameter has been deprecated and its value will be ignored.
+
+Additionally, Go has begun doing automated cipher suite ordering and no longer
+respects the order of suites given in `tls_cipher_suites`.
+
+See [this blog post](https://go.dev/blog/tls-cipher-suites) for more information.