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.

Introduction

This document defines Content Security Policy, a mechanism web applications can use to mitigate the 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 restrict from where the application can load resources.

To mitigate XSS, for example, a web application can restrict itself to loading scripts only from known, trusted URIs, making it difficult for an attacker who can inject content into the web application to inject malicious script.

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.

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 needs to opt into using CSP by supplying a Content-Security-Policy HTTP header or an appropriate HTML meta element. Such policies apply the current document only. To supply a policy for an entire site, the server need to supply a policy along with each resource representation.

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.

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

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

Terminology

This section defines several terms used throughout the document.

The term security policy, or simply policy, for the purposes of this specification refers to either:

  1. a set of security preferences for restricting the behavior of content within a given document, or
  2. a fragment of text that codifies these preferences.

The security policies defined by this document are applied by a user-agent on a per-resource representation basis. Specifically, when a user agent receives a policy along with the representation of a given resource, that policy applies to that resource representation only. That resource representation is often referred to in this document as the protected document.

A server transmits its security policy for a particular resource as a collection of directives, such as default-src 'self', each of which controls a specific set of privileges for a document rendered by a user-agent. More details are provided in the directives section.

A directive consists of a directive name, which indicates the privileges controlled by the directive, and a directive value, which specifies the restrictions the policy imposes on those privileges.

Fetching resources requires resolving and parsing URLs. The algorithms for resolving a URL and parsing a URL are defined in the HTML5 standard [[!HTML5]].

The term origin is defined in the Origin specification. [ORIGIN]

The term URI is defined in the URI specification. [[!URI]]

The <script>, <object>, <embed>, <img>, <video>, <audio>, <link>, <frame> and <iframe> elements are defined in the HTML5 standard. [[!HTML5]].

The <applet> element is defined in the HTML 4.01 standard. [[!HTML401]].

The @font-face CSS rule is defined in the CSS Fonts Module Level 3 standard. [[!CSS3FONT]]

The XMLHttpRequest object is defined in the XMLHttpRequest standard. [[!XMLHTTPREQUEST]]

The WebSocket object is defined in the WebSocket standard. [WEBSOCKET].

The EventSource object is defined in the EventSource standard. [EVENTSOURCE].

The Augmented Backus-Naur Form (ABNF) notation used in this document is specified in RFC 5234. [[!ABNF]]

The following core rules are included by reference, as defined in [ABNF Appendix B.1]: ALPHA (letters), DIGIT (decimal 0-9), WSP (white space) and VCHAR (printing characters).

Framework

This section defines the general framework for content security policies, including the delivery mechanisms and general syntax for policies. The next section contains the details of the specific directives introduced in this specification.

Policy Delivery

The policy can be delivered from the server to the client via an HTTP response header or an HTML meta element.

Of the two delivery mechanisms, servers SHOULD use the HTTP response header mechanism whenever possible because, when using the meta element mechanism, there is a period of time between when the user agent begins to process the document and when the user agent encounters the meta element when the document is not protected by the policy.

Content-Security-Policy Header Field

The Content-Security-Policy header field is the preferred mechanism for delivering a CSP policy.

A server MAY supply one or more CSP policies in HTTP response header fields named Content-Security-Policy along with the protected document.

Upon receiving an HTTP response containing at least one Content-Security-Policy header field, the user agent MUST enforce the combination of all the policies contained in these header fields.

Content-Security-Policy-Report-Only Header Field

The Content-Security-Policy-Report-Only header field lets server experiment with CSP by monitoring (rather than enforcing) a policy. This feature lets server operators develop their security policy iteratively. They can deploy a report-only policy based on their best estimate of how their site behaves. If their site violates this policy, instead of breaking the site, the user agent will send violation reports to a URI specified in the policy. Once a site has confidence that the policy is appropriate, they can promote the report-only policy to normal blocking mode.

