W3C

Uniform Messaging, Level One

Editor's Draft 19 November 2009

Editors:
Tyler Close (Google)
Mark Miller (Google)

Abstract

This document defines a mechanism to enable requests that are independent of the client's context. Using this mechanism, a client can engage in cross-site messaging without the danger of Cross-Site-Request-Forgery and similar attacks that abuse the cookies and other HTTP headers that form a client's context. For example, code from customer.example.org can use this mechanism to send requests to resources determined by service.example.com without further need to protect the client's context.

Status of this Document

This document is for review by the WebApps Working Group and is subject to change without notice. This document has no formal standing within W3C. Please consult the group's home page and the W3C technical reports index for information about the latest publications by this group.

Table of Contents

1 Introduction

This section is non-normative.

There are two main goals for the mechanism defined by this specification: (A) provide a means for resources to allow cross-origin messaging; and (B) provide a means for clients to engage in origin independent messaging without the danger of Cross-Site-Request-Forgery (CSRF) and similar attacks. To illustrate the need for these two goals, consider the case of content from customer.example.org sending a request to a resource specified by service.example.com.

In a legitimate case, service.example.com wants the request delivered to a resource that it hosts, and so needs a way to allow cross-origin messaging so that the user agent will allow content from customer.example.org to send the request and receive the response. For the protection of service.example.com, user agents that enforce the Same Origin Policy (SOP) currently prohibit this message exchange. To enable the message exchange (A), service.example.com needs some means to opt-out of this protection. This specification defines an HTTP response header that allows a resource to opt-out of SOP protection for a given HTTP response.

In an attack case, service.example.com wants the request delivered to a resource that customer.example.org has permission to use but service.example.com does not. When informing customer.example.org of the intended request target, service.example.com provides the URL for a resource hosted by customer.example.org, such as https://customer.example.org/deleteImportantStuff. When the request is sent, customer.example.org receives a request with the user's cookies, sent by content hosted by customer.example.org. The request is indistinguishable from a legitimate request to the resource, so it is processed. In a variation on this attack, service.example.com provides the URL for a resource hosted by a third-site, partner.example.net. The user has permission to use the resource at partner.example.net, and the site accepts cross-site requests from customer.example.org, but again service.example.com does not have permission to use the resource. This attack variation is particularly troublesome, since it is identical to a legitimate variation in which service.example.com does have permission to use the resource and has granted that permission to the user.

In the attack cases, client permissions (such as cookies) are automatically applied to requests whose content is partly determined by another site. These cases are similar to the familiar CSRF attack, in which another site uses an HTML form element to determine the content of a request sent with the client's permissions. To avoid this class of attacks (B), this specification defines a messaging mechanism for sending requests that don't automatically include any of the client's context. With this context removed, the only permissions in a request are those explicitly provided by the requestor, such as a secret token. These requests are uniform, meaning the permissions applied to a request are the same, regardless of the context of the client. Since request data carries the same permissions, regardless of which client sent it, data sent by one client can instead be sent by another without affecting the permissions applied. Consequently, clients can use this mechanism to safely send requests produced in collaboration with other sites, even when the request target is within the same origin.

Many of the most popular user agents have recently deployed messaging mechanisms that support opting-out of SOP protection. The mechanism defined in this specification is within the intersection of HTTP messaging functionality supported across all these user agents. Unfortunately, this subset does not include many parts of HTTP messaging, such as custom request headers and methods such as PUT and DELETE. It is expected that a Level Two specification will eventually provide this functionality.

The HTTP messaging subset supported by this specification has the virtue of being the same subset supported by the HTML form element. All of the requests that can be sent using the messaging mechanism defined here can also be sent by the HTML form element. Consequently, this specification introduces no new request vulnerabilities for existing resources. Responses that lack the newly defined SOP opt-out header are not deliverd to the requestor, as with the HTML form element, so there also can be no new response vulnerabilities for existing resources.

This specification is a building block for other specifications, so-called UMP API specifications, which will define the precise model by which this specification is used. Among others, such specifications are likely to include Server-Sent Events, XBL 2.0, and a uniform alternative to XMLHttpRequest. [SSE] [XBL] [XHR]

