Abstract

This document defines a policy language used to declare a set of content restrictions for a web resource, and a mechanism for transmitting the policy from a server to a client where the policy is enforced.

Status of this document

This is a public copy of the editors’ draft.
It is provided for discussion only and may change at any moment.
Its publication here does not imply endorsement of its contents by W3C.
Don’t cite this document other than as work in progress.

The (archived) public mailing list
public-webappsec@w3.org
(see instructions)
is preferred for discussion of this specification.
When sending e-mail,
please put the text “CSP3” in the subject,
preferably like this:
“[CSP3] …summary of comment…”

1. Introduction

This section is not normative.

This document defines Content Security Policy, a mechanism web applications
can use to mitigate a broad class of content injection vulnerabilities, such
as cross-site scripting (XSS). Content Security Policy is a declarative policy
that lets the authors (or server administrators) of a web application inform
the client about the sources from which the application expects to load
resources.

To mitigate XSS attacks, for example, a web application can declare that it
only expects to load script from specific, trusted sources. This declaration
allows the client to detect and block malicious scripts injected into the
application by an attacker.

Content Security Policy (CSP) is not intended as a first line of defense
against content injection vulnerabilities. Instead, CSP is best used as
defense-in-depth, to reduce the harm caused by content injection attacks. As
a first line of defense against content injection, server operators should
validate their input and encode their output.

There is often a non-trivial amount of work required to apply CSP to an
existing web application. To reap the greatest benefit, authors will need to
move all inline script and style out-of-line, for example into external
scripts, because the user agent cannot determine whether an inline script
was injected by an attacker.

To take advantage of CSP, a web application opts into using CSP by supplying a
Content-Security-Policy HTTP header. Such policies apply to the
current resource representation only. To supply a policy for an entire site,
the server needs to supply a policy with each resource representation.

2. Key Concepts and Terminology

The Augmented Backus-Naur Form (ABNF) notation used in this document is
specified in RFC5234 [ABNF]. We use the #rule extension
defined in [RFC7230].

security policy

security policy directive

security policy directive name

security policy directive value

A security policy refers to both a set of security
preferences for restrictions within which content can operate, and
to a fragment of text that codifies or transmits these preferences.
For example, the following string is a policy which restricts script
and object content:

Security policies contain a set of security policy
directives (script-src and
object-src in the example above), each responsible
for declaring the restrictions for a particular resource type, or
manipulating a specific aspect of the policy’s restrictions. The list
of directives defined by this specification can be found in
§7 Directives.

If their site violates this policy the user agent will send violation
reports to the URL specified in the policy’s report-uri
directive, but allow the violating resources to load regardless. Once a site
has confidence that the policy is appropriate, they can start enforcing the
policy using the Content-Security-Policy header field.

A server MUST NOT send more than one HTTP header field named
Content-Security-Policy-Report-Only with a given
resource representation.

A server MAY send different
Content-Security-Policy-Report-Only header field values
with different representations of the same resource or with different
resources.

Upon receiving an HTTP response containing at least one
Content-Security-Policy-Report-Only header field, the
user agent MUST monitor each of the policies
contained in each such header field.

Authors are strongly encouraged to place meta elements as early
in the document as possible, because policies in meta elements are not
applied to content which preceeds them. In particular, note that resources
fetched or prefetched using the Link HTTP response header
field, and resources fetched or prefetched using link and script
elements which preceed a meta-delivered policy will not be blocked.

Note: A policy specified via a meta element will be enforced
along with any other policies active for the protected resource, regardless
of where they’re specified. The general impact of enforcing multiple
policies is described in §3.5 Enforcing multiple policies..

Note: Modifications to the content attribute of a meta element
after the element has been parsed will be ignored.

The user agent MAY choose to send this header only if the request is for a
resource type which the active policy would effect. That is, given a policy
of img-src example.com, the user agent would send CSP:
active along with requests for images, but might choose not to send
the header with requests for script.

Note: The central reason for including this header is that it hints to a
server that information about redirects might be leaked as a side-effect
of a page’s active policy. If this header is present, a server might decline
to redirect a logged-out user from example.com to
accounts.example.com, for example, as a malicious embedder
might otherwise be able to determine the user’s logged-in status.

3.5. Enforcing multiple policies.

This section is not normative.

The above sections note that when multiple policies are present,
each must be enforced or reported, according to its type. An example
will help clarify how that ought to work in practice. The behavior of
an XMLHttpRequest might seem unclear given a site
that, for whatever reason, delivered the following HTTP headers:

Is a connection to example.com allowed or not? The
short answer is that the connection is not allowed. Enforcing both
policies means that a potential connection would have to pass through
both unscathed. Even though the second policy would allow this
connection, the first policy contains connect-src
'none', so its enforcement blocks the connection. The impact is
that adding additional policies to the list of policies to enforce can
only further restrict the capabilities of the protected resource.

