Chromium Code Reviews Chromium Code Reviews
Issue 9212044:
Improving `content_security_policy` documentation. (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src| 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 71% |
| copy from chrome/common/extensions/docs/tut_analytics.html |
| copy to chrome/common/extensions/docs/contentSecurityPolicy.html |
| index f3b07fe10722f1212892c961d68f5e8d785ae3e3..215e9a4b0a0f4437a03a077feee5b0e14aef1d71 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="gc-container" class="labs"> |
| <div id="devModeWarning"> |
| 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. |
| @@ -261,7 +261,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> |
| @@ -295,49 +295,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> |
| - </ol> |
| - </li><li> |
| - <a href="#toc-tracking-pageviews">Tracking page views</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> |
| + <a href="#H3-1">Inline JavaScript will not be executed</a> |
|
abarth-chromium
2012/01/24 16:42:36
Also, eval is banned.
Mike West
2012/01/25 16:08:29
I note that down in the body. This line is just th
|
| + </li><li> |
| + <a href="#H3-2">Only local script and and object resources are loaded</a> |
| </li> |
| </ol> |
| </li><li> |
| - <a href="#toc-tracking-events">Tracking events</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-samplecode">Sample code</a> |
| + <a href="#H2-4">Tightening the default policy</a> |
| <ol> |
| <li style="display: none; "> |
| <a>h3Name</a> |
| @@ -363,197 +344,227 @@ |
| </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> |
| + 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> |
| -<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 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> |
| - 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"> |
| + 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 clickHandler(element) { |
| + // Do something awesome with `element`! |
| + } |
| + </script> |
| + </head> |
| + <body> |
| + <button onclick="clickHandler(this)">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. |
| + 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> |
| -<h2 id="toc-tracking-pageviews">Tracking page views</h2> |
| +<pre>popup.js: |
| +========= |
| -<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. |
| -</p> |
| +function clickHandler(e) { |
| + // Do something awesome with `e.target`! |
| +} |
| -<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> |
| +// 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); |
| +}); |
| -<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> |
| +popup.html: |
| +=========== |
| -<h2 id="toc-debugging">Monitoring analytics requests</h2> |
| +<!doctype html> |
| +<html> |
| + <head> |
| + <title>My Awesome Popup!</title> |
| + <script src="popup.js"></script> |
| + </script> |
| + </head> |
| + <body> |
| + <button>Click for awesomeness!</button> |
| + </body> |
| +</html></pre> |
| + |
| +<a name="H3-2"></a><h3>Only local script and and object resources are loaded</h3> |
| <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. |
| + 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 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> |
| + 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> |
| -<h2 id="toc-tracking-events">Tracking events</h2> |
| +<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> |
| - 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> |
| + Download the file, include it in your package, and write: |
| +</p><p> |
| -<pre> <button>Button 1</button> |
| - <button>Button 2</button> |
| - <button>Button 3</button> |
| -</pre> |
| +</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> |
| - Write a function that sends click events to Google Analytics: |
| + 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> |
| -<pre> function trackButton(button_id) { |
| - _gaq.push(['_trackEvent', 'button' + button_id, 'clicked']); |
| - }; |
| -</pre> |
| - |
| <p> |
| - And call it when each button is pressed: |
| + 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. |
|
abarth-chromium
2012/01/24 16:42:36
Maybe explain why allowing HTTP scripts would be p
Mike West
2012/01/25 16:08:29
Good idea. I've added a sentence or two, and linke
|
| </p> |
| -<pre> <button onclick="trackButton(1);">Button 1</button> |
| - <button onclick="trackButton(2);">Button 2</button> |
| - <button onclick="trackButton(3);">Button 3</button> |
| -</pre> |
| - |
| <p> |
| - The Google Analytics event tracking overview page will give you metrics |
| - regarding how many times each individual button is clicked: |
| + A relaxed policy definition which allows script resources to be loaded from |
| + <code>https://example.com/</code> might look like: |
| </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>{ |
| + ..., |
| + "content_security_policy": "script-src 'self' https://example.com; object-src 'self'", |
| + ... |
| +}</pre> |
| -<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. |
| +<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> |
| - 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>. |
| + 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 id="toc-samplecode">Sample code</h2> |
| +<a name="H2-4"></a><h2>Tightening the default policy</h2> |
| <p> |
| - A sample extension that uses these techniques is |
| - available in the Chromium source tree: |
| + 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> |
| - |
| -<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> |
| </div> |
| <!-- API PAGE --> |
