mirror of
https://git.friendi.ca/friendica/friendica-addons.git
synced 2024-08-19 07:30:52 +00:00
561 lines
17 KiB
Text
561 lines
17 KiB
Text
|
|
|||
|
|
|||
|
|
|||
|
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]
|
|||
|
|