From f9b6f6fdfdd83d3639f6e8c55836401d749c19e1 Mon Sep 17 00:00:00 2001 From: James Roper Date: Wed, 14 Aug 2024 16:05:47 +1000 Subject: [PATCH] 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 --- site/content/docs/main/config/tls-termination.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/site/content/docs/main/config/tls-termination.md b/site/content/docs/main/config/tls-termination.md index d1b26dc2f4e..d284ba082b0 100644 --- a/site/content/docs/main/config/tls-termination.md +++ b/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