Content Security Policy

Preliminaries

Let your browser know your intentions. Enlist its help in enforcing your safe coding practices. Use the content-security-policy to fine tune where your document gets its resources.

No matter how careful you are, it seems like there's always a new way for bad actors to mess with your website.

To help combat this, you can enlist the browser's support in enforcing the security of your online resources, and the safety of your visitor's actions. This is done by establishing rules that govern how your online documents are allowed to retrieve the resources it needs. Resources are things like style sheets, fonts, scripts, media, and embedded documents. Rules declare who can request those resources, and where those resource can be retrieved from.

The set of rules that your website adheres to, can be published as a policy, and that policy can be shared with the browser. This is done with the "content-security-policy" response header. It is sent by the server with the response to a browser request for a document, that is, it is sent when the response has a content-type of text/html or application/xhtml+xml.

A policy can be as simple as a single rule with a single policy declaration, for example, default-src 'self'.

In this example default-src is a policy rule, and 'self' is a policy declaration.

A policy can, and often does, include several rules. Furthermore, a policy declaration can include multiple allowable sources. Because of this, a full policy can be complex and intimidating to parse visually. The Read Write Serve configuration file, provides a structured way to declare the parts of a full policy. This makes it visually cleaner for humans to parse. Internally, the server converts this structured declaration into a single comma-separated string, suitable for sending in a response header.

Rules

Most policy rules are related to HTML elements of a specific type, such as script, style, img, etc. A few advanced policy rules are related to additional processing restrictions that are placed on how the browser is allowed to access resources.

HTML Element Rules

Here are the policy rules that relate to specific HTML elements:

Web Technologies Rules

Here are the policy rules that relate to web technologies:

Rules for Additional Restrictions

Here are the policy rules that relate to how the browser is allowed to access resources:

Policy declarations

The policy rules just described, are paired with a policy declaration. A policy declaration consists of one or more allowable sources, which are described here.

One additional allowable source may be used with style-src rules. If your documents use CSS within the HTML itself — either within a <style> element or within a style="" attribute — they must declare the special 'unsafe-inline' allowable source.

Similarly, two additional allowable sources are available for use with script-src rules. If your documents use JavaScript within the HTML itself — either within a <script> element or within an event handler, such as onclick="", — they must declare the special 'unsafe-inline' allowable source. Furthermore, if any script uses eval(), the allowable source 'unsafe-eval' must be declared.

Syntax for additional restrictions

The upgrade-insecure-requests and block-all-mixed-content rules do not need any policy declarations. These two special rules are declared simply by using their name.

The plugin-types rules accepts a space-separated list of MIME-types. For example, when embedding an <object> with Flash, the MIME-type application/x-shockwave-flash should be specified. When embedding an <applet> using Java, the MIME-type application/x-java-applet should be specified.

If your documents require subresource integrity for scripts, the require-sri-for rule should declare script. If your documents require subresource integrity for stylesheets, the require-sri-for rule should declare style.

If you want to place limits on script interaction, the sandbox rule can be enabled by declaring it as a rule, by itself. If you want to enable the sandbox, but allow exceptions, any of these allowable interactions can be declared:

report to

When the browser assembles your document, it examines the security policy that you've declared. Then, for each resource needed by the document, the browser enforces the rules of your policy. If a rule is violated, the browser will block the resource from being retrieved.

In many cases, during the development of your website, you can visually determine which resources were blocked by your policy. But to understand exactly which resources were blocked, and which policy rules triggered the blocking, you can examine the browser's debug console. All policy violations will be reported there.

Of course, once you allow visitors onto your new website, you won't see those console errors — your visitors will! This is where the report-to response header comes into the picture. By specifying a report-to rule, you can tell the browser to send policy violation reports to a designated HTTP endpoint. That endpoint will receive the same information that you would previously have seen in the browser's debug console.

Every content-security-policy should have a report-to rule. The rule expects the name of a report group, which references a group name defined in a report-to response header. The report-to header specifies an endpoint that is responsible for accepting and processing the reports sent to it by the browser. Reports are sent as JSON-encoded HTTP POSTs. See the separate note about policy reports for details.

The report-to rule declaration is simple, but its actual setup (with respect to the report-to response header) can be tricky to get right. Refer to the separate note about the Report To header.

Report Only

Getting the content-security policy wrong can have major repercussions. Setting it too strong, may prevent your documents from loading media or styles that make your documents look good. Or it may prevent them from loading necessary scripts, preventing important functionality from working. Or it may block the submission of forms or the inclusion of embedded documents.

When developing a new website you can catch these mistakes early, and fix the document or change the policy. But when retroactively attempting to apply a set of policy rules to an existing website, it isn't always obvious what might break.

Your can use the content-security-policy-report-only header to ease your way into a fully fledged policy. The report only header is specified using all the same rules and policy declarations. And its usage by the browser is nearly identical. Policy violations are reported to the browser's debug console, or to the report-to endpoint, just as with the regular header. The difference is that the violations are not enforced.

You may use the content-security-policy-report-only header alone, or together with the regular header. The policies they specify may be different. In this way you might, for example, specify a permissive policy to be enforced with content-security-policy and a more restrictive, experimental policy to be reported, but not enforced, with the content-security-policy-report-only header.

The content-security-policy section is configured subordinate to the policies section. It comprises one or more rules, each as a separate line item. Each line item starts with the name of the rule, followed by a space-separated list of allowable sources.

The content-security-policy-report-only section is configured the same way as the content-security-policy section. Both sections may be configured at the same time — each with its own set of rules and policy declarations — and both, or either, will be used.

To be effective, the policies module must be turned on.

† These are defined in separate notes