HTTP Working Group J. Mogul, DECWRL,
Internet-Draft J. Cohen, Netscape,
Expires: 28 February 1998 S. Lawrence, Agranat Systems
26 August 1997
Specification of HTTP/1.1 OPTIONS messages
draft-ietf-http-options-02.txt
STATUS OF THIS MEMO
This document is an Internet-Draft. Internet-Drafts are
working documents of the Internet Engineering Task Force
(IETF), its areas, and its working groups. Note that other
groups may also distribute working documents as
Internet-Drafts.
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."
To learn the current status of any Internet-Draft, please
check the "1id-abstracts.txt" listing contained in the
Internet-Drafts Shadow Directories on ftp.is.co.za
(Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific
Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US
West Coast).
Distribution of this document is unlimited. Please send
comments to the HTTP working group at
<http-wg@cuckoo.hpl.hp.com>. Discussions of the working
group are archived at
<URL:http://www.ics.uci.edu/pub/ietf/http/>. General
discussions about HTTP and the applications which use HTTP
should take place on the <www-talk@w3.org> mailing list.
ABSTRACT
RFC2068 defined a new OPTIONS method for HTTP/1.1. The
purpose of OPTIONS is to allow a 'client to determine the
options and/or requirements associated with a resource, or
the capabilities of a server, without implying a resource
action or initiating a resource retrieval.' However,
RFC2068 did not defined a specific syntax for using OPTIONS
to make such a determination. This proposal clarifies the
original specification of OPTIONS, adds several new HTTP
message headers to provide syntactic support for OPTIONS,
and establishes new IANA registries to avoid namespace
conflicts.
Mogul, Cohen, Lawrence [Page 1]
Internet-Draft HTTP OPTIONS messages 26 August 1997 17:58
TABLE OF CONTENTS
1 Introduction 2
2 Outline of proposed solution 2
3 Proposed solution 3
3.1 Changes to section 5.1.2, Request-URI 3
3.2 Changes to section 9.2, OPTIONS 4
3.3 Changes to section 14.31, Max-Forwards 6
3.4 The Compliance header 6
3.5 The Non-Compliance header 9
3.6 Changes to sections 14.7 and 14.35, Allow and Public 10
3.6.1 Alternative A: proxies MUST NOT modify Allow/Public 11
3.6.2 Alternative B: proxies MUST modify Allow/Public 12
3.7 Examples 12
4 Security Considerations 13
5 Acknowledgements 13
6 References 13
7 Authors' addresses 14
1 Introduction
Section 9.2 of RFC2068 [2] defines an OPTIONS method, to allow a
"client to determine the options and/or requirements associated with
a resource, or the capabilities of a server, without implying a
resource action or initiating a resource retrieval." For example, a
client may wish to determine if a particular HTTP method is supported
by a server, or for a specific resource. Or, a client may wish to
determine if a server supports the use of a particular HTTP
request-header.
The description of OPTIONS in RFC2068 has left some implementors
confused about what is required, and does not provide a specific
syntax for determining support for specific options or extensions.
While some of this might be obviated in the future by the Protocol
Extension Protocol (PEP) [1], there exists an immediate need to
define a simple and well-specified OPTIONS mechanism for HTTP/1.1.
2 Outline of proposed solution
- The intended recipient of an OPTIONS request may be any
server (including proxies) along the request path. RFC2068
supported this by requiring a transformation of the
request-URI for a set of methods (actually, only for
OPTIONS); in the current proposal, one can either use the
Host header to address a specific server or proxy, or the
Max-Forwards header to address the Nth server on a path.
- As in RFC2068, the URI '*' refers to the server,
independent of any specific resource. Any other URI refers
to the resource normally identified by that URI.
Mogul, Cohen, Lawrence [Page 2]
Internet-Draft HTTP OPTIONS messages 26 August 1997 17:58
- The descriptions of the Allow and Public headers, and of
the OPTIONS method, are made consistent in their
requirements for proxy editing of OPTIONS responses. (In
RFC2068, these sections were contradictory).
- A (new) Compliance header is proposed, which allows a
client to specify exactly what options it is asking about,
and which allows a server to specify exactly what subset of
those options are supported.
Discussion question: it might make more sense to use two
different header names, one for requests and one for
responses, to clarify that in a request, the client
is asking the server about its supported options, and
in a response, the server is stating its supported
options.
- The Compliance header allows several namespaces for
options; the set of namespaces is under IANA control. One
namespace is that of IETF-issued RFCs; this allows a more
specific definition of compliance than is available using
protocol version numbers. While various interpretations
can and do exist about the specific meaning of a protocol
version number (such as "HTTP/1.1"), the meaning of an RFC
is both well-defined and (more important) immutable.
- A (new) Non-Compliance header is proposed, allowing a proxy
processing an OPTIONS response to indicate its
non-compliance with one or more options, and without
requiring the proxy to edit the rest of the response (which
would result in loss of information).
3 Proposed solution
Here we propose specific changes to RFC2068.
3.1 Changes to section 5.1.2, Request-URI
Remove this:
Mogul, Cohen, Lawrence [Page 3]
Internet-Draft HTTP OPTIONS messages 26 August 1997 17:58
If a proxy receives a request without any path in the Request-URI
and the method specified is capable of supporting the asterisk form
of request, then the last proxy on the request chain MUST forward
the request with "*" as the final Request-URI. For example, the
request
OPTIONS http://www.ics.uci.edu:8001 HTTP/1.1
would be forwarded by the proxy as
OPTIONS * HTTP/1.1
Host: www.ics.uci.edu:8001
after connecting to port 8001 of host "www.ics.uci.edu".
3.2 Changes to section 9.2, OPTIONS
Replace:
Unless the server's response is an error, the response MUST NOT
include entity information other than what can be considered as
communication options (e.g., Allow is appropriate, but Content-Type
is not). Responses to this method are not cachable.
with:
An OPTIONS request MAY include Compliance headers (see section
14.ZZZ) that indicate the set of options the sender wants
information about.
Responses to OPTIONS are not cachable, unless caching is explicitly
allowed by the server that first sent the OPTIONS reply (see section
13.4).
Replace:
If the Request-URI is an asterisk ("*"), the OPTIONS request is
intended to apply to the server as a whole. A 200 response SHOULD
include any header fields which indicate optional features
implemented by the server (e.g., Public), including any extensions
not defined by this specification, in addition to any applicable
general or response-header fields. As described in section 5.1.2, an
"OPTIONS *" request can be applied through a proxy by specifying the
destination server in the Request-URI without any path information.
with:
Mogul, Cohen, Lawrence [Page 4]
Internet-Draft HTTP OPTIONS messages 26 August 1997 17:58
If the Request-URI is an asterisk ("*"), the OPTIONS request is
intended to apply to the server as a whole. A 200 response SHOULD
include a Public header field (see section 14.35). If the request
includes a Compliance header field, a 200 response SHOULD include a
Compliance header field, indicating the subset of the requested
Compliance options supported by the server as a whole. The response
SHOULD include any other applicable general or response-header
fields.
If an OPTIONS request includes a Host header (see section 14.23),
this is the intended destination of the OPTIONS method.
Proxy servers MUST forward such a message until it reaches
the specified host. If the specified host has more than
one `virtual server', the OPTIONS request applies to the
specified virtual server.
Note: An OPTIONS request may also include a Max-Forwards header,
as described in section 14.31. This allows the sender to select
the Nth proxy on a path, without knowing its hostname.
Replace:
If the Request-URI is not an asterisk, the OPTIONS request applies
only to the options that are available when communicating with that
resource. A 200 response SHOULD include any header fields which
indicate optional features implemented by the server and applicable
to that resource (e.g., Allow), including any extensions not defined
by this specification, in addition to any applicable general or
response-header fields. If the OPTIONS request passes through a
proxy, the proxy MUST edit the response to exclude those options
which apply to a proxy's capabilities and which are known to be
unavailable through that proxy.
with:
Mogul, Cohen, Lawrence [Page 5]
Internet-Draft HTTP OPTIONS messages 26 August 1997 17:58
If the Request-URI is not an asterisk, the OPTIONS request applies
only to the options that are available when communicating with that
resource. A 200 response SHOULD include an Allow header field (see
section 14.7). If the request includes a Compliance header field, a
200 response SHOULD include a Compliance header field, indicating
the subset of the requested Compliance options supported by the
server as a whole. If the subset is empty, the response SHOULD
include a Compliance header with an empty field-value. The response
SHOULD include any other applicable general or response-header
fields.
Note: if an OPTION request contains a Compliance header, and the
response does not, the response may have been generated by
RFC2068-compliant implementation, which would not support
Compliance. In this case, it is not possible to infer that the
sender fails to support all of the options listed in the
Compliance header of the request.
If the OPTIONS request passes through a
proxy, the proxy SHOULD add a Non-Compliance header field (see
section 14.QQQ) to the response, to list those options that apply to
a proxy's capabilities and that are known to be unavailable through
that proxy.
3.3 Changes to section 14.31, Max-Forwards
Replace:
Each proxy or gateway recipient of a TRACE request containing a Max-
Forwards header field SHOULD check and update its value prior to
forwarding the request.
with:
Each proxy or gateway recipient of a TRACE or OPTIONS request
containing a Max-Forwards header field SHOULD check and update its
value prior to forwarding the request.
3.4 The Compliance header
Insert in section 14, as a new subsection titled ``14.ZZZ
Compliance''
Mogul, Cohen, Lawrence [Page 6]
Internet-Draft HTTP OPTIONS messages 26 August 1997 17:58
The Compliance general header field lists a set of options
that may or may not be supported by a server. In a request
message, this header lists the set of options that a client
wishes to know about. In a response message, this header
lists the subset of the requested options that the server
complies with.
A compliance header MAY appear on any message, but is
normally used with the OPTIONS request (see section 9.2).
Compliance = "Compliance" ":" ("*" | #(compliance-option))
compliance-option = compliance-namespace "="
option-item [ option-params ]
compliance-namespace = token
option-item = token | quoted-string
| rfc-option-item | hdr-option-item
option-params = 1*( ";" option-param)
option-param = "cond" | "uncond" | token | quoted-string
A Compliance header field with the field-value of "*" MAY
be used in a request, to ask about all options complied
with by the recipient. This field-value MUST NOT be used
in a response.
When the Compliance header is present in a response, it takes
priority over an Allow header or a Public header in the same
response.
Tokens used for compliance-namespace, option-item, and
option-param values are case-insensitive.
The compliance-namespace is used to select from one of several
namespaces for compliance options. The option-item is used
to specify one or more options within a namespace.
Mogul, Cohen, Lawrence [Page 7]
Internet-Draft HTTP OPTIONS messages 26 August 1997 17:58
The Internet Assigned Numbers Authority (IANA) acts as a registry
for compliance-namespace tokens. Initially, the registry contains
the following tokens:
"RFC" Compliance is with an RFC, specified by an RFC number.
For example, "rfc=1945".
rfc-option-item = "RFC" "=" RFC-number
RFC-number = 1*DIGIT
Leading zeroes are permitted and ignored in
RFC-number (i.e., comparisons are numeric).
"HDR" Compliance is with a named HTTP header. For example,
"HDR=Authorization". There is no IANA registry for
HTTP header names, but to avoid potential namespace
confusion, only those HTTP headers listed in an
IETF standards-track document should be used in
this namespace.
hdr-option-item = "HDR" "=" field-name
An implementation SHOULD NOT send option-param values other
than "cond" or "uncond" with an rfc-option-item or a
hdr-option-item.
The option-param is used to provide additional parameters.
Unconditional compliance with a compliance-option is indicated
using the "uncond" option-param; for example, "rfc=1945;uncond".
Conditional compliance is indicated using the "cond" option-param;
for example, "HDR=Authorization;uncond". Additional option-param
values might be defined as part of another specification.
For the purposes of this header field, an implementation that
satisfies all the MUST and all the SHOULD requirements for its
protocols is defined as "unconditionally compliant"; one that
satisfies all the MUST requirements but not all the SHOULD
requirements for its protocols is defined as "conditionally
compliant." See also RFC2119 for a discussion of the terms MUST
and SHOULD.
Examples:
Compliance: rfc=2068;uncond
Compliance: rfc=1945;uncond, rfc=2068;cond
Compliance: rfc=2068, hdr=SetCookie2
Mogul, Cohen, Lawrence [Page 8]
Internet-Draft HTTP OPTIONS messages 26 August 1997 17:58
Note: when a resource is implemented using a subprogram
outside the control of the server itself (such as a CGI
application), and the server cannot ensure that this
implementation of the resource will comply with a requested
option, the server's Compliance response-header for the
resource ought not to assert compliance with the option.
That is, in case of uncertainty, it is better to imply
non-compliance when the implementation might comply, than
to claim compliance when the implementation might not comply.
3.5 The Non-Compliance header
Insert in section 14, as a new subsection titled ``14.QQQ
Non-Compliance''
A proxy server SHOULD add this response-header to a response
containing a Compliance header if the proxy does not implement one
or more of the options described in the Compliance header.
Non-Compliance = "Non-Compliance" ":" 1#non-compliance-option
proxy-host = host [ ":" port ]
non-compliance-option = compliance-option "@" proxy-host
Mogul, Cohen, Lawrence [Page 9]
Internet-Draft HTTP OPTIONS messages 26 August 1997 17:58
A non-compliance-option listed in a Non-Compliance response-header
field indicates that the proxy server named by the proxy-host value
does not support the listed compliance-option. The set of
non-compliance options SHOULD be a subset of the compliance-options
listed in a Compliance header field of the forwarded message.
Note: because the proxy-host value is not authenticated,
this is only for advisory purposes (e.g., for debugging).
If the compliance-option in a non-compliance-option includes one or
more option-param(s) (see section 14.ZZZ), then the proxy server's
non-compliance is limited to the scope of the option-param(s). If
the compliance-option does not include an option-param, then the
proxy server is asserting non-compliance with the option in
general.
For example, a response with:
Compliance: rfc=9999;uncond
Non-Compliance: rfc=9999;uncond@proxy.foo.net
states that proxy.foo.net is not unconditionally compliant with
RFC9999, but does not imply that proxy.foo.net is not
conditionally compliant with RFC9999. If the proxy is not even
conditionally compliant with RFC9999, it should instead send
Compliance: rfc=9999;uncond
Non-Compliance: rfc=9999@proxy.foo.net
when forwarding the response.
A proxy MUST NOT delete a Non-Compliance header that it has
received from another server.
3.6 Changes to sections 14.7 and 14.35, Allow and Public
The problem we address here is that RFC2068's specifications for the
Allow and Public headers are inconsistent as to whether a proxy
"MUST" or "MUST NOT" edit them. We believe that they should be
consistent. Given that, there are arguments for either alternative:
- Requiring proxies to edit these headers provides the
ultimate client with a simple way to determine if a method
is allowed along the entire path to the origin server.
- However, requiring proxies not to edit these headers allows
a client to find out about the capabilities of the origin
server, since (as RFC2068 says about the Allow header) "the
user agent may have other means of communicating with the
origin server."
The second alternative seems more robust. Although we do not
Mogul, Cohen, Lawrence [Page 10]
Internet-Draft HTTP OPTIONS messages 26 August 1997 17:58
currently have an efficient mechanism for finding out if a method is
supported along the entire path, presumbly any request using an
unsupported method would immediately be rejected. However, we list
both alternatives in the hope that further discussion will lead to a
more satisfying solution.
Note: one possibility, not yet explored in detail, is that the
compliance-namespace could be extended to include a "METH"
token, allowing the Compliance header (and hence the
Non-Compliance header) to completely replace the Allow and
Public headers. E.g., the client could send
Compliance: METH=*
to which the origin server might respond
Compliance: METH=GET,METH=PUT,METH=HEAD
If this passes through a proxy that bans (e.g.) PUT, the proxy
could forward the response as
Compliance: METH=GET,METH=PUT,METH=HEAD
Non-Compliance: METH=PUT@roproxy.net
3.6.1 Alternative A: proxies MUST NOT modify Allow/Public
In section 14.35 (Public), replace
This header field applies only to the server directly connected to
the client (i.e., the nearest neighbor in a chain of connections).
If the response passes through a proxy, the proxy MUST either remove
the Public header field or replace it with one applicable to its own
capabilities.
with:
A proxy MUST NOT modify the Public header field even if it does not
understand all the methods specified, since the user agent might
have other means of communicating with the origin server.
Also, in section 14.7 (Allow), replace
A proxy MUST NOT modify the Allow header field even if it does not
understand all the methods specified, since the user agent MAY have
other means of communicating with the origin server.
with:
A proxy MUST NOT modify the Allow header field even if it does not
understand all the methods specified, since the user agent might
have other means of communicating with the origin server.
(removes an incorrect use of the term "MAY").
Mogul, Cohen, Lawrence [Page 11]
Internet-Draft HTTP OPTIONS messages 26 August 1997 17:58
3.6.2 Alternative B: proxies MUST modify Allow/Public
In section 14.7 (Allow), replace
A proxy MUST NOT modify the Allow header field even if it does not
understand all the methods specified, since the user agent MAY have
other means of communicating with the origin server.
with:
A proxy MUST remove methods from an Allow header field if it
does not support the use of those methods for the resource
identified by the Request-URI.
and in section 14.35 (Public), replace this paragraph:
This header field applies only to the server directly connected to
the client (i.e., the nearest neighbor in a chain of connections).
If the response passes through a proxy, the proxy MUST either remove
the Public header field or replace it with one applicable to its own
capabilities.
with:
A proxy MUST remove methods from a Public header field if it
does not support the use of those methods.
3.7 Examples
To list all extensions supported by proxy "proxy4.example.com"
Client sends:
OPTIONS * HTTP/1.1
Host: proxy4.example.com
Compliance: *
proxy4.example.com responds:
HTTP/1.1 200 OK
Date: Tue, 22 Jul 1997 20:21:51 GMT
Server: SuperProxy/1.0
Public: OPTIONS, GET, HEAD, PUT, POST, TRACE
Compliance: rfc=1543, rfc=2068, hdr=set-proxy
Compliance: hdr=wonder-bar-http-widget-set
Content-Length: 0
Mogul, Cohen, Lawrence [Page 12]
Internet-Draft HTTP OPTIONS messages 26 August 1997 17:58
Probing for a feature which is not supported by
"proxy4.example.com"
Client sends:
OPTIONS * HTTP/1.1
Host: proxy4.example.com
Compliance: HDR=TimeTravel
proxy4.example.com responds:
HTTP/1.1 200 OK
Date: Tue, 22 Jul 1997 20:21:52 GMT
Server: SuperProxy/1.0
Public: OPTIONS, GET, HEAD, PUT, POST, TRACE
Compliance:
Content-Length: 0
4 Security Considerations
Because the proxy-host value in a Non-Compliance header is not
authenticated, in theory, a malicious proxy along the path could
insert a Non-Compliance header with the name of some other proxy,
perhaps one not even involved in the response. However, because the
proxy-host value is used only for advisory purposes (e.g., for
debugging), there does not appear to be a serious security problem
with this lack of authentication.
Besides, any proxy along the request/response path for an HTTP
interaction is able to perform far more disruptive (and far less
easily detected) modifications of the messages it forwards; this
proposal does not change that.
5 Acknowledgements
We would like to thank Roy Fielding, Jim Gettys, Paul Leach, Larry
Masinter, Henrik Frystyk Nielsen, Ross Patterson, and Jim Whitehead
for help in constructing this proposal.
6 References
1. D. Connolly, R. Khare, H. Frystyk Nielsen. PEP - an Extension
Mechanism for HTTP. Internet Draft draft-ietf-http-pep-04, HTTP
Working Group, July, 1997. This is a work in progress.
2. Roy T. Fielding, Jim Gettys, Jeffrey C. Mogul, Henrik Frystyk
Nielsen, and Tim Berners-Lee. Hypertext Transfer Protocol --
HTTP/1.1. RFC 2068, HTTP Working Group, January, 1997.
Mogul, Cohen, Lawrence [Page 13]
Internet-Draft HTTP OPTIONS messages 26 August 1997 17:58
7 Authors' addresses
Jeffrey C. Mogul
Western Research Laboratory
Digital Equipment Corporation
250 University Avenue
Palo Alto, California, 94305, USA
Email: mogul@wrl.dec.com
Josh Cohen
Netscape Communications Corporation
501 E. Middlefield Rd
Mountain View, CA 94043
Phone (415) 937-4157
EMail: josh@netscape.com
Scott Lawrence
Agranat Systems, Inc.
1345 Main St.
Waltham, MA 02154
Phone: +1-617-893-7868
Fax: +1-617-893-5740
Email: lawrence@agranat.com
Mogul, Cohen, Lawrence [Page 14]
