Docs: Clarify format of Subject field in X-Forwarded-Client-Cert header

[NeilMadden]

Title: Clarify format of Subject field in X-Forwarded-Client-Cert header

Description: The documentation for the X-Forwarded-Client-Cert header says that the Subject field is the subject of the client certificate.

The Subject field in an X.509 certificate is binary ASN.1 DER formatted, so it is ambiguous as to which string syntax is used when converting to the header. The examples in the documentation use the format Subject="/C=US/ST=CA/L=San Francisco/OU=Lyft/CN=Test Client" which appears to be an old X.500 syntax.

The code appears to actually serialize into standard RFC 2253 format, in which case the examples should read something like cn=Test Client,ou=Lyft,l=San Francisco,st=CA,c=US.

However, even in that standard format there is an ambiguity on how Envoy serializes DN attributes that are unrecognized. Because the syntax of attributes depends on the schema, it can either attempt to format them as strings or else encode the DER bytes directly using the #<hex-encoded-DER-value> syntax. There are client certs in the wild that use non-standard attributes in the subject DN, so it would be good to know how Envoy will serialize those so that I can have a fighting chance of matching them correctly on the backend.

[yanavlasov]

@PiotrSikora do you have any thoughts on this subject?

[PiotrSikora]

It's very likely that the docs are wrong, because the only place I can find the old syntax is in the test mocks. Patches welcome.

Regarding unknown DN attributes, I have no idea, but we're using BoringSSL's X509_NAME_print_ex(..., XN_FLAG_RFC2253) for formatting, so it should be deterministic.

[NeilMadden]

I'll see if I can come up with a PR to improve the docs wording. I'll run some experiments with BoringSSL and see how it translates unknown attributes.