Content-Security-Policy

The HTTP Content-Security-Policy response header allows websites a certain degree of control over the resources that a client is allowed to access.

Usage

The Content-Security-Policy response header is used to help protect against cross-site scripting attacks. It gives control to website administrators over resources that the client is allowed to load.

The general syntax is:

Content-Security-Policy: <directive> <value>

A large number of directives are supported and they fall into categories including document directives, fetch directives, navigation directives, reporting directives, and others. Also noteworthy are the directives that have been deprecated.

Document directives

A document directive works within the scope of a document or worker environment.

base-uri

The base-uri directive restricts the URLs that can be used in the base element.

sandbox

The sandbox directive creates a sandbox for the requested resource. This is similar to the iframe sandbox attribute.

Fetch directives

The fetch directives control the locations that particular resources can be loaded from.

child-src

The child-src directive defines sources nested browsing contexts and web workers for web elements such as frame and iframe. However, regulating nested browsing context shall be done using frame-src, whereas regulating web workers shall be done using worker-src.

connect-src

The connect-src directive is used to retract URLs that can be loaded using scripts.

default-src

The default-src directive acts as a fallback for all of the other fetch directives.

font-src

The font-src directive is used to specify valid sources for fonts using CSS @font-face.

frame-src

The frame-src directive is used to specify valid sources for nested browsing contexts using web elements such as frame and iframe.

img-src

The img-src directive is used to specify valid sources for images and favicons.

manifest-src

The manifest-src directive refers to valid sources for application manifest files.

media-src

The media-src directive specifies sources for loading media including audio, video, and track elements.

object-src

The object-src directive refers to valid sources for elements including object, embed, and applet.

prefetch-src

This prefetch-src directive specifies sources that will be prefetched or prerendered.

script-src

The script-src directive specifies a valid source for JavaScript.

script-src-elem

The script-src-elem directive is similar to script-src, except that it is specific to JavaScript script elements.

script-src-attr

The script-src-attr directive is similar to script-src, except that it specifies sources for JavaScript inline event handlers.

style-src

The style-src directive specifies valid sources for CSS stylesheets.

style-src-elem

The style-src-elem directive is similar to style-src, except that it is for stylesheet style elements, and link elements that include rel="stylesheet".

style-src-attr

The style-src-attr directive relates to inline styles applicable to DOM elements.

worker-src

The worker-src directive applies to Worker, SharedWorker, and ServiceWorker scripts.

The navigation directives are used to grant permissions over where clients can navigate or submit forms from.

form-action

The form-action directive is used to restrict the URLs used as a target of a form submission given a certain context.

frame-ancestors

The frame-ancestors directive specifies parents that might embed pages using frame, iframe, object, embed, or applet.

The navigate-to directive restricts URLs that a document can navigate to. The navigation can be done by any method.

Reporting directives

The reporting directives are used to control the reporting process for content security policy violations. Further information is available in the section on the HTTP Content-Security-Policy-Report-Only header.

report-uri

When the report-uri directive is included, it will report violations of the content security policy to the specified address. The report-uri directive is being replaced by report-to.

report-to

The report-to directive is used to report violations.

Other Directives

require-sri-for

The require-sri-for directive implies that the page requires SRI for scripts of styles.

require-trusted-types-for

The require-trusted-types-for directive enforces the use of Trusted Types policies for DOM XSS injections.

trusted-types

The trusted-types directive is used to provide a list of Trusted Types policies. These allow applications to restrict DOM XSS injection, disallowing strings in favor of more secure typed values.

upgrade-insecure-requests

This upgrade-insecure-requests directive asks clients to consider all of the URLs to be secure, even if they are being served using HTTP. This is useful for websites that are in the process of upgrading and have a large number of insecure resources still available.

Deprecated directives

Several directives are no longer used and deprecated, including those in this section.

block-all-mixed-content

The block-all-mixed-content directive blocks all assets that use HTTP while the page is loaded using HTTPS.

plugin-types

The plugin-types directive was used to restrict the plugins embedded into a document.

referrer

The referrer directive was used to include information in the HTTP Referer header for links that navigated away from the current page. The HTTP Referrer-Policy header is used instead of this.

Values

Directives accept certain values and the following is an overview of the acceptable values. Several values have the prefix unsafe-, which makes exceptional allowances.

none

A value of none will not allow any resources to be loaded.

self

When self is specified, only resources from the current origin are allowed.

strict-dynamic

The value for the strict-dynamic directive implies that the trust granted to a script on the page is extended to any script that it loads.

report-sample

When the report-sample value is included, a sample of the code that caused the violation is included in the report.

unsafe-inline

The value for the unsafe-inline directive allows the use of inline resources.

unsafe-eval

The value for the unsafe-eval directive will allow the use of dynamic code evaluation, such as eval.

unsafe-hashes

The unsafe-hashes directive allows for certain inline event handlers.

unsafe-allow-redirects

The value for the unsafe-allow-redirects directive allows for redirects including HTTP 301 Moved Permanently, 302 Found, 307 Temporary Redirect and 308 Permanent Redirect status codes, as long as the final destination is compliant.

nonce-*

The value for the nonce-* directive is a cryptographic none that is used only once, and it is done to allow scripts. Each time the server transmits a policy, it generates a new nonce value. It is used in conjunction with the script tag nonce attribute.

SHA-

The value for the SHA*-* directive is a message digest generated using sha256, sha384, or sha512.

Example

In the first example, Content-Security-Policy only allows access to resources using the HTTPS protocol.

Content-Security-Policy: default-src https:

In this next example, the policy contains two directives. The default-src directs that URL resources can only be loaded from the same origin, or same domain and scheme. When the img-src directive is included, it relaxes the policy to allow the loading of images from domain images.example.re.

Content-Security-Policy: default-src ‘self’; img-src ‘self’ images.example.re

The following example is a minimal Content-Security-Policy header intended to work with Google Maps. Without it, an attempt to load a Google map might return a Content-Security-Policy failure.

Content-Security-Policy: script-src maps.googleapis.com;img-src data: maps.gstatic.com *.googleapis.com *.ggpht.com

The following is another Google example, where the site intends to render various Google fonts and styles. Without the Content-Security-Policy allowance, an attempt to use Google fonts may fail.

Content-Security-Policy: default-src 'self'; font-src fonts.gstatic.com; style-src 'self' fonts.googleapis.com

Content-Security-Policy-Report-Only

Before a new content security policy is enforced, site owners may choose to simply report violations that will have occurred under the circumstances. This can be accomplished using the Content-Security-Policy-Report-Only HTTP response header.

Takeaway

The Content-Security-Policy header gives developers control over what resources are loaded for specific pages, primarily focused on server Origins and script endpoints and assist to protect against cross-site scripting attacks.

See also

Last updated: August 2, 2023