docs: Clarify how XFCC headers are handled (#6586)

Since XFCC headers contain authentication information, it's important to know
precisely how Contour (ie Envoy) handle existing XFCC headers from clients -
ie, are they blocked, or appended to, and in what circumstances are they
blocked? Getting this wrong could allow serious vulnerabilities such as
spoofing client certs.

This documents Contours behaviour, so that users can know exactly how they are
required to handle that header without needing to dive into the Contour source
code. My understanding from reading the source code:

https://github.com/gautierdelorme/contour/blob/main/internal/envoy/v3/listener.go#L483

as well as the Envoy documentation:

https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-enum-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-forwardclientcertdetails

is that when forwarding client certificate details is not configured in
Contour, Contour leaves `ForwardClientCertDetails` in Envoy unset, which means
it defaults to `SANITIZE`, which means incoming headers from clients are
blocked. Meanwhile, when forwarding client certificate details is configured in
Contour, Contour sets `ForwardClientCertDetails` to `SANITIZE_SET` in Envoy,
which means incoming XFCC headers are blocked, and if an incoming cert is
present, a new XFCC header is added.

Signed-off-by: James Roper <[email protected]>

site/content/docs/main/config/tls-termination.md

@@ -265,7 +265,11 @@ spec:
 
 ## Client Certificate Details Forwarding
 
-HTTPProxy supports passing certificate data through the `x-forwarded-client-cert` header to let applications use details from client certificates (e.g. Subject, SAN...). Since the certificate (or the certificate chain) could exceed the web server header size limit, you have the ability to select what specific part of the certificate to expose in the header through the `forwardClientCertificate` field. Read more about the supported values in the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-forwarded-client-cert).
+HTTPProxy supports passing certificate data through the `x-forwarded-client-cert` (XFCC) header to let applications use details from client certificates (e.g. Subject, SAN...).
+
+Contour will never forward or append to an existing XFCC header from a client, regardless of whether forwarding client certificate details is enabled. It will always sanitize the request, first dropping the header if present, and then if configured to pass client certificate details, and a client certificate has been presented, then it will add a new XFCC header.
+
+Since the certificate (or the certificate chain) could exceed the web server header size limit, you have the ability to select what specific part of the certificate to expose in the header through the `forwardClientCertificate` field. Read more about the supported values in the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-forwarded-client-cert).
 
 ```yaml
 apiVersion: projectcontour.io/v1