The design this specification introduces is based on requirements and use cases, both included as appendix. A FAQ describing the design decisions is also available.

If a resource author has a simple text resource residing at https://service.example.com/hello which contains the string "Hello World!" and would like other sites to be able to access it, the response combined with a header introduced by this specification would look as follows:

Access-Control-Allow-Origin: *

Hello World!

Using a XMLHttpRequest-like API, a client-side Web application from customer.example.org can access this resource as follows:

var xhr = new UniformRequest();
xhr.open("GET", "https://service.example.com/hello");
xhr.onreadystatechange = function() { /* do something */ };
xhr.send();

2 Conformance Criteria

This specification is written for resource authors and user agents. It includes advice for specifications that define APIs that use the uniform request algorithm defined in this specification. The general security considerations section includes some advice for Web application authors.

As well as sections and appendices marked as non-normative, all diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

In this specification, the words must, should and may are to be interpreted as described in RFC 2119. [RFC2119]

Requirements phrased in the imperative as part of algorithms (e.g. "terminate the algorithm") are to be interpreted with the meaning of the key word (e.g. must) used in introducing the algorithm.

A conformant resource is one that implements all the requirements listed in this specification that are applicable to resources.

A conformant user agent is one that implements all the requirements listed in this specification that are applicable to user agents.

User agents and resource authors may employ any algorithm to implement this specification, so long as the end result is indistinguishable from the result that would be obtained by the specification's algorithms.

2.1 Terminology

Terminology is generally defined throughout the specification. However, the few definitions that did not really fit anywhere else are defined here instead.

Comparing two strings in a case-sensitive manner means comparing them exactly, codepoint for codepoint.

Comparing two strings in an ASCII case-insensitive manner means comparing them exactly, codepoint for codepoint, except that the characters in the range U+0041 LATIN CAPITAL LETTER A to U+005A LATIN CAPITAL LETTER Z and the corresponding characters in the range U+0061 LATIN SMALL LETTER A to U+007A LATIN SMALL LETTER Z are considered to also match.

URL and userinfo are defined by RFC 3986. [RFC3986]

When the current ongoing URL debate is over this specification will be updated to use the accepted terminology. For now it will remain using URL as to not flip-flop every other month.

3 Security Considerations

This section is non-normative.

Web application authors, in designing server-side behavior of resources, should consider one of the following choices:

  1. Resources that are not useful to other sites, such as login pages, should not add the Access-Control-Allow-Origin header to responses.

    If these resources respond to HTML form POSTs, then to avoid CSRF hazards, the resource still needs to check for permissions (such as secret tokens) in the explicitly provided content of the request.

    If the permissions needed for a POST are provided in response to a GET, then a user action to submit the POST could be vulnerable to clickjacking. (Note that scriptless HTML pages are sufficient to cause clickjacking vulnerabilities.) To guard against clickjacking, applications should perform additional access checks on the GET request.

    The security properties of such resources are unaffected by user agents conformant to this specification.

  2. Resources that are publicly accessible, with no access control checks, should add the Access-Control-Allow-Origin header to all responses.

    Legacy user agents remain limited by SOP from accessing such resources cross-origin. Currently deployed user agents that understand the Access-Control-Allow-Origin header, as well as user agents conformant to this specification, will be able to access such resources regardless of origin.

  3. Resources that are only accessible to authorized requestors should check for permissions in the explicitly provided content of the request. If these resources might be useful to other sites, the Access-Control-Allow-Origin header should be included in responses.

    Again, legacy user agents remain limited by SOP from accessing such resources cross-origin. Currently deployed user agents that understand the Access-Control-Allow-Origin header, as well as user agents conformant to this specification, will be able to access such resources regardless of origin.

When placing permissions in the explicitly provided content of a request, plausible places are within the request URL (e.g., as a query parameter) or in the entity body. Before chosing to place such information in the URL, the application designer should examine whether such URLs are likely to be used where they might leak via a Referer header. This specification does not recommend any particular scheme for including permissions in a request.

Application designers should design protocols that transmit only those permissions justified by the purpose of each request.

The Access-Control-Allow-Origin response header provides another reason for HTTP server implementers to fix HTTP response splitting vulnerabilities. Such vulnerabilities currently make a site vulnerable to Cross-Site-Scripting (XSS), but could also be used to inject an Access-Control-Allow-Origin response header.

