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..494387e171bd6deb0c809506fa0b1ce6e986e8fd |
--- /dev/null |
+++ b/chrome/common/extensions/docs/static/contentSecurityPolicy.html |
@@ -0,0 +1,272 @@ |
+<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> |
+ 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><script></code> blocks <strong>and</strong> inline event handlers |
+ (e.g. <code><button onclick="..."></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><!doctype html> |
+<html> |
+ <head> |
+ <title>My Awesome Popup!</title> |
+ <script> |
+ function awesome() { |
+ // do something awesome! |
+ } |
+ |
+ function totallyAwesome() { |
+ // do something TOTALLY awesome! |
+ } |
+ |
+ function clickHandler(element) { |
+ setTimeout(<strong>"awesome(); totallyAwesome()"</strong>, 1000); |
+ } |
+ </script> |
+ </head> |
+ <body> |
+ <button <strong>onclick="clickHandler(this)"</strong>> |
+ Click for awesomeness! |
+ </button> |
+ </body> |
+</html></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: |
+=========== |
+ |
+<!doctype html> |
+<html> |
+ <head> |
+ <title>My Awesome Popup!</title> |
+ <script <strong>src="popup.js"</strong>></script> |
+ </script> |
+ </head> |
+ <body> |
+ <button>Click for awesomeness!</button> |
+ </body> |
+</html></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><!doctype html> |
+<html> |
+ <head> |
+ <title>My Awesome Popup!</title> |
+ <script src="<strong>http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js</strong>"></script> |
+ </script> |
+ </head> |
+ <body> |
+ <button>Click for awesomeness!</button> |
+ </body> |
+</html></pre> |
+ |
+<p> |
+ Download the file, include it in your package, and write: |
+<p> |
+ |
+<pre><!doctype html> |
+<html> |
+ <head> |
+ <title>My Awesome Popup!</title> |
+ <script src="<strong>jquery.min.js</strong>"></script> |
+ </script> |
+ </head> |
+ <body> |
+ <button>Click for awesomeness!</button> |
+ </body> |
+</html></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> |