idnits 2.17.1 draft-nottingham-http-new-status-03.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([2], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. -- The draft header indicates that this document updates RFC2616, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC2616, updated by this document, for RFC5378 checks: 1997-10-16) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 31, 2011) is 4562 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) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft Rackspace 4 Updates: 2616 (if approved) R. Fielding 5 Intended status: Standards Track Adobe 6 Expires: May 3, 2012 October 31, 2011 8 Additional HTTP Status Codes 9 draft-nottingham-http-new-status-03 11 Abstract 13 This document specifies additional HyperText Transfer Protocol (HTTP) 14 status codes for a variety of common situations. 16 Editorial Note (To be removed by RFC Editor before publication) 18 Distribution of this document is unlimited. Although this is not a 19 work item of the HTTPbis Working Group, comments should be sent to 20 the Hypertext Transfer Protocol (HTTP) mailing list at 21 ietf-http-wg@w3.org [1], which may be joined by sending a message 22 with subject "subscribe" to ietf-http-wg-request@w3.org [2]. 24 Discussions of the HTTPbis Working Group are archived at 25 . 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 May 3, 2012. 44 Copyright Notice 46 Copyright (c) 2011 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 3. 428 Precondition Required . . . . . . . . . . . . . . . . . . . 3 64 4. 429 Too Many Requests . . . . . . . . . . . . . . . . . . . . . 3 65 5. 431 Request Header Fields Too Large . . . . . . . . . . . . . . 4 66 6. 511 Network Authentication Required . . . . . . . . . . . . . . 5 67 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 68 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 69 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 70 9.1. Normative References . . . . . . . . . . . . . . . . . . . 7 71 9.2. Informative References . . . . . . . . . . . . . . . . . . 8 72 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 8 73 Appendix B. Issues Raised by Captive Portals . . . . . . . . . . . 8 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 76 1. Introduction 78 This document specifies additional HTTP [RFC2616] status codes for a 79 variety of common situations, to improve interoperability and avoid 80 confusion when other, less precise status codes are used. 82 2. Requirements 84 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 85 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 86 document are to be interpreted as described in [RFC2119]. 88 3. 428 Precondition Required 90 This status code indicates that the origin server requires the 91 request to be conditional. 93 Its typical use is to avoid the "lost update" problem, where a client 94 GETs a resource's state, modifies it, and PUTs it back to the server, 95 when meanwhile a third party has modified the state on the server, 96 leading to a conflict. By requiring requests to be conditional, the 97 server can assure that clients are working with the correct copies. 99 Responses using this status code SHOULD explain how to resubmit the 100 request successfully. For example: 102 HTTP/1.1 428 Precondition Required 103 Content-Type: text/html 105 106 107 Precondition Required 108 109 110

Precondition Required

111

This request is required to be conditional; 112 try using "If-Match".

113 114 116 Responses with the 428 status code MUST NOT be stored by a cache. 118 4. 429 Too Many Requests 120 This status code indicates that the user has sent too many requests 121 in a given amount of time ("rate limiting"). 123 The response representations SHOULD include details explaining the 124 condition, and MAY include a Retry-After header indicating how long 125 to wait before making a new request. 127 For example: 129 HTTP/1.1 429 Too Many Requests 130 Content-Type: text/html 131 Retry-After: 3600 133 134 135 Too Many Requests 136 137 138

Too many Requests

139

I only allow 50 requests per hour to this Web site per 140 logged in user. Try again soon.

141 142 144 Note that this specification does not define how the origin server 145 identifies the user, nor how it counts requests. For example, an 146 origin server that is limiting request rates can do so based upon 147 counts of requests on a per-resource basis, across the entire server, 148 or even among a set of servers. Likewise, it might identify the user 149 by its authentication credentials, or a stateful cookie. 151 Responses with the 429 status code MUST NOT be stored by a cache. 153 5. 431 Request Header Fields Too Large 155 This status code indicates that the server is unwilling to process 156 the request because its header fields are too large. The request MAY 157 be resubmitted after reducing the size of the request header fields. 159 It can be used both when the set of request header fields in total 160 are too large, and when a single header field is at fault. In the 161 latter case, the response representation SHOULD specify which header 162 field was too large. 164 For example: 166 HTTP/1.1 431 Request Header Fields Too Large 167 Content-Type: text/html 169 170 171 Request Header Fields Too Large 172 173 174

Request Header Fields Too Large

175

The "Example" header was too large.

176 177 179 Responses with the 431 status code MUST NOT be stored by a cache. 181 6. 511 Network Authentication Required 183 This status code indicates that the client needs to authenticate to 184 gain network access. 186 The response representation SHOULD indicate how to do this; e.g., 187 with an HTML form for submitting credentials. 189 The 511 status SHOULD NOT be generated by origin servers; it is 190 intended for use by intercepting proxies that are interposed as a 191 means of controlling access to the network. 193 Responses with the 511 status code MUST NOT be stored by a cache. 195 6.1. The 511 Status Code and Captive Portals 197 A network operator wishing to require some authentication, acceptance 198 of terms or other user interaction before granting access usually 199 does so by identify clients who have not done so ("unknown clients") 200 using their MAC addresses. 202 Unknown clients then have all traffic blocked, except for that on TCP 203 port 80, which is sent to a HTTP server (the "login server") 204 dedicated to "logging in" unknown clients, and of course traffic to 205 the login server itself. 207 For example, a user agent might connect to a network and make the 208 following HTTP request on TCP port 80: 210 GET /index.htm HTTP/1.1 211 Host: www.example.com 212 Upon receiving such a request, the login server would generate a 511 213 response: 215 HTTP/1.1 511 Network Authentication Required 216 Content-Type: text/html 218 219 220 Network Authentication Required 221 223 224 225

