W3C

Uniform Messaging Policy, Level One

Editor's Draft 15 June 2010

Previous Versions:
http://www.w3.org/TR/2010/WD-UMP-20100126/
Latest Version:
http://www.w3.org/TR/UMP/
Editor's Version:
http://dev.w3.org/2006/waf/UMP/
Editors:
Tyler Close (Google)
Mark Miller (Google)

Abstract

The Uniform Messaging Policy (UMP) enables cross-site messaging that avoids Cross-Site-Request-Forgery and similar attacks that abuse HTTP cookies and other credentials. For example, content from customer.example.org can safely specify requests to resources determined by service.example.com. Rather than restricting information retrieval to a single origin, as the Same Origin Policy almost does, the Uniform Messaging Policy supports origin independent messaging.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is the 15 June 2010 Editor's Draft of the "Uniform Messaging Policy" document. It is expected that this document will progress along the W3C Recommendation track. This document is produced by the Web Applications (WebApps) Working Group. The WebApps Working Group is part of the Rich Web Clients Activity in the W3C Interaction Domain.

Please send comments to the WebApps Working Group's public mailing list public-webapps@w3.org with [UMP] at the start of the subject line. Archives of this list are available. See also W3C mailing list and archive usage guidelines.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Table of Contents

1 Introduction

This section is non-normative.

Web applications increasingly seek to interact with resources from multiple administrative domains. Consider the case of content from customer.example.org specifying a request (via a script, a form, etc.) to a resource hosted by service.example.com. For the protection of service, user-agents enforce a Same Origin Policy that restricts this message exchange. To enable the message exchange, service needs some means to opt-out of this protection.

The main goals of this specification are:

  1. Provide a means for a resource owner to consent to cross-origin information retrieval.
  2. Support origin independent messaging that avoids Cross-Site-Request-Forgery [CSRF] and similar attacks.

We introduce an HTTP response header that enables opting-out of Same Origin Policy protection for a given HTTP response in order to meet the first of these goals.

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

In the attack cases, user credentials (such as cookies) are automatically included in 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 target and body of a request that includes the user's credentials. To avoid this class of attacks, and so meet the second goal, we introduce a messaging policy for uniform requests that don't automatically include any credentials. By withholding credentials, requests can be safely 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 Same Origin Policy protection. Level One of the Uniform Messaging Policy 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 Level One has the virtue of being within the subset defined by the <form> element in HTML 4.01. [HTML4] All of the requests that can be sent in Level One can also be sent using the HTML <form> element, as commonly implemented in currently deployed user-agents. Consequently, Level One introduces no new request vulnerabilities for existing resources. Responses that lack the newly defined Same Origin Policy opt-out header are not delivered to the requestor, as with the HTML <form> element, so there also can be no new response vulnerabilities for existing resources.

In this specification, we only define a security model for cross-site messaging. Other specifications, so-called UMP API specifications, define messaging APIs that adhere to this security model. 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 of the Uniform Messaging Policy 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 the introduced Same Origin Policy opt-out response header would look as follows:

Access-Control-Allow-Origin: *

Hello World!

Using a XMLHttpRequest-like API, a client-side 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 Messeaging Policy defined in this specification. The general security considerations section includes some advice for 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 terms MUST and MUST NOT are to be interpreted as described in [RFC2119].

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.

2.1 Terminology

This specification reuses the terminology and ABNF syntax used in [HTTP].

3 Uniform Request

A uniform request is an HTTP request produced according to the restrictions defined in this section.

3.1 Uniform Request Parameters

Content specifying a uniform request MUST only provide values for the following parameters:

request URL

The URL for the request. The URL MUST NOT contain the userinfo [RFC3986] production.

request method

The method for the request.

The request method MUST be one of the following allowed methods:

Note: These are the same methods supported by the HTML <form> element.

request entity media type (optional if there is no request entity body)

The media type of the request entity-body.

The request entity media type (excluding media type parameters) MUST be one of the following allowed media types:

At most a single charset media type parameter is allowed.

Note: These are the same media types supported by the HTML <form> element.

request entity body (optional)

The entity body for the request.

3.2 HTTP Caching

When producing a uniform request, a user-agent can make use of an [HTTP] cache; however, the user-agent MUST only use a cache entry resulting from a uniform response to a uniform request.

3.3 Proxy Credentials

If a user-agent is configured to send requests via a proxy, instead of directly to the host specified by the request URL, this proxy configuration information can be used to send the request to the proxy. In this case, the request sent by the user-agent is not a uniform request; however, the request ultimately delivered to the resource host will be, since any Proxy-Authorization request header is removed by the proxy before forwarding the request to the resource host.

3.4 Connection

Some forms of client authentication, such as [TLS] client certificates or [NTLM], authenticate a connection rather than only a particular HTTP request. A user-agent MUST NOT send a uniform request over a client authenticated connection.

3.5 Other Data

The content of a uniform request is determined solely by the information discussed in this section and the required structure of an HTTP request. The user-agent MUST NOT augment the sent request with any other 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). For example, the user-agent MUST NOT identify the source of the requesting content using either an Origin or Referer request header. An Origin header with value null is allowed.

