HTTP Working Group H. Frystyk Internet Draft W3C April 1997 PEP - an Extension Mechanism for HTTP 1. Status of this Document 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). This document is also available as a W3C Working Draft. The most recent release is available at http://www.w3.org/pub/WWW/TR/WD-http- pep. 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 http://www.ics.uci.edu/pub/ietf/http/. The editor maintains background information about PEP at http://www.w3.org/pub/WWW/Protocols/PEP/ The contribution of World Wide Web Consortium staff time to the HTTP working group is part of the W3C HTTP Activity. Frystyk W3C Working Draft [Page 1] WD-pep PEP $Date: 1997/04/28 02:58:33 $ 2. Abstract HTTP is used increasingly in applications that need more facilities than the standard version of the protocol provides, from distributed authoring, collaboration and printing, to various remote procedure call mechanisms. The Protocol Extension Protocol (PEP) is an extension mechanism designed to address the tension between private agreement and public specification and to accommodate extension of HTTP clients and servers by software components. The PEP mechanism is to associate each extension with a URI, and use a few new header fields to carry the extension identifier and related information from HTTP clients, through proxies and intermediaries, to servers, and back again. The kind of extensions capable of being introduced by PEP are envisioned as ranging from: * a simple qualification of a normal HTTP transaction; * changes to HTTP semantics; * new HTTP syntax, encoding or marshaling; * initiation of HTTP-based protocols for new applications; to... * protocols, which once initiated by a PEP transaction, run completely independently of HTTP. PEP interacts with specific features of HTTP/1.1 [RFC2068] including scoping rules and cache semantics. PEP is intended to be compatible with HTTP/1.0 [RFC1945] inasmuch as HTTP/1.1 is compatible with HTTP/1.0, see [RFC2068], Section 19.7. It is proposed that the PEP extension mechanism is included in future versions of HTTP. 3. Contents 1. Status of this Document ........................................ 1 2. Abstract ....................................................... 2 3. Contents ....................................................... 2 4. Introduction ................................................... 3 4.1. Purpose ................................................... 4 4.2. Operational Overview ...................................... 4 5. Notational Conventions ......................................... 6 5.1. Bag Syntax ................................................ 6 6. Extension Declarations ......................................... 6 6.1. Header Field Mappings ..................................... 7 6.2. Unmapping Header Fields ................................... 8 6.3. Extra Parameters ......................................... 9 6.4. Strength .................................................. 9 6.5. End-to-End Extensions .................................... 10 6.6. Hop-by-Hop Extensions .................................... 10 7. Binding HTTP Requests ......................................... 11 8. Extension Policy Information .................................. 12 8.1. End to End Policies ...................................... 13 8.2. Hop by Hop Policies ...................................... 13 9. Status Codes .................................................. 14 Frystyk W3C Working Draft [Page 2] WD-pep PEP $Date: 1997/04/28 02:58:33 $ 9.1. 420 Bad Extensions ....................................... 14 9.2. 421 Bad Mapping .......................................... 14 10. Proxy Servers as End to End Recipients ....................... 15 10.1. Proxy Servers Acting on Behalf of User Agents ........... 15 10.2. Proxy Servers Acting on Behalf of Origin Servers ........ 15 11. Practical Considerations ..................................... 16 11.1. Publishing an Extension ................................. 16 11.2. Interaction with Existing HTTP/1.1 Headers .............. 16 11.3. Identifying the Source of a Mapping ..................... 18 12. Security Considerations ...................................... 18 13. Normative References ......................................... 19 14. Bibliography: Informative References ......................... 20 15. Acknowledgements ............................................. 21 16. Authors Addresses ............................................ 22 17. Summary of Protocol Interactions ............................. 22 18. Open Issues .................................................. 23 4. Introduction HTTP is a generic request-response protocol, designed to accommodate a variety of applications, from network information retrieval and searching to file transfer and repository access to query and forms processing. The agents in an HTTP transaction are a client and a server, which send HTTP messages to each other, with intermediaries between them in some cases. However, semantically, an HTTP transaction is between a client party (for example, the referent of the From: header field) and a principal responsible for the publication of a given resource. The publishing party is the one responsible for the service provided at any particular URI, for example, the mapping between the URI and any representation of the resource to which it refers. Exactly who takes this role is beyond the scope of this document, but for example, it may be the writer of a document, the server administrator, the organization running the server, or a combination of these. HTTP is used increasingly in applications that need more facilities than the standard version of the protocol provides, from distributed authoring, collaboration and printing, to various remote procedure call mechanisms. Many of these applications do not require agreement across the whole Internet about the extended facilities; rather, it suffices: * That conforming HTTP peers supporting a particular protocol extension or feature should be able to employ this in real time with no prior agreement; * That the extended HTTP protocol to the extend possible should be able to work through HTTP proxies - especially caching proxies; * That it should be possible for one party having a capability Frystyk W3C Working Draft [Page 3] WD-pep PEP $Date: 1997/04/28 02:58:33 $ for a new protocol to require that the other party either understand and abide by the new protocol or abort the operation; * That negotiation of matching capabilities should be possible. The need for extensibility creates a tension between dynamically extensible applications and public, static specification. 4.1. Purpose The Protocol Extension Protocol (PEP) is an extension mechanism for HTTP/1.1 designed to accommodate dynamic extensions of HTTP clients and servers by software components and to address the tension between private agreement and public specification. The kind of extension s capable of being introduced by PEP are envisioned as ranging from: * a simple qualification of a normal HTTP transaction; * changes to HTTP semantics; * new HTTP syntax, encoding or marshaling; * initiation of HTTP-based protocols for new applications; to... * protocols, which once initiated by a PEP transaction, run completely independently of HTTP. This document defines the HTTP extension mechanism referred to as "PEP". The PEP design is the result of analyzing a variety of HTTP extensions and extension mechanisms, and the motivation behind them. PEP interacts with specific parts of HTTP/1.1 including scoping rules and cache semantics and is intended to be compatible with HTTP/1.0 inasmuch as HTTP/1.1 is compatible with HTTP/1.0 (see section "Considerations for Defining Extensions"). It is proposed that the PEP extension mechanism is included in future versions of HTTP. 4.2. Operational Overview PEP allows applications to employ extensions dynamically by providing a mechanism for mapping the global definition of an extension to its local representation in a particular transaction. The local representation does not have to be globally unique and can be defined on the fly by the parties involved. The mapping is furthermore assigned a strength and a scope describing the requirements for interacting with the extension. This allows an application to require that another party either obeys the rules given by the extension or aborts the transaction. PEP is intended to be used as follows: Frystyk W3C Working Draft [Page 4] WD-pep PEP $Date: 1997/04/28 02:58:33 $ * Some party designs and specifies an extension to HTTP; the party assigns the extension an identifier, which is a URI, and makes one or more representations of the extension available at that address. * An HTTP/1.1 and PEP compliant application knows about that extension and wishes to use it in one or more transactions. The application can either have an a priori knowledge about the extension or may learn about it as a result of interacting with other PEP enabled applications. * The application declares the use of the extension by referencing its URI in PEP extended HTTP requests and responses. If the extension becomes ubiquitous, a new version of the HTTP specification can include the extension, and messages can declare use of the new HTTP version instead of the extension. The PEP mechanism is designed to accommodate dynamic extension of clients, servers, and proxies by software components as follows: * Clients and servers are implemented with software component interfaces that allow dynamic installation of extension facilities. * An extension is assigned a URI; in addition to a human- readable specification of an extension, a machine-readable implementation or description of the extension is published at that address. * If a message that refers to an extension is received by a party that has no awareness of the extension, the receiver can dereference the extension's identifier and dynamically load support for the extended facility. The advantage of the self-describing data model used by PEP is that at the cost of some extra bytes to spell out the URI in full, the use of a central registry of extension names is avoided. PEP can also be used to extend applications to support centrally registered extensions as long as a URI is published as part of the registration. The representation and implementation of dynamic extensible software component interfaces is outside the scope of this specification (see section "Publishing an Extension (Section 11.1)"). Frystyk W3C Working Draft [Page 5] WD-pep PEP $Date: 1997/04/28 02:58:33 $ 5. Notational Conventions This specification uses the same notational conventions and basic parsing constructs as RFC 2068 [RFC2068]. In particular the BFN constructs "token", "quoted-string", "URI", and "delta-seconds" in this document are to be interpreted as described in RFC 2068 [RFC2068]. 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 RFC 2119 [RFC2119]. PEP does not rely on particular features defined in URLs that cannot potentially be expressed using URNs, see section "Publishing an Extension (Section 11.1)". Therefore, the more generic term "URI" is used throughout this specification. 5.1. Bag Syntax The bag syntax uses braces to delimit an attribute-value bag, which may consist of a set, list, or recursively defined tokens and quoted strings. The bag semantics are defined by its context and the bag name, which may be a URI in some fields. The BNF for the bag syntax is as follows: bag = "{" bagname *bagitem "}" bagname = token bagitem = bag | token | quoted-string | <"> URI <"> Unless explicitly stated otherwise, all tokens within a bag are case-insensitive. Comments as defined by RFC 822 [RFC822] indicated by surrounding the comment text with parentheses MUST NOT be used within a bag construct. 6. Extension Declarations Clients and proxies can initiate a new instance or terminate an existing instance of an extension by issuing an extension declaration as part of a request. The declaration can be intended for one or more other agents depending on the scope of the declaration, see section "End-to-End Extensions (Section 6.5)" and "Hop-by-Hop Extensions (Section 6.6)", and either may or must be accepted depending on the strength, see section "Strength (Section 6.4)". The grammar for an extension declaration is as follows: Frystyk W3C Working Draft [Page 6] WD-pep PEP $Date: 1997/04/28 02:58:33 $ ext-decl = "{" required-decl *optional-decl "}" required-decl = ( map [ strength ] ) | unmap optional-decl = parameters | attribute-ext map = "{" "map" <"> absoluteURI <"> 1#(header-wildcard) "}" unmap = "{" "unmap" 1#(header-wildcard) "}" strength = "{" "strength" ( "must" | "may" "}" parameters = "{" "params" *bagitem "}" attribute-ext = bag header-wildcard = field-name [ wildcard ] wildcard = "*" In many ways, an extension declaration is equivalent to calling either the constructor or destructor of the class representing the extension. The map attribute is equivalent to the constructor and the unmap attribute is equivalent to the destructor. Additional information can be passed using either of the following three mechanisms: * Construction and destruction parameters for an extension instance can be passed using the parameters attribute, see section "Extra Parameters" (Section 6.3); * Extension instance data can be passed using the header fields (header-wildcard) mapped by the map attribute, see section "Header Field Mappings" (Section 6.1); * Extensions to the PEP engine itself can be passed using the attribute-ext attribute. Unrecognized extension declaration attributes (attribute-ext) MUST be ignored; it is assumed that any unrecognized attributes will be combined with standard attributes such that the application behavior will remain minimally correct even if it does not understand the extension attribute(s). If neither a map nor an unmap attribute is present in an extension declaration, the server SHOULD respond with 400 (Bad Request). 6.1. Header Field Mappings The map attribute can be used to declare a new instance of an extension. The map attribute defines a mapping between a resource describing the syntax and semantics of the extension and a set of header fields representing this instance of the extension. The resource is identified by a URI which MAY be resolved dynamically by either of the parties using the extension, see section "Bootstrapping and Dynamic Loading". A header-wildcard can either be a single header field or a header field prefix. A header field prefix is indicated using a Frystyk W3C Working Draft [Page 7] WD-pep PEP $Date: 1997/04/28 02:58:33 $ terminating wildcard and can be used to describe that all header fields with this prefix are part of this instance of the extension. Linear white space (LWS) MUST NOT be used between the field-name and the wildcard (if any) and all header-wildcard values are case-insensitive. Clients SHOULD NOT overload well-known or widely deployed header fields with new semantics unless the new semantics are a superset of the existing semantics so that the header fields still can be interpreted according to the old semantics. Clients MUST not reuse already mapped header fields in new extension declarations. If the server finds that a header field is already mapped by another extension instance initiated by the same client, it MUST respond with a 421 (Bad Mapping) status code. Proxies initiating new extension instances MUST make sure that the header fields introduced by the map attribute does not conflict with header fields already mapped by user-agents or previous proxies taking part in a proxy chain. 6.2. Unmapping Header Fields When a mapping has been declared, the mapped header fields can be used to convey information according to the syntax and semantics of the extension described by the URI. A mapping can be valid for zero, one, or more transactions depending on the extension and the agreement between the involved parties. Specifically, a mapping is valid until one of the following events occur: * The header fields are unmapped by the client issuing a request containing an extension declaration with the unmap attribute, or * the header fields are unmapped by the server issuing a 421 (Bad Mapping) response. This rule allows PEP aware applications to maintain long-lived mappings without relying on global, persistent state, see section "PEP - an Extension Mechanism for HTTP (Section 11.3)". At the cost of one additional transaction, PEP aware applications can always jump to a single well-known state describing which extension instances are currently mapped, see section "Binding Requests" for how this rule interacts with existing HTTP applications. The unmap attribute can be used to indicate that the mapping between a URI and one or more header-wildcards has terminated and the semantics described by the URI no longer are valid for these header fields. Unmapped header fields SHOULD be treated as unknown headers and ignored by the recipient and forwarded by proxies. Applications MAY reuse unmapped header fields in future mappings if they have been redeclared using the map attribute. Frystyk W3C Working Draft [Page 8] WD-pep PEP $Date: 1997/04/28 02:58:33 $ There does not have to be a 1:1 relationship between a set of header fields used by the map attribute and the set used by the unmap attribute. This allows the unmap attribute to unmap subparts of an extension instance or potentially multiple extension instances. A client SHOULD only attempt to unmap header fields that it has initiated itself. Unmapping extension instances initiated by others may cause an extra transaction to happen in order to reach a shared state. A server MUST always accept a client's request for unmapping a set of header fields. If a client in a request unmaps header fields in use by extensions required for accessing that resource, the server MUST respond with 420 (Bad Extensions). 6.3. Extra Parameters The parameters attribute can be used to pass additional parameters to the construction or destruction of the extension instance. The params values may or may not be case-sensitive, depending on the semantics of the parameter name. No default parameters are defined. Note: Server implementations should pass any extra parameters to the module or modules handling a particular extension as this may have significant impact on the success of the transaction. 6.4. Strength The strength attribute can be used to specify how the ultimate recipient MUST handle the extension instance declared using the map attribute. The strength indicates whether this instance is required (must) or optional (may) for the transaction to succeed. If the strength is "must", the ultimate recipient of the extension declaration MUST consult and adhere to the relevant extension specification(s) before executing the transaction or respond with 420 (Bad Extensions), see section "Binding Requests" for how to interact with existing HTTP applications. Not accepting an extension instance is different from not accepting a mapping proposed by the map attribute. If the server cannot accept a mapping, for example if a header field is already mapped by another extension instance, it MUST respond with a 421 (Bad Mapping) status code, see section "421 Bad Mapping (Section 9.2)". If the strength is "may" the ultimate recipient of the extension MAY consult and adhere to the relevant extension specification(s) before executing the transaction or ignore the extension completely. If no strength attribute is present, the default strength is "may". A client cannot distinguish whether a server does not understand an extension or does not want to initiate an extension instance of strength "may". Frystyk W3C Working Draft [Page 9] WD-pep PEP $Date: 1997/04/28 02:58:33 $ 6.5. End-to-End Extensions For the purpose of defining the behavior of caches and non-caching proxies, PEP extensions are divided into two categories: End-to- end extensions and hop-by-hop extensions. The PEP header is an end-to-end request-header and is defined as follows: pep = "PEP" ":" 1#ext-decl For example GET / HTTP/1.1 Host: some.host PEP: {{map "http://www.w3.org/ext/end-to-end" Ext-1} {params x y z}} End-to-end extensions MUST be transmitted to the ultimate recipient of a request, see section "Proxy Servers as End to End Recipients". If multiple end-to-end extensions have been declared for a transaction, the extensions MUST be listed in the order in which they were applied. 6.6. Hop-by-Hop Extensions Hop-by-hop extensions are meaningful only for a single transport- level connection. The C-PEP header allows the sender to specify hop-by-hop extensions and MUST NOT be communicated by proxies over further connections. The C-PEP header has the following grammar: c-pep = "C-PEP" ":" 1#ext-decl The C-PEP header uses the Connection header so that existing HTTP/1.1 applications can filter the information out appropriately. For example GET / HTTP/1.1 Host: some.host Ext-1: bar C-PEP: {{map "http://www.w3.org/ext/my-extension" Ext-1} {params x y z}} Connection: C-PEP, Ext-1 If multiple hop-by-hop extensions been declared for a transaction, the extensions MUST be listed in the order in which they were applied. C-PEP extensions MUST be executed before any end-to-end extensions. The C-PEP header MUST always be protected by a Connection header in a request by including C-PEP as a Connection header directive. The directive MUST be handled according to the HTTP/1.1 Frystyk W3C Working Draft [Page 10] WD-pep PEP $Date: 1997/04/28 02:58:33 $ specification of the Connection header. A client MUST NOT send the C-PEP header field to an HTTP/1.0 proxy as it does not obey the rules of HTTP/1.1 for parsing the Connection header field, see also [RFC2068], section 19.7.1. 7. Binding HTTP Requests If any extension in an HTTP request is of strength "must", the transaction MUST NOT succeed without consulting and adhering to the relevant extension specification(s). We call such a request for "binding". In [RFC2068], Section 7.1 it is stated that "Unrecognized header fields SHOULD be ignored by the recipient and forwarded by proxies." Hence, using a PEP or a C-PEP extension declaration is not sufficient to evoke the correct behavior from existing HTTP agents. However, in [RFC2068], Section 5.1.1, Method, it is indicated that "Servers SHOULD return the status code 405 (Method Not Allowed) if the method is known by the server but not allowed for the requested resource, and 501 (Not Implemented) if the method is unrecognized or not implemented by the server." A similar statement is made in [RFC1945], Section 9.5. Therefore, PEP uses the request method to provide a binding mechanism for handling a binding HTTP request. The method name of all HTTP requests containing a PEP extension of strength "must" MUST be prefixed by "PEP-". The "PEP-" prefix is reserved by PEP and MUST NOT be used by other HTTP extensions. PEP- aware applications MUST prior to processing a binding HTTP request remove the "PEP-" prefix from the method name leaving the rest of the HTTP request as is. For example, a client might express the binding rights-management constraints in an HTTP request as follows: PEP-PUT /a-resource HTTP/1.1 PEP: {{map "http://some.org/rights-management" my-rights-*} {strength must} {params {copyright-remains-with-client} {nonexclusive-right-to-redistribute}} Host: some.host Content-Length: 1203 Content-Type: text/html absoluteURI <"> "}" for = "{" "for" #URI-wildcard "}" max-age = "{" "max-age" delta-seconds "}" URI-wildcard = <"> URI <"> [ wildcard ] The id attribute specifies the URI identifying the extension. The URI MAY be resolved dynamically by either of the parties using the extension (see section "Bootstrapping and Dynamic Loading"). The id attribute differs from the map attribute in that no header fields are associated with the URI. If no id attribute is present in an extension policy, the client SHOULD ignore it. The for attribute specifies the URI (or set of URIs) to which the policy declaration applies. A URI followed by a wildcard represents the set of URIs that contains the given URI as a prefix. A linear white space (LWS) MUST be used between the URI and the wildcard (if any). In case a for attribute does not appear, the default value is the Request-URI of the transaction. An empty for value indicates that the extension is not used by any resource. Policy declarations are unordered and can contain information about any number of resources. Servers MAY specify an explicit expiration time for a policy declaration using the max-age attribute. The max-age attribute indicates that the information SHOULD no longer be used if the age is greater than the specified time in seconds, see HTTP/1.1, Section 13.2.3 for how to calculate the age. An expiration time cannot be used to force a client to discard the information or reload a resource; its semantics apply only to caching of policy information. If the URI is a relative URI, the URI is interpreted relative to any Content-Base URI provided in the response. If no Content-Base is Frystyk W3C Working Draft [Page 12] WD-pep PEP $Date: 1997/04/28 02:58:33 $ provided, the relative URI is interpreted relative to the Request- URI. Examples of URI-wildcards are {for "http://www.w3.org" *} {for "http://www.w3.org/pub/" *} {for "secret/Overview.html"} Unrecognized extension policy attributes MUST be ignored; it is assumed that any unrecognized attributes will be combined with standard attributes such that the application behavior will remain minimally correct even if it does not understand the attribute(s). 8.1. End to End Policies As for extension declarations, extension policies are divided into two categories: End-to-end policies and hop-by-hop policies. The PEP-Info header expresses the end-to-end policies and is defined as follows: pep-info = "PEP-Info" ":" 1#policy-decl For example HTTP/1.1 200 OK Content-Type: text/html Content-Length: 250 PEP-Info: {{id "http://some.org/payment-extension"} {for "/cgi-bin/buy" *} {strength must}}
... End-to-end policies MUST be transmitted to the ultimate recipient of a response, see section "Proxy Servers as End to End Recipients". 8.2. Hop by Hop Policies Hop-by-hop policies are meaningful only for a single transport- level connection. The C-PEP-Info header allows the sender to specify hop-by-hop policies and MUST NOT be communicated by proxies over further connections. The C-PEP-Info header has the following grammar: c-pep-info = "C-PEP-Info" ":" 1#policy-decl For example Frystyk W3C Working Draft [Page 13] WD-pep PEP $Date: 1997/04/28 02:58:33 $ HTTP/1.1 420 Bad Extensions C-PEP-Info: {{id "http://some.org/provide-stats"} {for "/" *}} Connection: C-PEP-Info ... The C-PEP-Info header MUST always be protected by a Connection header in a response by including C-PEP-Info as a Connection header directive. The directive MUST be handled according to the HTTP/1.1 specification of the Connection header. A server MUST NOT send the C-PEP-Info header field to an HTTP/1.0 proxy as it does not obey the rules of HTTP/1.1 for parsing the Connection header field, see also [RFC2068], section 19.7.1. 9. Status Codes PEP adds two new status codes to be added to the set already defined by HTTP/1.1 [RFC2068]. Each Status-Code is described below, including a description the metainformation required in the response. 9.1. 420 Bad Extensions The policy for accessing the resource has not been met in the request. The response MUST include a PEP-Info header field specifying the extensions required by the publishing party for accessing the resource. The server MAY also include policy information for other resources using the for attribute and optional extensions specified having a strength of "may". The client MAY repeat the request using the appropriate extension(s) if it believes that it can fulfill the policy. If the initial request already included all the extensions requested in the 420 response with the appropriate set of extra parameters (if any), then the 420 response indicates that access has been refused for any additional extension(s) requested by the client. If no extension(s) have been requested by the client, then the user MAY be presented the entity that was given in the response (if any), since that entity may include relevant diagnostic information. Implementers may note the similarity to the way authentication challenges are issued with the 401 (Unauthorized) status code. 9.2. 421 Bad Mapping The mappings indicated by the map attribute in the request were refused. If the initial request contained a change to the current set of mappings using the "map" attribute then this change was refused but other mappings are still valid. The client MAY repeat the request using a new set of header fields if it believes that it can find a unique set of header fields for the mapping to Frystyk W3C Working Draft [Page 14] WD-pep PEP $Date: 1997/04/28 02:58:33 $ succeed. If the initial request did not indicate any changes to the current set of mappings, then all mappings currently held by the client MUST be discarded. 10. Proxy Servers as End to End Recipients Normally, the ultimate recipients of an end-to-end extension declaration and extension policies are the origin server and the user agent participating in the extension. In some cases, however, intermediate caching and non-caching proxies MAY act authoritatively on behalf of user agents and origin servers. Note, that regardless of the role of the proxy, it MUST always obey the cache directives indicated by the cache-control directive, see also section "Interaction with Existing HTTP/1.1 Headers (Section 11.2)". 10.1. Proxy Servers Acting on Behalf of User Agents In case a proxy is authorized to act as the ultimate recipient on behalf of its proxy clients on end-to-end extensions, it MUST obey the following rules: * The proxy MUST remove the extension policies on which it can act authoritatively before forwarding the response to a proxy client; * it SHOULD issue extension declarations for the extensions on which it can act authoritatively as if it was a user agent; * it MUST remove any header fields that are part of the extension(s) initiated by the proxy before forwarding the response to a proxy client; * if any extension(s) added by an HTTP proxy are of strength "must" it MUST prepend the "PEP-" method name prefix, before forwarding the response to the origin server, see section "Binding Requests". This can for example be the case if an elementary school wishes to enforce a certain policy for accessing information on the Internet. The local school proxy can then act authoritatively on behalf of the pupils using the proxy. 10.2. Proxy Servers Acting on Behalf of Origin Servers In case a proxy is authorized to act as the ultimate recipient on behalf of an origin server on end-to-end extensions, it MUST obey the following rules: * The proxy MUST remove the extension declarations on which it can act authoritatively before forwarding the request to the origin server; * it SHOULD issue extension policies for the extensions on which it can act authoritatively as if it was an origin server; * it MUST remove any header fields that are part of the Frystyk W3C Working Draft [Page 15] WD-pep PEP $Date: 1997/04/28 02:58:33 $ extension(s) initiated by the proxy before forwarding the request to the origin server; * if any extension(s) added by an HTTP proxy are of strength "must" and there are no other extensions of strength "must" in the request, it MUST remove any "PEP-" method name prefix before forwarding the request to the origin server, see section "Binding Requests". An example of this is a corporation having a subscription on an on-line journal. All access to the origin server goes through the corporate firewall that runs a caching proxy server. The organization reports to the publisher of the journal on a monthly basis at which point the subscription is re-evaluated. In the day-to-day access, the proxy has the authority to act on behalf of the origin server registering usage of the journal. 11. Practical Considerations 11.1. Publishing an Extension While the protocol extension definition should be published at the address of the extension identifier, this is not a requirement of the PEP protocol. The only absolute requirement is that distinct names be used for distinct semantics. For example, one way to achieve this is to use a mid, cid, or uuid URI. The association between the extension identifier and the specification might be made by distributing a specification, which references the extension identifier. Care should be taken not to distribute conflicting specifications that reference the same name. Even when a URI is used to publish extension specifications, care must be taken that the specification made available at that address does not change significantly over time. One agent may associate the identifier with the old semantics, and another might associate it with the new semantics. The extension definition may be made available in different representations. For example, a software component that implements the specification may reside at the same address as a human-readable specification (distinguished by content negotiation). The human-readable representation serves to document the extension and encourage deployment, while the software component allows clients and servers to be dynamically extended. 11.2. Interaction with Existing HTTP/1.1 Headers Designers of extensions to be used within the HTTP messaging model should consider the interaction with existing HTTP/1.1 headers. Especially, it should be noted that PEP is designed to be compatible with HTTP/1.0 [RFC1945] inasmuch as HTTP/1.1 is Frystyk W3C Working Draft [Page 16] WD-pep PEP $Date: 1997/04/28 02:58:33 $ compatible with HTTP/1.0, see [RFC2068], Section 19.7. There are two specific categories of HTTP/1.1 headers that are of special importance to PEP extensions: The HTTP/1.1 caching headers and headers used by existing extension mechanisms provided by HTTP/1.1. This section discusses some of the issues regarding these two categories. The Cache-Control header as described in [RFC2068], Section 14.9, allows a client or server to transmit a variety of directives in either requests or responses with the purpose of overriding the default caching algorithms performed by HTTP/1.1 caches. Regardless of whether any PEP headers are used as cache-control directives, PEP-aware proxies MUST always obey the cache-control directives. The Vary header, described in [RFC2068], Section 14.43, is used by a server to signal that the response entity was selected from the available representations of the response using server-driven negotiation. If either a PEP extension or any header fields used by an extension instance is taking part in a server-driven negotiation, then the server MUST include an appropriate Vary header field with any cachable response that is subject to server-driven negotiation. The Connection header as described in [RFC2068], Section 14.10, allows the sender to specify options that are desired for that particular transport connection only. All PEP hop-by-hop extension and policy declarations along with any header fields used by hop- by-hop extension instances MUST be included as Connection header directives. PEP applications MUST NOT send any hop-by-hop extension or policy declarations to an HTTP/1.0 proxy as it does not obey the rules of HTTP/1.1 for parsing the Connection header field, see also [RFC2068], section 19.7.1. The Upgrade header, [RFC2068], Section 14.41, allows the client to specify what additional communication protocols it supports and would like to use if the server finds it appropriate to switch protocols. PEP supersedes the Upgrade header in that it allows the same functionality but without the need for a central registry. PEP extensions MAY use the 101 (Switching Protocols) status code to switch to HTTP-based protocols and protocols, which once initiated by a PEP transaction, run completely independently of HTTP. The content coding values in the Content-Encoding header as described in [RFC2068], Section 14.12, indicate an encoding transformation that has been or can be applied to an entity. As for the Upgrade header, PEP supersedes the Content-Encoding header in that it allows the same functionality but without the need for a central registry. As both the content encoding mechanism and the PEP mechanism is ordered, using both MAY lead to ambiguous situations. Simultaneous use of both mechanism is therefore Frystyk W3C Working Draft [Page 17] WD-pep PEP $Date: 1997/04/28 02:58:33 $ strongly discouraged. 11.3. Identifying the Source of a Mapping A mapping declared by the map attribute can be valid for zero, one, or more transactions depending on the extension and the agreement between the involved parties. In case a server wishes to maintain a mapping initiated by a client for more than a single transaction, it must be able to link the mapping to the client so that it can use the mapping in future requests initiated by that client. In other words, the server must maintain some sort of state, which uniquely links a mapping to the client initiating that mapping. This requires that the server uniquely can identify a client over the span of multiple, possibly unrelated transactions. A server can identify a client initiating a mapping using one of the following mechanisms (in order of precedence): * a parameter defined by the extension uniquely identifying all requests originating from the client issuing the extension declaration; * a persistent transport connection. This can only the used if the extension has a hop-by-hop scope and the connection is maintained throughout the lifetime of the extension; * an HTTP cookie provided with every request identifying the originating client, see [RFC2069]; * HTTP authentication credentials provided with every request identifying the originating client, see [RFC2068] If none of the above applies then the server MAY look for a From header field in the request. This MUST NOT be considered a reliable mechanism and explicit care SHOULD be taken by the server not to rely on this. 12. Security Considerations * The for parameter allows one party to give information about the extensions used by another party's resources. The parties may provide resources on different servers, or at different addresses on the same server. While distinguishing between the parties responsible for different resources at the same server may be infeasible, clients SHOULD ignore information given by one server about another unless they have reason to trust it, or reason to believe that trusting it will have no significant negative consequences. * Dynamic installation of extension facilities as described in the introduction involves software written by one party (the provider of the implementation) to be executed under the authority of another (the party operating the host software). This opens the host party to a variety of "Trojan horse" attacks by the provider, or a malicious third party that forges Frystyk W3C Working Draft [Page 18] WD-pep PEP $Date: 1997/04/28 02:58:33 $ implementations under a provider's name. See, for example, section 7.4.2 of RFC1521 for a discussion of these risks 13. Normative References [RFC822] D. H. Crocker. "Standard for the Format of ARPA Internet Text Messages", STD 11, RFC 822, UDEL, August 1982 [RFC1630] T. Berners-Lee, "Universal Resource Identifiers in WWW. A Unifying Syntax for the Expression of Names and Addresses of Objects on the Network as used in the World-Wide Web", RFC 1630, CERN, June 1994. [RFC1808] R. Fielding, "Relative Uniform Resource Locators", RFC 1808, UC Irvine, June 1995. [RFC1945] T. Berners-Lee, R. Fielding, H. Frystyk, "Hypertext Transfer Protocol -- HTTP/1.0", RFC 1945, W3C/MIT, UC Irvine, W3C/MIT, May 1996. [RFC2068] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, U.C. Irvine, DEC W3C/MIT, DEC, W3C/MIT, W3C/MIT, January 1997 [RFC2069] D. Kristol, L. Montulli, "HTTP State Management Mechanism", RFC 2069, Bell Laboratories Lucent Technologies, Netscape Communications, February 1997 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, Harvard University, March 1997 [HTTPVer] J. C. Mogul, R. Fielding, J. Gettys, H. Frystyk, "Use and interpretation of HTTP version numbers", Internet Draft draft- ietf-http-versions-01.txt, DEC, U.C. Irvine, DEC W3C/MIT, W3C/MIT, HTTP Working Group, March, 1997. This is work in progress [URL] T. Berners-Lee, R. Fielding, L. Masinter, Uniform Resource Locators (URL), draft-fielding-url-syntax-03, W3C/MIT, U.C. Irvine, Xerox Corporation, December 1996. This is work in progress Frystyk W3C Working Draft [Page 19] WD-pep PEP $Date: 1997/04/28 02:58:33 $ 14. Bibliography: Informative References [CGI] D. Robinson The WWW Common Gateway Interface Version 1.1, work in progress 15 February 1996 [NSAPI] Netscape server API documentation, 1995 [ISAPI] ISAPI documentation, Microsoft Corporation, in ActiveX Alpha SDK, http://www.msn.com/download/sdk/msactivedk.zip, 1996 [Apache] Thau, Robert, Design considerations for the Apache Server API, Fifth International World Wide Web Conference, May 6-10, 1996, Paris, France [OM] OpenMarket server technical overview sometime in 1996. [Spy95] Spyglass Server Application Development Interface Spyglass, Inc. version 1.17 1995/09/11 [MAILCAP] N. Borenstein, RFC 1524: A User Agent Configuration Mechanism For Multimedia Mail Format Information, pp. 12, Sep 1993. [STATE] D. Kristol, L. Montulli, 22 Nov 1996. "HTTP State Management Mechanism", RFC xxxx. Proposed Standard Approved by the IESG, not yet assigned an RFC. [Kristol95] David M. Kristol, A Proposed Extension Mechanism for HTTP, Jan 1995. D. Kristol, A Proposed Extension Mechanism for HTTP, Internet Draft, January 1995 (Work in Progress, Expired). [RFC822] D. H. Crocker. Standard for the Format of ARPA Internet Text Messages. STD 11, RFC 822, UDEL, August 1982. [UPP] D. Eastlake, "Universal Payment Preamble", Internet Draft CyberCash, March 1996 (Work in Progress). [JEPI] JEPI, "Selecting Payment Mechanisms Over HTTP", Internet Draft, August 1996 (Work in Progress). [Also available as http://www.w3.org/pub/WWW/Payments/JEPI/draft-jepi-uppflow- 00.html] Frystyk W3C Working Draft [Page 20] WD-pep PEP $Date: 1997/04/28 02:58:33 $ [MAILEXT] J. Klensin, N. Freed, M. Rose, E. Stefferud, and D. Crocker. "SMTP Service Extensions." RFC 1869. MCI, Innosoft, Dover Beach Consulting, Network Management Associates, Brandenburg Consulting, November 1995. [PICS] J. Miller. PICS Label Syntax and Communication Protocols (Version 1.1). 31 October 1996 [SpyClient] Spyglass Client Software Development Kit [SpyEcom] Electronic Commerce Standards for the WWW [WN] WN server documentation, 1995 [Spinner] Spinner server technical overview, http://spinner.infovav.se/overview.html, 1995 15. Acknowledgements The PEP protocol is the product of a substantial amount of investigation and collaboration. Dave Kristol did some of the first writing on HTTP extension mechanisms. [Kristol95]. Jim Miller and Dave Raggett sketched out an initial design, which Rohit Khare wrote up in a number of drafts. Tim Berners-Lee, Paul Leach and Daniel Dardailler deserve special recognition for their efforts in commenting in the design phase of the protocol. This specification is a direct reflection of some implementation work: a client implementation in Libwww (see the HTPEP module) and a server implementation by Eui-Suk Chung and Anit Chakraborty for the JEPI project. This document has benefited greatly from the comments of all those participating in the HTTP-WG. In addition to those already mentioned, the following individuals have contributed to this specification: * Don Eastlake, * Roy Fielding, * Yaron Goland, * Phill Hallam-Baker, * Paul Hoffman, * Koen Holtman, and * Larry Masinter Frystyk W3C Working Draft [Page 21] WD-pep PEP $Date: 1997/04/28 02:58:33 $ 16. Authors Addresses Dan Connolly Architecture Domain Lead, W3 Consortium MIT Laboratory for Computer Science 545 Technology Square Cambridge, MA 02139, U.S.A. Tel: +1 (512) 310 2971 Email: connolly@w3.org Rohit Khare Technical Staff, W3 Consortium MIT Laboratory for Computer Science 545 Technology Square Cambridge, MA 02139, U.S.A. Tel: +1 (617) 253 5884 Fax: +1 (617) 258 5999 Email: khare@w3.org Henrik Frystyk Nielsen Technical Staff, W3 Consortium MIT Laboratory for Computer Science 545 Technology Square Cambridge, MA 02139, U.S.A. Tel: +1 (617) 258 8143 Fax: +1 (617) 258 5999 Email: frystyk@w3.org Appendices 17. Summary of Protocol Interactions The following table summarizes the outcome of how PEP-aware servers and proxies MUST handle PEP extension declarations. The table also summarized how existing HTTP servers and proxies interact with PEP extension declarations. Note, that applications MUST NOT send hop- by-hop header fields to an HTTP/1.0 proxy as it does not obey the rules of HTTP/1.1 for parsing the Connection header field, see also [RFC2068], section 19.7.1. See also section "Interaction with Existing HTTP/1.1 Headers (Section 11.2)". Pass The proxy MUST pass the extension declaration along to the next agent. Strip The proxy MUST strip the extension declaration out and pass the remainder along to the next agent. Extended processing The agent MUST process the request in conformance with the extension specification. Frystyk W3C Working Draft [Page 22] WD-pep PEP $Date: 1997/04/28 02:58:33 $ Standard processing The agent MUST process the request in the standard, unextended fashion. 420 Bad Extensions The agent MUST report a 420 Bad Extension error Strength / Scope PEP Summary   Hop-by-hop *) End-to-end Optional (may) Required (must) Optional (may) Required (must) Proxy PEP not supported Strip 501 (Not Implemented) Pass 501 (Not Implemented) Extension not supported Strip 420 (Bad Extensions) Pass Pass Extension supported Extended processing Extended processing Extended processing Extended processing Origin Server PEP not supported Standard processing 501 (Not Implemented) Standard processing 501 (Not Implemented) Extension not supported Standard processing 420 (Bad Extensions) Standard processing 420 (Bad Extensions) Extension supported Extended processing extended processing Extended processing Extended processing *) Applications MUST NOT send hop-by-hop header fields to an HTTP/1.0 proxy as it does not obey the rules of HTTP/1.1 for parsing the Connection header field, see also [RFC2068], section 19.7.1. 18. Open Issues Some of the things we have to consider What can be done with Asynchronous Notification? If we take the limited case of having the server sending async notifications on an already established TCP connection then I believe that this is something that PEP needs to be able to support. Frystyk W3C Working Draft [Page 23] WD-pep PEP $Date: 1997/04/28 02:58:33 $ Does Simple PEP fulfill the Original Requirements? I will have to check that further - look at the JEPI requirements. I have done so and believe there are no problems! Transparent Content Negotiation How does this fit with TNC and how can we use a single proposal? Do we need Refused? Note, that this proposal has removed the "strength refused" as I can't find an example where this has to be part of the basic extension mechanism. An extension may not be allowed because of some of the parameters but not the extension itself - this can be an issue with extensions using public keys, for example. Or a certain combination of extensions may not be allowed but not necessarily each of the individual extensions. Another change is that the for list is now a linked list which make it possible to assign metainformation to large set of resources. Do we need the "enc" parameter? There is no reason to make the "enc" parameter/flag distinction in the Protocol header. After we removed the interaction with the content-encoding header, there is nowhere in the protocol message any encoding token may show up. It was only needed while we used the content-encoding header for ordering purposes. The protocol id defines the encoding. Generic Metainformation Syntax It would be nice if we could use some generic meta data mechanism for handling this instead of the PI header. Do Certain Extensions only work for certain Methods? Roy mentioned whether it make sense to have an extension bound not only to a particular URL but also to a particular method. It could be that an extension only is valid for PUT, say, and not GET. I think that we can push this of into the extension itself and don't have to be concerned about it in PEP directly. Proxies as Ultimate Recipient Should a proxy acting on behalf of either an origin server or a user agent issue a warning header? Frystyk W3C Working Draft [Page 24]