Security/CSP/Specification: Difference between revisions

A <b>policy</b> is composed of <b>directives</b>, such as "<tt>allow none</tt>".  Each directive is composed of a <b>directive name</b> and a <b>directive value</b>, which is either a list of <b>host items</b> or a <b>URI</b>, for certain types of directives.

A policy is composed of directives with their corresponding values.  Any number of directives can be defined, but the <b><tt>allow</tt> directive must always be present</b>.  Each directive is followed with a list of host expressions except for <tt>policy-uri</tt> and <tt>report-uri</tt> which contain a single URI value. Some [[Security/CSP/Spec#Sample_Policy_Definitions|example policy sets]] are provided below.

====allow====

* The catch-all section that defines the security policy for all types of content which are not called out in any of the other directives.  Defines the default policy for un-specified content types.

* If the allow directive is not explicitly specified, no content from any source will be loaded. This is equivalent to the policy "allow 'none'".

* All HTTP requests not subject to one of the more specific directives are subject to the allow directive (including XMLHttpRequests).

====options====

* Any tokens not recognized by CSP are ''ignored'', and a non-fatal warning is posted to the error console.

====img-src====

* Images from non-approved sources will not be requested or loaded.

* If img-src is not explicitly specified, image requests are subject to the allow directive.  

====media-src====

* <tt>audio</tt> and <tt>video</tt> elements from non-approved sources will not be requested or loaded.

* If media-src is not explicitly specified, media requests are subject to the allow directive.

====script-src====

* Only scripts loaded via the <tt>src=</tt> attribute will be loaded

* Scripts from non-approved sources will not be requested or loaded.

* If script-src is not explicitly specified, script requests are subject to the allow directive.

====object-src====

* Objects from non-approved sources will not be requested or loaded.

* If object-src is not explicitly specified, object requests are subject to the allow directive.

====frame-src====

* Answers the question: "Documents from which sources may be embedded in my resource?"

* Frame content from non-approved sources will not be requested or loaded.

* If frame-src is not explicitly specified, frame requests are subject to the allow directive.

====font-src====

* Fonts served from non-approved sources must not be requested for use as a font in CSS.

* If font-src is not explicitly specified, requests by <tt>@font-src</tt> are subject to the allow directive.

====xhr-src====

* XMLHttpRequests may not be opened to sources not permitted by this directive.

* If xhr-src is not explicitly specified, requests by <tt>XMLHttpRequest</tt> objects are subject to the allow directive.

====frame-ancestors====

====style-src====

* Inline stylesheets and style attributes of HTML tags are globally allowed.

* Stylesheets from non-white-listed sources will not be requested or loaded.

* If style-src is not explicitly specified, stylesheet requests are subject to the allow directive.

====report-uri====

* The report will be an XML document with MIME type application/xml sent via POST to the specified URI contained in the value of this directive.

* Report URIs must be from the scheme and port as the protected content, and the [http://publicsuffix.org public suffix] and most general DNS label of the protected content and the report URI must match.  For example www.foo.co.uk and reports.foo.co.uk, but not reports.bar.co.uk.  Relative URIs are acceptable, and are resolved within the same scheme, host and port as the document served with the CSP.   

* Report URIs that don't match the public suffix and base host match requirements will not be sent reports and one error will be logged to an error console.  CSP enforcement will continue as if the report URI were not specified.

* Details about the information provided in violation reports are found in the [[#Violation Report Syntax|Violation Report Syntax]] section.

* HTTP 3xx response codes are not honored by the user agent.  No redirection from the Report URI is allowed to prevent HTTP header leakage across domains.

====policy-uri====

* <tt>policy-uri</tt> should only be defined in the absence of other policy definitions in the <tt>X-Content-Security-Policy</tt> HTTP header.  If <tt>policy-uri</tt> is defined among other directives in the header, a [[Security/CSP#Error_Handling|console error]] is raised and the policy enforced by CSP is the most restrictive policy: "allow none".

* Policy URIs must be of the same origin (scheme/host/port) as the protected content. Relative URIs are acceptable, and are resolved within the same scheme, host and port as the document served with the CSP.

If the scheme is not specified as part of the source expression it ''defaults to the same scheme as the protected document.''   

If a port is not specified as the source expression, the port used for the source is the default port for the source's scheme (whether it is inherited or explicitly specified in the source expression).

When a scheme alone is the entire source expression (e.g., <tt>javascript:</tt>) host and port restrictions are not enforced.  This is because for some schemes, host and port are irrelevant (e.g., <tt>data:</tt>).

 

Valid sources do not always require a host.  Schemes such as <tt>data</tt> and <tt>javascript</tt> can be enabled as a source by stating the name of the scheme followed by a colon.  For example:

Each source expression's host name may contain up to one wildcard (*) and it must be the left-most DNS label.   

  <allow-directive>  ::= allow <source-list>

                       | <ldh-symbol><let-dig-hyp>

 

CSP supports a reporting mechanism that allows browsers to notify content providers when their policy is violated. When a <tt>report-uri</tt> is provided and a policy is violated, information about the protected resource and the violating content is transmitted to the <tt>report-uri</tt> via HTTP POST if available in the employed scheme, otherwise an appropriate "submit" method is used.  The user agent <i>must not</i> honor redirection responses.  Such a report is an XML document containing the following fields:

NOTE: in the case where a protected resource is not rendered because the <tt>frame-ancestors</tt> directive was violated, <tt>blocked-uri</tt> is not sent and is assumed to be the same as the request URI. The reason for this is because this situation is different from other policy violations: no third-party content was blocked, rather the protected content elected not to load since it does not trust the sites that have enframed it.

 

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

The MIME type of the transmitted report will be set to <tt>application/xml</tt>.

In this example, a page located at <tt>http://example.com/index.html</tt> was requested using HTTP 1.1 via the GET method.  It provided a policy that included the directive "<tt>img-src self</tt>", which was violated by a request for <tt><nowiki>http://evil.com/some_image.png</nowiki></tt>.  The sample XML data sent to the policy-specified <tt>report-uri</tt> follows.

  <csp-report>

  <request>GET /index.html HTTP/1.1</request>

  <request-headers><![CDATA[

            Host: example.com

            User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9) Gecko/2008061015 Firefox/3.0

            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: 300

            Connection: keep-alive

  <blocked-uri><nowiki>http://evil.com/some_image.png</nowiki></blocked-uri>

  <violated-directive>img-src self</violated-directive>

  <original-policy>allow none; img-src *, allow self; img-src self</original-policy>

  </csp-report>

* Restricted:

* Allowed:

** Script imported from external files hosted by white-listed sources and served with a Content-Type of <tt>application/javascript</tt> or <tt>application/json</tt>.

'''On Violation:''' a violation report will be sent with the <tt>violated-directive</tt> value set to "Base Restriction Violation: no inline scripts will execute.".

* Restricted:

** eval()

** setTimeout called with a String argument, e.g. setTimeout("evil string...", 1000)

** setInterval called with a String argument, e.g. setInterval("evil string...", 1000)

** new Function constructor, e.g. var f = new Function("evil string...")

* Allowed:

** setTimeout called with a Function argument, e.g. setTimeout(myFunc, 1000)

** setInterval called with a Function argument, e.g. setInterval(myFunc, 1000)

'''On Violation:''' a violation report will be sent with the <tt>violated-directive</tt> value set to "Base Restriction Violation: no code will be created with strings".

* Restricted:

** data: URIs as a source for inline content

* Allowed:

** data: URIs as a source for inline content when explicitly opted-in to, e.g. X-Content-Security-Policy: allow self; img-src data:

** The data: URI scheme is designed to allow the loading of arbitrary textual or binary data into a document, including HTML, scripts, images, media files, etc.

** The increase in attack surface created by data: URIs, and additional input sanitization required by sites wishing to use them justifies the opt-in requirement for this feature in CSP.

* data: URIs can be re-enabled by adding "data:" as a source to any source directive.  For example: <tt>img-src data: https://my-host.com</tt>.

* Restricted:

* Allowed:

The optional directive policy-uri must refer to the same origin (scheme/host/port) as the protected document. The report-uri directive must refer to an origin with the same public suffix and base host. For instance, a report-uri in a policy for "www.mysite.com" may refer to anything that ends with "mysite.com". Additionally, policy-uri documents must be served with the MIME type text/x-content-security-policy to be valid

* Restricted:

** policy-uri directives which refer to a URI on a different host as the protected document, e.g. policy-uri http://other.tld/csp-policy.cgi

** policy-uri responses served with Content-Type other than text/x-content-security-policy, e.g. Content-Type: text/html, or Content-type: image/jpeg

** report-uri directives which refer to a URI on a different public suffix or base host than the protected document, e.g. report-uri http://other.tld/csp-report.cgi

* Allowed:

** The report sent to the report-uri contains potentially sensitive information, including cookie values and query string parameters. This information is intended only for the protected site for debugging purposes or similar. An attacker should not be allowed to steal the report information by injecting a report-uri, along with an arbitrary policy to be violated.

CSP is activated by a client's browser when the <tt>X-Content-Security-Policy</tt> HTTP header is provided in a HTTP response.

The Content Security Policy to be enforced can be delivered to the browser in one of two ways: directly as the value in the <tt>X-Content-Security-Policy</tt> HTTP header or a file served from the same host as the resource to be secured. The <tt>X-Content-Security-Policy</tt> header must either contain a policy definition <i>or</i> a <tt>policy-uri</tt> field; if both are present, the browser will raise a [[Security/CSP/Spec#Error_Handling|CSP console error]] and enforce the most restrictive ("allow none") policy.

The syntax is identical between file-based and header-based policy. The contents of a policy file are equivalent to the value of the X-Content-Security-Policy header.

When multiple instances of the <tt>X-Content-Security-Policy</tt> HTTP header are present in an HTTP response, the intersection of the policies is enforced; essentially, the browser enforces a policy that is more strict than both the policies specified in the multiple headers, but only strict enough to correspond to rules in all policies.  Any web request that satisfied ''all'' policies alone will be accepted by the new policy, but any request rejected by ''any of'' of the two policies will be rejected.  The intersection is calculated on a directive-by-directive basis (i.e., the intersection of the <tt>allow</tt> directive is taken and enforced as the <tt>allow</tt> part of the effective policy). Explicitly, for two policies:

If more than two instances of the <tt>X-Content-Security-Policy</tt> header are present in the response, the intersection is done digest-style: the first two policies are removed from the set of headers to digest, intersected, and the result is placed back in the set.  This continues until only one policy remains.  e.g.,

If two policy headers are present, one (P₁) may allow scripts from domains A, B and C.  The policy in the other header (P₂) may allow scripts from domains B, C and D.  The policy enforced (P_enforced) by the browser will allow scripts from domains B and C only (P_enforced = P₁ &cap; P₂).

 

 

Because the <tt>X-Content-Security-Policy</tt> header may appear multiple times in the response, it is possible they're crafted by different entities and may conflict.  A decision must be made about which policy to use, or whether to combine them or not.  Assuming there are two different policies present, there are five obvious ways to address this conflict:

 

#<b>Use the first header's policy.</b>

 

If multiple headers define policies with <tt>report-uri</tt> values, a single report is sent to each of the provided URIs.  If any <tt>report-uri</tt> values are the same, only one report for each violation is sent to that URI; essentially one report is sent to each distinct URI upon policy violation.

Report-duplication (or multiple reporting) is useful in the case where two different groups want to receive reports, but may not share access to the reports archive.  Take for instance a large web company that has a separate sysadmin staff (who are also in charge of security at some level) and project teams.  One project team may be interested in receiving reports about violations of their CSP, but are not interested in violations on other parts of the web site.  The sysadmin team wants to record all violations from all parts of the site into a massive archive.  The multiple reporting technique allows both entities to receive the reports they want without causing extra data-mining work on the part of the sysadmin team to isolate the reports that each project team may want.

Since HTTP headers and the entire request string are sent in the report, it is possible that, in case of compromise, a violation report could leak private information to an arbitrary URI.  To avoid any possible cross-domain cookie or authentication token transfer, <b>all reports must be sent to the same origin (scheme/host/port) that served the protected content</b>.

Two headers present conflicting policies, they are resolved through a straightforward process: first the policies are made explicit (see below), then they are intersected, and the resulting policy is enforced.  Through this process, the enforced policy will <i>never be more lenient</i> than either of the conflicting policies.

This refinement procedure is only followed if there are multiple instances of the <tt>X-Content-Security-Policy</tt> HTTP header present in the HTTP response.

These parse errors are not <em>policy violations</em>, and any error messages caused by parse errors are separate from the violation report sites may elect to receive when their site's <em>policies are violated</em>, via the report-uri directive.  Parse errors are only reported locally in the user agent.

;Unrecognized Directive: If an unrecognized directive (name not recognized) is encountered by CSP, the directive and its value are skipped (up to a semicolon or end of header, whichever is first) and a warning message is logged to the Error Console stating the unrecognized directive name.

;Unrecognized <tt>options</tt> token: If an unrecognized token is present in the <tt>options</tt> directive value, it is ignored and a warning message is logged to the Error Console stating the unrecognized token.

;Missing "allow": If the "allow" directive is not present, a warning message is logged to the Error Console and "allow none" is assumed by the policy.  The rest of the policy is enforced as written assuming no other policy errors are encountered.

;Directive Syntax Error: When any known directive contains a value that violates [[Security/CSP/Spec#Policy_Language_and_Syntax|CSP syntax]], Content Security Policy follows a "fail closed" security model and falls back to the most secure policy, "allow none".

;No Recognized Directives: If no recognized directives are present in the stated policy, a warning message will be logged to the Error Console stating "invalid policy", and CSP will enforce the policy "allow none".

;Other Parsing Errors: Any other parsing errors not covered here may cause CSP to fail closed.  If such a case should arise, a message will be logged to the Error Console describing the violation.

To ease deployment, CSP can be deployed in "report-only" mode where a policy served is not enforced, but any violations are reported to a provided URI.  The effect is a "what if" scenario where a site can specify a policy and measure how much breaks.

If both a <tt>X-Content-Security-Policy-Report-Only</tt> header and a <tt>X-Content-Security-Policy</tt> header are present in the same response, a warning is posted to the user agent's error console and any policy specified in <tt>X-Content-Security-Policy-Report-Only</tt> is ignored.  The policy specified in <tt>X-Content-Security-Policy</tt> headers is enforced.

 

==HTTP Header Placement==

The <tt>X-Content-Security-Policy</tt> HTTP Response header should be present in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2 Message Headers] section of a server's HTTP response.  Specifically, it must NOT appear in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.40 Trailer Headers] section of the response, so that the policy may be enforced as the rest of the page content loads.  Multiple <tt>X-Content-Security-Policy</tt> Response headers will be considered; if more than one is present, the intersection of the policies is enforced.