4 Syntax

This section defines the syntax of the new headers this specification introduces. It also provides a short description of the function of each header.

The resource processing model section details how resources are to use these headers in a response. Likewise, the user agent processing model section details how user agents are to use these headers.

The ABNF syntax used in this section is from HTTP/1.1. [HTTP]

HTTP/1.1 is used as ABNF basis to ensure that the new headers have equivalent parsing rules to those introduced in that specification.

4.1 Access-Control-Allow-Origin Response Header

The Access-Control-Allow-Origin response header indicates the resource expects the response to be delivered, regardless of the origin of the request.

Access-Control-Allow = "Access-Control-Allow-Origin" ":" "*"

The length of this header name is unfortunate since it is included, uncompressed, on all shared responses. Ideally, we'd prefer:

Access-Control-Allow = "U" ":" ""

Where user-agents would only check for the presence of a header named "U" and ignore its value.

5 Resource Processing Model

This section describes the processing model that resources have to implement.

A resource indicates whether or not to share a response by adding a single Access-Control-Allow-Origin header, with the literal string "*" as value.

6 User Agent Processing Model

This section describes the processing model user agents have to implement.

The processing model in this section is typically referenced by a hosting specification that defines when the algorithm is invoked and how the return values are to be handled. The processing model is not suitable for standalone use.

6.1 Uniform Request Parameters

The uniform request algorithm takes the following parameters:

request URL

The URL for the request.

request method

The method for the request.

The request method must be a case-sensitive match for one of the following allowed methods:

It might be safe to also allow OPTIONS and HEAD, but these are not currently allowed since they are not allowed by the HTML form element.

request entity media type (optional)

The media type of the request entity-body.

The request entity media type (excluding media type parameters) must be an ASCII case-insensitive match for one of the following allowed media types:

At most a single charset media type parameter is allowed.

These are the same media types supported by the HTML form element.

request entity body (optional)

The entity body for the request.

6.2 Uniform Request Status

Each uniform request has an associated uniform request status. The values are:

success
The resource can be shared.
abort error
The user aborted the request.

Does this case really need to be distinguished from network error?

network error
An error of some sorts occured.

6.3 Uniform Request

The content of a uniform request is determined solely by the provided uniform request parameters and the required structure of an HTTP request. A user agent must not augment this content with any data that identifies the user or the origin of the request. In particular, the user agent must not add any information obtained from: HTTP cookies, HTTP Auth headers, client certificates, or the referring resource (other than the request parameters).

To further assist uniformity, and reduce message size, the user agent also should not augment a uniform request with information about the user agent or its configuration. This does not include HTTP headers required for caching, which should still be sent. In particular, the user agent should not add the HTTP headers: User-Agent, Accept, Accept-Language, Accept-Encoding, or Accept-Charset. If the information conveyed by these headers needs to be included, it can be explicitly provided by the uniform request parameters; for example, in request URL query string arguments.

The steps below describe what user agents must do for a uniform request:

  1. Make a request to request URL, using the request method. If the request method supports an entity body, include a Content-Type request header whose value is the request entity media type, and include the request entity body.

  2. If the response has an HTTP status code of 301, 302, 303, or 307:

    If the URL conveyed by the Location response header contains the userinfo production, or its scheme is not supported, or infinite loop precautions are violated, or the user agent does not wish to make the new request for some other reason, terminate the request and set the uniform request status to network error.

    Otherwise, transparently follow the redirect by making a uniform request with arguments indicated by the redirect status code.

    If the response includes a single Access-Control-Allow-Origin header, whose value is the literal "*" character

    Set the uniform request status to success and allow the request to complete, making the response headers and response entity body available to the requestor.

    If the user cancels the request

    Terminate the request and set the uniform request status to abort error.

    Otherwise

    Terminate the request and set the uniform request status to network error.

In the above algorithm, a redirect is followed even though the target resource may have omitted the Access-Control-Allow-Origin header in the redirect response. The HTML form element also follows this redirect.

7 Uniform Messaging API Specification Advice

This section is non-normative.

