Improving `content_security_policy` documentation.

chrome/common/extensions/docs/static/contentSecurityPolicy.html

Index: chrome/common/extensions/docs/static/contentSecurityPolicy.html
diff --git a/chrome/common/extensions/docs/static/contentSecurityPolicy.html b/chrome/common/extensions/docs/static/contentSecurityPolicy.html
new file mode 100644
index 0000000000000000000000000000000000000000..aa4dc0c95510c7f2e0f251e96f127d7c48363f8e
--- /dev/null
+++ b/chrome/common/extensions/docs/static/contentSecurityPolicy.html
@@ -0,0 +1,270 @@
+<div id="pageData-name" class="pageData">Content Security Policy (CSP)</div>
+<div id="pageData-showTOC" class="pageData">true</div>
+
+<p>
+  Content Security Policy is a language used to describe restrictions on the
+  content that can be loaded and executed by your extension. In order to

[mkearney, 2012/01/25 22:39:22]

Is there any value in defining CSP in the larger, global content, similar to how
it is defined in the specification? This seems to imply that CSP is specifically
for extensions.

[Mike West, 2012/01/25 23:34:36]

Rephrased.

+  mitigate a large class of potental cross-site scripting issues, Chrome's
+  extension system enforces a fairly strict <strong>Content Security Policy
+  (CSP)</strong> that has a few impacts on the way you build extensions and
+  applications.
+</p>
+
+<p>
+  In general, CSP works as a black/whitelisting mechanism for resources loaded
+  or execute by your extensions. Defining a reasonable policy for your extension

[mkearney, 2012/01/25 22:39:22]

Change 'execute' to be 'executed'.

[Mike West, 2012/01/25 23:34:36]

Done.

+  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">

[mkearney, 2012/01/25 22:39:22]

What about linking directly to the syntax (#syntax)?

[Mike West, 2012/01/25 23:34:36]

Done.

+    the Content Security Policy specification
+  </a>.
+</p>
+
+<h2>Default Policy Restrictions</h2>
+
+<p>
+  By default, Chrome defines a content security policy of:
+</p>
+
+<pre>script-src 'self'; object-src 'self'</pre>
+
+<p>
+  This policy limits extensions 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 docuent, and adding your listeners to

[mkearney, 2012/01/25 22:39:22]

'docuent' should be 'document'.

[Mike West, 2012/01/25 23:34:36]

Done.

+// specific elements when it triggers.
+document.addEventListener('DOMContentLoaded', function () {
+  document.querySelector('button').addEventListener('click', clickHandler);
+});
+
+popup.html:
+===========
+
+<!doctype html>
+<html>
+  <head>
+    <title>My Awesome Popup!</title>
+    &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>https://example.com/</code> might look like:

[mkearney, 2012/01/25 22:39:22]

This is coming up as a link, and when you click it, the link is broken. Maybe
try [verbatim]...[endverbatim] around the <code> tags. I haven't tried this in
chromium, mind you, so not too sure if this is the right solution.

[Mike West, 2012/01/25 23:34:36]

Dunno. Reworded to avoid the URL. :)

+</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 convinience. To specify

[mkearney, 2012/01/25 22:39:22]

Spelling - 'convinience' should be 'convenience'.

[Mike West, 2012/01/25 23:34:36]

Spelling a word only one way is boring.

+  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>