A server MAY supply one or more CSP policies in HTTP response header fields named Content-Security-Policy-Report-Only along with the protected document.

If a server supplies at least one Content-Security-Policy-Report-Only header field in an HTTP response, the server MUST NOT supply any Content-Security-Policy header fields.

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

HTML meta Element

The server MAY supply a CSP policy in an HTML meta element with an http-equiv attribute that is a case insensitive match for either Content-Security-Policy or Content-Security-Policy-Report-Only.

Add the following entries to the pragma directives for the meta element:

Content security policy (http-equiv="content-security-policy")
  1. If the document already has a csp-policy, abort these steps.
  2. If the meta element lacks a content attribute, abort these steps.
  3. Enforce the CSP policy contained in the content attribute of the meta element.
Content security policy, report only (http-equiv="content-security-policy-report-only")
  1. If the document already has a csp-policy, abort these steps.
  2. If the meta element lacks a content attribute, abort these steps.
  3. Monitor the CSP policy contained in the content attribute of the meta element.

Syntax

Policies

A CSP policy consists of a U+003B SEMICOLON (;) delimited list of directives:

policy            = directive-list
directive-list    = [ directive *( ";" [ directive ] ) ]

Each directive consists of a directive-name and (optionally) a directive-value:

directive         = *WSP [ directive-name [ WSP directive-value ] ]
directive-name    = 1*( ALPHA / DIGIT / "-" )
directive-value   = *( WSP / <VCHAR except ";"> )

To parse a CSP policy policy, the user agent MUST use an algorithm equivalent to the following:

  1. Let the set of directives be the empty set.
  2. For each token returned by strictly splitting the string policy on the character U+003B SEMICOLON (;):
    1. Skip whitespace.
    2. Collect a sequence of characters that are not space characters. The collected characters are the directive name.
    3. If position doesn't point past the end of the token, skip ahead one character (which must be a space character).
    4. The remaining characters in token (if any) are the directive value.
    5. If the set of directives already contains a directive with name directive name, ignore this instance of the directive and continue to the next token.
    6. Add a directive to the set of directives with name directive name and value directive value.
  3. Return the set of directives.

Source List

Many CSP directives use a value consisting of a source list.

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 'self' represents the set of URIs which are in the same origin as the protected document and the source expression 'unsafe-inline' represents content supplied inline in the document itself.

source-list       = *WSP [ source-expression *( 1*WSP source-expression ) *WSP ]
                  / *WSP "'none'" *WSP
source-expression = scheme-source / host-source / keyword-source
scheme-source     = scheme ":"
host-source       = ( [ scheme "://" ] host [ port ] )
keyword-source    = "'self'" / "'unsafe-inline'" / "'unsafe-eval'"
scheme            = <scheme> production from RFC 3986
host              = "*" / [ "*." ] 1*host-char *( "." 1*host-char )
host-char         = ALPHA / DIGIT / "-"
port              = ":" ( 1*DIGIT / "*" )

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

  1. If source list (with leading and trailing whitespace stripped) is a case insensitive match for the string 'none' (including the quotation marks), return the empty set.
  2. Let the set of source expressions be the empty set.
  3. For each token returned by splitting source list on spaces, if the token matches the grammar for source-expression, add the token to the set of source expressions.
  4. Return the set of source expressions.