This specification defines a messaging policy that cannot be implemented without an API that utilizes it. The specification of the API that uses the policy is a Uniform Messaging Policy (UMP) API specification.

If an UMP API specification defines multiple APIs that utilize the policy, the advice is to be considered separately for each API.

7.1 Constructing a Uniform Request

For all requests an UMP API makes, the API specification needs to reference the uniform-request algorithm and set the uniform request arguments appropriately.

UMP API specifications are allowed to let these input variables be controlled by the API, but can also set fixed values.

An UMP API specification for an API that only allows requests using the GET method might set request method to GET, request entity body and request entity media type to empty, and let the other variables be controlled by the API.

7.2 Dealing with the Uniform Request Status

While a uniform request is progressing, its associated uniform request status is updated. Depending on the provided value, the API is to react in a different way:

success

The contents of the response can be shared with the API.

The request itself can still be progressing. I.e. the uniform request status value does not indicate that the request has completed.

abort error

Handle analogous to requests where the user aborted the request. This can be handled equivalently to how network error is handled. Ensure not to reveal any further information about the request.

network error

Handle analogous to requests where some kind of error occured. Ensure not the reveal any further information about the request.

7.3 Naming a Uniform Messaging API

In an UMP API, both cross-origin and same-origin requests are made according to the Uniform Messaging policy. An existing API for same-origin messaging cannot be extended for cross-origin messaging by adopting the Uniform Messaging policy for only the cross-origin requests. In an UMP API, the policy is applied to all requests, including same-origin requests. Since changing the policy applied to same-origin requests in an existing API could create compatibility issues, use a new name for the corresponding UMP API.

For example, to extend the existing XMLHttpRequest API to support cross-origin messaging, the constructor could be renamed, leaving the rest of the API intact:

xhr = new UniformRequest();
xhr.open("GET", "https://service.example.com/hello");
xhr.send();

Requirements

This appendix is non-normative.

This appendix outlines the various requirements that influenced the design of the Uniform Messaging specification.

  1. Must not introduce attack vectors to servers that are only protected by a firewall.

  2. The solution should not introduce additional attack vectors against services that are protected only by way of firewalls. This requirement addresses "intranet" style services that authorize any requests that can be sent to the service.

  3. It should not be possible to perform cross-origin operations that are not already enabled by deployed user agents, without an authorization check being performed. For example, a PUT operation.

  4. Should try to prevent dictionary-based, distributed, brute-force attacks that try to get login accounts to 3rd party servers, to the extent possible.

  5. Should properly enforce security policy in the face of commonly deployed proxy servers sitting between the user agent and any of servers with whom the user agent is communicating.

  6. Should not allow loading and exposing of resources from 3rd party servers without explicit consent of these servers as such resources can contain sensitive information.

  7. Must not require content authors or site maintainers to implement new or additional security protections to preserve their existing level of security protection.

  8. Must be deployable to IIS and Apache without requiring actions by the server administrator in a configuration where the user can upload static files, run serverside scripts (such as PHP, ASP, and CGI), control headers, and control authorization, but only do this for URLs under a given set of subdirectories on the server.

  9. Must be able to deploy support for cross-origin GET requests without having to use server-side scripting (such as PHP, ASP, or CGI) on IIS and Apache.

  10. The solution must be applicable to arbitrary media types. It must be deployable without requiring special packaging of resources, or changes to resources' content.

    To retain compatibility with deployed implementations of this specification, support for POSTs of other media types beyond those allowed by this specification is deferred to a future Uniform Messaging, Level Two specification.

  11. It should be possible to configure distinct cross-origin authorization policies for different target resources that reside within the same origin.

  12. It should be possible to distribute content of any type. Likewise, it should be possible to transmit content of any type to the server if the API in use allows such functionality.

    To retain compatibility with deployed implementations of this specification, support for POSTs of other media types beyond those allowed by this specification is deferred to a future Uniform Messaging, Level Two specification.

  13. It should be possible to allow only specific servers, or sets of servers to fetch the resource.

  14. Must not require the server to filter the entity body of the resource in order to deny cross-origin access to all resources on the server.

  15. Cross-origin requests should not require API changes other than allowing cross-origin requests. This means that the following examples should work for resources residing on customer.example.org (modulo changes to the respective specifications to allow cross-origin requests):

  16. It should be possible to issue methods other than GET to the server, such as POST and DELETE.

    To retain compatibility with deployed implementations of this specification, support for methods other than the allowed methods is deferred to a future Uniform Messaging, Level Two specification.

  17. Should be compatible with commonly used HTTP authentication and session management mechanisms. I.e. on an IIS server where authentication and session management is generally done by the server before ASP pages execute this should be doable also for requests coming from cross-origin requests. Same thing applies to PHP on Apache.

    These common uses of HTTP cookies and HTTP auth are not safe when used cross-origin, so this requirement is in conflict with the following one.

  18. Should reduce the risk of inadvertently allowing access when it is not intended. This is, it should be clear to the content provider when access is granted and when it is not.

