Using Content Security Policy

Configuring Content Security Policy involves adding the Content-Security-Policy HTTP header to a web page and giving it values to control resources the user agent is allowed to load for that page. For example, a page that uploads and displays images could allow images from anywhere, but restrict a form action to a specific endpoint. A properly designed Content Security Policy helps protect a page against a cross site scripting attack. This article explain how to construct such headers properly, and provides examples.

Prior to Firefox 23, the X-Content-Security-Policy HTTP header was used. Firefox 23 and later use the now-standard Content-Security-Policy header. During the transition from the previous header to the new header, sites can send both the X-Content-Security-Policy and Content-Security-Policy headers. In this situation, the X-Content-Security-Policy will be ignored and the policy contained in the Content-Security-Policy header will be used.

Specifying your policy

You can use the Content-Security-Policy HTTP header to specify your policy, like this:

Content-Security-Policy: policy

The policy is a string containing the policy directives describing your Content Security Policy.

Writing a policy

A policy is described using a series of policy directives, each of which describes the policy for a certain resource type or policy area. Your policy should include a default-src policy directive, which is a fallback for other resource types when they don't have policies of their own. (For a complete list, see the description of the default-src directive.) A policy needs to include a default-src or script-src directive to prevent inline scripts from running, as well as blocking the use of eval(). A policy needs to include a default-src or style-src directive to restrict inline styles from being applied from a <style> element or a .style attribute

The syntax for a policy is a string of semicolon-separated directives, each following the syntax described in Supported policy directives.

Examples: Common use cases

This section provides examples of some common security policy scenarios.

Example 1

A web site administrator wants all content to come from the site's own origin (this excludes subdomains.)

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

Example 2

A web site administrator wants to allow content from a trusted domain and all its subdomains (it doesn't have to be the same domain that the CSP is set on.)

Content-Security-Policy: default-src 'self' *.trusted.com

Example 3

A web site administrator wants to allow users of a web application to include images from any origin in their own content, but to restrict audio or video media to trusted providers, and all scripts only to a specific server that hosts trusted code.

Content-Security-Policy: default-src 'self'; img-src *; media-src media1.com media2.com; script-src userscripts.example.com

Here, by default, content is only permitted from the document's origin, with the following exceptions:

Images may loaded from anywhere (note the "*" wildcard).
Media is only allowed from media1.com and media2.com (and not from subdomains of those sites).
Executable script is only allowed from userscripts.example.com.

Example 4

A web site administrator for an online banking site wants to ensure that all its content is loaded using SSL, in order to prevent attackers from eavesdropping on requests.

Content-Security-Policy: default-src https://onlinebanking.jumbobank.com

The server only permits access to documents being loaded specifically over HTTPS through the single origin onlinebanking.jumbobank.com.

Example 5

A web site administrator of a web mail site wants to allow HTML in email, as well as images loaded from anywhere, but not JavaScript or other potentially dangerous content.

Content-Security-Policy: default-src 'self' *.mailsite.com; img-src *

Note that this example doesn't specify a script-src; with the example CSP, this site uses the setting specified by the default-src directive, which means that scripts can be loaded only from the originating server.

Testing your policy

To ease deployment, CSP can be deployed in "report-only" mode. The policy is not enforced, but any violations are reported to a provided URI. Additionally, a report-only header can be used to test a future revision to a policy without actually deploying it.

You can use the Content-Security-Policy-Report-Only HTTP header to specify your policy, like this:

Content-Security-Policy-Report-Only: policy

If both a Content-Security-Policy-Report-Only header and a Content-Security-Policy header are present in the same response, both policies are honored. The policy specified in Content-Security-Policy headers is enforced while the Content-Security-Policy-Report-Only policy generates reports but is not enforced.

Note that the X-Content-Security-Policy-Report-Only header was used before Firefox 23. If both the X-Content-Security-Policy-Report-Only and Content-Security-Policy-Report-Only are sent, the Content-Security-Policy-Report-Only will be used and the X-Content-Security-Policy-Report-Only will be ignored.

The UserCSP Addon also helps test and develop Content Security Policies for a site.