561 lines
17 KiB
Plaintext
561 lines
17 KiB
Plaintext
|
||
|
||
|
||
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]
|
||
|