idnits 2.17.1 draft-nottingham-proxy-explanation-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 : ---------------------------------------------------------------------------- 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 (February 17, 2016) is 2990 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '4' on line 214 -- Looks like a reference, but probably isn't: '5' on line 220 -- Looks like a reference, but probably isn't: '1' on line 304 -- Looks like a reference, but probably isn't: '2' on line 306 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft February 17, 2016 4 Intended status: Informational 5 Expires: August 20, 2016 7 The application/proxy-explanation+json media type 8 draft-nottingham-proxy-explanation-00 10 Abstract 12 This specification defines the application/proxy-explanation+json 13 media type, to allow HTTP proxies to explain to clients why a request 14 is unsuccessful. 16 Note to Readers 18 The issues list for this draft can be found at 19 https://github.com/mnot/I-D/labels/proxy-explanation . 21 The most recent (often, unpublished) draft is at 22 https://mnot.github.io/I-D/proxy-explanation/ . 24 Recent changes are listed at https://github.com/mnot/I-D/commits/gh- 25 pages/proxy-explanation . 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on August 20, 2016. 44 Copyright Notice 46 Copyright (c) 2016 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 62 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 63 2. The application/proxy-explanation+json Media Type . . . . . . 3 64 2.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 4 65 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 66 4. Security Considerations . . . . . . . . . . . . . . . . . . . 5 67 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 68 5.1. Normative References . . . . . . . . . . . . . . . . . . 6 69 5.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 7 70 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 7 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 73 1. Introduction 75 HTTP requests [RFC7230] to a proxy might not succeed variety of 76 reasons; the request itself might violate a policy, or the requested 77 content might be deemed unacceptable (e.g., it contains a virus, or 78 itself violate a policy being imposed by the proxy). 80 For HTTP URLs, information about the reason is often injected into 81 the HTTP response, so that the user understands what has happened, 82 even if the message is only an HTML "Access Denied." This practice 83 is problematic, because both users and non-browser clients can become 84 confused about the source of the information, mistaking content from 85 the proxy as being from the origin. 87 Furthermore, for HTTPS URLs, there is no way for the proxy to inform 88 the end user about its actions. Proxies could provide HTML content 89 in a 403 (Forbidden) response, but browsers are unwilling to show 90 this to end users, since doing so would subject them to a potential 91 man-in-the-middle attack. 93 This specification defines a new response format with a constrained 94 vocabulary, so that proxies can communicate basic information about 95 why a request has not succeeded, and browsers can provide that 96 information to users without risking it being mistaken for an 97 authoritative response from the origin server. 99 1.1. Notational Conventions 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 103 document are to be interpreted as described in [RFC2119]. 105 2. The application/proxy-explanation+json Media Type 107 The "application/proxy-explanation+json" media type denotes a JSON 108 [RFC7159] format whose root is an object containing the following 109 members: 111 o *name* - A short string identifying the party operating the proxy 113 o *title* - A short string title for the explanation 115 o *description* - A string explaining why the request wasn't 116 successful 118 o *moreinfo* - A string containing an absolute URL [RFC3986] which 119 the user can find relevant information. 121 The "name" and "title" members MUST be present; all other members are 122 OPTIONAL. 124 This media type MUST NOT be generated by origin servers and gateway 125 servers (i.e., "reverse proxies" and "content delivery networks"); it 126 is only intended to be generated by proxies. It MAY be generated by 127 interception proxies (so-called "transparent proxies"), although as 128 per below, it might be ignored by clients in this case. 130 It MUST NOT be used with a 2xx or 3xx status code, and clients MUST 131 ignore its presence on them. Typical status codes that it will be 132 used with include 403 (Forbidden), 451 (Unavailable For Legal 133 Reasons), 502 (Bad Gateway), and 504 (Gateway Timeout). 135 Proxies SHOULD carefully consider what caching metadata [RFC7234] is 136 appropriate to include in such responses. 138 Clients MAY selectively support this media type. For example, an 139 implementation might deem it only useful (or safe) in CONNECT 140 requests. 142 Clients SHOULD indicate that they support this media type by 143 including it in the field-value of the Accept request header field 144 [RFC7231] of all supported requests. 146 2.1. Example 148 For example: 150 CONNECT www.example.net:80 HTTP/1.1 151 Host: www.example.net 152 Accept: application/proxy-explanation+json 153 Accept-Language: en-us 155 HTTP/1.1 403 Forbidden 156 Content-Type: application/proxy-explanation+json 157 Cache-Control: no-cache 159 { 160 "name": "Acme Networks" 161 "title": "Policy Violation" 162 "description": "This content is above your pay grade." 163 "moreinfo": "https://acme.example.com/why" 164 } 166 A browser might display this to the end user in a manner similar to 167 this: 169 Policy Violation 171 The proxy "Acme Networks" says: 173 This content is above your pay grade. 175 For more information, see: 176 "https://acme.example.com/why?https://www.example.net" 178 3. IANA Considerations 180 This specification defines a new Internet Media Type [RFC6838]: 182 o Type name: application 184 o Subtype name: proxy-explanation+json 186 o Required parameters: None 188 o Optional parameters: None; unrecognised parameters should be 189 ignored 191 o Encoding considerations: Same as [RFC7159] 193 o Security considerations: See Section 4 195 o Interoperability considerations: None 197 o Published specification: [this document] 199 o Applications that use this media type: HTTP 201 o Fragment identifier considerations: Same as [RFC7159] 203 o Additional information: 205 * Deprecated alias names for this type: N/A 207 * Magic number(s): N/A 209 * File extension(s): N/A 211 * Macintosh file type code(s): N/A 213 o Person & email address to contact for further information: Mark 214 Nottingham mnot@mnot.net [4] 216 o Intended usage: COMMON 218 o Restrictions on usage: N/A 220 o Author: Mark Nottingham mnot@mnot.net [5] 222 o Change controller: IESG 224 4. Security Considerations 226 The approach taken in this specification precludes a proxy presenting 227 itself as the origin, provided that, when presented to the user, the 228 information is sufficiently contextualised as being from the proxy. 230 This approach does not preclude an origin server presenting itself as 231 a the proxy, in cases where the client supports the media type on 232 requests other than CONNECT. 234 Likewise, it does not prevent a man-in-the-middle from presenting 235 itself as a proxy, in cases where the connection is unencrypted. 237 Because the payload can contain a URL, it could be used by an 238 attacker (either a hostile origin or MitM, as above) to direct users 239 to an origin under their control. For example, an attacker could 240 convince users that they need to provide payment before the network 241 is available. 243 An attacker could also include a URL in the textual content of its 244 message (e.g., in the "description" member), to encourage the user to 245 copy the link and follow it. 247 However, both origins and cleartext MitMs can misrepresent their 248 identities on the Web currently, without the benefit of this 249 mechanism. These risks are introduced only when users trust the 250 "proxy" interface more than they would trust a "normal" Web site. 252 They can be mitigated in a few ways: 254 o Not displaying the "moreinfo" member in situations when this is 255 possible (i.e., on any response other than that to a CONNECT on an 256 encrypted connection). 258 o Not supporting the "application/proxy-connection+json" media type 259 when the method is not CONNECT and the connection is not 260 encrypted. 262 o Cautioning the user that the content might not be trustworthy. 264 5. References 266 5.1. Normative References 268 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 269 Requirement Levels", BCP 14, RFC 2119, 270 DOI 10.17487/RFC2119, March 1997, 271 . 273 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 274 Resource Identifier (URI): Generic Syntax", STD 66, 275 RFC 3986, DOI 10.17487/RFC3986, January 2005, 276 . 278 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 279 Specifications and Registration Procedures", BCP 13, 280 RFC 6838, DOI 10.17487/RFC6838, January 2013, 281 . 283 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 284 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 285 2014, . 287 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 288 Protocol (HTTP/1.1): Message Syntax and Routing", 289 RFC 7230, DOI 10.17487/RFC7230, June 2014, 290 . 292 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 293 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 294 DOI 10.17487/RFC7231, June 2014, 295 . 297 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 298 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 299 RFC 7234, DOI 10.17487/RFC7234, June 2014, 300 . 302 5.2. URIs 304 [1] mailto:mnot@mnot.net 306 [2] mailto:mnot@mnot.net 308 Appendix A. Acknowledgements 310 Thanks to Thomas Mangin for his suggestions. 312 Author's Address 314 Mark Nottingham 316 Email: mnot@mnot.net 317 URI: https://www.mnot.net/