Abstract

This document defines a mechanism to enable client-side cross-origin
requests. Specifications that enable an API to make cross-origin requests
to resources can use the algorithms defined by this specification. If
such an API is used on http://example.org resources, a
resource on http://hello-world.example can opt in using the
mechanism described by this specification (e.g., specifying
Access-Control-Allow-Origin: http://example.org as response
header), which would allow that resource to be fetched cross-origin from
http://example.org.

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 document was published by the Web Applications
(WebApps) and Web Application Security (WebAppSec) Working Group as a Candidate Recommendation. There is no preliminary implementation report. The Working Groups have not identified any feature at risk. This document is intended to become a W3C Recommendation.
If you wish to make comments regarding this document, please send them to
public-webappsec@w3.org
(subscribe,
archives).
W3C publishes a Candidate Recommendation
to indicate that the document is believed
to be stable and to encourage implementation by the developer community. This
Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 01 March 2013.
All feedback is welcome. A diff-marked version against the previous version of this document is available.

Publication as a Candidate Recommendation 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.

The entrance criteria for this document to enter the Proposed Recommendation
stage is to have a minimum of two independent and interoperable user agents
that implement each feature of this specification, which will be determined
by passing the user agent tests defined in the test suite developed by the Working Group.

1 Introduction

This section is non-normative.

User agents commonly apply same-origin restrictions to network
requests. These restrictions prevent a client-side Web application
running from one origin from obtaining data retrieved from another origin,
and also limit unsafe HTTP requests that can be automatically launched
toward destinations that differ from the running application's origin.

In user agents that follow this pattern, network requests typically
include user credentials with cross-origin requests, including HTTP
authentication and cookie information.

This specification extends this model in several ways:

A response can include an
Access-Control-Allow-Origin
header, with the origin of where the request originated from as the
value, to allow access to the resource's contents.

The user agent validates that the value and origin of where the
request originated match.

User agents can discover via a preflight request whether
a cross-origin resource is prepared to accept requests, using a
non-simple method, from a given origin.

This is again validated by the user agent.

Server-side applications are enabled to discover that an HTTP request
was deemed a cross-origin request by the user agent, through the
Origin header.

This extension enables server-side applications to enforce
limitations (e.g. returning nothing) on the cross-origin requests that
they are willing to service.

This specification is a building block for other specifications,
so-called CORS API specifications, which define how this specification is
used. Examples are Server-Sent Events and XMLHttpRequest.
[EVENTSOURCE][XHR]

The CORS wiki page provides
more background information about this document.

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

Access-Control-Allow-Origin: http://hello-world.example
Hello World!

Using XMLHttpRequest a client-side
Web application on http://hello-world.example can access
this resource as follows:

It gets slightly more complicated if the resource author wants to be
able to handle cross-origin requests using methods other than
simple methods. In that case
the author needs to reply to a preflight request that uses the
OPTIONS method and then needs to handle the actual request
that uses the desired method (DELETE in this example) and
give an appropriate response. The response to the preflight request could
have the following headers specified:

The
Access-Control-Max-Age
header indicates how long the response can be cached, so that for
subsequent requests, within the specified time, no preflight request has
to be made. The
Access-Control-Allow-Methods
header indicates the methods that can be used in the actual request. The
response to the actual request can simply contain this header:

Access-Control-Allow-Origin: http://hello-world.example

The complexity of invoking the additional preflight request is
the task of the user agent. Using
XMLHttpRequest again and assuming the
application were hosted at http://calendar.example/app the
author could use the following ECMAScript snippet:

2 Conformance

This specification is written for resource authors and user agents. It
includes advice for specifications that define APIs that use the
cross-origin request algorithm defined in this specification
— CORS API specifications — and the general
security considerations section includes some
advice for client-side 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 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.

3 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.

Converting a string to ASCII lowercase
means replacing all characters in the range U+0041 LATIN CAPITAL LETTER A
to U+005A LATIN CAPITAL LETTER Z with the corresponding characters in the
range U+0061 LATIN SMALL LETTER A to U+007A LATIN SMALL LETTER Z).

The term user credentials for the purposes of this
specification means cookies, HTTP authentication, and client-side SSL
certificates. Specifically it does not refer to proxy authentication or
the Origin header.
[COOKIES]

A method is said to be a
simple method if it is a
case-sensitive match for one of the following:

GET

HEAD

POST

A header is said to be a
simple header if the header field name is an
ASCII case-insensitive match for Accept,
Accept-Language, or Content-Language or if it
is an ASCII case-insensitive match for
Content-Type and the header field value media type (excluding
parameters) is an ASCII case-insensitive match for
application/x-www-form-urlencoded,
multipart/form-data, or text/plain.

A header is said to be a
simple response header if the
header field name is an ASCII case-insensitive match for one
of the following:

Cache-Control

Content-Language

Content-Type

Expires

Last-Modified

Pragma

When
parsing a header the
header must be parsed per the corresponding ABNF
production in the syntax section. If the header does
not match the production it is said that
header parsing failed.