To demonstrate that further, consider a script tag on this page.
The first policy would lock scripts down to 'self',
https://example.com and https://example.net
via the default-src directive. The second, however,
would only allow script from https://example.com/. Script
will only load if it meets both policy’s criteria: in this case, the only
origin that can match is https://example.com, as both
policies allow it.

3.6. Policy applicability

This section is not normative.

Policies are associated with an protected resource, and
enforced or monitored for that resource.
If a resource does not create a new execution context (for example, when
including a script, image, or stylesheet into a document), then any policies
delivered with that resource are discarded without effect. Its execution is
subject to the policy or policies of the including context. The following
table outlines examples of these relationships:

The policy of the embedding resource controls what may be
embedded. The embedded resource, however, is controlled by the
policy delivered with the resource, or the policy of the embedding
resource if the embedded resource is a globally unique
identifier (or a srcdoc frame).

4. Syntax and Algorithms

4.1. Policy Syntax

A Content Security Policy consists of a U+003B SEMICOLON
(;) delimited list of directives. Each directive
consists of a directive name and (optionally) a
directive value, defined by the following ABNF:

If there are characters remaining in token,
skip ahead exactly one character (which must be a
space character).

The remaining characters in token (if any) are
the directive value.

If the set of directives already contains a
directive whose name is a case insensitive match for
directive name, ignore this instance of the directive
and continue to the next token.

Add a directive to the set of
directives with name directive name and value
directive value.

Return the set of directives.

4.2. Source List Syntax

Many CSP directives use a value consisting of a source
list, defined in the ABNF grammar below.

Each source expression in the source list represents a
location from which content of the specified type can be retrieved.
For example, the source expression 'none' represents
the empty set of URLs, and the source expression
'unsafe-inline' represents content supplied inline in the
resource itself.

If the policy contains a nonce-source expression, the
server MUST generate a fresh value for the nonce-value
directive at random and independently each time it transmits a policy.
The generated value SHOULD be at least 128 bits long (before encoding),
and generated via a cryptographically secure random number generator.
This requirement ensures that the nonce-value is
difficult for an attacker to predict.

Note: Using a nonce to whitelist inline script or style is less secure than
not using a nonce, as nonces override the restrictions in the directive in
which they are present. An attacker who can gain access to the nonce can
execute whatever script they like, whenever they like. That said, nonces
provide a substantial improvement over 'unsafe-inline' when
layering a content security policy on top of old code. When considering
'unsafe-inline', authors are encouraged to consider nonces (or
hashes) instead.

The host-char production intentionally contains only
ASCII characters; internationalized domain names cannot be entered
directly into a policy string, but instead MUST be Punycode-encoded
[RFC3492]. For example, the domain üüüüüü.de would be
encoded as xn--tdaaaaaa.de.

NOTE: Though IP addresses do match the grammar above, only
127.0.0.1 will actually match a URL when used in a source
expression (see §4.2.2 Matching Source Expressions for details). The security
properties of IP addresses are suspect, and authors ought to prefer
hostnames to IP addresses whenever possible.

4.2.1. Parsing Source Lists

To parse a source listsource list, the user agent MUST use an algorithm
equivalent to the following:

Note: Characters like U+003B SEMICOLON (;) and
U+002C COMMA (,) cannot appear in source expressions
directly: if you’d like to include these characters in a source
expression, they must be percent
encoded as %3B and %2C respectively.

4.2.2. Matching Source Expressions

A URL url is said to match a source expression for
a protected resource if the following algorithm returns
does match:

If the source expression has a scheme-part
that is not a case insensitive match for url-scheme,
then return does not match.

If the source expression does not have a
scheme, return does not match if any of the following
are true:

the scheme of the protected resource’s URL is a case
insensitive match for HTTP, and
url-scheme is not a case
insensitive match for either HTTP or
HTTPS

the scheme of the protected resource’s URL is
not a case insensitive match for
HTTP, and url-scheme is
not a case insensitive match
for the scheme of the protected resource’s URL.

If the first character of the source expression’s
host-part is an U+002A ASTERISK character
(*) and the remaining characters, including the
leading U+002E FULL STOP character (.), are not a
case insensitive match for the rightmost characters of
url-host, then return does not match.

If the first character of the source expression’s
host-part is not an U+002A ASTERISK
character (*) and url-host is not a
case insensitive match for the source expression’s
host-part, then return does not
match.

Note: A future version of this specification may allow literal
IPv6 and IPv4 addresses, depending on usage and demand. Given the
weak security properties of IP addresses in relation to named
hosts, however, authors are encouraged to prefer the latter
whenever possible.

If the source expression does not contain
a port-part and url-port is not the
default port for url-scheme, then return
does not match.

If the source expression does contain a port-part,
then return does not match if both of the following
are true:

