idnits 2.17.1 draft-campbell-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 (July 17, 2017) is 2473 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 445 -- Looks like a reference, but probably isn't: '2' on line 447 -- Looks like a reference, but probably isn't: '3' on line 449 == 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 July 17, 2017 5 Expires: January 18, 2018 7 HTTPS Token Binding with TLS Terminating Reverse Proxies 8 draft-campbell-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 January 18, 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. Open Issues . . . . . . . . . . . . . . . . . . . . 9 68 Appendix C. Document History . . . . . . . . . . . . . . . . . . 10 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 71 1. Introduction 73 Token Binding over HTTP [I-D.ietf-tokbind-https] provides a mechanism 74 that enables HTTP servers to cryptographically bind cookies and other 75 security tokens to a key held by the browser or other HTTP client, 76 possession of which is proven on the TLS [RFC5246] connections over 77 which the tokens are used. When Token Binding is negotiated in the 78 TLS handshake [I-D.ietf-tokbind-negotiation] the client sends an 79 encoded Token Binding Message [I-D.ietf-tokbind-protocol] as a header 80 in each HTTP request, which proves possession of one or more private 81 keys held by the client. The public portion of the keys are 82 represented in the Token Binding IDs of the Token Binding Message and 83 for each one there is a signature over some data, which includes the 84 exported keying material [RFC5705] of the TLS connection. An HTTP 85 server issuing cookies or other security tokens can associate them 86 with the Token Binding ID, which ensures those tokens cannot be used 87 successfully over a different TLS connection or by a different client 88 than the one to which they were issued. 90 A fairly common deployment architecture for HTTPS applications is to 91 have the backend HTTP application servers sit behind a reverse proxy 92 that terminates TLS. The proxy is accessible to the internet and 93 dispatches client requests to the appropriate backend server within a 94 private or protected network. The backend servers are not directly 95 accessible outside the private network and are only reachable through 96 the reverse proxy. The details of such deployments are typically 97 opaque to clients who make requests to the proxy server and see 98 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 implementation 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 "Provided-Token-Binding-ID" and "Referred- 143 Token-Binding-ID" HTTP headers respectively. The value of both 144 headers is an "EncodedTokenBindingID", for which the ABNF [RFC5234] 145 syntax is shown in Figure 1 below. "EncodedTokenBindingID" is a 146 single HTTP header field-value as defined in Section 3.2 of 147 [RFC7230], which MUST NOT have a list of values or occur multiple 148 times in a request. An "EncodedTokenBindingID" is only for use in 149 HTTP requests and MUST NOT to be used in HTTP responses. 151 EncodedTokenBindingID = *( DIGIT / ALPHA / "-" / "_" ) 153 DIGIT = 154 ALPHA = 156 Figure 1: Encoded Token Binding ID Header ABNF 158 The value of an "EncodedTokenBindingID" is a base64url encoding of 159 the TokenBindingID byte sequence (see section 3 of 160 [I-D.ietf-tokbind-protocol]) using the URL and filename safe alphabet 161 described in Section 5 of [RFC4648], with all trailing pad characters 162 '=' omitted and without the inclusion of any line breaks, whitespace, 163 or other additional characters. 165 2.2. Processing Rules 167 This section defines the applicable processing rules for a TLS 168 terminating reverse proxy (TTRP) and backend server(s) to provide 169 server side support of Token Binding over HTTP 170 [I-D.ietf-tokbind-https] using the HTTP headers described in 171 Section 2.1. Use of the technique is to be a configuration or 172 deployments option and the processing rules described herein are for 173 servers operating with that option enabled. 175 A TTRP negotiates the use of Token Binding with the client per 176 [I-D.ietf-tokbind-negotiation] and validates the Token Binding 177 Message as defined in The Token Binding Protocol 178 [I-D.ietf-tokbind-protocol] and Token Binding over HTTP 179 [I-D.ietf-tokbind-https] for each HTTP request on the underlying TLS 180 connection. Requests with a valid Token Binding Message (and meeting 181 any other authorization or policy requirements of the TTRP) are 182 dispatched to the backend server with the following modifications. 184 1. The "Sec-Token-Binding" header in the original incoming request 185 MUST be removed from the request that is dispatched to the 186 backend server. 188 2. The Token Binding ID of the provided Token Binding of the Token 189 Binding Message MUST be placed in the "Provided-Token-Binding-ID" 190 header field of the dispatched request using the format defined 191 in Section 2.1. 193 3. If the Token Binding Message contains a referred Token Binding, 194 the referred Token Binding ID MUST be placed in the "Referred- 195 Token-Binding-ID" header field of the dispatched request using 196 the format defined in Section 2.1. Otherwise, the "Referred- 197 Token-Binding-ID" header field MUST NOT be present in the 198 dispatched request. 200 4. Any occurrence of the "Provided-Token-Binding-ID" or "Referred- 201 Token-Binding-ID" header in the original incoming request MUST be 202 removed or overwritten before forwarding the request. 204 Requests made over a TLS connection where the use of Token Binding 205 was not negotiated MUST be sanitized by removing any occurrences of 206 the "Provided-Token-Binding-ID" and "Referred-Token-Binding-ID" 207 header fields prior to dispatching the request to the backend server. 209 Forward proxies and other intermediaries MUST NOT add the "Provided- 210 Token-Binding-ID" or "Referred-Token-Binding-ID" header to requests. 212 2.3. Examples 214 Extra line breaks and whitespace have been added to the following 215 examples for display and formatting purposes only. 217 2.3.1. Provided Token Binding ID 219 The following "Sec-Token-Binding" header is from an HTTP request made 220 over a TLS connection between the client and the TTRP where the use 221 of Token Binding has been negotiated (The base64url-encoded 222 representation of the exported keying material, which can be used to 223 validate the Token Binding Message, for that connection is 224 "AYVUayPTP9RmELNpGjFl6Ykm2CUx7pUMxe35yb11dgU"). The encoded Token 225 Binding Message has the provided Token Binding the client uses with 226 the server. 228 Sec-Token-Binding: AIkAAgBBQKzyIrmcY_YCtHVoSHBut69vrGfFdy1_YKTZfFJv 229 6BjrZsKD9b9FRzSBxDs1twTqnAS71M1RBumuihhI9xqxXKkAQEtxe4jeUJU0WezxlQ 230 XWVSBFeHxFMdXRBIH_LKOSAuSMOJ0XEw1Q8DE248qkOiRKzw3KdSNYukYEPmO21bQi 231 3YYAAA 233 Figure 2: Header in HTTP Request to TTRP 235 After validating the Token Binding Message, the TTRP removes the 236 "Sec-Token-Binding" header and adds the following "Provided-Token- 237 Binding-ID" header with the provided Token Binding ID to the request 238 that is dispatched to the backend server. 240 Provided-Token-Binding-ID: AgBBQKzyIrmcY_YCtHVoSHBut69vrGfFdy1_YKTZ 241 fFJv6BjrZsKD9b9FRzSBxDs1twTqnAS71M1RBumuihhI9xqxXKk 243 Figure 3: Header in HTTP Request to Backend Server 245 2.3.2. Provided and Referred Token Binding IDs 247 The following "Sec-Token-Binding" header is from an HTTP request made 248 over a TLS connection between the client and the TTRP where the use 249 of Token Binding has been negotiated (The base64url-encoded 250 representation of the exported keying material, which can be used to 251 validate the Token Binding Message, for that connection is 252 "wEWWCP1KPxfq-QL4NxYII_P4ti_9YYqrTpGs28BZEqE"). The encoded Token 253 Binding Message has the provided Token Binding the client uses with 254 the server as well as the referred Token Binding that it uses with a 255 different server. 257 Sec-Token-Binding: ARIAAgBBQCfsI1D1sTq5mvT_2H_dihNIvuHJCHGjHPJchPav 258 NbGrOo26-2JgT_IsbvZd4daDFbirYBIwJ-TK1rh8FzrC-psAQMyYIqXj7djGPev1dk 259 jV9XxLYGCyqOrBVEtBHrMUCeo22ymLg3OiFcl_fmOPxJbjxI6lKcF0lyfy-dSQmPIe 260 zQ0AAAECAEFArPIiuZxj9gK0dWhIcG63r2-sZ8V3LX9gpNl8Um_oGOtmwoP1v0VHNI 261 HEOzW3BOqcBLvUzVEG6a6KGEj3GrFcqQBAHQm0pzgUTXKLRamuKE1pmmP9I3UBVpoe 262 1DBCe9H2l1VPpsImakUa6crAqZ-0CGBmji7bYzQogpKcyxTTFk5zdwAA 264 Figure 4: Header in HTTP Request to TTRP 266 After validating the Token Binding Message, the TTRP removes the 267 "Sec-Token-Binding" header and adds the following "Provided-Token- 268 Binding-ID" and "Referred-Token-Binding-ID" headers, with the 269 provided and referred Token Binding IDs respectively, to the request 270 that is dispatched to the backend server. 272 Provided-Token-Binding-ID: AgBBQCfsI1D1sTq5mvT_2H_dihNIvuHJCHGjHPJc 273 hPavNbGrOo26-2JgT_IsbvZd4daDFbirYBIwJ-TK1rh8FzrC-ps 274 Referred-Token-Binding-ID: AgBBQKzyIrmcY_YCtHVoSHBut69vrGfFdy1_YKTZ 275 fFJv6BjrZsKD9b9FRzSBxDs1twTqnAS71M1RBumuihhI9xqxXKk 277 Figure 5: Headers in HTTP Request to Backend Server 279 3. Security Considerations 281 The headers described herein enable a reverse proxy and backend 282 server to function together as though they are single logical server 283 side deployment of HTTPS Token Binding. Use of the headers outside 284 that intended use case, however, may undermine the protections 285 afforded by Token Binding. Therefore steps MUST be taken to prevent 286 unintended use, both in sending the headers and in relying on their 287 value. 289 Producing and consuming the headers SHOULD be a configurable option, 290 respectively, in a reverse proxy and backend server (or individual 291 application in that server). The default configuration for both 292 should be to not use the headers thus requiring an "opt-in" to the 293 functionality. 295 Reverse proxies SHOULD only add the headers to requests that are 296 forwarded to trusted backend servers. 298 Backend servers MUST only accept the headers from trusted reverse 299 proxies. And reverse proxies MUST sanitize the incoming request 300 before forwarding it on by removing or overwriting any existing 301 instances of the headers. Otherwise arbitrary clients can control 302 the header values as seen and used by the backend server. 304 The communication between a reverse proxy and backend server needs to 305 be secured against eavesdropping and modification by unintended 306 parties. 308 The configuration options and request sanitization are necessarily 309 functionally of the respective servers. The other requirements can 310 be met in a number of ways, which will vary based on specific 311 deployments. The communication between a reverse proxy and backend 312 server, for example, might be over a mutually authenticated TLS with 313 the insertion and consumption headers occurring only on that 314 connection. Alternatively the network topology might dictate a 315 private network such that the backend application is only able to 316 accept requests from the reverse proxy and the proxy can only make 317 requests to that server. Other deployments that meet the 318 requirements set forth herein are also possible. 320 4. IANA Considerations 322 4.1. HTTP Message Header Field Names Registration 324 This document specifies the following new HTTP header fields, 325 registration of which is requested in the "Permanent Message Header 326 Field Names" registry defined in [RFC3864]. 328 o Header Field Name: "Provided-Token-Binding-ID" 329 o Applicable protocol: HTTP 330 o Status: standard 331 o Author/change Controller: IETF 332 o Specification Document(s): [[ this specification ]] 334 o Header Field Name: "Referred-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 5. References 342 5.1. Normative References 344 [I-D.ietf-tokbind-https] 345 Popov, A., Nystrom, M., Balfanz, D., Langley, A., and J. 346 Hodges, "Token Binding over HTTP", draft-ietf-tokbind- 347 https-09 (work in progress), April 2017. 349 [I-D.ietf-tokbind-negotiation] 350 Popov, A., Nystrom, M., Balfanz, D., and A. Langley, 351 "Transport Layer Security (TLS) Extension for Token 352 Binding Protocol Negotiation", draft-ietf-tokbind- 353 negotiation-08 (work in progress), April 2017. 355 [I-D.ietf-tokbind-protocol] 356 Popov, A., Nystrom, M., Balfanz, D., Langley, A., and J. 357 Hodges, "The Token Binding Protocol Version 1.0", draft- 358 ietf-tokbind-protocol-14 (work in progress), April 2017. 360 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 361 Requirement Levels", BCP 14, RFC 2119, 362 DOI 10.17487/RFC2119, March 1997, 363 . 365 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 366 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 367 . 369 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 370 Specifications: ABNF", STD 68, RFC 5234, 371 DOI 10.17487/RFC5234, January 2008, 372 . 374 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 375 (TLS) Protocol Version 1.2", RFC 5246, 376 DOI 10.17487/RFC5246, August 2008, 377 . 379 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport 380 Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705, 381 March 2010, . 383 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 384 Protocol (HTTP/1.1): Message Syntax and Routing", 385 RFC 7230, DOI 10.17487/RFC7230, June 2014, 386 . 388 5.2. Informative References 390 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 391 Procedures for Message Header Fields", BCP 90, RFC 3864, 392 DOI 10.17487/RFC3864, September 2004, 393 . 395 Appendix A. Acknowledgements 397 The author would like to thank the following people for their various 398 contributions to the specification: Vinod Anupam, Dirk Balfanz, John 399 Bradley, Jeff Hodges, Subodh Iyengar, Leif Johansson, Yoav Nir, 400 Andrei Popov, Eric Rescorla, Piotr Sikora, Martin Thomson, Hans 401 Zandbelt and others (please let me know, if you've contributed and 402 I've forgotten you). 404 Appendix B. Open Issues 406 o During discussions at a side meeting in Chicago (IETF 98) there 407 seemed to be general support for having the TTRP rename the "Sec- 408 Token-Binding" header to something else and pass the full original 409 EncodedTokenBindingMessage to the backend server via a different 410 header (maybe "TTRP-Token-Binding" or something) in addition to 411 the "Provided-Token-Binding-ID" and if applicable the "Referred- 412 Token-Binding-ID" headers defined herein. The idea was largely 413 that the backend server "might need it for something" so pass the 414 whole thing along just in case. However, as I sat down to write 415 this draft, I couldn't bring myself to add it in the main text. 416 On thinking about it more, it feels inefficient/duplicative and 417 rather inelegant. And without the EKM, much of the data not 418 already made available via the Token Binding IDs is meaningless 419 (e.g. the signature value). Data in TokenBinding.extensions, if 420 extensions are present, might be useful to the backend server. 421 But might also only be useful/meaningful at the TTRP where the 422 initial TLS connection is terminated. I really don't know. 423 Perhaps any extensions, if present, should be passed to the 424 backend via different header(s)? Or maybe it would be more 425 appropriate to not attempt to cover TokenBinding.extensions in 426 this document and defer to the definition of individual extensions 427 to say how/if they are to be handled in a TTRP type deployment? 429 Appendix C. Document History 431 [[ to be removed by the RFC Editor before publication as an RFC ]] 433 draft-campbell-tokbind-ttrp-01 435 o Minor editorial fixes. 437 o Add to the Acknowledgements. 439 draft-campbell-tokbind-ttrp-00 441 o Initial draft based on 'consensus to work on the problem' from the 442 Seoul meeting [1][2] and reflecting the consensus approach from 443 discussions at the Chicago meeting [3]. 445 [1] https://www.ietf.org/proceedings/97/minutes/minutes-97- 446 tokbind-01.txt (minutes from Seoul) 447 [2] https://www.ietf.org/proceedings/97/slides/slides-97-tokbind- 448 reverse-proxies-00.pdf (slides from Seoul) 449 [3] https://mailarchive.ietf.org/arch/msg/ 450 unbearable/_ZHI8y2Vs5WMP8VMRr7zroo_sNU (summary of discussion) 452 Author's Address 454 Brian Campbell 455 Ping Identity 457 Email: brian.d.campbell@gmail.com