CSP policy directives

  • Revision slug: Security/CSP/CSP_policy_directives
  • Revision title: CSP policy directives
  • Revision id: 4692
  • Created:
  • Creator: bsterne
  • Is current revision? No
  • Comment 2 words added

Revision Content

{{ gecko_minversion_header("2.0") }}{{ draft() }}

There are several policy areas that web site administrators can define using Content Security Policy (CSP). Any combination of these can be used to customize your policy set to suit your web site's needs; you don't need to specify them all. Any you don't explicitly configure will use the default restrictions.

All of these policy areas are optional with the exception of the allow section, which must be specified for every site that has CSP enabled. If no allow section is provided, the policy is invalid and an error occurs.

Content sources

Most policy directives require one or more content sources. A content source is a string indicating a possible source from which content might be loaded.

Host expressions

A host expression is a string specifying one or more Internet hosts by name or IP address, as well as an optional URL scheme and/or port number. The site's address may include an optional leading wildcard (the asterisk character, "*"), and you may use a wildcard (again, "*") as the port number, indicating that all legal ports are valid for the source. The hosts are space-delimited.

Valid host expressions include:

http://*.foo.com
Matches all attempts to load from foo.com and any subdomain thereof using the http: URL scheme.
mail.foo.com:443
Matches all attempts to access port 443 on mail.foo.com.
https://store.foo.com
Matches all attempts to access store.foo.com using https:.

If a port number isn't specified, the browser will use the default port number for the specified scheme. If no scheme is specified, the same scheme as the one used to access the protected document is assumed.

Keywords

There are also some keywords available to describe special classes of content sources. These are:

'self'
Refers to the host from which the protected document is being served, including the same URL scheme and port number. You must include the single quotes.
'none'
Refers to the empty set; that is, no hosts match. The single quotes are required.

For example, you can specify that content may be loaded from the document's host as well as trustedscripts.foo.com as follows:

X-Content-Security-Policy: allow 'self' trustedscripts.foo.com

Data

data:
Allows data: URIs to be used as a content source
X-Content-Security-Policy: allow 'self'; img-src 'self' data:

Supported policy directives

The following policy directives are available to control the security policy for the various policy areas.

allow

The allow section is the only required section; it defines the security policy for all types of content which are not expressly called out by more specific directives.

Syntax

allow host-expression

options

The options section lets you modify core restrictions of CSP.

Syntax

options option-list

The options-list consists of one or more of the following options, space-delimited:

inline-script
If this option is specified, inline script and javascript: URIs are enabled.
eval-script
If this option is specified, eval() and similar methods for creating code from strings are permitted.

img-src

The img-src section specifies what sources may be used for loading images and favicons. Attempts to requested or load images from other sources are not  allowed.

Syntax

img-src host-expr

media-src

The media-src section specifies what sources may be used for loading media using the {{ HTMLElement("audio") }} and {{ HTMLElement("video") }} elements. Attempts to requested or load media from other sources are not allowed.

Syntax

media-src host-expr

script-src

The script-src section specifies valid sources for JavaScript; attempts to request or load scripts from other sources are not allowed.

Syntax

script-src host-expr

object-src

The object-src section specifies valid sources for the {{ HTMLElement("object") }}, {{ HTMLElement("embed") }}, and {{ HTMLElement("applet") }} elements. Attempts to use other sources for these elements are not allowed.

Syntax

object-src host-expr

frame-src

The frame-src section specifies valid sources for frame content loaded using the {{ HTMLElement("frame") }} and {{ HTMLElement("iframe") }} elements; attempts to request or load frame content from other sources are not allowed.

Syntax

frame-src host-expr

font-src

The font-src section specifies valid sources for fonts loaded using {{ cssxref("@font-face") }}. Downloadable fonts from other sources are not requested or loaded.

Syntax

font-src host-expr

xhr-src

The xhr-src section indicates valid sources for XMLHttpRequest connections. Attempts to open connections to other locations are not allowed.

Syntax

xhr-src host-expr

frame-ancestors