You need to 226 authenticate with the local network in order to gain 227 access.

228 229 231 Here, the 511 status code assures that non-browser clients will not 232 interpret the response as being from the origin server, and the META 233 HTML element redirects the user agent to the login server. 235 Note that the 511 response can itself contain the login interface, 236 but it may not be desirable to do so, because browsers would show the 237 login interface as being associated with the originally requested 238 URL, which may cause confusion. 240 7. Security Considerations 242 7.1. 428 Precondition Required 244 The 428 status code is optional; clients cannot rely upon its use to 245 prevent "lost update" conflicts. 247 7.2. 429 Too Many Requests 249 Servers are not required to use the 429 status code; when limiting 250 resource usage, it may be more appropriate to just drop connections, 251 or take other steps. 253 7.3. 431 Request Header Fields Too Large 255 Servers are not required to use the 431 status code; when under 256 attack, it may be more appropriate to just drop connections, or take 257 other steps. 259 7.4. 511 Network Authentication Required 261 In common use, a response carrying the 511 status code will not come 262 from the origin server indicated in the request's URL. This presents 263 many security issues; e.g., an attacking intermediary may be 264 inserting cookies into the original domain's name space, may be 265 observing cookies or HTTP authentication credentials sent from the 266 user agent, and so on. 268 However, these risks are not unique to the 511 status code; in other 269 words, a captive portal that is not using this status code introduces 270 the same issues. 272 8. IANA Considerations 274 The HTTP Status Codes Registry should be updated with the following 275 entries: 277 o Code: 428 278 o Description: Precondition Required 279 o Specification: [ this document ] 281 o Code: 429 282 o Description: Too Many Requests 283 o Specification: [ this document ] 285 o Code: 431 286 o Description: Request Header Fields Too Large 287 o Specification: [ this document ] 289 o Code: 511 290 o Description: Network Authentication Required 291 o Specification: [ this document ] 293 9. References 295 9.1. Normative References 297 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 298 Requirement Levels", BCP 14, RFC 2119, March 1997. 300 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 301 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 302 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 304 9.2. Informative References 306 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 307 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 308 March 2007. 310 [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed 311 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 313 URIs 315 [1] 317 [2] 319 Appendix A. Acknowledgements 321 Thanks to Jan Algermissen and Julian Reschke for their suggestions 322 and feedback. 324 The authors take all responsibility for errors and omissions. 326 Appendix B. Issues Raised by Captive Portals 328 Since clients cannot differentiate between a portal's response and 329 that of the HTTP server that they intended to communicate with, a 330 number of issues arise. 332 One example is the "favicon.ico" 333 commonly used by browsers to 334 identify the site being accessed. If the favicon for a given site is 335 fetched from a captive portal instead of the intended site (e.g., 336 because the user is unauthenticated), it will often "stick" in the 337 browser's cache (most implementations cache favicons aggressively) 338 beyond the portal session, so that it seems as if the portal's 339 favicon has "taken over" the legitimate site. 341 Another browser-based issue comes about when P3P 342 is supported. Depending on how it is 343 implemented, it's possible a browser might interpret a portal's 344 response for the p3p.xml file as the server's, resulting in the 345 privacy policy (or lack thereof) advertised by the portal being 346 interpreted as applying to the intended site. Other Web-based 347 protocols such as WebFinger 348 , CORS 349 and OAuth 350 may also be 351 vulnerable to such issues. 353 Although HTTP is most widely used with Web browsers, a growing number 354 of non-browsing applications use it as a substrate protocol. For 355 example, WebDAV [RFC4918] and CalDAV [RFC4791] both use HTTP as the 356 basis (for remote authoring and calendaring, respectively). Using 357 these applications from behind a captive portal can result in 358 spurious errors being presented to the user, and might result in 359 content corruption, in extreme cases. 361 Similarly, other non-browser applications using HTTP can be affected 362 as well; e.g., widgets , software 363 updates, and other specialised software such as Twitter clients and 364 the iTunes Music Store. 366 It should be noted that it's sometimes believed that using HTTP 367 redirection to direct traffic to the portal addresses these issues. 368 However, since many of these uses "follow" redirects, this is not a 369 good solution. 371 Authors' Addresses 373 Mark Nottingham 374 Rackspace 376 Email: mnot@mnot.net 377 URI: http://www.mnot.net/ 379 Roy T. Fielding 380 Adobe Systems Incorporated 381 345 Park Ave 382 San Jose, CA 95110 383 USA 385 Email: fielding@gbiv.com 386 URI: http://roy.gbiv.com/