Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(3322)

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
« no previous file with comments | « no previous file | chrome/common/extensions/docs/examples/tutorials/analytics.zip » ('j') | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
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>&lt;script&gt;</code> blocks <strong>and</strong> inline event handlers
+ (e.g. <code>&lt;button onclick="..."&gt;</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>&lt;!DOCTYPE html&gt;
+<pre>&lt;!doctype html&gt;
&lt;html&gt;
- &lt;head&gt;
- ...
- &lt;/head&gt;
- &lt;body&gt;
- &lt;script&gt;
- 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);
- })();
- &lt;/script&gt;
-
- ...
- &lt;/body&gt;
-&lt;/html&gt;
-</pre>
+ &lt;head&gt;
+ &lt;title&gt;My Awesome Popup!&lt;/title&gt;
+ &lt;script&gt;
+ function awesome() {
+ // do something awesome!
+ }
+
+ function totallyAwesome() {
+ // do something TOTALLY awesome!
+ }
+
+ function clickHandler(element) {
+ setTimeout(<strong>"awesome(); totallyAwesome()"</strong>, 1000);
+ }
+ &lt;/script&gt;
+ &lt;/head&gt;
+ &lt;body&gt;
+ &lt;button <strong>onclick="clickHandler(this)"</strong>&gt;
+ Click for awesomeness!
+ &lt;/button&gt;
+ &lt;/body&gt;
+&lt;/html&gt;</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:
+===========
+
+&lt;!doctype html&gt;
+&lt;html&gt;
+ &lt;head&gt;
+ &lt;title&gt;My Awesome Popup!&lt;/title&gt;
+ &lt;script <strong>src="popup.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>
- 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> &lt;button&gt;Button 1&lt;/button&gt;
- &lt;button&gt;Button 2&lt;/button&gt;
- &lt;button&gt;Button 3&lt;/button&gt;
-</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> &lt;button onclick="trackButton(1);"&gt;Button 1&lt;/button&gt;
- &lt;button onclick="trackButton(2);"&gt;Button 2&lt;/button&gt;
- &lt;button onclick="trackButton(3);"&gt;Button 3&lt;/button&gt;
-</pre>
+<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>
- 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>&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>
+
+<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 -->
« no previous file with comments | « no previous file | chrome/common/extensions/docs/examples/tutorials/analytics.zip » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698