4 Security Considerations

This section is non-normative.

Security requirements and considerations are listed throughout this
specification. This section lists advice that did not fit anywhere
else.

A simple cross-origin request has been defined as congruent
with those which may be generated by currently deployed user agents that do
not conform to this specification. Simple cross-origin requests generated
outside this specification (such as cross-origin form submissions using
GET or POST or cross-origin GET
requests resulting from script elements) typically include
user credentials, so resources conforming to this specification
must always be prepared to expect simple cross-origin requests with
credentials.

Because of this, resources for which simple requests have significance
other than retrieval must protect themselves from Cross-Site Request Forgery
(CSRF)
by requiring the inclusion of an unguessable token in the explicitly
provided content of the request.
[CSRF]

This specification defines how to authorize an instance of an application
from a foreign origin, executing in the user agent, to access the
representation of the resource in an HTTP response. Certain types of
resources should not attempt to specify particular authorized origins, but
instead either deny or allow all origins.

A resource that is not useful to applications from other origins, such as a login page, ought not to return an
Access-Control-Allow-Origin
header. The resource still must protect itself against CSRF attacks, such
as by requiring the inclusion of an unguessable token in the explicitly
provided content of the request. The security properties of such resources
are unaffected by user-agents conformant to this specification.

A resource that is publicly accessible, with no access control checks,
can always safely return an
Access-Control-Allow-Origin
header whose value is "*".

A GET response whose entity body happens to parse as
ECMAScript can return an
Access-Control-Allow-Origin
header whose value is "*" provided there are no sensitive
comments as it can be accessed cross-origin using an HTML
script element. If needed, such resources can implement access
control and CSRF protections as described above.

When requests have significance other than retrieval, and when relying on the Origin header, resources must be careful to distinguish between authorizing a request (including its side-effects) and authorizing access to the representation of that resource in the response.

Authorization for a request should be performed using only the intersection of the authority of the user and the requesting origin(s).

It is often appropriate for resources to require an authorization ceremony which explicitly asks for a user to consent that cross-origin requests with credentials be honored from a given origin. In such cases, passing security tokens explicitly as part of the cross-origin request can remove any ambiguity as to the scope of authorization. OAuth is an example of this pattern.
[OAUTH]

A cross-origin request with credentials as defined in this
specification is used to substitute for alternate methods of
authenticated resource sharing, such as server-to-server back channels,
JSONP, or cross-document messaging.
[JSONP][HTML]

This substitution can expose additional attack surface in some cases,
as a cross-site scripting vulnerability in the requesting origin can
allow elevation of privileges against the requested resource when
compared to a server-to-server back channel.

As a substitute for JSONP-style cross-origin credentialed requests,
use of this specification significantly improves the security posture of
the requesting application, as it provides cross-origin data access
whereas JSONP operates via cross-origin code-injection.

As a substitute for cross-origin communication techniques relying on loading a resource, with credentials, into an HTML iframe element, and subsequently employing cross-document messaging or other cross-origin side channels, this specification provides a roughly equivalent security posture. Again, data received from origins that are not completely trusted has to be validated to conform to expected formats and authorized values.

For requests to resources that have no significance other than retrieval, and where the credentials are used only to provide user-specific customization for otherwise publicly accessible information. In this case, restricting access to certain origins may protect user privacy by preventing customizations from being used to identify a user, except at authorized origins.

When this specification is used for requests which have significance
other than retrieval and which involve coordination between or data
originating from more than two origins, (e.g. between resources enabling
editing, printing and storage, each at distinct origins) requests ought to
set the omit credentials flag and resources ought to
perform authorization using security tokens explicitly provided in the
content of the request, especially if the origins are not all mutually and
completely trusted.

In such multi-origin scenarios, a malicious resource at one of the
origins may be able to enlist the user-agent as a confused deputy and
elevate its privileges by abusing user credentials sent with cross-origin
requests. Avoiding
such attacks requires that the coordinating applications have explicit
knowledge of the scope of privilege for each origin and that all
parameters and instructions received are carefully validated at each step
in the coordination to ensure that effects implied do not exceed the
authority of the originating principal.
[CONFUSED]

Given the difficulty of avoiding such vulnerabilities in multi-origin
interactions it is recommended that, instead of using user
credentials automatically attached to the request by the user agent,
security tokens which specify the particular capabilities and
resources authorized be passed as part of the explicit content of a request.
OAuth again provides an example of such a pattern.

Authors of client-side Web applications are strongly encouraged to
validate content retrieved from a cross-origin resource as it
might be harmful.

Web applications that are not uniquely identified by specific host names,
and/or mapped to specific ports, do not necessarily have a unique origin, and
thus will not be able to securely utilize the mechanism defined in this
specification. This is because an origin is composed of only the
scheme, hostname, and port.

For example, a web application whose URL is of the type
example.org/app-name/ and the app-name portion is necessary to distinguish the
web application from other web applications also running at example.org, will
be unable to securely employ the mechanism defined in this specification.

