1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
|
<!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note:
1) The <head> information in this page is significant, should be uniform
across api docs and should be edited only with knowledge of the
templating mechanism.
3) All <body>.innerHTML is genereated as an rendering step. If viewed in a
browser, it will be re-generated from the template, json schema and
authored overview content.
4) The <body>.innerHTML is also generated by an offline step so that this
page may easily be indexed by search engines.
--><html xmlns="http://www.w3.org/1999/xhtml"><head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css">
<link href="css/print.css" rel="stylesheet" type="text/css" media="print">
<script type="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.js">
</script>
<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>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>
<div id="branchWarning" class="displayModeWarning">
<span>WARNING: This is the <span id="branchName">BETA</span> documentation.
It may not work with the stable release of Chrome.</span>
<select id="branchChooser">
<option>Choose a different version...
</option><option value="">Stable
</option><option value="beta">Beta
</option><option value="dev">Dev
</option><option value="trunk">Trunk
</option></select>
</div>
<div id="unofficialWarning" class="displayModeWarning">
<span>WARNING: This is unofficial documentation. It may not work with the
current release of Chrome.</span>
<button id="goToOfficialDocs">Go to the official docs</button>
</div>
<div id="gc-container" class="labs">
<!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION -->
<!-- In particular, sub-templates that recurse, must be used by allowing
jstemplate to make a copy of the template in this section which
are not operated on by way of the jsskip="true" -->
<!-- /SUBTEMPLATES -->
<a id="top"></a>
<div id="skipto">
<a href="#gc-pagecontent">Skip to page content</a>
<a href="#gc-toc">Skip to main navigation</a>
</div>
<!-- API HEADER -->
<table id="header" width="100%" cellspacing="0" border="0">
<tbody><tr>
<td valign="middle"><a href="http://code.google.com/"><img src="images/code_labs_logo.gif" height="43" width="161" alt="Google Code Labs" style="border:0; margin:0;"></a></td>
<td valign="middle" width="100%" style="padding-left:0.6em;">
<form action="http://www.google.com/cse" id="cse" style="margin-top:0.5em">
<div id="gsc-search-box">
<input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno">
<input type="hidden" name="ie" value="UTF-8">
<input type="text" name="q" value="" size="55">
<input class="gsc-search-button" type="submit" name="sa" value="Search">
<br>
<span class="greytext">e.g. "page action" or "tabs"</span>
</div>
</form>
<script type="text/javascript" src="https://www.google.com/jsapi"></script>
<script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script>
<script type="text/javascript" src="https://www.google.com/coop/cse/t13n?form=cse&t13n_langs=en"></script>
<script type="text/javascript" src="https://www.google.com/coop/cse/brand?form=cse&lang=en"></script>
</td>
</tr>
</tbody></table>
<div id="codesiteContent" class="">
<a id="gc-topnav-anchor"></a>
<div id="gc-topnav">
<h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Labs</a>)</h1>
<ul id="home" class="gc-topnav-tabs">
<li id="home_link">
<a href="index.html" title="Google Chrome Extensions home page">Home</a>
</li>
<li id="docs_link">
<a href="docs.html" title="Official Google Chrome Extensions documentation">Docs</a>
</li>
<li id="faq_link">
<a href="faq.html" title="Answers to frequently asked questions about Google Chrome Extensions">FAQ</a>
</li>
<li id="samples_link">
<a href="samples.html" title="Sample extensions (with source code)">Samples</a>
</li>
<li id="group_link">
<a href="http://groups.google.com/a/chromium.org/group/chromium-extensions" title="Google Chrome Extensions developer forum">Group</a>
</li>
<li id="so_link">
<a href="http://stackoverflow.com/questions/tagged/google-chrome-extension" title="[google-chrome-extension] tag on Stack Overflow">Questions?</a>
</li>
</ul>
</div> <!-- end gc-topnav -->
<div class="g-section g-tpl-170">
<!-- SIDENAV -->
<div class="g-unit g-first" id="gc-toc">
<ul>
<li><a href="getstarted.html">Getting Started</a></li>
<li><a href="overview.html">Overview</a></li>
<li><a href="whats_new.html">What's New?</a></li>
<li><h2><a href="devguide.html">Developer's Guide</a></h2>
<ul>
<li>Browser UI
<ul>
<li><a href="browserAction.html">Browser Actions</a></li>
<li><a href="contextMenus.html">Context Menus</a></li>
<li><a href="notifications.html">Desktop Notifications</a></li>
<li><a href="omnibox.html">Omnibox</a></li>
<li><a href="options.html">Options Pages</a></li>
<li><a href="override.html">Override Pages</a></li>
<li><a href="pageAction.html">Page Actions</a></li>
</ul>
</li>
<li>Browser Interaction
<ul>
<li><a href="bookmarks.html">Bookmarks</a></li>
<li><a href="cookies.html">Cookies</a></li>
<li><a href="devtools.html">Developer Tools</a></li>
<li><a href="events.html">Events</a></li>
<li><a href="history.html">History</a></li>
<li><a href="management.html">Management</a></li>
<li><a href="tabs.html">Tabs</a></li>
<li><a href="windows.html">Windows</a></li>
</ul>
</li>
<li>Implementation
<ul>
<li><a href="a11y.html">Accessibility</a></li>
<li><a href="background_pages.html">Background Pages</a></li>
<li><a href="content_scripts.html">Content Scripts</a></li>
<li><a href="xhr.html">Cross-Origin XHR</a></li>
<li><a href="i18n.html">Internationalization</a></li>
<li><a href="messaging.html">Message Passing</a></li>
<li><a href="permissions.html">Optional Permissions</a></li>
<li><a href="npapi.html">NPAPI Plugins</a></li>
</ul>
</li>
<li>Finishing
<ul>
<li><a href="hosting.html">Hosting</a></li>
<li><a href="external_extensions.html">Other Deployment Options</a></li>
</ul>
</li>
</ul>
</li>
<li><h2><a href="apps.html">Packaged Apps</a></h2></li>
<li><h2><a href="tutorials.html">Tutorials</a></h2>
<ul>
<li><a href="tut_debugging.html">Debugging</a></li>
<li><a href="tut_analytics.html">Google Analytics</a></li>
<li><a href="tut_oauth.html">OAuth</a></li>
</ul>
</li>
<li><h2>Reference</h2>
<ul>
<li>Formats
<ul>
<li><a href="manifest.html">Manifest Files</a></li>
<li><a href="match_patterns.html">Match Patterns</a></li>
</ul>
</li>
<li><a href="permission_warnings.html">Permission Warnings</a></li>
<li><a href="api_index.html">chrome.* APIs</a></li>
<li><a href="api_other.html">Other APIs</a></li>
</ul>
</li>
<li><h2><a href="samples.html">Samples</a></h2></li>
<div class="line"> </div>
<li><h2>More</h2>
<ul>
<li><a href="http://code.google.com/chrome/webstore/docs/index.html">Chrome Web Store</a></li>
<li><a href="http://code.google.com/chrome/apps/docs/developers_guide.html">Hosted Apps</a></li>
<li><a href="themes.html">Themes</a></li>
</ul>
</li>
</ul>
</div>
<script>
initToggles();
</script>
<div class="g-unit" id="gc-pagecontent">
<div id="pageTitle">
<h1 class="page_title">Content Security Policy (CSP)</h1>
</div>
<!-- TABLE OF CONTENTS -->
<div id="toc">
<h2>Contents</h2>
<ol>
<li>
<a href="#H2-0">Default Policy Restrictions</a>
<ol>
<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="#H2-3">Relaxing the default policy</a>
<ol>
</ol>
</li><li>
<a href="#H2-4">Tightening the default policy</a>
<ol>
</ol>
</li>
</ol>
</div>
<!-- /TABLE OF CONTENTS -->
<!-- Standard content lead-in for experimental API pages -->
<!-- STATIC CONTENT PLACEHOLDER -->
<div id="static"><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>
<a name="H2-0"></a><h2>Default Policy Restrictions</h2>
<p>
Packages that do not define a <a href="manifestVersion.html">
<code>manifest_version</code>
</a> have no default content security policy. Those that select
<code>manifest_version</code> 2, have a default content security policy
of:
</p>
<pre>script-src 'self'; object-src 'self'</pre>
<p>
This policy adds security by limiting extensions and applications in two ways:
</p>
<a name="H3-1"></a><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>
</p><a name="H3-2"></a><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><p>
</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>
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>
<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 -->
<!-- /apiPage -->
</div> <!-- /gc-pagecontent -->
</div> <!-- /g-section -->
</div> <!-- /codesiteContent -->
<div id="gc-footer" --="">
<div class="text">
<p>
Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>,
the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons
Attribution 3.0 License</a>, and code samples are licensed under the
<a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>.
</p>
<p>
©2011 Google
</p>
<!-- begin analytics -->
<script src="https://www.google-analytics.com/urchin.js" type="text/javascript"></script>
<script src="https://www.google-analytics.com/ga.js" type="text/javascript"></script>
<script type="text/javascript">
// chrome doc tracking
try {
var engdocs = _gat._getTracker("YT-10763712-2");
engdocs._trackPageview();
} catch(err) {}
// code.google.com site-wide tracking
try {
_uacct="UA-18071-1";
_uanchor=1;
_uff=0;
urchinTracker();
}
catch(e) {/* urchinTracker not available. */}
</script>
<!-- end analytics -->
</div>
</div> <!-- /gc-footer -->
</div> <!-- /gc-container -->
</body></html>
|
