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..4809a828fdf8b7aae5adfe9afe71cbe532a84ed3
--- /dev/null
+++ b/chrome/common/extensions/docs/static/contentSecurityPolicy.html
@@ -0,0 +1,221 @@
+<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
+  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
+  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">
+    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 clickHandler(element) {
+        // Do something awesome with `element`!
+      }
+    &lt;/script&gt;
+  &lt;/head&gt;
+  &lt;body&gt;
+    &lt;button onclick="clickHandler(this)"&gt;Click for awesomeness!&lt;/button&gt;
+  &lt;/body&gt;
+&lt;/html&gt;</pre>
+
+<p>
+  Two things will need to change in order to make this work the way you expect
+  it to. First, the <code>clickHandler</code> definition needs to move into an
+  external JavaScript file (<code>popup.js</code> would be a good target).
+  Second, the inline event handler definition must be rewritten in terms of
+  <code>addEventListener</code> and extracted into <code>popup.js</code>. This
+  might look something like the following:
+</p>
+
+<pre>popup.js:
+=========
+
+function clickHandler(e) {
+  // Do something awesome with `e.target`!
+}
+
+// Add event listeners once the DOM has fully loaded by listening for the
+// `DOMContentLoaded` event on the docuent, 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 src="popup.js"&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>
+
+<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. Only HTTPS
+  origins will be accepted, whitelisting insecure HTTP resources will have no
+  effect. This is intentional.
+</p>
+
+<p>
+  A relaxed policy definition which allows script resources to be loaded from
+  <code>https://example.com/</code> 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 convinience. 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>