diff options
Diffstat (limited to 'vendor/sabre/dav/docs/draft-nottingham-http-new-status-04.txt')
| -rw-r--r-- | vendor/sabre/dav/docs/draft-nottingham-http-new-status-04.txt | 560 |
1 files changed, 560 insertions, 0 deletions
diff --git a/vendor/sabre/dav/docs/draft-nottingham-http-new-status-04.txt b/vendor/sabre/dav/docs/draft-nottingham-http-new-status-04.txt new file mode 100644 index 000000000..37d6808c3 --- /dev/null +++ b/vendor/sabre/dav/docs/draft-nottingham-http-new-status-04.txt @@ -0,0 +1,560 @@ + + + +Network Working Group M. Nottingham +Internet-Draft Rackspace +Updates: 2616 (if approved) R. Fielding +Intended status: Standards Track Adobe +Expires: August 7, 2012 February 4, 2012 + + + Additional HTTP Status Codes + draft-nottingham-http-new-status-04 + +Abstract + + This document specifies additional HyperText Transfer Protocol (HTTP) + status codes for a variety of common situations. + +Editorial Note (To be removed by RFC Editor before publication) + + Distribution of this document is unlimited. Although this is not a + work item of the HTTPbis Working Group, comments should be sent to + the Hypertext Transfer Protocol (HTTP) mailing list at + ietf-http-wg@w3.org [1], which may be joined by sending a message + with subject "subscribe" to ietf-http-wg-request@w3.org [2]. + + Discussions of the HTTPbis Working Group are archived at + <http://lists.w3.org/Archives/Public/ietf-http-wg/>. + +Status of this Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at http://datatracker.ietf.org/drafts/current/. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + This Internet-Draft will expire on August 7, 2012. + +Copyright Notice + + Copyright (c) 2012 IETF Trust and the persons identified as the + document authors. All rights reserved. + + + + +Nottingham & Fielding Expires August 7, 2012 [Page 1] + +Internet-Draft Additional HTTP Status Codes February 2012 + + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 3. 428 Precondition Required . . . . . . . . . . . . . . . . . . . 3 + 4. 429 Too Many Requests . . . . . . . . . . . . . . . . . . . . . 4 + 5. 431 Request Header Fields Too Large . . . . . . . . . . . . . . 4 + 6. 511 Network Authentication Required . . . . . . . . . . . . . . 5 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 + 9.1. Normative References . . . . . . . . . . . . . . . . . . . 8 + 9.2. Informative References . . . . . . . . . . . . . . . . . . 8 + Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 8 + Appendix B. Issues Raised by Captive Portals . . . . . . . . . . . 8 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 + + + + + + + + + + + + + + + + + + + + + + + + +Nottingham & Fielding Expires August 7, 2012 [Page 2] + +Internet-Draft Additional HTTP Status Codes February 2012 + + +1. Introduction + + This document specifies additional HTTP [RFC2616] status codes for a + variety of common situations, to improve interoperability and avoid + confusion when other, less precise status codes are used. + + Note that these status codes are optional; servers cannot be required + to support them. However, because clients will treat unknown status + codes as a generic error of the same class (e.g., 499 is treated as + 400 if it is not recognized), they can be safely deployed by existing + servers (see [RFC2616] Section 6.1.1 for more information). + + +2. Requirements + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + +3. 428 Precondition Required + + The 428 status code indicates that the origin server requires the + request to be conditional. + + Its typical use is to avoid the "lost update" problem, where a client + GETs a resource's state, modifies it, and PUTs it back to the server, + when meanwhile a third party has modified the state on the server, + leading to a conflict. By requiring requests to be conditional, the + server can assure that clients are working with the correct copies. + + Responses using this status code SHOULD explain how to resubmit the + request successfully. For example: + + HTTP/1.1 428 Precondition Required + Content-Type: text/html + + <html> + <head> + <title>Precondition Required</title> + </head> + <body> + <h1>Precondition Required</h1> + <p>This request is required to be conditional; + try using "If-Match".</p> + </body> + </html> + + + + +Nottingham & Fielding Expires August 7, 2012 [Page 3] + +Internet-Draft Additional HTTP Status Codes February 2012 + + + Responses with the 428 status code MUST NOT be stored by a cache. + + +4. 429 Too Many Requests + + The 429 status code indicates that the user has sent too many + requests in a given amount of time ("rate limiting"). + + The response representations SHOULD include details explaining the + condition, and MAY include a Retry-After header indicating how long + to wait before making a new request. + + For example: + + HTTP/1.1 429 Too Many Requests + Content-Type: text/html + Retry-After: 3600 + + <html> + <head> + <title>Too Many Requests</title> + </head> + <body> + <h1>Too Many Requests</h1> + <p>I only allow 50 requests per hour to this Web site per + logged in user. Try again soon.</p> + </body> + </html> + + Note that this specification does not define how the origin server + identifies the user, nor how it counts requests. For example, an + origin server that is limiting request rates can do so based upon + counts of requests on a per-resource basis, across the entire server, + or even among a set of servers. Likewise, it might identify the user + by its authentication credentials, or a stateful cookie. + + Responses with the 429 status code MUST NOT be stored by a cache. + + +5. 431 Request Header Fields Too Large + + The 431 status code indicates that the server is unwilling to process + the request because its header fields are too large. The request MAY + be resubmitted after reducing the size of the request header fields. + + It can be used both when the set of request header fields in total + are too large, and when a single header field is at fault. In the + latter case, the response representation SHOULD specify which header + + + +Nottingham & Fielding Expires August 7, 2012 [Page 4] + +Internet-Draft Additional HTTP Status Codes February 2012 + + + field was too large. + + For example: + + HTTP/1.1 431 Request Header Fields Too Large + Content-Type: text/html + + <html> + <head> + <title>Request Header Fields Too Large</title> + </head> + <body> + <h1>Request Header Fields Too Large</h1> + <p>The "Example" header was too large.</p> + </body> + </html> + + Responses with the 431 status code MUST NOT be stored by a cache. + + +6. 511 Network Authentication Required + + The 511 status code indicates that the client needs to authenticate + to gain network access. + + The response representation SHOULD contain a link to a resource that + allows the user to submit credentials (e.g. with a HTML form). + + Note that the 511 response SHOULD NOT contain a challenge or the + login interface itself, because browsers would show the login + interface as being associated with the originally requested URL, + which may cause confusion. + + The 511 status SHOULD NOT be generated by origin servers; it is + intended for use by intercepting proxies that are interposed as a + means of controlling access to the network. + + Responses with the 511 status code MUST NOT be stored by a cache. + +6.1. The 511 Status Code and Captive Portals + + The 511 status code is designed to mitigate problems caused by + "captive portals" to software (especially non-browser agents) that is + expecting a response from the server that a request was made to, not + the intervening network infrastructure. It is not intended to + encouraged deployment of captive portals, only to limit the damage + caused by them. + + + + +Nottingham & Fielding Expires August 7, 2012 [Page 5] + +Internet-Draft Additional HTTP Status Codes February 2012 + + + A network operator wishing to require some authentication, acceptance + of terms or other user interaction before granting access usually + does so by identifing clients who have not done so ("unknown + clients") using their MAC addresses. + + Unknown clients then have all traffic blocked, except for that on TCP + port 80, which is sent to a HTTP server (the "login server") + dedicated to "logging in" unknown clients, and of course traffic to + the login server itself. + + For example, a user agent might connect to a network and make the + following HTTP request on TCP port 80: + + GET /index.htm HTTP/1.1 + Host: www.example.com + + Upon receiving such a request, the login server would generate a 511 + response: + + HTTP/1.1 511 Network Authentication Required + Content-Type: text/html + + <html> + <head> + <title>Network Authentication Required</title> + <meta http-equiv="refresh" + content="0; url=https://login.example.net/"> + </head> + <body> + <p>You need to <a href="https://login.example.net/"> + authenticate with the local network</a> in order to gain + access.</p> + </body> + </html> + + Here, the 511 status code assures that non-browser clients will not + interpret the response as being from the origin server, and the META + HTML element redirects the user agent to the login server. + + +7. Security Considerations + +7.1. 428 Precondition Required + + The 428 status code is optional; clients cannot rely upon its use to + prevent "lost update" conflicts. + + + + + +Nottingham & Fielding Expires August 7, 2012 [Page 6] + +Internet-Draft Additional HTTP Status Codes February 2012 + + +7.2. 429 Too Many Requests + + When a server is under attack or just receiving a very large number + of requests from a single party, responding to each with a 429 status + code will consume resources. + + Therefore, servers are not required to use the 429 status code; when + limiting resource usage, it may be more appropriate to just drop + connections, or take other steps. + +7.3. 431 Request Header Fields Too Large + + Servers are not required to use the 431 status code; when under + attack, it may be more appropriate to just drop connections, or take + other steps. + +7.4. 511 Network Authentication Required + + In common use, a response carrying the 511 status code will not come + from the origin server indicated in the request's URL. This presents + many security issues; e.g., an attacking intermediary may be + inserting cookies into the original domain's name space, may be + observing cookies or HTTP authentication credentials sent from the + user agent, and so on. + + However, these risks are not unique to the 511 status code; in other + words, a captive portal that is not using this status code introduces + the same issues. + + Also, note that captive portals using this status code on an SSL or + TLS connection (commonly, port 443) will generate a certificate error + on the client. + + +8. IANA Considerations + + The HTTP Status Codes Registry should be updated with the following + entries: + + o Code: 428 + o Description: Precondition Required + o Specification: [ this document ] + + o Code: 429 + o Description: Too Many Requests + o Specification: [ this document ] + + + + + +Nottingham & Fielding Expires August 7, 2012 [Page 7] + +Internet-Draft Additional HTTP Status Codes February 2012 + + + o Code: 431 + o Description: Request Header Fields Too Large + o Specification: [ this document ] + + o Code: 511 + o Description: Network Authentication Required + o Specification: [ this document ] + + +9. References + +9.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., + Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext + Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. + +9.2. Informative References + + [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, + "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, + March 2007. + + [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed + Authoring and Versioning (WebDAV)", RFC 4918, June 2007. + +URIs + + [1] <mailto:ietf-http-wg@w3.org> + + [2] <mailto:ietf-http-wg-request@w3.org?subject=subscribe> + + +Appendix A. Acknowledgements + + Thanks to Jan Algermissen and Julian Reschke for their suggestions + and feedback. + + +Appendix B. Issues Raised by Captive Portals + + Since clients cannot differentiate between a portal's response and + that of the HTTP server that they intended to communicate with, a + number of issues arise. The 511 status code is intended to help + mitigate some of them. + + + +Nottingham & Fielding Expires August 7, 2012 [Page 8] + +Internet-Draft Additional HTTP Status Codes February 2012 + + + One example is the "favicon.ico" + <http://en.wikipedia.org/wiki/Favicon> commonly used by browsers to + identify the site being accessed. If the favicon for a given site is + fetched from a captive portal instead of the intended site (e.g., + because the user is unauthenticated), it will often "stick" in the + browser's cache (most implementations cache favicons aggressively) + beyond the portal session, so that it seems as if the portal's + favicon has "taken over" the legitimate site. + + Another browser-based issue comes about when P3P + <http://www.w3.org/TR/P3P/> is supported. Depending on how it is + implemented, it's possible a browser might interpret a portal's + response for the p3p.xml file as the server's, resulting in the + privacy policy (or lack thereof) advertised by the portal being + interpreted as applying to the intended site. Other Web-based + protocols such as WebFinger + <http://code.google.com/p/webfinger/wiki/WebFingerProtocol>, CORS + <http://www.w3.org/TR/cors/> and OAuth + <http://tools.ietf.org/html/draft-ietf-oauth-v2> may also be + vulnerable to such issues. + + Although HTTP is most widely used with Web browsers, a growing number + of non-browsing applications use it as a substrate protocol. For + example, WebDAV [RFC4918] and CalDAV [RFC4791] both use HTTP as the + basis (for remote authoring and calendaring, respectively). Using + these applications from behind a captive portal can result in + spurious errors being presented to the user, and might result in + content corruption, in extreme cases. + + Similarly, other non-browser applications using HTTP can be affected + as well; e.g., widgets <http://www.w3.org/TR/widgets/>, software + updates, and other specialised software such as Twitter clients and + the iTunes Music Store. + + It should be noted that it's sometimes believed that using HTTP + redirection to direct traffic to the portal addresses these issues. + However, since many of these uses "follow" redirects, this is not a + good solution. + + +Authors' Addresses + + Mark Nottingham + Rackspace + + Email: mnot@mnot.net + URI: http://www.mnot.net/ + + + + +Nottingham & Fielding Expires August 7, 2012 [Page 9] + +Internet-Draft Additional HTTP Status Codes February 2012 + + + Roy T. Fielding + Adobe Systems Incorporated + 345 Park Ave + San Jose, CA 95110 + USA + + Email: fielding@gbiv.com + URI: http://roy.gbiv.com/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Nottingham & Fielding Expires August 7, 2012 [Page 10] + |