diff --git a/client-cert/auth48/draft-ietf-httpbis-client-cert-field.html b/client-cert/auth48/draft-ietf-httpbis-client-cert-field.html deleted file mode 100644 index 82d7e5010..000000000 --- a/client-cert/auth48/draft-ietf-httpbis-client-cert-field.html +++ /dev/null @@ -1,1990 +0,0 @@ - - -
- - - -RFC 9440 | -Client-Cert Header | -July 2023 | -
Campbell & Bishop | -Informational | -[Page] | -
This document describes HTTP extension header fields that allow a TLS -terminating reverse proxy (TTRP) to convey the client certificate information of -a mutually authenticated TLS connection to the origin server in a common and -predictable manner.¶
-- This document is not an Internet Standards Track specification; it is - published for informational purposes.¶
-- This document is a product of the Internet Engineering Task Force - (IETF). It has been approved for publication by the Internet - Engineering Steering Group (IESG). Not all documents approved by the - IESG are candidates for any level of Internet Standard; see Section 2 - of RFC 7841.¶
-- Information about the current status of this document, any - errata, and how to provide feedback on it may be obtained at - https://www.rfc-editor.org/info/rfc9440.¶
-- Copyright (c) 2023 IETF Trust and the persons identified as the - document authors. All rights reserved.¶
-- This document is subject to BCP 78 and the IETF Trust's Legal - Provisions Relating to IETF Documents - (https://trustee.ietf.org/license-info) in effect on the date of - publication of this document. Please review these documents - carefully, as they describe your rights and restrictions with - respect to this document. Code Components extracted from this - document must include Revised BSD License text as described in - Section 4.e of the Trust Legal Provisions and are provided without - warranty as described in the Revised BSD License.¶
-A fairly common deployment pattern for HTTPS applications is to have the origin -HTTP application servers sit behind a reverse proxy that terminates TLS -connections from clients. The proxy is accessible to the Internet and dispatches -client requests to the appropriate origin server within a private or protected -network. The origin servers are not directly accessible by clients and are only -reachable through the reverse proxy. The backend details of this type of -deployment are typically opaque to clients who make requests to the proxy server -and see responses as though they originated from the proxy server itself. -Although HTTPS is also usually employed between the proxy and the origin server, -the TLS connection that the client establishes for HTTPS is only between itself -and the reverse proxy server.¶
-The deployment pattern is found in a number of varieties such as n-tier -architectures, content delivery networks, application load-balancing services, -and ingress controllers.¶
-Although not exceedingly prevalent, TLS client certificate authentication is -sometimes employed, and in such cases the origin server often requires -information about the client certificate for its application logic. Such logic -might include access control decisions, audit logging, and binding issued tokens -or cookies to a certificate, including the respective validation of such -bindings. The specific details needed from the certificate also vary with the -application requirements. In order for these types of application deployments to -work in practice, the reverse proxy needs to convey information about the client -certificate to the origin application server. At the time of writing, a common -way this information is conveyed is by using non-standard fields to carry the -certificate (in some encoding) or individual parts thereof in the HTTP request -that is dispatched to the origin server. This solution works, but -interoperability between independently developed components can be cumbersome or -even impossible depending on the implementation choices respectively made (like -what field names are used or are configurable, which parts of the certificate -are exposed, or how the certificate is encoded). A well-known predictable -approach to this commonly occurring functionality could improve and simplify -interoperability between independent implementations.¶
-The scope of this document is to describe existing practice while codifying specific -details sufficient to facilitate improved and lower-touch interoperability. -As such, this document describes two HTTP header fields, "Client-Cert" -and "Client-Cert-Chain", which a TLS terminating reverse proxy (TTRP) adds to -requests sent to the backend origin servers. The Client-Cert field value -contains the end-entity client certificate from the mutually authenticated TLS -connection between the originating client and the TTRP. Optionally, the -Client-Cert-Chain field value contains the certificate chain used for -validation of the end-entity certificate. This enables the backend origin -server to utilize the client certificate -information in its application logic. While there may be additional proxies or -hops between the TTRP and the origin server (potentially even with -mutually authenticated TLS connections between them), the scope of the -Client-Cert header field is intentionally limited to exposing to the origin -server the certificate that was presented by the originating client in its -connection to the TTRP.¶
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", -"MAY", and "OPTIONAL" in this document are to be interpreted as -described in BCP 14 [RFC2119] [RFC8174] when, and only when, they -appear in all capitals, as shown here.¶
-This document uses the following terminology from Section 3 of [STRUCTURED-FIELDS] -to specify syntax and parsing: List and Byte Sequence.¶
-Phrases like "TLS client certificate authentication" or "mutually authenticated TLS" -are used throughout this document to refer to the process whereby, in addition -to the normal TLS server authentication with a certificate, a client presents -its X.509 certificate [RFC5280] and proves possession of the corresponding -private key to a server when negotiating a TLS connection or the resumption of -such a connection. In contemporary versions of TLS [TLS] - [TLS1.2], mutual authentication requires the client to send the Certificate and -CertificateVerify messages during the handshake and the server to verify the -CertificateVerify and Finished messages.¶
-HTTP/2 restricts TLS 1.2 renegotiation (Section 9.2.1 of [HTTP/2]) and -prohibits TLS 1.3 post-handshake authentication (Section 9.2.3 of [HTTP/2]). However, they are -sometimes used to implement reactive client certificate authentication in HTTP/1.1 -[HTTP/1.1] where the server decides whether to request a client certificate -based on the HTTP request. HTTP application data sent on such a connection -after receipt and verification of the client certificate is also -mutually authenticated and thus suitable for the mechanisms described in this -document. With post-handshake authentication, there is also the possibility, though -unlikely in practice, of multiple certificates and certificate chains from the -client on a connection. In this case, only the certificate and chain -of the last post-handshake authentication are to be utilized for the header -fields described herein.¶
-This document designates the following headers, defined further in Sections 2.2 -and 2.3, respectively, to carry the client certificate information of a -mutually authenticated TLS connection. The headers convey the information -from the reverse proxy to the origin server.¶
-The end-entity certificate used by the client in the TLS handshake with -the reverse proxy.¶
-The certificate chain used for validation of the end-entity -certificate provided by the client in the TLS handshake with the reverse proxy.¶
-The headers in this document encode certificates as Byte -Sequences (Section 3.3.5 of [STRUCTURED-FIELDS]) where the value of the binary data -is a DER-encoded [ITU.X690.1994] X.509 certificate [RFC5280]. -In effect, this means that the binary DER certificate is encoded using base64 -(without line breaks, spaces, or other characters outside the base64 alphabet) -and delimited with colons on either side.¶
-Note that certificates are often stored in an encoded textual format, such as -the one described in Section 5.1 of [RFC7468], which is already nearly -compatible with a Byte Sequence. If certificates are encoded as such, it will be sufficient to replace -"---(BEGIN|END) CERTIFICATE---" with ":" and remove line breaks in order -to generate an appropriate item.¶
-In the context of a TLS terminating reverse proxy deployment, the proxy -makes the TLS client certificate available to the backend application with the -Client-Cert HTTP header field. This field contains the end-entity certificate -used by the client in the TLS handshake.¶
-Client-Cert is a Byte Sequence with the value of -the header encoded as described in Section 2.1.¶
-The Client-Cert header field is only for use in HTTP requests and MUST NOT be -used in HTTP responses. It is a singleton header field value as defined in -Section 5.5 of [HTTP], which MUST NOT have a list of values or occur -multiple times in a request.¶
-Figure 2 in Appendix A has an example of the Client-Cert header field.¶
-In the context of a TLS terminating reverse proxy deployment, the proxy -MAY make the certificate chain -available to the backend application with the Client-Cert-Chain HTTP header -field.¶
-Client-Cert-Chain is a List (Section 3.1 of [STRUCTURED-FIELDS]). Each item in the -List MUST be a Byte Sequence encoded as described in Section 2.1. The order -is the same as the ordering in TLS (as described in Section 4.4.2 of [TLS]).¶
-Client-Cert-Chain MUST NOT appear unless Client-Cert is also present, and it does -not itself include the end-entity certificate that is already present in Client-Cert. -The root certificate MAY be omitted from Client-Cert-Chain, provided that the target -origin server is known to possess the omitted trust anchor.¶
-The Client-Cert-Chain header field is only for use in HTTP requests and MUST NOT be used in HTTP responses. It MAY have a list of values or occur multiple -times in a request. For header compression purposes, it might be advantageous -to split lists into multiple instances.¶
-Figure 3 in Appendix A has an example of the Client-Cert-Chain header field.¶
-This section outlines the applicable processing rules for a TTRP that has negotiated a mutually authenticated TLS connection -to convey the client certificate from that connection to the backend origin -servers. This technique is to be used as a configuration or deployment option, and -the processing rules described herein are for servers operating with that option -enabled.¶
-A TTRP negotiates the use of a mutually authenticated TLS connection with the -client, such as is described in [TLS] or [TLS1.2], and validates the -client certificate per its policy and trusted certificate authorities. Each -HTTP request on the underlying TLS connection is dispatched to the origin -server with the following modifications:¶
-Requests to the TTRP made over a TLS connection where the use of client certificate -authentication was not negotiated MUST be sanitized by removing any and all -occurrences of the Client-Cert and Client-Cert-Chain header fields prior to -dispatching the request to the backend server.¶
-Backend origin servers may then use the Client-Cert header field of the -request to determine if the connection from the client to the TTRP was -mutually authenticated and, if so, the certificate thereby presented by the -client. -Access control decisions based on the client certificate (or lack thereof) can be -conveyed by selecting response content as appropriate or with an HTTP 403 response, -if the certificate is deemed unacceptable for the given context. -Note that TLS clients that rely on error indications at the TLS layer for an -unacceptable certificate will not receive those signals.¶
-When the value of the Client-Cert request header field is used to select a -response (e.g., the response content is access-controlled), the response MUST -either be uncacheable (e.g., by sending "Cache-Control: no-store") or be -designated for selective reuse only for subsequent requests with the same -Client-Cert header field value by sending a "Vary: Client-Cert" response header. If a -TTRP encounters a response with Client-Cert or Client-Cert-Chain in the Vary -header field (Section 12.5.5 of [HTTP]), it SHOULD prevent the user agent from -caching the response by transforming the value of the Vary response header field -to "*".¶
-Forward proxies and other intermediaries MUST NOT add the Client-Cert or -Client-Cert-Chain header fields to requests or modify an existing -Client-Cert or Client-Cert-Chain header field. Similarly, clients MUST NOT -employ the Client-Cert or Client-Cert-Chain header field in requests.¶
-If the connection between the TTRP and origin is capable of field compression -(e.g., HPACK [HPACK] or QPACK [QPACK]), and the TTRP multiplexes more -than one client's requests into that connection, the size and variation of Client-Cert and -Client-Cert-Chain field values can reduce compression efficiency significantly. -An origin could mitigate the efficiency loss by increasing the size of the dynamic table. -If the TTRP determines that the origin dynamic table is not sufficiently large, -it may find it beneficial to always send the field value as a literal -rather than entering it into the table.¶
-A server in receipt of a larger message header than it is willing to handle can send -an HTTP 431 (Request Header Fields Too Large) status code per Section 5 of [RFC6585]. -Due to the typical size of the field values containing certificate data, -recipients may need to be configured to allow for a larger maximum header size. -An intermediary generating client certificate header fields on connections that allow -for advertising the maximum acceptable header size (e.g., HTTP/2 [HTTP/2] -or HTTP/3 [HTTP/3]) should account for the additional size of the header -of the requests it sends, versus the requests it receives, by advertising a value to its -clients that is sufficiently smaller so as to allow for the addition of certificate data.¶
-Some TLS implementations do not retain client certificate information when resuming. -Providing inconsistent values of Client-Cert and Client-Cert-Chain when resuming might -lead to errors, so implementations that are unable to provide these values SHOULD -either disable resumption for connections with client certificates or initially omit a -Client-Cert or Client-Cert-Chain field if it might not be available after resuming.¶
-The header fields described herein enable a TTRP and backend or origin server to -function together as though, from the client's perspective, they are a single -logical server-side deployment of HTTPS over a mutually authenticated TLS -connection. However, use of the header fields outside that intended use -case may undermine the protections afforded by TLS client certificate -authentication. Therefore, steps such as those described below need to be taken -to prevent unintended use, both in sending the header field and in relying on its value.¶
-Producing and consuming the Client-Cert and Client-Cert-Chain header -fields SHOULD be configurable -options, respectively, in a TTRP and backend server (or in an individual application in -that server). The default configuration for both should be to not use the -header fields, thus requiring an "opt-in" to the functionality.¶
-In order to prevent field injection, backend servers MUST only accept the -Client-Cert and Client-Cert-Chain header fields from a trusted -TTRP (or other proxy in a trusted path -from the TTRP). A TTRP MUST sanitize the incoming request before forwarding it -on by removing or overwriting any existing instances of the fields. Otherwise, -arbitrary clients can control the field values as seen and used by the backend -server. It is important to note that neglecting to prevent field injection does -not "fail safe" in that the nominal functionality will still work as expected -even when malicious actions are possible. As such, extra care is recommended in -ensuring that proper field sanitation is in place.¶
-The communication between a TTRP and backend server needs to be secured against -eavesdropping and modification by unintended parties.¶
-The configuration options and request sanitization are necessary functionalities -of the respective servers. The other requirements can be met in a number of -ways, which will vary based on specific deployments. The communication between a -TTRP and backend or origin server, for example, might be authenticated in some -way with the insertion and consumption of the Client-Cert -and Client-Cert-Chain header fields occurring -only on that connection. -Appendix B.3 of [HTTPSIG] gives one example of -this with an application of HTTP Message Signatures. -Alternatively, the network topology might dictate a -private network such that the backend application is only able to accept -requests from the TTRP and the proxy can only make requests to that server. -Other deployments that meet the requirements set forth herein are also possible.¶
-IANA has registered the following entries in the "Hypertext Transfer Protocol (HTTP) Field -Name Registry" defined by "HTTP Semantics" [HTTP]:¶
-Field Name | -Status | -Reference | -
---|---|---|
Client-Cert | -permanent | -RFC 9440, Section 2 - | -
Client-Cert-Chain | -permanent | -RFC 9440, Section 2 - | -
In a hypothetical example where a TLS client would present the client and -intermediate certificate from Figure 1 when establishing a mutually -authenticated TLS connection with the TTRP, the proxy would send the Client-Cert -field shown in Figure 2 to the backend. Note that line breaks and -extra spaces have been added to the field value in Figures 2 -and 3 for display and formatting purposes only.¶
-If the proxy were configured to also include the certificate chain, it would -also include the Client-Cert-Chain header field. Note that while -the following example does illustrate the TTRP inserting the root certificate, -many deployments will opt to omit the trust anchor.¶
-This document requires that the TTRP sanitize the fields of the incoming request by -removing or overwriting any existing instances of the Client-Cert -and Client-Cert-Chain header fields -before dispatching that request to the backend application. Otherwise, a client -could inject its own values that would appear to the backend to -have come from the TTRP. Although numerous other methods of detecting and preventing -field injection are possible, such as the use of a unique secret value as part -of the field name or value or the application of a signature, HMAC, or AEAD, -there is no common general mechanism. The potential problem of -client field injection is not at all unique to the functionality of this document; -therefore, it would be inappropriate for this document to define a one-off -solution. Since a generic common solution does not currently exist, -stripping and sanitizing the fields is the de facto means of protecting against -field injection in practice. Sanitizing the fields is sufficient when -properly implemented and is a normative requirement of Section 4.¶
-The Forwarded HTTP header field defined in [RFC7239] allows proxy -components to disclose information lost in the proxying process. The TLS client -certificate information of concern to this document could have been communicated -with an extension parameter to the Forwarded field; however, doing so -would have had some disadvantages that this document endeavored to avoid. The -Forwarded field syntax allows for information about a full chain of proxied -HTTP requests, whereas the Client-Cert and Client-Cert-Chain -header fields of this document are concerned -only with conveying information about the certificate presented by the -originating client on the TLS connection to the TTRP (which appears as the -server from that client's perspective) to backend applications. The multi-hop -syntax of the Forwarded field is expressive but also more complicated, which -would make processing it more cumbersome and, more importantly, would make properly -sanitizing its content, as required by Section 4 to prevent field injection, -considerably more difficult and error-prone. Thus, this document opted for a -flatter and more straightforward structure.¶
-Different applications will have varying requirements about what information -from the client certificate is needed, such as the subject and/or issuer -distinguished name, subject alternative name(s), serial number, subject public -key info, fingerprint, etc. Furthermore, some applications, such as that -described in -[RFC8705], make use of the entire certificate. In order to accommodate the -latter and ensure wide applicability by not trying to cherry-pick particular -certificate information, this document opted to pass the full, encoded certificate -as the value of the Client-Cert field.¶
-The validation of the client certificate and chain of the mutually authenticated -TLS connection is typically performed by the TTRP during the handshake. With the -responsibility of certificate validation falling on the TTRP, the -end-entity certificate is oftentimes sufficient for the needs of the origin server. -The separate Client-Cert-Chain field can convey the certificate chain for -origin server deployments that require this additional information.¶
-The authors would like to thank the following individuals who have contributed -to this document in various ways, ranging from just being generally supportive -of bringing forth the document to providing specific feedback or content:¶
-