idnits 2.17.1 draft-ietf-tokbind-ttrp-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 2, 2017) is 2458 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 446 -- Looks like a reference, but probably isn't: '2' on line 448 -- Looks like a reference, but probably isn't: '3' on line 450 == Outdated reference: A later version (-18) exists of draft-ietf-tokbind-https-09 == Outdated reference: A later version (-14) exists of draft-ietf-tokbind-negotiation-08 == Outdated reference: A later version (-19) exists of draft-ietf-tokbind-protocol-14 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force B. Campbell 3 Internet-Draft Ping Identity 4 Intended status: Standards Track August 2, 2017 5 Expires: February 3, 2018 7 HTTPS Token Binding with TLS Terminating Reverse Proxies 8 draft-ietf-tokbind-ttrp-01 10 Abstract 12 This document defines common HTTP header fields that enable a TLS 13 terminating reverse proxy to convey information about the validated 14 Token Binding Message sent by the client to a backend server, which 15 enables that backend server to bind, or verify the binding of, 16 cookies and other security tokens to the client's Token Binding key. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on February 3, 2018. 35 Copyright Notice 37 Copyright (c) 2017 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 54 2. HTTP Header Fields and Processing Rules . . . . . . . . . . . 3 55 2.1. Token Binding ID HTTP Header Fields . . . . . . . . . . . 3 56 2.2. Processing Rules . . . . . . . . . . . . . . . . . . . . 4 57 2.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 5 58 2.3.1. Provided Token Binding ID . . . . . . . . . . . . . . 5 59 2.3.2. Provided and Referred Token Binding IDs . . . . . . . 6 60 3. Security Considerations . . . . . . . . . . . . . . . . . . . 6 61 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 62 4.1. HTTP Message Header Field Names Registration . . . . . . 7 63 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 64 5.1. Normative References . . . . . . . . . . . . . . . . . . 8 65 5.2. Informative References . . . . . . . . . . . . . . . . . 9 66 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 67 Appendix B. Document History . . . . . . . . . . . . . . . . . . 9 68 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 70 1. Introduction 72 Token Binding over HTTP [I-D.ietf-tokbind-https] provides a mechanism 73 that enables HTTP servers to cryptographically bind cookies and other 74 security tokens to a key held by the browser or other HTTP client, 75 possession of which is proven on the TLS [RFC5246] connections over 76 which the tokens are used. When Token Binding is negotiated in the 77 TLS handshake [I-D.ietf-tokbind-negotiation] the client sends an 78 encoded Token Binding Message [I-D.ietf-tokbind-protocol] as a header 79 in each HTTP request, which proves possession of one or more private 80 keys held by the client. The public portion of the keys are 81 represented in the Token Binding IDs of the Token Binding Message and 82 for each one there is a signature over some data, which includes the 83 exported keying material [RFC5705] of the TLS connection. An HTTP 84 server issuing cookies or other security tokens can associate them 85 with the Token Binding ID, which ensures those tokens cannot be used 86 successfully over a different TLS connection or by a different client 87 than the one to which they were issued. 89 A fairly common deployment architecture for HTTPS applications is to 90 have the backend HTTP application servers sit behind a reverse proxy 91 that terminates TLS. The proxy is accessible to the internet and 92 dispatches client requests to the appropriate backend server within a 93 private or protected network. The backend servers are not directly 94 accessible outside the private network and are only reachable through 95 the reverse proxy. The details of such deployments are typically 96 opaque to clients who make requests to the proxy server and see 97 responses as though they originated from the proxy server itself. 99 TLS connections for HTTPS are established between each client and the 100 reverse proxy server. 102 Token Binding facilitates a binding of security tokens to a key held 103 by the client by way of the TLS connection between that client and 104 the server. In a deployment where TLS is terminated by a reverse 105 proxy, however, the TLS connection is between the client and the 106 proxy while the backend server is likely the system that will issue 107 cookies or other security tokens. Additional steps are therefore 108 needed to enable the use of Token Binding in such deployment 109 architectures. In the absence of a standardized approach, different 110 implementations will address it differently, which will make 111 interoperability between such implementations difficult or impossible 112 without complex configurations or custom integrations. 114 This document standardizes HTTP header field names that a TLS 115 terminating reverse proxy (TTRP) adds to requests that it sends to 116 the backend servers. The headers contain the information from the 117 validated Token Binding Message sent by the client to the proxy with 118 the "Sec-Token-Binding" header, thus enabling the backend server to 119 bind, or verify the binding of, cookies and other security tokens to 120 the client's Token Binding key. The usage of the headers, both the 121 reverse proxy adding it and the application server using them to bind 122 cookies or other tokens, are to be configuration options of the 123 respective systems as they will not always be applicable. 125 1.1. Requirements Notation and Conventions 127 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 128 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 129 "OPTIONAL" in this document are to be interpreted as described in RFC 130 2119 [RFC2119]. 132 2. HTTP Header Fields and Processing Rules 134 2.1. Token Binding ID HTTP Header Fields 136 The Token Binding Protocol [I-D.ietf-tokbind-protocol] recommends 137 that implementations make Token Binding IDs available to the 138 application as opaque byte sequences, enabling those applications to 139 use the Token Binding IDs when generating and verifying bound tokens. 140 In the context of a TLS terminating reverse proxy (TTRP) deployment, 141 the provided and referred Token Binding IDs are made available to the 142 backend application as the "Sec-Provided-Token-Binding-ID" and "Sec- 143 Referred-Token-Binding-ID" HTTP headers respectively. The value of 144 both headers is an "EncodedTokenBindingID", for which the ABNF 145 [RFC5234] syntax is shown in Figure 1 below. "EncodedTokenBindingID" 146 is a single HTTP header field-value as defined in Section 3.2 of 148 [RFC7230], which MUST NOT have a list of values or occur multiple 149 times in a request. An "EncodedTokenBindingID" is only for use in 150 HTTP requests and MUST NOT to be used in HTTP responses. 152 EncodedTokenBindingID = *( DIGIT / ALPHA / "-" / "_" ) 154 DIGIT = 155 ALPHA = 157 Figure 1: Encoded Token Binding ID Header ABNF 159 The value of an "EncodedTokenBindingID" is a base64url encoding of 160 the TokenBindingID byte sequence (see section 3 of 161 [I-D.ietf-tokbind-protocol]) using the URL and filename safe alphabet 162 described in Section 5 of [RFC4648], with all trailing pad characters 163 '=' omitted and without the inclusion of any line breaks, whitespace, 164 or other additional characters. 166 2.2. Processing Rules 168 This section defines the applicable processing rules for a TLS 169 terminating reverse proxy (TTRP) and backend server(s) to provide 170 server side support of Token Binding over HTTP 171 [I-D.ietf-tokbind-https] using the HTTP headers described in 172 Section 2.1. Use of the technique is to be a configuration or 173 deployments option and the processing rules described herein are for 174 servers operating with that option enabled. 176 A TTRP negotiates the use of Token Binding with the client per 177 [I-D.ietf-tokbind-negotiation] and validates the Token Binding 178 Message as defined in The Token Binding Protocol 179 [I-D.ietf-tokbind-protocol] and Token Binding over HTTP 180 [I-D.ietf-tokbind-https] for each HTTP request on the underlying TLS 181 connection. Requests with a valid Token Binding Message (and meeting 182 any other authorization or policy requirements of the TTRP) are 183 dispatched to the backend server with the following modifications. 185 1. The "Sec-Token-Binding" header in the original incoming request 186 MUST be removed from the request that is dispatched to the 187 backend server. 189 2. The Token Binding ID of the provided Token Binding of the Token 190 Binding Message MUST be placed in the "Sec-Provided-Token- 191 Binding-ID" header field of the dispatched request using the 192 format defined in Section 2.1. 194 3. If the Token Binding Message contains a referred Token Binding, 195 the referred Token Binding ID MUST be placed in the "Sec- 196 Referred-Token-Binding-ID" header field of the dispatched request 197 using the format defined in Section 2.1. Otherwise, the "Sec- 198 Referred-Token-Binding-ID" header field MUST NOT be present in 199 the dispatched request. 201 4. Any occurrence of the "Sec-Provided-Token-Binding-ID" or "Sec- 202 Referred-Token-Binding-ID" header in the original incoming 203 request MUST be removed or overwritten before forwarding the 204 request. 206 Requests made over a TLS connection where the use of Token Binding 207 was not negotiated MUST be sanitized by removing any occurrences of 208 the "Sec-Provided-Token-Binding-ID" and "Sec-Referred-Token-Binding- 209 ID" header fields prior to dispatching the request to the backend 210 server. 212 Forward proxies and other intermediaries MUST NOT add the "Sec- 213 Provided-Token-Binding-ID" or "Sec-Referred-Token-Binding-ID" header 214 to requests. 216 2.3. Examples 218 Extra line breaks and whitespace have been added to the following 219 examples for display and formatting purposes only. 221 2.3.1. Provided Token Binding ID 223 The following "Sec-Token-Binding" header is from an HTTP request made 224 over a TLS connection between the client and the TTRP where the use 225 of Token Binding has been negotiated (The base64url-encoded 226 representation of the exported keying material, which can be used to 227 validate the Token Binding Message, for that connection is 228 "AYVUayPTP9RmELNpGjFl6Ykm2CUx7pUMxe35yb11dgU"). The encoded Token 229 Binding Message has the provided Token Binding the client uses with 230 the server. 232 Sec-Token-Binding: AIkAAgBBQKzyIrmcY_YCtHVoSHBut69vrGfFdy1_YKTZfFJv 233 6BjrZsKD9b9FRzSBxDs1twTqnAS71M1RBumuihhI9xqxXKkAQEtxe4jeUJU0WezxlQ 234 XWVSBFeHxFMdXRBIH_LKOSAuSMOJ0XEw1Q8DE248qkOiRKzw3KdSNYukYEPmO21bQi 235 3YYAAA 237 Figure 2: Header in HTTP Request to TTRP 239 After validating the Token Binding Message, the TTRP removes the 240 "Sec-Token-Binding" header and adds the following "Sec-Provided- 241 Token-Binding-ID" header with the provided Token Binding ID to the 242 request that is dispatched to the backend server. 244 Sec-Provided-Token-Binding-ID: AgBBQKzyIrmcY_YCtHVoSHBut69vrGfFdy1_ 245 YKTZfFJv6BjrZsKD9b9FRzSBxDs1twTqnAS71M1RBumuihhI9xqxXKk 247 Figure 3: Header in HTTP Request to Backend Server 249 2.3.2. Provided and Referred Token Binding IDs 251 The following "Sec-Token-Binding" header is from an HTTP request made 252 over a TLS connection between the client and the TTRP where the use 253 of Token Binding has been negotiated (The base64url-encoded 254 representation of the exported keying material, which can be used to 255 validate the Token Binding Message, for that connection is 256 "wEWWCP1KPxfq-QL4NxYII_P4ti_9YYqrTpGs28BZEqE"). The encoded Token 257 Binding Message has the provided Token Binding the client uses with 258 the server as well as the referred Token Binding that it uses with a 259 different server. 261 Sec-Token-Binding: ARIAAgBBQCfsI1D1sTq5mvT_2H_dihNIvuHJCHGjHPJchPav 262 NbGrOo26-2JgT_IsbvZd4daDFbirYBIwJ-TK1rh8FzrC-psAQMyYIqXj7djGPev1dk 263 jV9XxLYGCyqOrBVEtBHrMUCeo22ymLg3OiFcl_fmOPxJbjxI6lKcF0lyfy-dSQmPIe 264 zQ0AAAECAEFArPIiuZxj9gK0dWhIcG63r2-sZ8V3LX9gpNl8Um_oGOtmwoP1v0VHNI 265 HEOzW3BOqcBLvUzVEG6a6KGEj3GrFcqQBAHQm0pzgUTXKLRamuKE1pmmP9I3UBVpoe 266 1DBCe9H2l1VPpsImakUa6crAqZ-0CGBmji7bYzQogpKcyxTTFk5zdwAA 268 Figure 4: Header in HTTP Request to TTRP 270 After validating the Token Binding Message, the TTRP removes the 271 "Sec-Token-Binding" header and adds the following "Sec-Provided- 272 Token-Binding-ID" and "Sec-Referred-Token-Binding-ID" headers, with 273 the provided and referred Token Binding IDs respectively, to the 274 request that is dispatched to the backend server. 276 Sec-Provided-Token-Binding-ID: AgBBQCfsI1D1sTq5mvT_2H_dihNIvuHJCHGj 277 HPJchPavNbGrOo26-2JgT_IsbvZd4daDFbirYBIwJ-TK1rh8FzrC-ps 278 Sec-Referred-Token-Binding-ID: AgBBQKzyIrmcY_YCtHVoSHBut69vrGfFdy1_ 279 YKTZfFJv6BjrZsKD9b9FRzSBxDs1twTqnAS71M1RBumuihhI9xqxXKk 281 Figure 5: Headers in HTTP Request to Backend Server 283 3. Security Considerations 285 The headers described herein enable a reverse proxy and backend 286 server to function together as though they are single logical server 287 side deployment of HTTPS Token Binding. Use of the headers outside 288 that intended use case, however, may undermine the protections 289 afforded by Token Binding. Therefore steps MUST be taken to prevent 290 unintended use, both in sending the headers and in relying on their 291 value. 293 Producing and consuming the headers SHOULD be a configurable option, 294 respectively, in a reverse proxy and backend server (or individual 295 application in that server). The default configuration for both 296 should be to not use the headers thus requiring an "opt-in" to the 297 functionality. 299 Backend servers MUST only accept the headers from trusted reverse 300 proxies. And reverse proxies MUST sanitize the incoming request 301 before forwarding it on by removing or overwriting any existing 302 instances of the headers. Otherwise arbitrary clients can control 303 the header values as seen and used by the backend server. 305 The communication between a reverse proxy and backend server needs to 306 be secured against eavesdropping and modification by unintended 307 parties. 309 The configuration options and request sanitization are necessarily 310 functionally of the respective servers. The other requirements can 311 be met in a number of ways, which will vary based on specific 312 deployments. The communication between a reverse proxy and backend 313 server, for example, might be over a mutually authenticated TLS with 314 the insertion and consumption headers occurring only on that 315 connection. Alternatively the network topology might dictate a 316 private network such that the backend application is only able to 317 accept requests from the reverse proxy and the proxy can only make 318 requests to that server. Other deployments that meet the 319 requirements set forth herein are also possible. 321 Employing the "Sec-" header field prefix for the headers defined 322 herein denotes them as forbidden header names (see [fetch-spec]), 323 which means they cannot be set or modified programmatically by script 324 running in-browser. 326 4. IANA Considerations 328 4.1. HTTP Message Header Field Names Registration 330 This document specifies the following new HTTP header fields, 331 registration of which is requested in the "Permanent Message Header 332 Field Names" registry defined in [RFC3864]. 334 o Header Field Name: "Sec-Provided-Token-Binding-ID" 335 o Applicable protocol: HTTP 336 o Status: standard 337 o Author/change Controller: IETF 338 o Specification Document(s): [[ this specification ]] 340 o Header Field Name: "Sec-Referred-Token-Binding-ID" 341 o Applicable protocol: HTTP 342 o Status: standard 343 o Author/change Controller: IETF 344 o Specification Document(s): [[ this specification ]] 346 5. References 348 5.1. Normative References 350 [I-D.ietf-tokbind-https] 351 Popov, A., Nystrom, M., Balfanz, D., Langley, A., and J. 352 Hodges, "Token Binding over HTTP", draft-ietf-tokbind- 353 https-09 (work in progress), April 2017. 355 [I-D.ietf-tokbind-negotiation] 356 Popov, A., Nystrom, M., Balfanz, D., and A. Langley, 357 "Transport Layer Security (TLS) Extension for Token 358 Binding Protocol Negotiation", draft-ietf-tokbind- 359 negotiation-08 (work in progress), April 2017. 361 [I-D.ietf-tokbind-protocol] 362 Popov, A., Nystrom, M., Balfanz, D., Langley, A., and J. 363 Hodges, "The Token Binding Protocol Version 1.0", draft- 364 ietf-tokbind-protocol-14 (work in progress), April 2017. 366 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 367 Requirement Levels", BCP 14, RFC 2119, 368 DOI 10.17487/RFC2119, March 1997, 369 . 371 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 372 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 373 . 375 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 376 Specifications: ABNF", STD 68, RFC 5234, 377 DOI 10.17487/RFC5234, January 2008, 378 . 380 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 381 (TLS) Protocol Version 1.2", RFC 5246, 382 DOI 10.17487/RFC5246, August 2008, 383 . 385 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport 386 Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705, 387 March 2010, . 389 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 390 Protocol (HTTP/1.1): Message Syntax and Routing", 391 RFC 7230, DOI 10.17487/RFC7230, June 2014, 392 . 394 5.2. Informative References 396 [fetch-spec] 397 WhatWG, "Fetch", Living Standard , 398 . 400 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 401 Procedures for Message Header Fields", BCP 90, RFC 3864, 402 DOI 10.17487/RFC3864, September 2004, 403 . 405 Appendix A. Acknowledgements 407 The author would like to thank the following people for their various 408 contributions to the specification: Vinod Anupam, Dirk Balfanz, John 409 Bradley, Nick Harper, Jeff Hodges, Subodh Iyengar, Leif Johansson, 410 Yoav Nir, Andrei Popov, Eric Rescorla, Piotr Sikora, Martin Thomson, 411 Hans Zandbelt and others (please let me know, if you've contributed 412 and I've forgotten you). 414 Appendix B. Document History 416 [[ to be removed by the RFC Editor before publication as an RFC ]] 418 draft-ietf-tokbind-ttrp-01 420 o Prefix the header names with "Sec-" so that they are denoted as 421 forbidden header names by Fetch https://fetch.spec.whatwg.org/ 423 o Removed potentially confusing sentence from Security 424 Considerations per 425 https://mailarchive.ietf.org/arch/msg/unbearable/ 426 O0IpppyyEqMrQjEkyEi8p8CeBGA 428 o Editorial fixes. 430 draft-ietf-tokbind-ttrp-00 432 o Initial WG draft from draft-campbell-tokbind-ttrp. 434 draft-campbell-tokbind-ttrp-01 436 o Minor editorial fixes. 438 o Add to the Acknowledgements. 440 draft-campbell-tokbind-ttrp-00 442 o Initial draft based on 'consensus to work on the problem' from the 443 Seoul meeting [1][2] and reflecting the consensus approach from 444 discussions at the Chicago meeting [3]. 446 [1] https://www.ietf.org/proceedings/97/minutes/minutes-97- 447 tokbind-01.txt (minutes from Seoul) 448 [2] https://www.ietf.org/proceedings/97/slides/slides-97-tokbind- 449 reverse-proxies-00.pdf (slides from Seoul) 450 [3] https://mailarchive.ietf.org/arch/msg/ 451 unbearable/_ZHI8y2Vs5WMP8VMRr7zroo_sNU (summary of discussion) 453 Author's Address 455 Brian Campbell 456 Ping Identity 458 Email: brian.d.campbell@gmail.com