Documentation for custom http response headers (#12524)

* Documentation for custom http response headers

* Adding more explanation of what custom headers are and when to use them

* Header in the config takes precedence

* Update website/content/docs/configuration/listener/tcp.mdx

Co-authored-by: Josh Black <raskchanky@users.noreply.github.com>

* Adding more information on how to use custom response headers

* adding an API link to the ui

Co-authored-by: Josh Black <raskchanky@users.noreply.github.com>

website/content/docs/configuration/listener/tcp.mdx

@@ -21,6 +21,29 @@ 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.
 
+## Listener's custom response headers
+Vault supports defining custom HTTP response headers for the root path (`/`) and also on API endpoints (`/v1/*`).
+The headers are defined based on the returned status code. For example, a user can define a list of
+custom response headers for the `200` status code, and another list of custom response headers for
+the `307` status code. There is a `"/sys/config/ui"` [API endpoint](/api/system/config-ui) which allows users
+to set `UI` specific custom headers. If a header is configured in a configuration file, it is not allowed
+to be reconfigured through the `"/sys/config/ui"` [API endpoint](/api/system/config-ui). In cases where a
+custom header value needs to be modified or the custom header needs to be removed, the Vault's configuration file
+needs to be modified accordingly, and a `SIGHUP` signal needs to be sent to the Vault process.
+
+If a header is defined in the configuration file and the same header is used by the internal
+processes of Vault, the configured header is not accepted. For example, a custom header which has
+the `X-Vault-` prefix will not be accepted. A message will be logged in the Vault's logs
+upon start up indicating the header with `X-Vault-` prefix is not accepted.
+
+### Order of precedence
+If the same header is configured in both the configuration file and
+in the `"/sys/config/ui"` [API endpoint](/api/system/config-ui), the header in the configuration file takes precedence.
+For example, the `"Content-Security-Policy"` header is defined by default in the
+`"/sys/config/ui"` [API endpoint](/api/system/config-ui). If that header is also defined in the configuration file,
+the value in the configuration file is set in the response headers instead of the
+default value in the `"/sys/config/ui"` [API endpoint](/api/system/config-ui).
+
 ## `tcp` Listener Parameters
 
 - `address` `(string: "127.0.0.1:8200")` – Specifies the address to bind to for
@@ -149,6 +172,24 @@ advertise the correct address to other nodes.
 - `unauthenticated_pprof_access` `(bool: false)` - If set to true, allows
   unauthenticated access to the `/v1/sys/pprof` endpoint.
 
+### `custom_response_headers` Parameters
+
+- `default` `(key-value-map: {})` - A map of string header names to an array of
+ string values. The default headers are set on all endpoints regardless of
+ the status code value. For an example, please refer to the
+ "Configuring custom http response headers" section.
+
+- `<specific status code>` `(key-value-map: {})` - A map of string header names
+ to an array of string values. These headers are set only when the specific status
+ code is returned. For example, `"200" = {"Header-A": ["Value1", "Value2"]}`, `"Header-A"`
+ is set when the http response status code is `"200"`.
+
+- `<collective status code>` `(key-value-map: {})` - A map of string header names
+ to an array of string values. These headers are set only when the response status
+ code falls under the collective status code.
+ For example, `"2xx" = {"Header-A": ["Value1", "Value2"]}`, `"Header-A"`
+ is set when the http response status code is `"200"`, `"204"`, etc.
+
 ## `tcp` Listener Examples
 
 ### Configuring TLS
@@ -205,6 +246,58 @@ listener "tcp" {
 ```
 
 
+### Configuring custom http response headers
+
+This example shows configuring custom http response headers. Operators can configure
+`"custom_response_headers"` sub-stanza in the listener stanza to set custom http
+headers appropriate to their applications. Examples of such headers are `"Strict-Transport-Security"`
+and `"Content-Security-Policy"` which are known HTTP headers, and could be configured to harden
+the security of an application communicating with the Vault endpoints. Note that vulnerability
+scans often examine such security related HTTP headers. In addition, application specific
+custom headers can also be configured. For example, `"X-Custom-Header"` has been configured
+in the example below.
+
+```hcl
+listener "tcp" {
+  custom_response_headers {
+    "default" = {
+      "Strict-Transport-Security" = ["max-age=31536000","includeSubDomains"],
+      "Content-Security-Policy" = ["connect-src https://clusterA.vault.external/"],
+      "X-Custom-Header" = ["Custom Header Default Value"],
+    },
+    "2xx" = {
+      "Content-Security-Policy" = ["connect-src https://clusterB.vault.external/"],
+      "X-Custom-Header" = ["Custom Header Value 1", "Custom Header Value 2"],
+    },
+    "301" = {
+      "Strict-Transport-Security" = ["max-age=31536000"],
+      “Content-Security-Policy" = ["connect-src https://clusterC.vault.external/"],
+    },
+  }
+}
+```
+
+In situations where a header is defined under several status code subsections,
+the header matching the most specific response code will be returned. For example,
+with the config example below, a `307` response would return `307 Custom header value`,
+while a `306` would return `3xx Custom header value`.
+
+```hcl
+listener "tcp" {
+  custom_response_headers {
+    "default" = {
+       "X-Custom-Header" = ["default Custom header value"]
+    },
+    "3xx" = {
+       "X-Custom-Header" = ["3xx Custom header value"]
+    },
+    "307" = {
+       "X-Custom-Header" = ["307 Custom header value"]
+    }
+  }
+}
+```
+
 ### Listening on all IPv6 & IPv4 Interfaces
 
 This example shows Vault listening on all IPv4 & IPv6 interfaces including localhost.