path: root/chrome/common/extensions/docs/static/contentSecurityPolicy.html

<div id="pageData-name" class="pageData">Content Security Policy (CSP)</div>
<div id="pageData-showTOC" class="pageData">true</div>

<p>
  In order to mitigate a large class of potental cross-site scripting issues,
  Chrome's extension system has incorporated the general concept of
  <a href="http://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html">
    <strong>Content Security Policy (CSP)</strong>
  </a>. This introduces some fairly strict policies that will make extensions
  more secure by default, and provides you with the ability to create and
  enforce rules governing the types of content that can be loaded and executed
  by your extensions and applications.
</p>

<p>
  In general, CSP works as a black/whitelisting mechanism for resources loaded
  or executed by your extensions. Defining a reasonable policy for your
  extension enables you to carefully consider the resources that your extension
  requires, and to ask the browser to ensure that those are the only resources
  your extension has access to. These policies provide security over and above
  the <a href="manifest.html#permissions">host permissions</a> your extension
  requests; they're an additional layer of protection, not a replacement.
</p>

<p>
  On the web, such a policy is defined via an HTTP header or <code>meta</code>
  element. Inside Chrome's extension system, neither is an appropriate
  mechanism. Instead, an extension's policy is defined via the extension's
  <a href="manifest.html"><code>manifest.json</code></a> file as follows:
</p>

<pre>{
  ...,
  "content_security_policy": "[POLICY STRING GOES HERE]"
  ...
}</pre>

<p class="note">
  For full details regarding CSP's syntax, please take a look at
  <a href="http://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html#syntax">
    the Content Security Policy specification
  </a>.
</p>

<h2>Default Policy Restrictions</h2>

<p>
  Packages that do not define a <a href="manifestVersion.html">
    <code>manifest_version</code>
  </a> have no default content security policy. Those that select
  <code>manifest_version</code></a> 2, have a default content security policy
  of:
</p>

<pre>script-src 'self'; object-src 'self'</pre>

<p>
  This policy adds security by limiting extensions and applications in two ways:
</p>

<h3>Inline JavaScript will not be executed</h3>

<p>
  Inline JavaScript, as well as dangerous string-to-JavaScript methods like
 <code>eval</code>, will not be executed. This restriction bans both inline
 <code>&lt;script&gt;</code> blocks <strong>and</strong> inline event handlers
 (e.g. <code>&lt;button onclick="..."&gt;</code>).
</p>

<p>
  The first restriction wipes out a huge class of cross-site scripting attacks
  by making it impossible for you to accidentally execute script provided by a
  malicious third-party. It does, however, require you to write your code with a
  clean separation between content and behavior (which you should of course do
  anyway, right?). An example might make this clearer. You might try to write a
  <a href="browserAction.html#popups">Browser Action's popup</a> as a single
  <code>popup.html</code> containing:
</p>

<pre>&lt;!doctype html&gt;
&lt;html&gt;
  &lt;head&gt;
    &lt;title&gt;My Awesome Popup!&lt;/title&gt;
    &lt;script&gt;
      function awesome() {
        // do something awesome!
      }

      function totallyAwesome() {
        // do something TOTALLY awesome!
      }

      function clickHandler(element) {
        setTimeout(<strong>"awesome(); totallyAwesome()"</strong>, 1000);
      }
    &lt;/script&gt;
  &lt;/head&gt;
  &lt;body&gt;
    &lt;button <strong>onclick="clickHandler(this)"</strong>&gt;
      Click for awesomeness!
    &lt;/button&gt;
  &lt;/body&gt;
&lt;/html&gt;</pre>

<p>
  Three things will need to change in order to make this work the way you expect
  it to:
</p>

<ul>
  <li>
    The <code>clickHandler</code> definition needs to move into an external
    JavaScript file (<code>popup.js</code> would be a good target).
  </li>
  <li>
    The inline event handler definition must be rewritten in terms of
    <code>addEventListener</code> and extracted into <code>popup.js</code>.
  </li>
  <li>
    The <code>setTimeout</code> call will need to be rewritten to avoid
    converting the string <code>"awesome(); totallyAwesome()"</code> into
    JavaScript for execution.
  </li>
</ul>

<p>
  Those changes might look something like the following:
</p>

<pre>popup.js:
=========

function awesome() {
  // Do something awesome!
}

function totallyAwesome() {
  // do something TOTALLY awesome!
}

<strong>
function awesomeTask() {
  awesome();
  totallyAwesome();
}
</strong>