Use Cases

This appendix is non-normative.

A primary motivation behind Uniform Messaging was to remove the same origin restriction from various APIs so that resources can be shared among different origins.

Here are various APIs that might make use of the functionality described in this specification to allow uniform requests:

Design Decision FAQ

This appendix is non-normative.

This appendix documents several frequently asked questions and their corresponding response.

Why is POST treated similarly to GET?

Cross-origin POST requests have long been possible using the HTML form element. However, this is only the case when Content-Type is set to one of the media types allowed by HTML forms.

What about the JSONRequest proposal?

Uniform Messaging supports more use-cases than does JSONRequest. A JSONRequest-like API can be implemented on top of Uniform Messaging.

Since the content of a uniform request could have been sent from anywhere on the internet, why does the Access-Control-Allow-Origin response header need to be sent?

If the resource is behind a firewall, the request could only have been sent by a client behind the same firewall. User agents that enforce SOP do not allow these responses to be delivered across origins. Some firewalled resources depend entirely on this protection. The safety of these resource must be preserved.

Since the content of a uniform request could have been sent from anywhere on the internet, why can't PUT and DELETE requests be sent?

If the resource is behind a firewall, the request could only have been sent by a client behind the same firewall. User agents that enforce SOP do not allow these requests to be sent across origins. Some firewalled resources depend entirely on this protection. The safety of these resource must be preserved.

References

[SSE] (non-normative)
Server-Sent Events (wok in progress), I. Hickson, editor. W3C, 2009.
[HTTP]
HTTP/1.1, part 1: URIs, Connections, and Message Parsing (work in progress), R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, Y. Lafon, J. Reschke. IETF, 2009.
HTTP/1.1, part 2: Message Semantics (work in progress), R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, Y. Lafon, J. Reschke. IETF, 2009.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF, March 1997.
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax, T. Berners-Lee, R. Fielding, L. Masinter, editors. IETF, January 2005.
[XBL] (non-normative)
XML Binding Language (XBL) 2.0 (work in progress), I. Hickson, editor. W3C, March 2007.
[XHR] (non-normative)
XMLHttpRequest (work in progress), A. van Kesteren. W3C, 2009.
[XMLSSPI] (non-normative)
Associating Style Sheets with XML documents, J. Clark. W3C, June 1999.

Acknowledgments

This appendix is non-normative.

The editor would like to thank Adam Barth, Alexey Proskuryakov, Arthur Barstow, Benjamin Hawkes-Lewis, Bert Bos, Björn Höhrmann, Cameron McCormack, Collin Jackson, David Håsäther, David Orchard, Dean Jackson, Eric Lawrence, Frank Ellerman, Frederick Hirsch, Graham Klyne, Hal Lockhart, Henri Sivonen, Ian Hickson, Ihab Awad, Jesse M. Heines, Jonas Sicking, Lachlan Hunt, Maciej Stachowiak, Marc Silbey, Marcos Caceres, Mark Nottingham, Martin Dürst, Matt Womer, Mike Samuel, Michael Smith, Mike Stay, Mohamed Zergaoui, Nikunj Mehta, Sharath Udupa, Sunava Dutta, Surya Ismail, Thomas Roessler, and Zhenbin Xu for their contributions to this specification.

Special thanks to Anne van Kesteren, Brad Porter, Matt Oshry and R. Auburn, who all helped editing earlier versions of this document.