Note: This includes IP addresses. That is, a document at
https://111.111.111.111/ with a policy of
img-src 'self' can load the image
https://111.111.111.111/image.png, as the origins
match.

Otherwise, return does not match.

Note: This algorithm treats the URLs https://example.com/
and https://example.com./ as non-matching. This
is consistent with browser behavior which treats documents served from
these URLs as existing in distinct origins.

Note: No URLs match an empty set of source expressions, such as the set
obtained by parsing the source list 'none'.

4.2.2.1.
Security Considerations for GUID URL schemes

This section is not normative.

As defined above, special URL schemes that refer to specific pieces of
unique content, such as "data:", "blob:" and "filesystem:" are
excluded from matching a policy of * and must be
explicitly listed. Policy authors should note that the content of
such URLs is often derived from a response body or execution in a
Document context, which may be unsafe. Especially for the
default-src and script-src
directives, policy authors should be aware that allowing "data:" URLs
is equivalent to unsafe-inline and allowing "blob:" or
"filesystem:" URLs is equivalent to unsafe-eval.

4.2.2.2. Path Matching

This section is not normative.

The rules for matching source expressions that contain paths
are simpler than they look: paths that end with the '/'
character match all files in a directory and its subdirectories. Paths
that do not end with the '/' character match only one
specific file. A few examples should make this clear:

The source expression example.com has no path,
and therefore matches any file served from that host.

The source expression example.com/scripts/
matches any file in the scripts directory of
example.com, and any of its subdirectories. For
example, both https://example.com/scripts/file.js
and https://example.com/scripts/js/file.js would
match.

The source expression
example.com/scripts/file.js matches only the file
named file.js in the scripts directory
of example.com.

Likewise, the source expression example.com/js
matches only the file named js. In particular, note
that it would not match files inside a directory named
js. Files like example.com/js/file.js
would be matched only if the source expression ended with a
trailing "/", as in example.com/js/.

Note: Query strings have no impact on matching: the source
expression example.com/file matches all of
https://example.com/file,
https://example.com/file?key=value,
https://example.com/file?key=notvalue, and
https://example.com/file?notkey=notvalue.

4.2.2.3. Paths and Redirects

To avoid leaking path information cross-origin (as discussed
in Egor Homakov’s
Using Content-Security-Policy for Evil),
the matching algorithm ignores the path component of a source
expression if the resource being loaded is the result of a
redirect. For example, given a page with an active policy of
img-src example.com not-example.com/path:

Directly loading https://not-example.com/not-path
would fail, as it doesn’t match the policy.

Directly loading https://example.com/redirector
would pass, as it matches example.com.

Assuming that https://example.com/redirector
delivered a redirect response pointing to https://not-example.com/not-path,
the load would succeed, as the initial URL matches example.com,
and the redirect target matches not-example.com/path
if we ignore its path component.

This restriction reduces the granularity of a document’s
policy when redirects are in play, which isn’t wonderful, but
given that we certainly don’t want to allow brute-forcing paths
after redirects, it seems a reasonable compromise.

The relatively long thread
"Remove paths from CSP?"
from public-webappsec@w3.org has more detailed discussion around
alternate proposals.

4.2.3.
The nonce attribute

Nonce sources require a new nonce attribute to be added to
both script and style elements.

The name of the policy directive that was violated. This will
contain the directive whose enforcement triggered the
violation (e.g. "script-src") even if that
directive does not explicitly appear in the policy, but is
implicitly activated via the default-src
directive.

The referrer attribute of the protected
resource, or the empty string if the protected resource has no
referrer.

status-code

The status-code of the HTTP response that
contained the protected resource, if the protected resource was
obtained over HTTP. Otherwise, the number 0.

violated-directive

The policy directive that was violated, as it appears in the
policy. This will contain the default-src directive
in the case of violations caused by falling back to the
default sources when enforcing
a directive.

If a specific line or a specific file can be identified as the
cause of the violation (for example, script execution that violates
the script-src directive), the user agent MAY add the
following keys and values to violation:

Note: blocked-uri will not contain the final location of a
resource that was blocked after one or more redirects. It instead will
contain only the location that the protected resource requested, before
any redirects were followed.

To send violation reports, the user agent MUST use an
algorithm equivalent to the following:

If the user agent has already sent a violation report for
the protected resource to report URL, and that report
contained an entity body that exactly matches
report body, the user agent MAY abort these
steps and continue to the next report URL.

Queue a task to fetchreport URL from the origin of the protected resource,
with the synchronous flag not set, using HTTP method
POST, with a Content-Type header field
of application/csp-report, and an entity body
consisting of report body. If the origin of
report URL is not the same as the
origin of the protected resource, the block cookies flag MUST also
be set. The user agent MUST NOT follow redirects when fetching this
resource. (Note: The user agent ignores the fetched resource.)
The task source for these
tasks is the Content Security Policy task
source.