To check whether a URI matches a source expression, the user agent MUST use an algorithm equivalent to the following:

  1. If the source expression a single U+002A ASTERISK character (*), then return does match.
  2. If the source expression matches the grammar for scheme-source, then the URI matches the source expression of the URI's scheme is a case-insensitive match for the source expression's scheme.
  3. Otherwise, if the source expression matches the grammar for host-source:
    1. If the URI does not contain a host, then return does not match.
    2. Let scheme, host, and port be the scheme, host, and port of the URI, respectively. If the URI does not have a port, then let port be the default port for scheme.
    3. If the source expression has a scheme that is not a case insensitive match for scheme, then return does not match.
    4. If scheme is not a case insensitive match for the scheme of the protected document's URI, then return does not match.
      FIXME: Should we allow HTTPS when the document's scheme is HTTP?
    5. If the first character of the source expression's host 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 host, then return does not match.
    6. If host is not a case insensitive match for the source expression's host, then return does not match.
    7. If the source expression does not contain a port and port is not the default port for scheme, then return does not match.
    8. If the source expression does contain a port that (a) does not contain an U+002A ASTERISK character (*) and (b) does not represent the same number as port, then return does not match.
    9. Return does match.
  4. Otherwise, if the source expression is a case insensitive match for 'self' (including the quotation marks), then return the URI matches the source expression if the URI has the same scheme, host, and port as the document's URI.
  5. Otherwise, the URI does not match the source expression.

A URI matches a source list, if, and only if, the URI matches at least one source expression in the set of source expressions obtained by parsing the source list. Notice that no URIs match an empty set of source expressions, such as the set obtained by parsing the source list 'none'.

Processing Model

To enforce a CSP 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 Directives, below).

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

Enforcing a CSP policy SHOULD NOT interfere with the operation of user-supplied scripts such as third-party user-agent add-ons and JavaScript bookmarklets.

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

Generally speaking, monitoring a directive does not prevent the protected document from undertaking any actions. Instead, any actions that would have been prevented by the directive are instead reported to the developer of the web application. Monitoring a CSP policy is most useful for testing whether enforcing the policy will break the web application.

If the user agent monitors or enforces a CSP 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 CSP 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.

To enforce the combination of one or more policies, the user agent MUST enforce each policy. For example, if an action is prevented by at least one of the policies, then the action will be prevented by the combination of the policies.

To monitor the combination of one or more policies, the user agent MUST monitor each each policy.

Directives

This section describes the content security policy directives introduced in this specification.

In order to protect against Cross-site Scripting (XSS), authors SHOULD include

In either case, authors SHOULD NOT include 'unsafe-inline' in their CSP policies if they wish to protect themselves against XSS.

default-src

The default-src directive sets a default source list for a number of directives. The syntax for the name and value of the directive are described by the following ABNF grammar:

directive-name    = "default-src"
directive-value   = source-list

Let the default sources be the result of parsing the directive's value as a source list.

To enforce the default-src directive, the user agent MUST enforce the following directives:

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

script-src

The script-src directive restricts which scripts the protected document can execute. The directive also controls other resources, such as XSLT stylesheets, 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:

directive-name    = "script-src"
directive-value   = source-list

If the policy contains an explicit script-src, let the allowed script sources be the result of parsing the directive's value as a source list. Otherwise, let the allowed script sources be the default sources

If 'unsafe-inline' is not in allowed script sources:

If 'unsafe-eval' is not in allowed script sources:

The term callable refers to an object whose interface has one or more callers as defined in the Web IDL specification [[!WEBIDL]].

Whenever the user agent fetches a URI (including when following redirects) in the course of one of the following activities, if the URI does not match the allowed script sources, the user agent MUST act as if it had received an empty HTTP 400 response:

object-src

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

directive-name    = "object-src"
directive-value   = source-list

If the policy contains an explicit object-src, let the allowed object sources be the result of parsing the directive's value as a source list. Otherwise, let the allowed object sources be the default sources

Whenever the user agent fetches a URI (including when following redirects) in the course of one of the following activities, if the URI does not match the allowed object sources, the user agent MUST act as if it had received an empty HTTP 400 response:

Whenever the user agent would load a plug-in without an associated URI (e.g., because the object element lacked a data attribute), if the protected document's URI does not match the allowed object sources, the user agent MUST NOT load the plug-in.

style-src

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

directive-name    = "style-src"
directive-value   = source-list

If the policy contains an explicit style-src, let the allowed style sources be the result of parsing the directive's value as a source list. Otherwise, let the allowed style sources be the default sources

