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.
See also
- Introducing Content Security Policy
- CSP policy directives
- Using CSP violation reports
- Content Security Policy recommendation bookmarklet
</style>