Note: This section of the specification should not be interpreted
as limiting user agents' ability to apply restrictions to violation
reports in order to limit data leakage above and beyond what these
algorithms specify. For example, a user agent might offer users the
option of disabling reporting entirely.

5. Processing Model

To enforce a policy, the user agent MUST parse the policy
and enforce each of the directives contained in the policy, where the
specific requirements for enforcing each directive are defined separately
for each directive (See §7 Directives, below).

Generally speaking, enforcing a directive prevents the protected
resource from performing certain actions, such as loading scripts from
URLs other than those indicated in a source list. These restrictions
make it more difficult for an attacker to abuse an injection
vulnerability in the resource because the attacker will be unable to
usurp the resource’s privileges that have been restricted in this
way.

Note: User agents may allow users to modify or bypass policy enforcement
through user preferences, bookmarklets, third-party additions to the user
agent, and other such mechanisms.

To monitor a policy, the user agent MUST parse the policy
and monitor each of the directives contained in the policy.

Monitoring a directive does not prevent the protected resource from
undertaking any actions. Instead, any actions that would have been
prevented by the directives are allowed, but a violation report is
generated and reported to the
developer of the web application. Monitoring a policy is useful for
testing whether enforcing the policy will cause the web application to
malfunction.

A server MAY cause user agents to monitor one policy while enforcing
another policy by returning both Content-Security-Policy
and Content-Security-Policy-Report-Only header fields.
For example, if a server operator may wish to enforce one policy but
experiment with a stricter policy, she can monitor the stricter policy while
enforcing the original policy. Once the server operator is satisfied that
the stricter policy does not break the web application, the server operator
can start enforcing the stricter policy.

If the user agent monitors or enforces a policy that does not contain any
directives, the user agent SHOULD report a warning message in the
developer console.

If the user agent monitors or enforces a policy that contains
an unrecognized directive, the user agent SHOULD report a warning message
in the developer console indicating the name of the unrecognized directive.

Whenever a user agent creates an iframesrcdoc document in a browsing context nested in the
protected resource, if the user agent is monitoring any policies for the
protected resource, the user agent MUST monitor those policies on
the iframesrcdoc document as well.

6. Script Interfaces

6.1. Strawman DOM API

This is a sketch of what an API might look like. It is neither complete nor
finalized; take it as an outline for discussion, nothing more. The general
idea is to model CSP as a set of SecurityPolicy objects, each
composed of a sequence of directives.

The following is what I think we’ll need for source-list directives
(§4.2 Source List Syntax). It’ll need some adjustment to deal well with
the other directive types.

include a default-src directive, which covers both
scripts and plugins.

In either case, authors SHOULD NOT include either
'unsafe-inline' or data: as valid sources in
their policies. Both enable XSS attacks by allowing code to be included
directly in the document itself; they are best avoided completely.

7.1. base-uri

The base-uri directive restricts the URLs that can
be used to specify the document base URL. The syntax for
the name and value of the directive are described by the following ABNF
grammar:

7.2. child-src

The child-src directive governs the creation of
nested browsing contexts as well as Worker execution
contexts. The syntax for the name and value of the directive are described
by the following ABNF grammar:

7.3.1. Usage

This section is not normative.

JavaScript offers a few mechanisms that directly connect to an
external server to send or receive information. EventSource
maintains an open HTTP connection to a server in order to receive push
notifications, WebSockets open a bidirectional communication
channel between your browser and a server, and XMLHttpRequest
makes arbitrary HTTP requests on your behalf. These are powerful APIs that
enable useful functionality, but also provide tempting avenues for data
exfiltration.

The connect-src directive allows you to ensure that
these sorts of connections are only opened to origins you trust.
Sending a policy that defines a list of source expressions for this
directive is straightforward. For example, to limit connections to
only example.com, send the following header:

If not specified explicitly in the policy, the directives listed
above will use the default sources as their source list.

7.4.1. Usage

This section is not normative.

default-src, as the name implies, serves as a default
source list which the other source list-style directives will use as
a fallback if they’re not otherwise explicitly set. That is, consider
the following policy declaration:

Under this policy, fonts, frames, images, media, objects, scripts,
and styles will all only load from the same origin as the protected
resource, and connections will only be made to the same origin. Adding
a more specific declaration to the policy would completely override
the default source list for that resource type.

Under this new policy, fonts, frames, and etc. continue to be load
from the same origin, but scripts will only load from
example.com. There’s no inheritance; the
script-src directive sets the allowed sources of
script, and the default list is not used for that resource type.

Given this behavior, one good way of building a policy for a site
would be to begin with a default-src of
'none', and to build up a policy from there that contains
only those resource types which are actually in use for the page you’d
like to protect. If you don’t use webfonts, for instance, there’s no
reason to specify a source list for font-src;
specifying only those resource types a page uses ensures that the
possible attack surface for that page remains as small as possible.