The frame-ancestors section specifies sources that may embed your site using the {{ HTMLElement("frame") }} and {{ HTMLElement("iframe") }} elements. All sites within the frame chain must be in your frame-ancestors list in order to embed your site in a frame. If any site in the frame chain isn't in your whitelist, the load is not allowed.

In other words, if foo.com embeds bar.com in a frame, which then embeds your site in an {{ HTMLElement("iframe") }}, your site's CSP must include both foo.com and bar.com in its frame-ancestors list.

Note: While this addresses the threat of clickjacking, it doesn't address cross-site request forgery (CSRF). That's because, while this policy prevents a site from being loaded, it doesn't prevent the request from being received by the server. To mitigate CSRF, you should use the Origin HTTP header.

Syntax

frame-ancestors host-expr

style-src

The style-src section specifies sources from which stylesheets may be loaded. This includes both externally-loaded stylesheets and inline use of the {{ HTMLElement("style") }} element and HTML style attributes. Stylesheets from sources that aren't included in the whitelist are not requested or loaded.

Syntax

style-src host-expr

report-uri

The report-uri section lets you instruct the browser to report attempts to violate the Content Security Policy. These violation reports consist of JSON documents sent via an HTTP POST request to the specified URI. See Using CSP violation reports for details.

Syntax

report-uri uri

Note: You must use the same URL scheme and port for the report-uri as the content being protected by Content Security Policy.

policy-uri

The policy-uri directive indicates the location of a file containing the security policies for the resource. This lets you specify your policies in a file instead of directly in your HTTP response headers. The specified file must be on the same host as the protected document, and must be served with the Content-Type text/x-content-security-policy.

If a valid policy-uri directive is specified, all other policies defined in the HTTP header are ignored.

If any other directives are present, the entire policy is considered invalid, an exception is raised, and the Content Security Policy "allow 'none'" is enforced.

Syntax

policy-uri uri

See also

Revision Source

