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 . Discussions of the working group are archived at . General discussions about HTTP and the applications which use HTTP should take place on the 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]