4 Uniform Response

This section places restrictions on the handling of a response to a uniform request.

4.1 Uniform Response Header

A uniform response is an HTTP response with a single Access-Control-Allow-Origin header, with the literal string "*" as its value.

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

This header MUST only be present if the resource owner permits access to the response by the content that specified the corresponding request, regardless of that content's origin.

4.2 Response Header Filtering

Some HTTP servers construct an HTTP response in multiple stages. In such a deployment, an earlier stage might produce a uniform response which is augmented with additional response headers by a later stage that does not understand a uniform response header. This later stage might add response headers with the expectation they will be protected by the Same Origin Policy. The developer of the earlier stage might be unable to update the program logic of the later stage. To accommodate this deployment scenario, user-agents can filter out response headers on behalf of the server before exposing a uniform response to the requesting content. The user-agent MUST filter out all response headers other than the following:

The above whitelist defines a minimal set of default headers that are always allowed and an extension mechanism for allowing additional headers. The default members of the whitelist include response entity headers defined by [HTTP], plus the Location and Warning headers. Response entity headers are needed to correctly interpret the response entity. The Location header is needed to support redirection. The Warning header enables requesting content to reject stale responses. The default part of the whitelist does not include: headers used for credential authentication, such as WWW-Authenticate; nor headers that might reveal private network configuration information, such as Via; nor caching headers, such as Age, which might reveal private information, such as when a given request was first made on behalf of content from another origin.

4.3 Non-Uniform Response

When processing a uniform request, the user-agent MUST treat any response other than a uniform response as an error condition. The response MUST NOT be made accessible to the requesting content. If the response is a redirect, it MUST NOT be followed.

Note: Even though a uniform request will not follow a non-uniform redirect, a non-uniform request, sent using an HTML tag such as <form> or <script>, might follow a non-uniform redirect, even cross-domain. Consequently, a non-uniform redirect is not a reliable means of prohibiting cross-domain access to a resource.

4.4 Redirection

If a uniform response to a uniform request is an HTTP redirect, any redirected request MUST also be a uniform request.

4.5 Changes to User-Agent State

When processing a uniform request, the user-agent MUST NOT make any state changes, other than delivering any corresponding uniform responses to the requesting content and updating the response cache. In particular, the user-agent MUST ignore any Set-Cookie response header.

5 Uniform Messaging Policy API Specification Advice

This section is non-normative.

A Uniform Messaging Policy (UMP) API is a messaging API that only produces uniform requests. This section provides implementation advice for such API specifications.

5.1 Constructing a Uniform Request

For all requests an UMP API makes, ensure the uniform request parameters are set appropriately.

Values for these parameters can be specified by content via the API, or the API may set fixed values.

For example, an UMP API that only supports information retrieval might set request method to GET, request entity body and request entity media type to empty, and let the other parameters be specified by content.

5.2 Uniform Messaging Status

For each uniform request there is an associated uniform messaging status that indicates the status of enforcement of the Uniform Messaging Policy. The values are:

pending

Enforcement has not yet completed and so the response cannot yet be shared. This status might change. The API should handle this case analogous to a request where no response has yet been received. Ensure not to reveal any further information about the response.

success

The response can be shared with the requesting content. This status is final.

The HTTP response itself can still be progressing. I.e. the uniform messaging status does not indicate that the full HTTP response has been received.

failure

An error of some sort occurred and so the response cannot be shared. This status is final. Inform the requesting content that an unspecified error occurred, but do not to reveal any further information about the response.

5.3 Uniform Messaging Algorithm

The steps below describe how to process a uniform request. Initially, the uniform messaging status is pending:

  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 is not a uniform response

    Terminate the request and set the uniform messaging status to failure.

    If the response is an HTTP redirect

    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 messaging status to failure.

    Otherwise, handle the redirect as specified by [HTTP], using a uniform request for any redirected request.

    Otherwise

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

The above algorithm is adapted from the "simple cross-origin request" algorithm in the CORS spec. The main difference is that the resource sharing check is performed first, to clarify that it applies to any kind of response.

5.4 Naming a Uniform Messaging Policy 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();

6 Security Considerations

This section is non-normative.

An application author, in designing the server-side behavior of a resource, should consider one of the following choices:

  1. A resource that is not useful to other sites, such as a login page, should not return uniform responses.

    The resource still must protect itself against CSRF attacks, such as by including an unguessable token in the explicitly provided content of the request. If the unguessable token is provided in response to a same-origin GET request, the resource may still be vulnerable to clickjacking [clickjacking]. (Note that scriptless HTML pages are sufficient to cause clickjacking vulnerabilities.) To guard against clickjacking, applications should perform additional access checks on that GET request (such as also requiring an unguessable token in that GET request).

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

  2. A resource that is publicly accessible, with no access control checks, should always return uniform responses.

    Legacy user-agents remain limited by the Same Origin Policy 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. A resource that is only accessible to authorized requestors should check for permission tokens in the explicitly provided content of the request. If the resource might be useful to other sites, it should return uniform responses.

    Again, legacy user-agents remain limited by the Same Origin Policy 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.

  4. A GET response whose body happens to parse as [ECMAScript] should be a uniform response. This category includes [JSON] content. These responses have already effectively opted-out of Same Origin Policy protection, since the content can be accessed cross-origin using an HTML <script> tag. If needed, such resources should implement access control in the same way as resources in category 3.