If 'unsafe-inline' is not in allowed style sources:

Note: These restrictions on inline do not prevent the user agent from applying style from an external stylesheet (e.g., found via <link rel="stylesheet">). The user agent is also not prevented from applying style from CSSOM.

Whenever the user agent fetches a URI (including when following redirects) in the course of one of the following activities, if the URI does not match the allowed style sources, the user agent MUST act as if it had received an empty HTTP 400 response:

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.

img-src

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

directive-name    = "img-src"
directive-value   = source-list

If the policy contains an explicit img-src, let the allowed image sources be the result of parsing the directive's value as a source list. Otherwise, let the allowed image sources be the default sources

Whenever the user agent fetches a URI (including when following redirects) in the course of one of the following activities, if the URI does not match the allowed image sources, the user agent MUST act as if it had received an empty HTTP 400 response:

Should the user agent fire the error event when one of these loads fails?

media-src

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

directive-name    = "media-src"
directive-value   = source-list

If the policy contains an explicit media-src, let the allowed media sources be the result of parsing the directive's value as a source list. Otherwise, let the allowed media sources be the default sources

Whenever the user agent fetches a URI (including when following redirects) in the course of one of the following activities, if the URI does not match the allowed media sources, the user agent MUST act as if it had received an empty HTTP 400 response:

frame-src

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

directive-name    = "frame-src"
directive-value   = source-list

If the policy contains an explicit frame-src, let the allowed frame sources be the result of parsing the directive's value as a source list. Otherwise, let the allowed frame sources be the default sources

Whenever the user agent fetches a URI (including when following redirects) in the course of one of the following activities, if the URI does not match the allowed frame sources, the user agent MUST act as if it had received an empty HTTP 400 response:

How does this work for the object element? We don't know whether the request is going to lead to a plug-in or a frame until we get the response back and can look at the MIME type.

font-src

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

directive-name    = "font-src"
directive-value   = source-list

If the policy contains an explicit font-src, let the allowed font sources be the result of parsing the directive's value as a source list. Otherwise, let the allowed font sources be the default sources

Whenever the user agent fetches a URI (including when following redirects) in the course of one of the following activities, if the URI does not match the allowed font sources, the user agent MUST act as if it had received an empty HTTP 400 response:

connect-src

The connect-src directive restricts which URIs the protected document can load using DOM APIs. The syntax for the name and value of the directive are described by the following ABNF grammar:

directive-name    = "connect-src"
directive-value   = source-list

If the policy contains an explicit connect-src, let the allowed connection targets be the result of parsing the directive's value as a source list. Otherwise, let the allowed connection targets be the default sources

Whenever the user agent fetches a URI (including when following redirects) in the course of one of the following activities, if the URI does not match the allowed font sources, the user agent MUST act as if it had received an empty HTTP 400 response:

sandbox

A future version of this document might include a sandbox directive for controlling the HTML5 sandbox flags.

report-uri

The report-uri directive specifies a URI 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:

directive-name    = "report-uri"
directive-value   = uri-reference *( 1*WSP uri-reference )
uri-reference     = <URI-reference from RFC 3986>

