chrome/common/extensions/docs/contentSecurityPolicy.html - Issue 9212044: Improving `content_security_policy` documentation.

Unified Diff: chrome/common/extensions/docs/contentSecurityPolicy.html

Issue 9212044: Improving `content_security_policy` documentation. (Closed) Base URL: svn://svn.chromium.org/chrome/trunk/src

Patch Set: Meggin's feedback. Created 8 years, 11 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View side-by-side diff with in-line comments

Download patch

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

- <title>Tutorial: Google Analytics - Google Chrome Extensions - Google Code</title></head>

+ <title>Content Security Policy (CSP) - Google Chrome Extensions - Google Code</title></head>

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

- <h1 class="page_title">Tutorial: Google Analytics</h1>

+ <h1 class="page_title">Content Security Policy (CSP)</h1>

</div>

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

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

@@ -379,197 +360,277 @@

</p>

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

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

« no previous file with comments | « no previous file | chrome/common/extensions/docs/examples/tutorials/analytics.zip » ('j') | no next file with comments »