Index: chrome/common/extensions/docs/contentSecurityPolicy.html |
diff --git a/chrome/common/extensions/docs/tut_analytics.html b/chrome/common/extensions/docs/contentSecurityPolicy.html |
similarity index 69% |
copy from chrome/common/extensions/docs/tut_analytics.html |
copy to chrome/common/extensions/docs/contentSecurityPolicy.html |
index 180cf1ed9be092124a253fcc4b03ff9c777c2079..4c4407fd750ad8051faa05b960c7ba571af2896a 100644 |
--- a/chrome/common/extensions/docs/tut_analytics.html |
+++ b/chrome/common/extensions/docs/contentSecurityPolicy.html |
@@ -16,7 +16,7 @@ |
<script type="text/javascript" src="js/api_page_generator.js"></script> |
<script type="text/javascript" src="js/bootstrap.js"></script> |
<script type="text/javascript" src="js/sidebar.js"></script> |
- <title>Tutorial: Google Analytics - Google Chrome Extensions - Google Code</title></head> |
+ <title>Content Security Policy (CSP) - Google Chrome Extensions - Google Code</title></head> |
<body> <div id="devModeWarning" class="displayModeWarning"> |
You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files. |
</div> |
@@ -277,7 +277,7 @@ |
<li><h2><a href="tutorials.html">Tutorials</a></h2> |
<ul> |
<li><a href="tut_debugging.html">Debugging</a></li> |
- <li class="leftNavSelected">Google Analytics</li> |
+ <li><a href="tut_analytics.html">Google Analytics</a></li> |
<li><a href="tut_oauth.html">OAuth</a></li> |
</ul> |
</li> |
@@ -311,49 +311,30 @@ |
<div class="g-unit" id="gc-pagecontent"> |
<div id="pageTitle"> |
- <h1 class="page_title">Tutorial: Google Analytics</h1> |
+ <h1 class="page_title">Content Security Policy (CSP)</h1> |
</div> |
<!-- TABLE OF CONTENTS --> |
<div id="toc"> |
<h2>Contents</h2> |
<ol> |
<li> |
- <a href="#toc-requirements">Requirements</a> |
+ <a href="#H2-0">Default Policy Restrictions</a> |
<ol> |
- <li style="display: none; "> |
- <a>h3Name</a> |
- </li> |
- </ol> |
- </li><li> |
- <a href="#toc-installing">Installing the tracking code</a> |
- <ol> |
- <li style="display: none; "> |
- <a>h3Name</a> |
+ <li> |
+ <a href="#H3-1">Inline JavaScript will not be executed</a> |
+ </li><li> |
+ <a href="#H3-2">Only local script and and object resources are loaded</a> |
</li> |
</ol> |
</li><li> |
- <a href="#toc-tracking-pageviews">Tracking page views</a> |
+ <a href="#H2-3">Relaxing the default policy</a> |
<ol> |
<li style="display: none; "> |
<a>h3Name</a> |
</li> |
</ol> |
</li><li> |
- <a href="#toc-debugging">Monitoring analytics requests</a> |
- <ol> |
- <li style="display: none; "> |
- <a>h3Name</a> |
- </li> |
- </ol> |
- </li><li> |
- <a href="#toc-tracking-events">Tracking events</a> |
- <ol> |
- <li style="display: none; "> |
- <a>h3Name</a> |
- </li> |
- </ol> |
- </li><li> |
- <a href="#toc-samplecode">Sample code</a> |
+ <a href="#H2-4">Tightening the default policy</a> |
<ol> |
<li style="display: none; "> |
<a>h3Name</a> |
@@ -379,197 +360,277 @@ |
</p> |
<!-- STATIC CONTENT PLACEHOLDER --> |
- <div id="static"><div id="pageData-name" class="pageData">Tutorial: Google Analytics</div> |
+ <div id="static"><div id="pageData-name" class="pageData">Content Security Policy (CSP)</div> |
<div id="pageData-showTOC" class="pageData">true</div> |
-<p>This tutorial demonstrates using Google Analytics to track the usage of your |
-extension.</p> |
+<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> |
-<h2 id="toc-requirements">Requirements</h2> |
<p> |
- This tutorial expects that you have some familiarity writing extensions for |
- Google Chrome. If you need information on how to write an extension, please |
- read the <a href="gettingstarted.html">Getting Started tutorial</a>. |
+ 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> |
- You will also need a <a href="http://www.google.com/analytics">Google |
- Analytics account</a> set up to track your extension. Note that when setting |
- up the account, you can use any value in the Website's URL field, as your |
- extension will not have an URL of its own. |
+ 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> |
-<p style="text-align: center"> |
- <img src="images/tut_analytics/screenshot01.png" style="width:400px;height:82px;" alt="The analytics setup with info for a chrome extension filled out."> |
+<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> |
+<a name="H2-0"></a><h2>Default Policy Restrictions</h2> |
+ |
<p> |
- Also note that Google Analytics requires version <strong>4.0.302.2</strong> |
- of Google Chrome to work correctly. Users with an earlier version of Google |
- Chrome will not show up on your Google Analytics reports. View |
- <a href="faq.html#faq-dev-14">this FAQ entry</a> to learn how to check which |
- version of Google Chrome is deployed to which platform. |
+ By default, Chrome defines a content security policy of: |
</p> |
-<h2 id="toc-installing">Installing the tracking code</h2> |
+<pre>script-src 'self'; object-src 'self'</pre> |
<p> |
- The standard Google Analytics tracking code snippet fetches a file named |
- <code>ga.js</code> from an SSL protected URL if the current page |
- was loaded using the <code>https://</code> protocol. <strong>It is strongly |
- advised to use the SSL protected ga.js in an extension</strong>, |
- but Google Chrome extension |
- pages are hosted under <code>chrome-extension://</code> URLs, so the tracking |
- snippet must be modified slightly to pull <code>ga.js</code> directly from |
- <code>https://ssl.google-analytics.com/ga.js</code> instead of the default |
- location. |
+ This policy limits extensions in two ways: |
</p> |
+<a name="H3-1"></a><h3>Inline JavaScript will not be executed</h3> |
+ |
<p> |
- Below is a modified snippet for the |
- <a href="http://code.google.com/apis/analytics/docs/tracking/asyncTracking.html">asynchronous |
- tracking API</a> (the modified line is bolded): |
+ 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> |
-<pre>(function() { |
- var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; |
- <strong>ga.src = 'https://ssl.google-analytics.com/ga.js';</strong> |
- var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); |
-})(); |
-</pre> |
- |
<p> |
- Here is a background page which loads the asynchronous tracking code and |
- tracks a single page view: |
+ 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> |
+<pre><!doctype html> |
<html> |
- <head> |
- ... |
- </head> |
- <body> |
- <script> |
- var _gaq = _gaq || []; |
- _gaq.push(['_setAccount', 'UA-XXXXXXXX-X']); |
- _gaq.push(['_trackPageview']); |
- |
- (function() { |
- var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; |
- ga.src = 'https://ssl.google-analytics.com/ga.js'; |
- var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); |
- })(); |
- </script> |
- |
- ... |
- </body> |
-</html> |
-</pre> |
+ <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> |
- Keep in mind that the string <code>UA-XXXXXXXX-X</code> should be replaced |
- with your own Google Analytics account number. |
+ Three things will need to change in order to make this work the way you expect |
+ it to: |
</p> |
-<h2 id="toc-tracking-pageviews">Tracking page views</h2> |
+<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> |
- The <code>_gaq.push(['_trackPageview']);</code> code will track a single |
- page view. This code may be used on any page in your extension. When |
- placed on a background page, it will register a view once per browser |
- session. When placed on a popup, it will register a view once every time |
- the popup is opened. |
+ Those changes might look something like the following: |
</p> |
-<p> |
- By looking at the page view data for each page in your extension, you can |
- get an idea of how many times your users interact with your extension per |
- browser session: |
-</p> |
+<pre>popup.js: |
+========= |
-<p style="text-align: center"> |
- <img src="images/tut_analytics/screenshot02.png" style="width:300px;height:119px;" alt="Analytics view of the top content for a site."> |
-</p> |
+function awesome() { |
+ // Do something awesome! |
+} |
-<h2 id="toc-debugging">Monitoring analytics requests</h2> |
+function totallyAwesome() { |
+ // do something TOTALLY awesome! |
+} |
-<p> |
- To ensure that tracking data from your extension is being sent to Google |
- Analytics, you can inspect the pages of your extension in the |
- Developer Tools window (see the |
- <a href="tut_debugging.html">debugging tutorial</a> for more information). |
- As the following figure shows, you should see requests for a file named |
- <strong>__utm.gif</strong> if everything is set up correctly. |
-</p> |
+<strong> |
+function awesomeTask() { |
+ awesome(); |
+ totallyAwesome(); |
+} |
+</strong> |
-<p style="text-align: center"> |
- <img src="images/tut_analytics/screenshot04.png" style="width:683px;height:418px;" alt="Developer Tools window showing the __utm.gif request"> |
-</p> |
+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); |
+}); |
-<h2 id="toc-tracking-events">Tracking events</h2> |
+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> |
- By configuring event tracking, you can determine which parts of your |
- extension your users interact with the most. For example, if you have |
- three buttons users may click: |
-</p> |
+ |
-<pre> <button>Button 1</button> |
- <button>Button 2</button> |
- <button>Button 3</button> |
-</pre> |
+</p><a name="H3-2"></a><h3>Only local script and and object resources are loaded</h3> |
<p> |
- Write a function that sends click events to Google Analytics: |
+ 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> |
-<pre> function trackButton(button_id) { |
- _gaq.push(['_trackEvent', 'button' + button_id, 'clicked']); |
- }; |
-</pre> |
- |
<p> |
- And call it when each button is pressed: |
+ 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> <button onclick="trackButton(1);">Button 1</button> |
- <button onclick="trackButton(2);">Button 2</button> |
- <button onclick="trackButton(3);">Button 3</button> |
-</pre> |
+<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> |
- The Google Analytics event tracking overview page will give you metrics |
- regarding how many times each individual button is clicked: |
-</p> |
+ Download the file, include it in your package, and write: |
+</p><p> |
-<p style="text-align: center"> |
- <img src="images/tut_analytics/screenshot03.png" style="width:300px;height:482px;" alt="Analytics view of the event tracking data for a site."> |
+</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> |
+ |
+<a name="H2-3"></a><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> |
- By using this approach, you can see which parts of your extension are |
- under-or-overutilized. This information can help guide decisions about UI |
- redesigns or additional functionality to implement. |
+ 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> |
- For more information about using the event tracking API, see the |
- Google Analytics |
- <a href="http://code.google.com/apis/analytics/docs/tracking/eventTrackerOverview.html">developer |
- documentation</a>. |
+ A relaxed policy definition which allows script resources to be loaded from |
+ <code>example.com</code> over HTTPS might look like: |
</p> |
-<h2 id="toc-samplecode">Sample code</h2> |
+<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> |
- A sample extension that uses these techniques is |
- available in the Chromium source tree: |
+ 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> |
-<blockquote> |
- <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/tutorials/analytics/">.../examples/tutorials/analytics/</a> |
-</blockquote> |
-<p></p> |
+<a name="H2-4"></a><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> |
</div> |
<!-- API PAGE --> |