If a header field name is a simple header and
is not Content-Type, it is not required to be listed.
Content-Type is to be listed as only a subset of its values
makes it qualify as simple header.

Since the list of headers can be unbounded
simply returning headers can be enough.

6.3 Security

This section is non-normative.

Resource authors are strongly encouraged to ensure that requests using
safe methods, e.g. GET or OPTIONS, have no side
effects so potential attackers cannot modify the user's data easily. If
resources are set up like this attackers would effectively have to be on
the list of origins to do harm.

In addition to checking the Origin
header, resource authors are strongly encouraged to also check the
Host header. That is, make sure that the host name provided
by that header matches the host name of the server on which the resource
resides. This will provide protection against DNS rebinding attacks.

6.4 Implementation Considerations

This section is non-normative.

Resources that wish to enable themselves to be shared with multiple
Origins but do not respond uniformly with "*"
must in practice generate the Access-Control-Allow-Origin
header dynamically in response to every request they wish
to allow. As a consequence, authors of such resources should send a
Vary: Origin HTTP header or provide other appropriate control
directives to prevent caching of such responses, which may be inaccurate
if re-used across-origins.

7 User Agent Processing Model

This section describes the processing models that user agents have to
implement.

The processing models in this sections need to be referenced by a
CORS API specification that defines when the algorithm is invoked and how
the return values are to be handled. The processing models are not
suitable for standalone use.

The resource cannot be shared. Also used when a DNS error, TLS
negotiation failure, or other type of network error occurs.
This does not include HTTP responses that indicate some
type of error, such as HTTP status code 410.

7.1.5 Cross-Origin Request with Preflight

To protect resources against cross-origin requests that could not
originate from certain user agents before this specification existed a
preflight request is made to ensure that the resource is
aware of this specification. The result of this request is stored in a
preflight result cache.

The steps below describe what user agents must do
for a
cross-origin request with preflight.
This is a request to a non same-origin URL that first needs to be
authorized using either a preflight result cache entry or a
preflight request.

Otherwise, make a
preflight request.
Fetch the request URL
from originsource origin using
referrer source as override referrer source
with the manual redirect flag and the
block cookies flag set, using the method
OPTIONS, and with the following additional constraints:

The user agent gets the request from an API, such as
XMLHttpRequest, to perform a
cross-origin request using the custom XMODIFY method from
source originhttp://example.org to
http://blog.example/entries/hello-world.

The user agent then performs the desired request using the
XMODIFY method to
http://blog.example/entries/hello-world as this was allowed
by the resource. In addition, for the coming forty-two minutes, no
preflight request will be needed.

To be clear, the method
and header fields are mutually
exclusive. When one of them is empty the other is non-empty.

The primary key of an entry consists of all fields
excluding the max-age field.

Entries must be removed when the time specified in
the max-age field has passed since
storing the entry. Entries can also be added and removed per the
algorithms below. They are added and removed in such a way that there can
never be duplicate items in the cache.

User agents may clear cache entries before the
time specified in the max-age field has
passed.

Although this effectively makes the
preflight result cache optional, user agents are strongly
encouraged to support it.

7.1.7 Generic Cross-Origin Request Algorithms

The variables used in the generic set of steps are part of the
algorithms that invoke these set of steps.

The above algorithm also functions when the
ASCII serialization of an origin is
the string "null".

7.3 Security

This section is non-normative.

At various places user agents are allowed to take additional
precautions. E.g. user agents are allowed to not store cache items, remove
cache items before they reached their
max-age, and not connect to certain
URLs.

As indicated as the first step of the cross-origin request
algorithm and in the redirect steps algorithm user agents
are allowed to terminate the algorithm and not make a request. This could
be done because e.g.:

The origin of the resource blacklisted.

The origin of the resource is known to be part of an
intranet.

The URL <scheme> is not supported.

https to http is not allowed.

https is not allowed because of certificate errors

User agents are encouraged to apply security decisions on a generic
level and not just to the resource sharing policy. E.g. if a user agent
disallows requests from the https to the http
scheme for a cross-origin request it is encouraged to do the
same for the HTML img element.

8 CORS API Specification Advice

This section is non-normative.

This specification defines a resource sharing policy that cannot be
implemented without an API that utilizes it. The specification that
defines the API that uses the policy is a CORS API specification.

In case a CORS API specification defines multiple APIs that utilize the
policy the advice is to be considered separately for each API.

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

A CORS API specification for an API that only allows
requests using the GET method might set
request method to GET,
request entity body to empty, and source origin
to some appropriate value and let the other variables be controlled by the
API.

8.2 Dealing with Same Origin to Cross-Origin Redirects

Since browsers are based on a
same origin security model and the
policy outlined in this specification is intended for APIs used in
browsers, it is expected that APIs that will utilize this policy will have
to handle a same origin request that
results in a redirect that is cross-origin in a special
way.

For APIs that transparently handle redirects CORS API specifications
are encouraged to handle this scenario transparently as well by "catching"
the redirect and invoking the cross-origin request algorithm
on the (cross-origin) redirect URL.