Clarified how XFCC headers are handled

[jroper]

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

This documents Contours precise 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 Contour source code, as well as the Envoy documentation, 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.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 81.76%. Comparing base (7fa5725) to head (bcbf1b7).
Report is 19 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6586   +/-   ##
=======================================
  Coverage   81.76%   81.76%           
=======================================
  Files         133      133           
  Lines       15942    15942           
=======================================
  Hits        13035    13035           
  Misses       2614     2614           
  Partials      293      293           

[tsaarni]

Good point, the change looks good to me!

Could you add DCO / signed-off-by line to the commit https://github.com/projectcontour/contour/blob/main/CONTRIBUTING.md#commit-message-and-pr-guidelines

[jroper]

Done.

[tsaarni]

Thank you @jroper!