Content Security Policy Details

Version: 0.1 | 0.2 | 1.0 | 2.0 (cur)

Policy Focus

There are a total of seven policy areas that website administrators can define via Content Security Policy. Meaningful policy sets can be created, however, by defining just a few of these policy areas. With the exception of the allow section, each policy area is optional and can be defined independently from the other areas. If Content Security Policy is specified by a web site, the allow section is required. It is treated as a catch-all for types of content whose policy may or may not be defined. If an allow section is not specified, then allow none is implied. Policies can be defined for more specific types of content including: images, scripts, objects, frames and iframes.

Security policy is defined on a per-resource basis and can vary according to the sensitivity of a particular resource. Some example policy sets are provided below.

1. allow
   • allow is the catch-all section that defines the security policy for all types of content which are not called out in any of the specific policy areas below
   • It is required to be defined for any resource which utilizes Content Security Policy
     • If Content Security Policy is enabled but allow is not defined, then allow none is implied
2. img-src
   • Indicates which hosts are valid sources for images
   • Images from non-white-listed hosts will not be requested or loaded
3. script-src
   • Indicates which hosts are valid sources for JavaScript
   • Scripts from non-white-listed hosts will not be requested or executed
   • If Content Security Policy is set for a resource, only script loaded from white-listed hosts will execute
     • Inline script (contents of <script> nodes) is disabled
     • Script called using event-handling attributes is not executed
   • In summary, only script which is placed in an external script file and served from a white-listed host will be executed.
4. object-src
   • Indicates which hosts are valid sources for <object>, <embed>, and <applet> elements
   • Objects from non-white-listed hosts will not be requested or loaded
5. frame-src
   • Indicates which hosts are valid sources for <frame> and <iframe> elements
   • Frame content from non-white-listed hosts will not be requested or loaded
6. report-uri
   • Instructs the browser where to send a report when Content Security Policy is violated
   • The report will be a XML document sent via POST to the specified URI containing the following:
     • request - HTTP request line which led to the policy violation (method, resource path, HTTP version)
     • headers - HTTP headers sent which led to the policy violation
     • blocked - URI of the resource that was blocked from loading
   • Sample report:

     <csp-report>
       <request>GET /index.html HTTP/1.1</request>
       <headers>Host: example.com
                User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9) Gecko/2008061015 Firefox/3.0
                Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
       </headers>
       <blocked>http://evil.com/some_image.png</blocked>
     </csp-report>

7. policy-uri
   • Indicates the location of a file containing the security policies for the resource
   • The policy-uri must point to the same host as the resource for which it defines policy
   • If a valid policy-uri is specified, any policy defined in the HTTP header will be ignored

Syntax and Delivery

Content Security Policy is delivered to the browser in one of two ways: a custom HTTP header or a file served from the same host as the resource to be secured. If a policy-uri is specified then the policy defined in that file will take precedence over any policy defined in the HTTP header. The syntax is identical between file-based and header-based policy. The contents of a policy file are equivalent to the value of the X-Content-Security-Policy header. Authors who are unable to support signaling via HTTP headers can use <meta> tags with http-equiv="X-Content-Security-Policy" to define their policies. HTTP header-based policy will take precedence over <meta> tag-based policy if both are present.

Much of the policy described below makes reference to host items since Content Security Policy applies levels of privilege to content based on its originating host. A host item is a domain string which may contain wildcards (*) which is explicitly allowed to be a source of content for a particular resource. Internationalized domain names are specified according to their punycode representations. Sets of security policies may contain both general (e.g. allow) and specific (e.g. script-src) instructions that could apply to the same content. In these cases, policy from the more specific instruction will be enforced.

Content Security Policy supports the following three keywords to be used as host items:

• self: refers to the host that the resource is served from
• none: indicates the empty set
• data: indicates data: URLs are a valid source of content

Content Security Policy will be specified according to the following format:

• Policy sections are delimited by semi-colon (;)
• Each policy section will consist of a policy section identifier followed by:
  1. a whitespace-delimited list of host items or
  2. a single URI
• Valid policy section identifiers include:
  1. allow
  2. img-src
  3. script-src
  4. object-src
  5. frame-src
  6. report-uri
  7. policy-uri

Example Use Cases

1. Site wants all content to come from its own domain:
   • X-Content-Security-Policy: allow self
   • <meta http-equiv="X-Content-Security-Policy" content="allow self" />
2. Auction site wants to allow images from anywhere, plugin content from a list of trusted media providers, and scripts only from its server hosting sanitized JavaScript:
   • X-Content-Security-Policy: allow self; img-src *; object-src media1.com media2.com; script-src userscripts.example.com
   • <meta http-equiv="X-Content-Security-Policy" content="allow self; img-src *; object-src media1.com media2.com; script-src userscripts.example.com" />

The Origin Header

Since Cross Site Request Forgery has been removed from the scope of Content Security Policy, we now propose that the Origin header be implemented to address CSRF.

Conclusions

Content Security Policy provides a way to greatly reduce or altogether eliminate a website's attack surface for Cross-Site Scripting. With proper Content Security Policy in place, a successful XSS attack will require the attacker to have control over the contents of white-listed script source files. No longer will XSS attacks which rely on echoing script into page contents be effective. Further, if a site knows it never wants to have JavaScript executing in its pages, it can simply globally disable JavaScript and not have to worry about script injection attacks against its users with supporting browsers.

The Origin header provides a simple way for a website to mitigate Cross-Site Request Forgery against its sensitive resources. The Origin header provides the information a server needs to validate its requests while avoiding the privacy concerns which were chief among the criticisms of Referer.

As seen in every aspect of Computer Security, the protection of a system is best achieved through a variety of overlapping controls. Content Security Policy aims to be one part of a larger defense-in-depth application security strategy, or as our colleague Gerv likes to say, "belt-and-braces". Web administrators, while maintaining their normal security auditing and remediation process, will embrace the opportunity to mitigate broad classes of web app vulnerabilities, for those users with compliant browsers, by defining a few simple rules.

Overview | Details | Download | Demo | Origin Header | Discussion