Let the set of report URIs be the value of the report-uri directive, each resolved relative to the protected document's URI.

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

  1. Prepare a dictionary violation dictionary with the following keys and values:
    request
    HTTP request line of the protected resource whose policy was violated including method, URI and HTTP version
    request-headers
    HTTP request headers sent with the request for the protected resource whose policy was violated
    blocked-uri
    URI of the resource that was prevented from loading due to the policy violation
    violated-directive
    The policy directive that was violated
    original-policy
    The original policy as received by the user-agent. If the policy was received via more than one Content Security Policy response header, this field MUST contain a comma separated list of original policies

    We might need to change some of these keys because they can leak sensitive information.

  2. If the origin of the blocked-uri is not the same as the document's origin, then replace the blocked-uri with the ASCII serialization of the blocked-uri's origin.
  3. Let the violation report be the JSON stringification of the violation dictionary.
  4. For each report URI in the set of report URIs:
    1. If the report URI has a different scheme than the URI of the protected document, then ignore this report URI and continue to the next iteration of the loop.
    2. If the report URI has a different port than the URI of the protected document, then ignore this report URI and continue to the next iteration of the loop.
    3. If the report URI's host does not share the same public suffix +1 DNS label as the URI of the protected document, then ignore this report URI and continue to the next iteration of the loop.

      Examples of public suffixes include .com, .net and .co.uk. Examples of "public suffix +1 DNS label" include example.com, example.net and example.co.uk. Therefore a protected document whose host is www.example.com could have a report-uri hosted on reports.example.com but not reports.example.net.

    4. Fetch the report URI from origin of the protected document, with the synchronous flag not set, using HTTP method POST, with a Content-Type header field of application/json with an entity body consisting of the violation report. The user agent MUST NOT follow redirects when fetching this resource. (Note: The user agent ignores the fetched resource.)

policy-uri

The policy-uri directive specifies a URI from which the user agent can retrieve the actual policy. The syntax for the name and value of the directive are described by the following ABNF grammar:

directive-name    = "policy-uri"
directive-value   = <URI-reference from RFC 3986>

The policy-uri directive might be removed from this document.

Authors MUST NOT specify policies that contain both a policy-uri directive and another directive.

If the user agent would enforce a policy containing both the policy-uri directive and another directive, instead the user agent MUST enforce the policy default-src 'none'.

When processing the policy-uri directive, the user agent MUST run an algorithm equivalent to the following:

Examples

Sample Policy Definitions

This section provides some sample use cases and accompanying security policies.

Example 1: A server wishes to load resources only form its own origin:

Content-Security-Policy: default-src 'self'

Example 2: An auction site wishes to load images from any URI, plug-in 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:

Content-Security-Policy: default-src 'self'; img-src *;
                         object-src media1.example.com media2.example.com *.cdn.example.com;
                         script-src trustedscripts.example.com

Example 3: A site operations group wishes to globally deny all third-party scripts in the site, and a particular project team wishes to also disallow third-party media in their section of the site. Site operations sends the first header while the project team sends the second header, and the user-agent takes the combination of the two headers to form the complete interpreted policy:

Content-Security-Policy: default-src *; script-src 'self'
Content-Security-Policy: default-src *; script-src 'self'; media-src 'self'

Example 4: Online banking site wishes to ensure that all of the content in its pages is loaded over TLS to prevent attackers from eavesdropping on insecure content requests:

Content-Security-Policy: default-src https:

Sample Violation Report

This section contains an example violation report the user agent might sent to a server when the protected document violations a sample policy.

In the following example, a document from http://example.org/page.html was rendered with the following CSP policy:

default-src 'self'; report-uri http://example.org/csp-report.cgi

The document loaded an image from http://evil.example.com/image.png, violating the policy.

{
  "csp-report": {
    "request": "GET http://example.org/page.html HTTP/1.1",
    "request-headers": "Host: example.org
                        User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:2.0b12pre) Gecko/20110222 Firefox/4.0b12pre
                        Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
                        Accept-Language: en-us,en;q=0.5
                        Accept-Encoding: gzip, deflate
                        Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
                        Keep-Alive: 115
                        Proxy-Connection: keep-alive
                        Cache-Control: max-age=0",
    "blocked-uri": "http://evil.example.com/image.png",
    "violated-directive": "default-src http://example.org"
  }
}

In the above sample report the violated-directive field was sent in the way it was interpreted by the user-agent. The directive was made explicit by replacing the keyword 'self' with the explicit host name of the protected resource. This is recommended behavior for user-agents as it reduces ambiguity, making policy violations easier to trace by server admins.

Should we add this as a requirement when preparing reports?