function clickHandler(e) {
  setTimeout(<strong>awesomeTask</strong>, 1000);
}

// Add event listeners once the DOM has fully loaded by listening for the
// `DOMContentLoaded` event on the document, and adding your listeners to
// specific elements when it triggers.
document.addEventListener('DOMContentLoaded', function () {
  document.querySelector('button').addEventListener('click', clickHandler);
});

popup.html:
===========

&lt;!doctype html&gt;
&lt;html&gt;
  &lt;head&gt;
    &lt;title&gt;My Awesome Popup!&lt;/title&gt;
    &lt;script <strong>src="popup.js"</strong>&gt;&lt;/script&gt;
    &lt;/script&gt;
  &lt;/head&gt;
  &lt;body&gt;
    &lt;button&gt;Click for awesomeness!&lt;/button&gt;
  &lt;/body&gt;
&lt;/html&gt;</pre>

<p>
  

<h3>Only local script and and object resources are loaded</h3>

<p>
  Script and object resources can only be loaded from the extension's
  package, not from the web at large. This ensures that your extension only
  executes the code you've specifically approved, preventing an active network
  attacker from maliciously redirecting your request for a resource.
</p>

<p>
  Instead of writing code that depends on jQuery (or any other library) loading
  from an external CDN, consider including the specific version of jQuery in
  your extension package. That is, instead of:
</p>

<pre>&lt;!doctype html&gt;
&lt;html&gt;
  &lt;head&gt;
    &lt;title&gt;My Awesome Popup!&lt;/title&gt;
    &lt;script src="<strong>http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js</strong>"&gt;&lt;/script&gt;
    &lt;/script&gt;
  &lt;/head&gt;
  &lt;body&gt;
    &lt;button&gt;Click for awesomeness!&lt;/button&gt;
  &lt;/body&gt;
&lt;/html&gt;</pre>

<p>
  Download the file, include it in your package, and write:
<p>

<pre>&lt;!doctype html&gt;
&lt;html&gt;
  &lt;head&gt;
    &lt;title&gt;My Awesome Popup!&lt;/title&gt;
    &lt;script src="<strong>jquery.min.js</strong>"&gt;&lt;/script&gt;
    &lt;/script&gt;
  &lt;/head&gt;
  &lt;body&gt;
    &lt;button&gt;Click for awesomeness!&lt;/button&gt;
  &lt;/body&gt;
&lt;/html&gt;</pre>

<h2>Relaxing the default policy</h2>

<p>
  There is no mechanism for relaxing the restriction against executing inline
  JavaScript. In particular, setting a script policy that includes
  <code>unsafe-inline</code> will have no effect. This is intentional.
</p>

<p>
  If, on the other hand, you have a need for some external JavaScript or object
  resources, you can relax the policy to a limited extent by whitelisting
  specific HTTPS origins from which scripts should be accepted. Whitelisting
  insecure HTTP resources will have no effect. This is intentional, because
  we want to ensure that executable resources loaded with an extension's
  elevated permissions is exactly the resource you expect, and hasn't been
  replaced by an active network attacker. As <a
  href="http://en.wikipedia.org/wiki/Man-in-the-middle_attack">man-in-the-middle
  attacks</a> are both trivial and undetectable over HTTP, only HTTPS origins
  will be accepted.
</p>

<p>
  A relaxed policy definition which allows script resources to be loaded from
  <code>example.com</code> over HTTPS might look like:
</p>

<pre>{
  ...,
  "content_security_policy": "script-src 'self' https://example.com; object-src 'self'",
  ...
}</pre>

<p class="note">
  Note that both <code>script-src</code> and <code>object-src</code> are defined
  by the policy. Chrome will not accept a policy that doesn't limit each of
  these values to (at least) <code>'self'</code>.
</p>

<p>
  Making use of Google Analytics is the canonical example for this sort of
  policy definition. It's common enough that we've provided an Analytics
  boilerplate of sorts in the <a href="samples.html#analytics">Event Tracking
  with Google Analytics</a> sample extension, and a
<a href="tut_analytics.html">brief tutorial</a> that goes into more detail.
</p>

<h2>Tightening the default policy</h2>

<p>
  You may, of course, tighten this policy to whatever extent your extension
  allows in order to increase security at the expense of convenience. To specify
  that your extension can only load resources of <em>any</em> type (images, etc)
  from its own package, for example, a policy of <code>default-src 'self'</code>
  would be appropriate. The <a href="samples.html#mappy">Mappy</a> sample
  extension is a good example of an extension that's been locked down above and
  beyond the defaults.
</p>