7.5. font-src

The font-src directive restricts from where the
protected resource can load fonts. The syntax for the name and value
of the directive are described by the following ABNF grammar:

Note: form-action does not fall back to the default
sources when the directive is not defined. That is, a policy that
defines default-src 'none' but not
form-action will still allow form submissions to any
target.

7.7. frame-ancestors

The frame-ancestors directive indicates whether the
user agent should allow embedding the resource using a frame,
iframe, object, embed or applet element, or equivalent
functionality in non-HTML resources. Resources can use this directive to
avoid many UI Redressing [UIREDRESS] attacks by avoiding being embedded
into potentially hostile contexts.

The syntax for the name and value of the directive are described by the
following ABNF grammar:

Steps 3.2.2 and 3.2.3 ensure that the blocked frame appears to be a
normal cross-origin document’s load. If these steps are ignored,
leakage of a document’s policy state is possible.

The frame-ancestors directive MUST be ignored
when monitoring a policy, and when a contained in a
policy defined via a meta element.

Note: frame-ancestors does not fall back to the
default sources when the directive is not defined. That is, a policy
that defines default-src 'none' but not
frame-ancestors will still allow the resource to be framed from
anywhere.

When generating a violation report for a frame-ancestors
violation, the user agent MUST NOT include the value of the embedding
ancestor as a blocked-uri value unless it is same-origin with
the protected resource, as disclosing the value of cross-origin ancestors
is a violation of the Same-Origin Policy.

7.7.1.
Relation to X-Frame-Options

This directive is similar to the X-Frame-Options header that
several user agents have implemented. The 'none' source
expression is roughly equivalent to that header’s DENY,
'self' to SAMEORIGIN, and so on. The major
difference is that many user agents implement SAMEORIGIN such
that it only matches against the top-level document’s location. This
directive checks each ancestor. If any ancestor doesn’t match, the load
is cancelled. [RFC7034]

The frame-ancestors directive obsoletes the
X-Frame-Options header. If a resource has both policies,
the frame-ancestors policy SHOULD be enforced and the
X-Frame-Options policy SHOULD be ignored.

7.7.2. Multiple Host Source Values

This section is not normative.

Multiple source-list expressions are allowed in a single policy (in contrast
to X-Frame-Options, which allows only one) to enable
scenarios involving embedded application components that are multiple levels
below the top-level browsing context.

Many common scenarios for permissioned embedding (e.g. embeddable payment,
sharing or social apps) involve potentially many hundreds or thousands of
valid source-list expressions, but it is strongly recommended
against accommodating such scenarios with a static
frame-ancestors directive listing multiple values. In such
cases it is beneficial to generate this value dynamically, based on an
HTTP Referer header or an explicitly passed-in value, to allow only the
sources necessary for each given embedding of the resource.

Consider a service providing a payments application at
https://payments/makeEmbedded. The service allows this resource
to be embedded by both merchant Alice and merchant Bob, who compete with each
other. Sending:

