idnits 2.17.1 draft-nottingham-web-proxy-desc-00.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 : ---------------------------------------------------------------------------- == There are 3 instances of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 1, 2014) is 3525 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) == Outdated reference: A later version (-17) exists of draft-ietf-httpbis-http2-14 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 5785 (Obsoleted by RFC 8615) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 4 errors (**), 0 flaws (~~), 3 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft 4 Intended status: Standards Track September 1, 2014 5 Expires: March 5, 2015 7 The Web Proxy Description Format 8 draft-nottingham-web-proxy-desc-00 10 Abstract 12 This specification defines a simple means of configuring Web proxies, 13 and places additional requirements upon them in order to promote 14 improved interoperability, security, and error handling. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on March 5, 2015. 33 Copyright Notice 35 Copyright (c) 2014 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 52 2. WPD Proxies . . . . . . . . . . . . . . . . . . . . . . . . . 4 53 3. The Web Proxy Description (WPD) Format . . . . . . . . . . . 5 54 3.1. name . . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 3.2. desc . . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 3.3. moreInfo . . . . . . . . . . . . . . . . . . . . . . . . 6 57 3.4. proxies . . . . . . . . . . . . . . . . . . . . . . . . . 6 58 3.4.1. host . . . . . . . . . . . . . . . . . . . . . . . . 6 59 3.4.2. port . . . . . . . . . . . . . . . . . . . . . . . . 6 60 3.4.3. clientNetworks . . . . . . . . . . . . . . . . . . . 6 61 3.5. forReferers . . . . . . . . . . . . . . . . . . . . . . . 7 62 3.6. alwaysDirect . . . . . . . . . . . . . . . . . . . . . . 8 63 3.7. failDirect . . . . . . . . . . . . . . . . . . . . . . . 8 64 4. Discovering WPD Files . . . . . . . . . . . . . . . . . . . . 9 65 4.1. The web-proxy-desc well-known URI . . . . . . . . . . . . 9 66 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 67 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 68 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 69 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 70 8.1. Normative References . . . . . . . . . . . . . . . . . . 10 71 8.2. Informative References . . . . . . . . . . . . . . . . . 11 72 Appendix A. User Experience for WPDs . . . . . . . . . . . . . . 11 73 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 75 1. Introduction 77 Web proxies are configured in a variety of ways today, but existing 78 approaches suffer from security, usability and interoperability 79 issues. 81 This specification defines: 83 o A simple format for describing a Web proxy ("WPD"; see Section 3) 84 to facilitate configuration, and so that it can be represented to 85 users in a consistent way, and 87 o A way to discover the proxy description using a well-known URL 88 (Section 4), so that direct configuration of a proxy is as simple 89 as entering a hostname, and 91 o A set of additional requirements for proxies described in this 92 fashion, as well as requirements for User Agents connecting to 93 them, designed to improve security, usability and 94 interoperability. See Section 2. 96 It can be used in a variety of ways, but is designed to meet the 97 following goals: 99 o Users should always be aware of a configured proxy and be able to 100 confidently identify it, and 102 o Configuring a proxy should be a deliberate act, but simple to do 103 for non-technical users, and 105 o Proxies should always respect the wishes of the end user and Web 106 site, and 108 o Proxies should never reduce or compromise the security of 109 connections, and improve it where possible, and 111 o The proxy should be able to reliably communicate with the end user 112 regarding its policies and problems that are encountered. 114 Furthermore, it is designed to be useful in the following cases: 116 o An end user wants to use a proxy network that provides improved 117 performance, by re-compressing responses to http:// resources. 119 o An end user wants to use a proxy network that provides improved 120 privacy, by routing requests through any number of intermediaries. 122 o An end user is required to use a proxy to access Internet 123 resources by their network (e.g., a school, workplace or prison). 125 o A network wants to offer enhanced access to selected Web sites, 126 through interposition of a proxy. 128 Importantly, this specification does not address the automatic 129 discovery of proxy configuration for a given network, because proxy 130 configuration is a security-sensitive action, and ought never be 131 performed without explicit user or administrator action. 133 It is expected that the mechanisms described could be implemented by 134 a single program (e.g., a Web browser), or through an Operating 135 System facility. 137 1.1. Notational Conventions 139 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 140 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 141 document are to be interpreted as described in [RFC2119]. 143 2. WPD Proxies 145 This specification defines a particular kind of HTTP proxy (as per 146 [RFC7230] Section 2.3) known as a "WPD proxy" that has additional 147 requirements placed upon it, as well as upon those using it. 149 WPD Proxies MUST support HTTP/2 [I-D.ietf-httpbis-http2] over TLS for 150 connections from clients. Clients that cannot establish a HTTP/2 151 connection to a WPD proxy MUST consider that proxy "failed." 153 WPD Proxies MUST support forwarding requests with the "http" scheme 154 [RFC7230], and SHOULD support the CONNECT method, as specified in 155 [I-D.ietf-httpbis-http2] Section 8.3. 157 [RFC7230] Section 5.7.2 requires proxies to honour the semantic of 158 the "no-transform" cache-control directive, and append the 214 159 (Transformation Applied) warn-code to other messages that have been 160 transformed; WPD proxies MUST honour these requirements. 162 When connecting to a WPD proxy, clients MUST use TLS and MUST 163 validate the proxy hostname as per [RFC2818] Section 3.1. If the 164 proxy presents an invalid certificate, that proxy MUST be considered 165 "failed" and not used (until a valid certificate is presented). 167 User agents MUST use a CONNECT tunnel when retrieving URLs with the 168 "https" scheme through WPD proxies. 170 When user agents encounter 5xx responses to a CONNECT request from a 171 WPD proxy, they MUST present the response to the end user, but MUST 172 NOT present or process it as a response to the eventual request to be 173 made through the tunnel (i.e., it has an unidentified payload, as per 174 [RFC7231] Section 3.1.4.1). 176 NOTE: Many user agents refuse to show an error response to a CONNECT 177 to the user, in order to deal with the issues brought to light by 178 [bad-proxy]. While effective in dealing with those attacks, doing so 179 effectively disallows communication between the proxy and the end 180 user; this requirement is designed to re-open that channel. 182 If a WPD proxy becomes unresponsive, clients SHOULD consider it 183 failed and attempt to use another proxy (if available) or inform the 184 end user (if not available). Clients SHOULD regularly attempt to re- 185 establish contact with failed WPD proxies (e.g., every minute). 187 3. The Web Proxy Description (WPD) Format 189 WPD is a JSON [RFC7159] format that describes a Web proxy to 190 potential clients. Its root is an object containing WPD-specific 191 object members. For example: 193 { 194 "name": "ExampleCorp Web Proxy", 195 "desc": "ExampleCorp's Proxy Gateway for Web access. Note that 196 all traffic through this proxy is logged, and may be 197 filtered for content.", 198 "moreInfo": "https://inside.example.com/proxy/", 199 "proxies": [ 200 { 201 "host": "proxy.example.com", 202 "port": 8080, 203 "clientNetworks": ["192.0.2.0/24"] 204 }, 205 { 206 "host": "proxy1.example.com", 207 "port": 8080, 208 "clientNetworks": ["192.0.2.0/24"] 209 } 210 ], 211 "alwaysDirect": ["example.com", "192.0.2.0/24"], 212 "failDirect": False 213 } 215 When configuring a proxy through WPD, a user agent SHOULD present the 216 relevant information contained within (i.e., the 'name', 'desc' and 217 'moreInfo' members, the latter as a link) to the end user. User 218 agents SHOULD also make this information available to the end user 219 whenever the WPD is in use. 221 The remainder of this section defines the content of these members. 222 Unrecognized members SHOULD be ignored. 224 3.1. name 226 A string containing a short, memorable name for the proxy; typically 227 64 characters or less. This member MUST be present for the WPD to be 228 considered valid. 230 3.2. desc 232 A string containing a textual description of the proxy's function(s); 233 typically 256 characters or less. This member MUST be present for 234 the WPD to be considered valid. 236 3.3. moreInfo 238 A string containing a URL [RFC3986] that leads to more information 239 about the proxy, its operation, who operates it, etc. The URL MUST 240 have a scheme of "https" [RFC7230], and MUST be able to respond with 241 an HTML [W3C.CR-html5-20140731] representation. This member MUST be 242 present for the WPD to be considered valid. 244 3.4. proxies 246 An array containing one or more proxy objects; each proxy object 247 represents a HTTP proxy endpoint that can be used when this WPD is 248 configured. See Section 2 for requirements specific to these 249 proxies, as well as those clients connecting to them. 251 Proxy objects' members are defined by the following subsections; 252 unrecognized members SHOULD be ignored. 254 The ordering of proxy objects within the proxies array is not 255 significant; clients MAY choose any proxy they wish (keeping in mind 256 the requirements of clientNetworks), and MAY use more than one at a 257 time. 259 NOTE: the array of proxy objects is functionally similar to, but not 260 as expressive as, the commonly-used "proxy.pac" format. While it 261 would be expedient for WPD to just reference a proxy.pac, feedback so 262 far is that proxy.pac has a number of deficiencies, and 263 interoperability over it is poor. Therefore, this document specifies 264 the proxy object instead, in order to gather feedback on an 265 alternative approach. 267 3.4.1. host 269 A string containing the host (as per [RFC3986], section 3.2.2) of the 270 proxy. This member MUST be present. 272 3.4.2. port 274 A number representing the port that the proxy is listening on. This 275 member MUST be present, and MUST be an integer. 277 3.4.3. clientNetworks 279 An array containing strings; each string contains a classless prefix 280 (see [RFC4632]) which the proxy can be used within. Clients MUST NOT 281 attempt to use the proxy if their IP address is not within one of the 282 stated ranges. 284 This member is optional. 286 For example, if the value of clientNetworks is 288 [ "192.168.1.0/32", "192.168.2.0/24" ] 290 then the only clients that could use the proxy would have IP 291 addresses in the ranges 192.168.1.0 to 192.168.1.3 and 192.168.2.0 to 292 192.168.2.255. 294 Note that by their nature private networks (as specified in 295 [RFC1918]) are not unique, and therefore there may be false 296 positives. As such, clients SHOULD NOT automatically configure a WPD 297 based upon clientNetworks when the IP address is in these ranges, 298 although they MAY notify the user of a WPD's possible applicability, 299 and MAY use additional information to correlate a WPD to its proper 300 network. 302 3.5. forReferers 304 An array containing strings; each string is a host (as per [RFC3986] 305 Section 3.2.2). 307 When forReferers is present, Clients MUST use the WPD's proxies to 308 access these hosts, hostnames that have the host as a root, and for 309 traffic generated by that content. They MUST NOT be used for other 310 traffic. 312 This member is optional. 314 For example, if the value of forReferers is 316 [ "friendface.example.com" ] 318 then requests to "friendface.example.com", 319 "www.friendface.example.com", "app.friendface.example.com" etc. would 320 use the associated proxies; likewise, if processing a response from 321 one of these hosts generated further requests to "images.example.net" 322 and "scripts.example.org", they would also use the proxies. 324 Note that alwaysDirect takes precedence over forReferers. 326 TODO: tighten up what "processing" means here; the intent is to omit 327 a href 329 3.6. alwaysDirect 331 An array containing strings; each string is one of: 333 o a host (as per [RFC3986] Section 3.2.2), 335 o a classless prefix [RFC4632]. 337 o the string "CONNECT". 339 Clients MUST NOT use the WPD's proxies to access nominated hosts and 340 hostnames that have the a nominated host as its root. Likewise, 341 clients MUST NOT use the WPD's proxies to access bare IP addresses 342 that fall within the classless prefix. 344 If the string "CONNECT" appears in alwaysDirect, it indicates that 345 requests that require establishment of a tunnel (e.g., for "https" 346 URLs) MUST NOT use the WPD's proxies, but instead ought to be made 347 directly to the origin (i.e., without a tunnel). 349 Note that when a "bare" IP address or classless prefix is used in 350 alwaysDirect, clients are not required to perform a reverse lookup on 351 hostnames; these forms are only intended for accessing URLs that use 352 the IP-literal or IPv4address forms. 354 This member is optional. 356 For example, if the value of alwaysDirect is: 358 [ "example.com", "192.168.5/24" ] 360 then requests to "example.com", "www.example.com", "foo.example.com" 361 etc would not use any proxy. Likewise, requests whose URL authority 362 were bare IP addresses in the range 192.168.5.0 to 192.168.5.255 363 would not use any proxy. 365 3.7. failDirect 367 A boolean indicating whether the client should attempt to directly 368 access the origin server if all applicable proxies are unavailable. 370 When False, clients MUST NOT attempt to directly access the origin 371 server when no proxy is available, but instead SHOULD inform the user 372 that the proxy is unavailable. 374 When True, clients MAY do so. If failDirect is not present, clients 375 MAY default to this behavior. 377 4. Discovering WPD Files 379 To facilitate easy configuration of WPD proxies, this specification 380 defines a well-known URI [RFC5785]. Doing so allows a proxy's 381 description to be found with a simple hostname; e.g., 382 "proxy.example.net" or even just "example.net". 384 Clients MUST NOT use the DHCP "WPAD" mechanism to discover WPDs. 386 4.1. The web-proxy-desc well-known URI 388 The "web-proxy-desc" well-known URI allows discovery of a Web Proxy 389 Description (Section 3). 391 This well-known URI is only valid when used with the "https" URI 392 Scheme [RFC7230]; it MUST NOT be used with "http" URIs. In other 393 words, WPD discovery is always protected by TLS [RFC5246]. 395 The description found at this location is considered valid for its 396 freshness lifetime, as defined in [RFC7234] Section 4.2. Once stale, 397 clients SHOULD refresh it and apply any changes. 399 If the WPD is not retrievable (e.g., a 404 response status), invalid 400 (as per JSON [RFC7159] or the requirements in Section 3), or its 401 certificate is not valid for the host (as per [RFC2818] Section 3.1), 402 the client MUST NOT use the WPD, and if a user agent, SHOULD inform 403 the end user. 405 The well-known URI MAY use proactive content negotiation ([RFC7231] 406 Section 3.4.1) to select an appropriate language for the response 407 representation. Therefore, clients SHOULD send an Accept-Language 408 request header field ([RFC7231] Section 5.3.5) when they wish to 409 advertise their configured language. 411 The registration template is: 413 o URI suffix: web-proxy-desc 415 o Change controller: IETF 417 o Specification document(s): [this document] 419 o Related information: only to be used with 'https' scheme 421 5. IANA Considerations 423 This specification registers a new well-known URI, as per [RFC5785]. 424 See Section 4.1 for the template. 426 6. Security Considerations 428 If a user can be convinced to configure a WPD hostname as their 429 proxy, that host can observe all unencrypted traffic by the client. 430 As such, WPD configuration interfaces ought only allow configuration 431 of proxies once their identity is validated (as required), and the 432 user ought to be given access to all relevant information about the 433 WPD proxy (i.e., 'name', 'desc' and 'moreInfo', the latter as a 434 link). Furthermore, WPD proxies ought only be configured as the 435 result of an intentional act, not as a side effect of normal Web 436 browsing. 438 7. Acknowledgements 440 Thanks to Patrick McManus for his feedback and suggestions. 442 8. References 444 8.1. Normative References 446 [I-D.ietf-httpbis-http2] 447 Belshe, M., Peon, R., and M. Thomson, "Hypertext Transfer 448 Protocol version 2", draft-ietf-httpbis-http2-14 (work in 449 progress), July 2014. 451 [RFC1918] Rekhter, Y., Moskowitz, R., Karrenberg, D., Groot, G., and 452 E. Lear, "Address Allocation for Private Internets", BCP 453 5, RFC 1918, February 1996. 455 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 456 Requirement Levels", BCP 14, RFC 2119, March 1997. 458 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 460 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 461 Resource Identifier (URI): Generic Syntax", STD 66, RFC 462 3986, January 2005. 464 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 465 (CIDR): The Internet Address Assignment and Aggregation 466 Plan", BCP 122, RFC 4632, August 2006. 468 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 469 Interchange Format", RFC 7159, March 2014. 471 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 472 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 473 2014. 475 [RFC7234] Fielding, R., Nottingham, M., and J. Reschke, "Hypertext 476 Transfer Protocol (HTTP/1.1): Caching", RFC 7234, June 477 2014. 479 [W3C.CR-html5-20140731] 480 Berjon, R., Faulkner, S., Leithead, T., Navara, E., 481 O'Connor, E., and S. Pfeiffer, "HTML5", World Wide 482 Web Consortium CR CR-html5-20140731, July 2014, 483 . 485 8.2. Informative References 487 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 488 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 490 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 491 Uniform Resource Identifiers (URIs)", RFC 5785, April 492 2010. 494 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 495 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 497 [bad-proxy] 498 Chen, S., Mao, Z., Wang, Y., and M. Zhang, "Pretty-Bad- 499 Proxy: An Overlooked Adversary in Browsers' HTTPS 500 Deployments", January 2009, . 503 Appendix A. User Experience for WPDs 505 There are a variety of ways to present proxy configuration to users 506 and administrators, so this specification does not constrain how this 507 is done. That said, guidance for the common case (visual Web 508 browsers) can be helpful in assuring consistent user experience. 510 One of the core principles of this specification is that WPDs need to 511 be explicitly configured, either by the end user or an administrator 512 on their behalf. This is because using a proxy is a security- 513 sensitive operation; if an attacker can automatically configure a 514 proxy, or convince a user to do so as part of accessing a site, they 515 can gain access to the user's traffic, even when the user leaves the 516 attacking network. 518 Therefore, a user agent might allow configuration by entering a 519 hostname (e.g., "example.net"), whereupon it retrieves the WPD, 520 validates its certificate and contents, and present its information 521 to the end user for confirmation. 523 Once a WPD is confirmed, a user agent might "remember" it for future 524 use; e.g., by allowing quick configuration through a drop-down menu. 525 When a WPD nominates clientNetworks and the client does not have a 526 suitable IP address, the drop-down might make that option 527 unavailable. 529 It is envisioned that only a single WPD ought be configured at a 530 time; combining WPDs leads to ambiguity regarding precedence and 531 therefore user confusion. 533 When a WPD is active, its ought be visible to the end user, to remind 534 them of its presence, and to offer more information about the 535 configured proxy. 537 Author's Address 539 Mark Nottingham 541 Email: mnot@mnot.net 542 URI: http://www.mnot.net/