A permission token represents a resource owner's consent to the use of that resource. In contrast to a credential, a permission is specific to a particular resource; whereas a credential may be used in requests to many resources. An unguessable token is commonly used to implement a permission token. Only agents that have been given the unguessable token have the resource owner's consent to use the resource. For example, in the common CSRF defense noted in category 1 above, an unguessable token is only provided to content from the same origin as the resource. This unguessable token represents permission to submit a request. A request without the unguessable token is rejected. A resource in category 3 above should use this technique to implement access control; providing an unguessable token only to agents who may use the resource.

When placing a permission token in a request, plausible places are within the request URL (e.g., as a query parameter) or in the entity body. Before choosing to place a permission token in the URL, the application author should examine whether the URL is likely to be used where it might leak via a Referer header. This specification does not recommend any particular scheme for including permission tokens in a request.

Application authors should design protocols that transmit only those permissions justified by the purpose of each request. These permissions should not be context sensitive, such as "apply delete permission to any identifier in this request". Such a permission creates the danger of a CSRF-like attack in which an attacker causes an unexpected identifier to be in the request. Instead, a permission should be specific, such as "apply delete permission to resource foo".

Definition of a uniform response header provides another reason for HTTP server implementers to fix [response splitting] vulnerabilities. Such vulnerabilities currently make a site vulnerable to Cross-Site-Scripting (XSS), but could also be used to inject a uniform response header.

Requirements

This appendix is non-normative.

Note: These requirements are taken from the CORS specification. A note indicates those requirements that could not be fully satisfied.

This appendix outlines the various requirements that influenced the design of the Uniform Messaging Policy 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 server-side scripts (such as PHP, ASP, and CGI), control headers, and control authorization, but only do this for URLs under a given set of sub-directories 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.

    Note: To retain compatibility with deployed implementations, support for POSTs of arbitrary media types is deferred to a future Uniform Messaging Policy, 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.

    Note: To retain compatibility with deployed implementations, support for POSTs of arbitrary media types is deferred to a future Uniform Messaging Policy, 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.

    Note: To retain compatibility with deployed implementations, support for methods other than the allowed methods is deferred to a future Uniform Messaging Policy, 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.

    Note: 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.

Note: These use-cases are taken from the CORS specification.

A primary motivation behind Uniform Messaging Policy 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 Uniform Messaging Policy:

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 an HTML <form>.

What about the JSONRequest proposal?

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

Since the content of a uniform request could have been sent from anywhere on the Internet, why does a uniform 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 the Same Origin Policy do not allow these responses to be delivered across origins. Some firewalled resources depend entirely on this protection. The safety of these resources 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 the Same Origin Policy do not allow these requests to be sent across origins. Some firewalled resources depend entirely on this protection. The safety of these resources must be preserved.

References

Normative References

[HTTP]
Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee. IETF, June 1999.
[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.

Non-normative References

[clickjacking]
Clickjacking, R. Hansen, J. Grossman. SecTheory 12 September 2008.
[CSRF]
Cross-Site Request Forgeries, P. Watkins. Bugtraq, 15 June 2001.
[ECMAScript]
ECMA-262: ECMAScript Language Specification, third edition, ECMA. December 1999.
[JSON]
The application/json Media Type for JavaScript Object Notation (JSON), D. Crockford. IETF, July 2006.
[HTML4]
HTML 4.01 Specification, D. Ragget, A. Le Hors, I. Jacobs. W3C, 24 December 1999.
[NTLM]
NT LAN Manager (NTLM) Authentication Protocol Specification. Microsoft, 2010
[response splitting]
CRLF Injection, U. Harnhammar. Bugtraq, 6 May 2002.
[SSE]
Server-Sent Events (wok in progress), I. Hickson, editor. W3C, 2009.
[TLS]
Transport Layer Security, E. Rescorla. IETF, 2009.
[XBL]
XML Binding Language (XBL) 2.0 (work in progress), I. Hickson, editor. W3C, March 2007.
[XHR]
XMLHttpRequest (work in progress), A. van Kesteren. W3C, 2009.
[XMLSSPI]
Associating Style Sheets with XML documents, J. Clark. W3C, June 1999.

Acknowledgments

This appendix is non-normative.

The editors thank Adam Barth, Alexey Proskuryakov, Arthur Barstow, Benjamin Hawkes-Lewis, Bert Bos, Björn Höhrmann, Cameron McCormack, Collin Jackson, Dan Connolly, 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, Jonathan Rees, Lachlan Hunt, Maciej Stachowiak, Marc Silbey, Marcos Caceres, Mark Nottingham, Martin Dürst, Matt Womer, Michael Smith, Mike Samuel, 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.