would allow Bob to re-frame Alice’s resource and create fraudulent clicks,
perhaps discrediting Alice with her customers or the payments service. If the
payments service used additional information (e.g. as part of a URL like
https://payments/makeEmbedded?merchant=alice) to send
individually-tailored headers listing only the source-list expressions
needed by each merchant, this attack would be eliminated.

7.8. frame-src

The frame-src directive is deprecated.
Authors who wish to govern nested browsing contexts SHOULD use the
child-src directive instead.

The frame-src directive restricts from where the
protected resource can embed frames. The syntax for the name
and value of the directive are described by the following ABNF
grammar:

Requesting data for an image, such as when processing the
src or srcset attributes of an img element, the
src attribute of an input element with a type of
image, the poster attribute of a video element,
the url(), image() or image-set() values on any
Cascading Style Sheets (CSS) property that is capable of loading an image
[CSS4-IMAGES], or the href attribute of a link element
with an image-related rel attribute, such as icon.

7.10. manifest-src

The manifest-src directive restricts which
application manifest [MANIFEST] the user agent may apply to the protected
resource. The syntax for the name and value of the directive are described by
the following ABNF grammar:

7.11. media-src

The media-src directive restricts from where the
protected resource can load video, audio, and associated text tracks.
The syntax for the name and value of the directive are described by the
following ABNF grammar:

It is not required that the consumer of the element’s data be a
plugin in order for the object-src directive to be
enforced. Data for any object, embed, or applet element MUST
match the allowed object sources in order to be fetched. This is true
even when the element data is semantically equivalent to content which would
otherwise be restricted by one of the other §7 Directives, such as an
object element with a text/html MIME type.

7.13. plugin-types

The plugin-types directive restricts the set
of plugins that can be invoked by the protected resource by limiting
the types of resources that can be embedded. The syntax for the name
and value of the directive are described by the following ABNF
grammar:

Whenever the user agent would instantiate a plugin
to handle resource while enforcing the plugin-types
directive, the user agent MUST instead act as though the plugin reported an
error andreport a violation if any of the following
conditions hold:

The plugin is embedded into the protected resource via an
object or embed element that does not explicitly
declare a MIME type via a type
attribute.

7.13.1. Usage

This section is not normative.

The plugin-types directive whitelists a certain set
of MIME types that can be embedded in a protected resource. For
example, a site might want to ensure that PDF content loads, but that
no other plugins can be instantiated. The following directive would
satisfy that requirement:

Resources embedded via an embed or
object element delivered with an
application/pdf content type would be rendered in the
appropriate plugin; resources delivered with some other content type
would be blocked. Multiple types can be specified, in any order. If the
site decided to additionally allow Flash at some point in the future, it
could do so with the following directive:

Note: Wildcards are not accepted in the plugin-types
directive. Only the resource types explicitly listed in the directive
will be allowed.

7.13.2.
Predeclaration of expected media types

This section is not normative.

Enforcing the plugin-types directive requires that
object and embed
elements declare the expected media type of the resource they include via
the type attribute. If an author expects
to load a PDF, she could specify this as follows:

<object data="resource" type="application/pdf"></object>

If resource isn’t actually a PDF file, it won’t
load. This prevents certain types of attacks that rely on serving
content that unexpectedly invokes a plugin other than that which the
author intended.

Note: resource will not load in this scenario even
if its media type is otherwise whitelisted: resources will only load
when their media type is whitelisted and matches the
declared type in their containing element.

7.14. reflected-xss

The reflected-xss directive instructs a user agent
to activate or deactivate any heuristics used to filter or block
reflected cross-site scripting attacks. The syntax for the name and
value of the directive are described by the following ABNF grammar:

A user agent with support for XSS protection MUST enforce this
directive as follows:

If the value of the directive is allow, the user
agent MUST disable its active protections against reflected cross-site
scripting attacks for the protected resource.

If the value of the directive is filter, the user
agent MUST enable its active protections against reflected cross-site
scripting attacks for the protected resource. This might result in
filtering script that is believed to be reflected being filtered or
selectively blocking script execution.

If the value of the directive is block, the user
agent MUST stop rendering the protected resource upon detection of
reflected script, and instead act as if there was a fatal network
error and no resource was obtained, andreport a
violation:

If the user agent’s active protections against reflected cross-site
scripting attacks detect or prevent script execution, the user agent
MUST report a violation.

Note: The reflected-xss directive will be ignored if
contained within a
meta element.

7.14.1.
Relationship to X-XSS-Protection

This directive is meant to subsume the functionality provided by
the proprietary X-XSS-Protection HTTP header which is
supported by a number of user agents. Roughly speaking:

reflected-xss allow is equivalent to
X-XSS-Protection: 0

reflected-xss filter is equivalent to
X-XSS-Protection: 1

reflected-xss block is equivalent to
X-XSS-Protection: 1; mode=block

7.15. report-uri

The report-uri directive specifies a URL to
which the user agent sends reports about policy violation. The syntax
for the name and value of the directive are described by the following
ABNF grammar:

The set of report URLs is the value of the
report-uri directive, each resolved relative to the
protected resource’s URL.

The process of sending violation reports to the URLs specified in
this directive’s value is defined in this document’s
§4.4 Reporting section.

Note: The report-uri directive will be ignored if contained
within a meta
element.

7.16. sandbox

The sandbox directive specifies an HTML
sandbox policy that the user agent applies to the protected resource.
The syntax for the name and value of the directive are described by
the following ABNF grammar:

The sandbox directive will be ignored when monitoring
a policy, and when contained in a policy defined via a
meta element.
Moreover, this directive has no effect when monitored, and has no
reporting requirements.

7.16.1. Sandboxing and Workers

When delivered via an HTTP header, a Content Security Policy may indicate
that sandboxing flags ought to be applied to a JavaScript execution
environment that is not a Document. Of particular interest is the
script content intended for use as a Worker, Shared Worker, or Service
Worker. Many of the sandboxing flags do not apply to such environments, but
allow-scripts and
allow-same-origin have special
requirements.

When a resource is loaded while executing the runs a
Worker algorithm, the user agent MUST act as if there was
a fatal network error and no resource could be obtained if either of the
following conditions holds:

The sandbox directive delivered with the resource
does not contain the
allow-same-origin flag, and
the creation of the new execution context requires it to be same-origin
with its creating context.

7.16.2. Usage

This section is not normative.

HTML5 defines a sandbox attribute for
iframe elements, intended to allow web authors
to reduce the risk of including potentially untrusted content by imposing
restrictions on that content’s abilities. When the attribute is set,
the content is forced into a unique origin, prevented from submitting
forms, running script, creating or navigating other browsing contexts,
and prevented from running plugins. These restrictions can be loosened
by setting certain flags as the attribute’s value.

The sandbox directive allows any resource, framed or
not, to ask for the same sorts of restrictions to be applied to
itself.

For example, a message board or email system might provide
downloads of arbitrary attachments provided by other users. Attacks
that rely on tricking a client into rendering one of these attachments
could be mitigated by requesting that resources only be rendered in a
very restrictive sandbox. Sending the sandbox directive
with an empty value establishes such an environment:

More trusted resources might be allowed to run in an environment
with fewer restrictions by adding allow-* flags to the
directive’s value. For example, you can allow a page that you trust
to run script, while ensuring that it isn’t treated as same-origin
with the rest of your site. This can be accomplished by sending the
sandbox directive with the
allow-scripts flag:

Note: Like the rest of Content Security Policy, the sandbox
directive is meant as a defense-in-depth. Web authors would be well-served
to use it in addition to standard sniffing-mitigation and
privilege-reduction techniques.

7.17. script-src

The script-src directive restricts which scripts the
protected resource can execute. The directive also controls other resources,
such as XSLT style sheets [XSLT], which can cause the user agent to
execute script. The syntax for the name and value of the directive are
described by the following ABNF grammar:

Requesting a script while invoking the importScripts
method on a WorkerGlobalScope object. [WORKERS]

Requesting an HTML component, such as
when processing the href attribute of a link
element with a rel attribute containing the token
import. [HTML-IMPORTS]

Requesting an Extensible Stylesheet Language Transformations
(XSLT) [XSLT], such as when processing the
<?xml-stylesheet?> processing directive in an XML
document [XML11], the href attributes
on <xsl:include> and <xsl:import>
elements.

The script-src directive lets developers specify
exactly which script elements on a page were intentionally included
for execution. Ideally, developers would avoid inline script entirely
and whitelist scripts by URL. However, in some cases, removing inline
scripts can be difficult or impossible. For those cases, developers can
whitelist scripts using a randomly generated nonce.

Usage is straightforward. For each request, the server
generates a unique value at random, and includes it in the
Content-Security-Policy header:

This same value is then applied as a nonce attribute
to each script element that ought to be
executed. For example, if the server generated the random value
Nc3n83cnSAd3wc3Sasdfn939hc3, the server would send the
following policy:

Note that the nonce’s value is not a hash or signature
that verifies the contents of the script resources. It’s quite simply
a random string that informs the user agent which scripts were
intentionally included in the page.

Script elements with the proper nonce execute, regardless of
whether they’re inline or external. Script elements without the
proper nonce don’t execute unless their URLs are whitelisted.
Even if an attacker is able to inject markup into the protected
resource, the attack will be blocked by the attacker’s inability
to guess the random value.

Each inline script block’s contents are hashed, and compared against
the whitelisted value. If there’s a match, the script is executed. For
example, the SHA-256 digest of alert('Hello, world.'); is
qznLcsROx4GACP2dm0UCKCzCG+HiZ1guq6ZZDob/Tng=.

You can obtain the digest of a string on the command line simply
via the openssl program. For example:

Note also that the hash applies only to inline script. An
externalized script containing the value
alert('Hello, world.'); would not execute if its
origin was not whitelisted as a valid source of script.

7.18. style-src

The style-src directive restricts which styles the
user may applies to the protected resource. The syntax for the name and
value of the directive are described by the following ABNF grammar:

Requesting an external stylesheet when processing the
href of a link element
whose rel attribute contains the token
stylesheet.

Requesting an external stylesheet when processing the <<@import>>
directive.

Requesting an external stylesheet when processing a Link
HTTP response header field [RFC5988].

Note: As this stylesheet might be prefetched before a Document
actually exists, user agents will need to carefully consider how to
instantiate a meaningful policy against which to compare this
request. See §10.1 Processing Complications for more detail.

Note: The style-src directive does not restrict the
use of XSLT. XSLT is restricted by the script-src
directive because the security consequences of including an untrusted
XSLT stylesheet are similar to those incurred by including an
untrusted script.

8. Examples

8.1. Sample Policy Definitions

An auction site wishes to load images from any URL, plugin content from a
list of trusted media providers (including a content distribution network),
and scripts only from a server under its control hosting sanitized
ECMAScript:

This policy allows inline content (such as inline
script elements), use of eval,
and loading resources over https. Note: This policy does
not provide any protection from cross-site scripting vulnerabilities.

A website that relies on inline script elements
wishes to ensure that script is only executed from its own origin, and those
elements it intentionally inserted inline:

9. Security Considerations

9.1. Cascading Style Sheet (CSS) Parsing

The style-src directive restricts the locations from
which the protected resource can load styles. However, if the user agent uses a
lax CSS parsing algorithm, an attacker might be able to trick the user
agent into accepting malicious "stylesheets" hosted by an otherwise
trustworthy origin.

These attacks are similar to the CSS
cross-origin data leakage attack described by Chris Evans in 2009.
User agents SHOULD defend against both attacks using the same
mechanism: stricter CSS parsing rules for style sheets with improper
MIME types.

9.2. Violation Reports

The violation reporting mechanism in this document has been
designed to mitigate the risk that a malicious web site could use
violation reports to probe the behavior of other servers. For example,
consider a malicious web site that white lists https://example.com
as a source of images. If the malicious site attempts to load
https://example.com/login as an image, and the
example.com server redirects to an identity provider (e.g.,
identityprovider.example.net), CSP will block the request.
If violation reports contained the full blocked URL, the violation
report might contain sensitive information contained in the redirected URL,
such as session identifiers or purported identities. For this reason, the
user agent includes only the origin of the blocked URL.

10. Implementation Considerations

The Content-Security-Policy header is an end-to-end
header. It is processed and enforced at the client and, therefore,
SHOULD NOT be modified or removed by proxies or other intermediaries not
in the same administrative domain as the resource.

The originating administrative domain for a resource might wish to
apply a Content-Security-Policy header outside of the
immediate context of an application. For example, a large organization
might have many resources and applications managed by different
individuals or teams but all subject to a uniform organizational
standard. In such situations, a Content-Security-Policy
header might be added or combined with an existing one at a network-edge
security gateway device or web application firewall. To enforce multiple
policies, the administrator SHOULD combine the policy into a single header.
An administrator might wish to use different combination algorithms
depending on his or her intended semantics.

One sensible policy combination algorithm is to start by allowing a
default set of sources and then letting individual upstream resource
owners expand the set of allowed sources by including additional origins.
In this approach, the resultant policy is the union of all allowed
origins in the input policies.

Another sensible policy combination algorithm is to intersect the
given policies. This approach enforces that content comes from a certain
whitelist of origins, for example, preventing developers from including
third-party scripts or content in violation of organizational standards
and practices. In this approach, the combination algorithm forms the
combined policy by removing disallowed hosts from the policies supplied
by upstream resource owners.

Interactions between the default-src and other directives
SHOULD be given special consideration when combining policies. If none
of the policies contains a default-src directive, adding new
src directives results in a more restrictive policy. However, if one or
more of the input policies contain a default-src directive,
adding new src directives might result in a less restrictive policy, for
example, if the more specific directive contains a more permissive set of
allowed origins.

Using a more restrictive policy than the input policy authored by the
resource owner might prevent the resource from rendering or operating as
intended.

Note: Migration to HTTPS from HTTP
may require updates to the policy in order to keep things running as
before. Source expressions like http://example.com do
not match HTTPS resources. For example,
administrators SHOULD carefully examine existing policies before rolling
out HTTP Strict Transport Security
headers for an application. [RFC6797]

Server administrators MAY wish to send multiple policies if different
reporting options are desired for subsets of an overall policy. For instance,
the following headers:

would have the same effect, as the comma splits the header during parsing.

10.1. Processing Complications

Many user agents implement some form of optimistic resource fetching algorithm
to speed up page loads. In implementing these features, user agents MUST
ensure that these optimizations do not alter the behavior of the page’s
security policy.

Here, we’ll note a few potential complications that could cause bugs in
implementations:

The frame-ancestor directive MUST take effect before a document is
loaded into a nested browsing context, and certainly before script
is potentially executed. One way to approach this constraint is to perform
the ancestor check defined in §7.7 frame-ancestors while parsing
the document’s headers. This might mean that no document object is
available at all, which can complicate checks against 'self',
and scheme- or port-relative source expressions.

Likewise, the Link HTTP response header could generate
requests for stylesheet resources before a document is available. User
agents MUST ensure that any policy contained in the response headers is
parsed and effective before these requests are generated. For
example, a response returning the following headers:

Conformance

Document conventions

Conformance requirements are expressed with a combination of
descriptive assertions and RFC 2119 terminology. The key words "MUST",
"MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
"RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this
document are to be interpreted as described in RFC 2119.
However, for readability, these words do not appear in all uppercase
letters in this specification.

All of the text of this specification is normative except sections
explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words "for example"
or are set apart from the normative text with class="example",
like this:

This is an example of an informative example.

Informative notes begin with the word "Note" and are set apart from the
normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as
"strip any leading space characters" or "return false and abort these
steps") are to be interpreted with the meaning of the key word ("must",
"should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be
implemented in any manner, so long as the end result is equivalent. In
particular, the algorithms defined in this specification are intended to
be easy to understand and are not intended to be performant. Implementers
are encouraged to optimize.

Conformance Classes

A conformant user agent must implement all the requirements
listed in this specification that are applicable to user agents.

A conformant server must implement all the requirements listed
in this specification that are applicable to servers.