<p>{{ gecko_minversion_header("2.0") }}{{ draft() }}</p>
<p>There are several policy areas that web site administrators can define using Content Security Policy (CSP). Any combination of these can be used to customize your policy set to suit your web site's needs; you don't need to specify them all. Any you don't explicitly configure will use the <a href="/en/Security/CSP/Default_CSP_restrictions" title="en/Security/CSP/Default CSP restrictions">default restrictions</a>.</p>
<p>All of these policy areas are optional with the exception of the <code>allow</code> section, which must be specified for every site that has CSP enabled. If no allow section is provided, the policy is invalid and an error occurs.</p>
<h2>Content sources</h2>
<p>Most policy directives require one or more content sources. A content source is a string indicating a possible source from which content might be loaded.</p>
<h3>Host expressions</h3>
<p>A host expression is a string specifying one or more Internet hosts by name or IP address, as well as an optional <a href="/en/URIs_and_URLs" title="en/URIs and URLs">URL scheme</a> and/or port number. The site's address may include an optional leading wildcard (the asterisk character, "*"), and you may use a wildcard (again, "*") as the port number, indicating that all legal ports are valid for the source. The hosts are space-delimited.</p>
<p>Valid host expressions include:</p>
<dl> <dt><span class="nowiki">http://*.foo.com</span></dt> <dd>Matches all attempts to load from foo.com and any subdomain thereof using the <code>http:</code> URL scheme.</dd> <dt><span class="nowiki">mail.foo.com:443</span></dt> <dd>Matches all attempts to access port 443 on mail.foo.com.</dd> <dt><span class="nowiki">https://store.foo.com</span></dt> <dd>Matches all attempts to access store.foo.com using <code>https:</code>.</dd>
</dl>
<p>If a port number isn't specified, the browser will use the default port number for the specified scheme. If no scheme is specified, the same scheme as the one used to access the protected document is assumed.</p>
<dl> <h3>Keywords</h3> <p>There are also some keywords available to describe special classes of content sources. These are:</p> <dl> <dt>'self'</dt> <dd>Refers to the host from which the protected document is being served, including the same URL scheme and port number. You must include the single quotes.</dd> <dt>'none'</dt> <dd>Refers to the empty set; that is, no hosts match. The single quotes are required.</dd> </dl> <p>For example, you can specify that content may be loaded from the document's host as well as trustedscripts.foo.com as follows:</p> <pre>X-Content-Security-Policy: allow 'self' trustedscripts.foo.com
</pre> <dl> <h3>Data</h3>
<dl> <dt>data:</dt> <dd>Allows <a href="/en/data_URIs" title="en/data URIs"><code>data:</code> URIs</a> to be used as a content source</dd>
</dl>
<pre>X-Content-Security-Policy: allow 'self'; img-src 'self' data:
</pre><h2>Supported policy directives</h2> <p>The following policy directives are available to control the security policy for the various policy areas.</p> <h3>allow</h3> <p>The <code>allow</code> section is the only <strong>required</strong> section; it defines the security policy for all types of content which are not expressly called out by more specific directives.</p> <h4>Syntax</h4> <p><code>allow </code><em><code>host-expression</code></em></p> <h3>options</h3> <p>The <code>options</code> section lets you modify core restrictions of CSP.</p> <h4>Syntax</h4> <p><code>options </code><em><code>option-list</code></em></p> <p>The <em>options-list</em> consists of one or more of the following options, space-delimited:</p> <dl> <dt><code>inline-script</code></dt> <dd>If this option is specified, inline script and <code>javascript:</code> URIs are enabled.</dd> <dt><code>eval-script</code></dt> <dd>If this option is specified, <a href="/en/JavaScript/Reference/Global_Objects/eval" title="en/JavaScript/Reference/Global Objects/eval"><code>eval()</code></a> and similar methods for creating code from strings are permitted.</dd> </dl> <h3>img-src</h3> <p>The <code>img-src</code> section specifies what sources may be used for loading images and favicons. Attempts to requested or load images from other sources are not  allowed.</p> <h4>Syntax</h4> <p><code>img-src </code><em><code>host-expr</code></em></p> <h3>media-src</h3> <p>The <code>media-src</code> section specifies what sources may be used for loading media using the {{ HTMLElement("audio") }} and {{ HTMLElement("video") }} elements. Attempts to requested or load media from other sources are not allowed.</p> <h4>Syntax</h4> <p><code>media-src </code><em><code>host-expr</code></em></p> <h3>script-src</h3> <p>The <code>script-src</code> section specifies valid sources for JavaScript; attempts to request or load scripts from other sources are not allowed.</p> <h4>Syntax</h4> <p><code>script-src </code><em><code>host-expr</code></em></p> <h3>object-src</h3> <p>The <code>object-src</code> section specifies valid sources for the {{ HTMLElement("object") }}, {{ HTMLElement("embed") }}, and {{ HTMLElement("applet") }} elements. Attempts to use other sources for these elements are not allowed.</p> <h4>Syntax</h4> <p><code>object-src </code><em><code>host-expr</code></em></p> <h3>frame-src</h3> <p>The <code>frame-src</code> section specifies valid sources for frame content loaded using the {{ HTMLElement("frame") }} and {{ HTMLElement("iframe") }} elements; attempts to request or load frame content from other sources are not allowed.</p> <h4>Syntax</h4> <p><code>frame-src </code><em><code>host-expr</code></em></p> <h3>font-src</h3> <p>The <code>font-src</code> section specifies valid sources for fonts loaded using {{ cssxref("@font-face") }}. Downloadable fonts from other sources are not requested or loaded.</p> <h4>Syntax</h4> <p><code>font-src </code><em><code>host-expr</code></em></p> <h3>xhr-src</h3> <p>The <code>xhr-src</code> section indicates valid sources for <a href="/en/XMLHttpRequest" title="en/XMLHttpRequest"><code>XMLHttpRequest</code></a> connections. Attempts to open connections to other locations are not allowed.</p> <h4>Syntax</h4> <p><code>xhr-src </code><em><code>host-expr</code></em></p> <h3>frame-ancestors</h3> <p>The <code>frame-ancestors</code> section specifies sources that may embed your site using the {{ HTMLElement("frame") }} and {{ HTMLElement("iframe") }} elements. All sites within the frame chain must be in your <code>frame-ancestors</code> list in order to embed your site in a frame. If any site in the frame chain isn't in your whitelist, the load is not allowed.</p> <p>In other words, if foo.com embeds bar.com in a frame, which then embeds your site in an {{ HTMLElement("iframe") }}, your site's CSP must include both foo.com and bar.com in its <code>frame-ancestors</code> list.</p> <div class="note"><strong>Note:</strong> While this addresses the threat of clickjacking, it doesn't address cross-site request forgery (CSRF). That's because, while this policy prevents a site from being loaded, it doesn't prevent the request from being received by the server. To mitigate CSRF, you should use the <a href="/En/HTTP_access_control#Origin" title="En/HTTP access control#Origin"><code>Origin</code></a> HTTP header.</div> <h4>Syntax</h4> <p><code>frame-ancestors </code><em><code>host-expr</code></em></p> <h3>style-src</h3> <p>The <code>style-src</code> section specifies sources from which stylesheets may be loaded. This includes both externally-loaded stylesheets and inline use of the {{ HTMLElement("style") }} element and HTML <code>style</code> attributes. Stylesheets from sources that aren't included in the whitelist are not requested or loaded.</p> <h4>Syntax</h4> <p><code>style-src </code><em><code>host-expr</code></em></p> <h3>report-uri</h3> <p>The <code>report-uri</code> section lets you instruct the browser to report attempts to violate the Content Security Policy. These violation reports consist of <a href="/en/JSON" title="en/JSON">JSON</a> documents sent via an HTTP <code>POST</code> request to the specified URI. See <a href="/en/Security/CSP/Using_CSP_violation_reports" title="en/Security/CSP/Using CSP violation reports">Using CSP violation reports</a> for details.</p> <h4>Syntax</h4> <p><code>report-uri </code><em><code><a class=" external" href="http://tools.ietf.org/html/rfc2396" title="http://tools.ietf.org/html/rfc2396">uri</a></code></em></p> <div class="note"><strong>Note:</strong> You must use the same URL scheme and port for the <code>report-uri</code> as the content being protected by Content Security Policy.</div> <h3>policy-uri</h3> <p>The <code>policy-uri</code> directive indicates the location of a file containing the security policies for the resource. This lets you specify your policies in a file instead of directly in your HTTP response headers. The specified file must be on the same host as the protected document, and must be served with the Content-Type <code>text/x-content-security-policy</code>.</p> <p>If a valid <code>policy-uri</code> directive is specified, all other policies defined in the HTTP header are ignored.</p> <p>If any other directives are present, the <code><span style="font-family: Verdana,Tahoma,sans-serif;">entire policy</span></code> is considered invalid, an exception is raised, and the Content Security Policy "<code>allow 'none'</code>" is enforced.</p> <h4>Syntax</h4> <p><code>policy-uri <a class=" external" href="http://tools.ietf.org/html/rfc2396" title="http://tools.ietf.org/html/rfc2396"><span style="font-style: italic;">uri</span></a></code></p> <h2>See also</h2> <ul> <li><a href="/en/Security/CSP/Introducing_Content_Security_Policy" title="en/Security/CSP/Introducing Content Security Policy">Introducing Content Security Policy</a></li> <li><a href="/en/Security/CSP/Using_Content_Security_Policy" title="en/Security/CSP/Using Content Security Policy">Using Content Security Policy</a></li> <li><a href="/en/Security/CSP/Default_CSP_restrictions" title="en/Security/CSP/Default CSP restrictions">Default CSP restrictions</a></li> <li><a href="/en/Security/CSP/Using_CSP_violation_reports" title="en/Security/CSP/Using CSP violation reports">Using CSP violation reports</a></li> </ul></dl></dl>
Revert to this revision