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

Side by Side Diff: chrome/common/extensions/docs/contentSecurityPolicy.html

Issue 10642015: Basic setup for generating app docs (Closed) Base URL: svn://svn.chromium.org/chrome/trunk/src
Patch Set: Created 8 years, 6 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 unified diff | Download patch | Annotate | Revision Log
OLDNEW
(Empty)
1 <!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note:
2 1) The <head> information in this page is significant, should be uniform
3 across api docs and should be edited only with knowledge of the
4 templating mechanism.
5 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a
6 browser, it will be re-generated from the template, json schema and
7 authored overview content.
8 4) The <body>.innerHTML is also generated by an offline step so that this
9 page may easily be indexed by search engines.
10 --><html xmlns="http://www.w3.org/1999/xhtml"><head>
11 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
12 <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css">
13 <link href="css/print.css" rel="stylesheet" type="text/css" media="print">
14 <script type="text/javascript" src="../../../third_party/jstemplate/jstempla te_compiled.js">
15 </script>
16 <script type="text/javascript" src="../../../../third_party/json_minify/mini fy-sans-regexp.js">
17 </script>
18 <script type="text/javascript" src="js/api_page_generator.js"></script>
19 <script type="text/javascript" src="js/bootstrap.js"></script>
20 <script type="text/javascript" src="js/sidebar.js"></script>
21 <title>Content Security Policy (CSP) - Google Chrome Extensions - Google Code< /title></head>
22 <body> <div id="devModeWarning" class="displayModeWarning">
23 You are viewing extension docs in chrome via the 'file:' scheme: are you exp ecting to see local changes when you refresh? You'll need run chrome with --allo w-file-access-from-files.
24 </div>
25 <div id="branchWarning" class="displayModeWarning">
26 <span>WARNING: This is the <span id="branchName">BETA</span> documentation.
27 It may not work with the stable release of Chrome.</span>
28 <select id="branchChooser">
29 <option>Choose a different version...
30 </option><option value="">Stable
31 </option><option value="beta">Beta
32 </option><option value="dev">Dev
33 </option><option value="trunk">Trunk
34 </option></select>
35 </div>
36 <div id="unofficialWarning" class="displayModeWarning">
37 <span>WARNING: This is unofficial documentation. It may not work with the
38 current release of Chrome.</span>
39 <button id="goToOfficialDocs">Go to the official docs</button>
40 </div>
41 <div id="gc-container" class="labs">
42 <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION -->
43 <!-- In particular, sub-templates that recurse, must be used by allowing
44 jstemplate to make a copy of the template in this section which
45 are not operated on by way of the jsskip="true" -->
46 <!-- /SUBTEMPLATES -->
47 <a id="top"></a>
48 <div id="skipto">
49 <a href="#gc-pagecontent">Skip to page content</a>
50 <a href="#gc-toc">Skip to main navigation</a>
51 </div>
52 <!-- API HEADER -->
53 <table id="header" width="100%" cellspacing="0" border="0">
54 <tbody><tr>
55 <td valign="middle"><a href="http://code.google.com/"><img src="images/c ode_labs_logo.gif" height="43" width="161" alt="Google Code Labs" style="border: 0; margin:0;"></a></td>
56 <td valign="middle" width="100%" style="padding-left:0.6em;">
57 <form action="http://www.google.com/cse" id="cse" style="margin-top:0. 5em">
58 <div id="gsc-search-box">
59 <input type="hidden" name="cx" value="002967670403910741006:61_cvz fqtno">
60 <input type="hidden" name="ie" value="UTF-8">
61 <input type="text" name="q" value="" size="55">
62 <input class="gsc-search-button" type="submit" name="sa" value="Se arch">
63 <br>
64 <span class="greytext">e.g. "page action" or "tabs"</span>
65 </div>
66 </form>
67 <script type="text/javascript" src="https://www.google.com/jsapi"></sc ript>
68 <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script>
69 <script type="text/javascript" src="https://www.google.com/coop/cse/t1 3n?form=cse&amp;t13n_langs=en"></script>
70 <script type="text/javascript" src="https://www.google.com/coop/cse/br and?form=cse&amp;lang=en"></script>
71 </td>
72 </tr>
73 </tbody></table>
74 <div id="codesiteContent" class="">
75 <a id="gc-topnav-anchor"></a>
76 <div id="gc-topnav">
77 <h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Lab s</a>)</h1>
78 <ul id="home" class="gc-topnav-tabs">
79 <li id="home_link">
80 <a href="index.html" title="Google Chrome Extensions home page">Home </a>
81 </li>
82 <li id="docs_link">
83 <a href="docs.html" title="Official Google Chrome Extensions documen tation">Docs</a>
84 </li>
85 <li id="faq_link">
86 <a href="faq.html" title="Answers to frequently asked questions abou t Google Chrome Extensions">FAQ</a>
87 </li>
88 <li id="samples_link">
89 <a href="samples.html" title="Sample extensions (with source code)"> Samples</a>
90 </li>
91 <li id="group_link">
92 <a href="http://groups.google.com/a/chromium.org/group/chromium-exte nsions" title="Google Chrome Extensions developer forum">Group</a>
93 </li>
94 <li id="so_link">
95 <a href="http://stackoverflow.com/questions/tagged/google-chrome-ext ension" title="[google-chrome-extension] tag on Stack Overflow">Questions?</a>
96 </li>
97 </ul>
98 </div> <!-- end gc-topnav -->
99 <div class="g-section g-tpl-170">
100 <!-- SIDENAV -->
101 <div class="g-unit g-first" id="gc-toc">
102 <ul>
103 <li><a href="getstarted.html">Getting Started</a></li>
104 <li><a href="overview.html">Overview</a></li>
105 <li><a href="whats_new.html">What's New?</a></li>
106 <li><h2><a href="devguide.html">Developer's Guide</a></h2>
107 <ul>
108 <li>Browser UI
109 <ul>
110 <li><a href="browserAction.html">Browser Actions</a></li>
111 <li><a href="contextMenus.html">Context Menus</a></li>
112 <li><a href="notifications.html">Desktop Notifications</a></li >
113 <li><a href="omnibox.html">Omnibox</a></li>
114 <li><a href="options.html">Options Pages</a></li>
115 <li><a href="override.html">Override Pages</a></li>
116 <li><a href="pageAction.html">Page Actions</a></li>
117 </ul>
118 </li>
119 <li>Browser Interaction
120 <ul>
121 <li><a href="bookmarks.html">Bookmarks</a></li>
122 <li><a href="cookies.html">Cookies</a></li>
123 <li><a href="devtools.html">Developer Tools</a></li>
124 <li><a href="events.html">Events</a></li>
125 <li><a href="history.html">History</a></li>
126 <li><a href="management.html">Management</a></li>
127 <li><a href="tabs.html">Tabs</a></li>
128 <li><a href="windows.html">Windows</a></li>
129 </ul>
130 </li>
131 <li>Implementation
132 <ul>
133 <li><a href="a11y.html">Accessibility</a></li>
134 <li><a href="background_pages.html">Background Pages</a></li>
135 <li><a href="content_scripts.html">Content Scripts</a></li>
136 <li><a href="xhr.html">Cross-Origin XHR</a></li>
137 <li><a href="i18n.html">Internationalization</a></li>
138 <li><a href="messaging.html">Message Passing</a></li>
139 <li><a href="permissions.html">Optional Permissions</a></li>
140 <li><a href="npapi.html">NPAPI Plugins</a></li>
141 </ul>
142 </li>
143 <li>Finishing
144 <ul>
145 <li><a href="hosting.html">Hosting</a></li>
146 <li><a href="external_extensions.html">Other Deployment Option s</a></li>
147 </ul>
148 </li>
149 </ul>
150 </li>
151 <li><h2><a href="apps.html">Packaged Apps</a></h2></li>
152 <li><h2><a href="tutorials.html">Tutorials</a></h2>
153 <ul>
154 <li><a href="tut_debugging.html">Debugging</a></li>
155 <li><a href="tut_analytics.html">Google Analytics</a></li>
156 <li><a href="tut_oauth.html">OAuth</a></li>
157 </ul>
158 </li>
159 <li><h2>Reference</h2>
160 <ul>
161 <li>Formats
162 <ul>
163 <li><a href="manifest.html">Manifest Files</a></li>
164 <li><a href="match_patterns.html">Match Patterns</a></li>
165 </ul>
166 </li>
167 <li><a href="permission_warnings.html">Permission Warnings</a></li >
168 <li><a href="api_index.html">chrome.* APIs</a></li>
169 <li><a href="api_other.html">Other APIs</a></li>
170 </ul>
171 </li>
172 <li><h2><a href="samples.html">Samples</a></h2></li>
173 <div class="line"> </div>
174 <li><h2>More</h2>
175 <ul>
176 <li><a href="http://code.google.com/chrome/webstore/docs/index.htm l">Chrome Web Store</a></li>
177 <li><a href="http://code.google.com/chrome/apps/docs/developers_gu ide.html">Hosted Apps</a></li>
178 <li><a href="themes.html">Themes</a></li>
179 </ul>
180 </li>
181 </ul>
182 </div>
183 <script>
184 initToggles();
185 </script>
186 <div class="g-unit" id="gc-pagecontent">
187 <div id="pageTitle">
188 <h1 class="page_title">Content Security Policy (CSP)</h1>
189 </div>
190 <!-- TABLE OF CONTENTS -->
191 <div id="toc">
192 <h2>Contents</h2>
193 <ol>
194 <li>
195 <a href="#H2-0">Default Policy Restrictions</a>
196 <ol>
197 <li>
198 <a href="#H3-1">Inline JavaScript will not be executed</a>
199 </li><li>
200 <a href="#H3-2">Only local script and and object resources are loaded</a>
201 </li>
202 </ol>
203 </li><li>
204 <a href="#H2-3">Relaxing the default policy</a>
205 <ol>
206 </ol>
207 </li><li>
208 <a href="#H2-4">Tightening the default policy</a>
209 <ol>
210 </ol>
211 </li>
212 </ol>
213 </div>
214 <!-- /TABLE OF CONTENTS -->
215 <!-- Standard content lead-in for experimental API pages -->
216 <!-- STATIC CONTENT PLACEHOLDER -->
217 <div id="static"><div id="pageData-name" class="pageData">Content Securi ty Policy (CSP)</div>
218 <div id="pageData-showTOC" class="pageData">true</div>
219 <p>
220 In order to mitigate a large class of potental cross-site scripting issues,
221 Chrome's extension system has incorporated the general concept of
222 <a href="http://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specif ication.dev.html">
223 <strong>Content Security Policy (CSP)</strong>
224 </a>. This introduces some fairly strict policies that will make extensions
225 more secure by default, and provides you with the ability to create and
226 enforce rules governing the types of content that can be loaded and executed
227 by your extensions and applications.
228 </p>
229 <p>
230 In general, CSP works as a black/whitelisting mechanism for resources loaded
231 or executed by your extensions. Defining a reasonable policy for your
232 extension enables you to carefully consider the resources that your extension
233 requires, and to ask the browser to ensure that those are the only resources
234 your extension has access to. These policies provide security over and above
235 the <a href="manifest.html#permissions">host permissions</a> your extension
236 requests; they're an additional layer of protection, not a replacement.
237 </p>
238 <p>
239 On the web, such a policy is defined via an HTTP header or <code>meta</code>
240 element. Inside Chrome's extension system, neither is an appropriate
241 mechanism. Instead, an extension's policy is defined via the extension's
242 <a href="manifest.html"><code>manifest.json</code></a> file as follows:
243 </p>
244 <pre>{
245 ...,
246 "content_security_policy": "[POLICY STRING GOES HERE]"
247 ...
248 }</pre>
249 <p class="note">
250 For full details regarding CSP's syntax, please take a look at
251 <a href="http://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specif ication.dev.html#syntax">
252 the Content Security Policy specification
253 </a>.
254 </p>
255 <a name="H2-0"></a><h2>Default Policy Restrictions</h2>
256 <p>
257 Packages that do not define a <a href="manifestVersion.html">
258 <code>manifest_version</code>
259 </a> have no default content security policy. Those that select
260 <code>manifest_version</code> 2, have a default content security policy
261 of:
262 </p>
263 <pre>script-src 'self'; object-src 'self'</pre>
264 <p>
265 This policy adds security by limiting extensions and applications in two ways:
266 </p>
267 <a name="H3-1"></a><h3>Inline JavaScript will not be executed</h3>
268 <p>
269 Inline JavaScript, as well as dangerous string-to-JavaScript methods like
270 <code>eval</code>, will not be executed. This restriction bans both inline
271 <code>&lt;script&gt;</code> blocks <strong>and</strong> inline event handlers
272 (e.g. <code>&lt;button onclick="..."&gt;</code>).
273 </p>
274 <p>
275 The first restriction wipes out a huge class of cross-site scripting attacks
276 by making it impossible for you to accidentally execute script provided by a
277 malicious third-party. It does, however, require you to write your code with a
278 clean separation between content and behavior (which you should of course do
279 anyway, right?). An example might make this clearer. You might try to write a
280 <a href="browserAction.html#popups">Browser Action's popup</a> as a single
281 <code>popup.html</code> containing:
282 </p>
283 <pre>&lt;!doctype html&gt;
284 &lt;html&gt;
285 &lt;head&gt;
286 &lt;title&gt;My Awesome Popup!&lt;/title&gt;
287 &lt;script&gt;
288 function awesome() {
289 // do something awesome!
290 }
291 function totallyAwesome() {
292 // do something TOTALLY awesome!
293 }
294 function clickHandler(element) {
295 setTimeout(<strong>"awesome(); totallyAwesome()"</strong>, 1000);
296 }
297 &lt;/script&gt;
298 &lt;/head&gt;
299 &lt;body&gt;
300 &lt;button <strong>onclick="clickHandler(this)"</strong>&gt;
301 Click for awesomeness!
302 &lt;/button&gt;
303 &lt;/body&gt;
304 &lt;/html&gt;</pre>
305 <p>
306 Three things will need to change in order to make this work the way you expect
307 it to:
308 </p>
309 <ul>
310 <li>
311 The <code>clickHandler</code> definition needs to move into an external
312 JavaScript file (<code>popup.js</code> would be a good target).
313 </li>
314 <li>
315 The inline event handler definition must be rewritten in terms of
316 <code>addEventListener</code> and extracted into <code>popup.js</code>.
317 </li>
318 <li>
319 The <code>setTimeout</code> call will need to be rewritten to avoid
320 converting the string <code>"awesome(); totallyAwesome()"</code> into
321 JavaScript for execution.
322 </li>
323 </ul>
324 <p>
325 Those changes might look something like the following:
326 </p>
327 <pre>popup.js:
328 =========
329 function awesome() {
330 // Do something awesome!
331 }
332 function totallyAwesome() {
333 // do something TOTALLY awesome!
334 }
335 <strong>
336 function awesomeTask() {
337 awesome();
338 totallyAwesome();
339 }
340 </strong>
341 function clickHandler(e) {
342 setTimeout(<strong>awesomeTask</strong>, 1000);
343 }
344 // Add event listeners once the DOM has fully loaded by listening for the
345 // `DOMContentLoaded` event on the document, and adding your listeners to
346 // specific elements when it triggers.
347 document.addEventListener('DOMContentLoaded', function () {
348 document.querySelector('button').addEventListener('click', clickHandler);
349 });
350 popup.html:
351 ===========
352 &lt;!doctype html&gt;
353 &lt;html&gt;
354 &lt;head&gt;
355 &lt;title&gt;My Awesome Popup!&lt;/title&gt;
356 &lt;script <strong>src="popup.js"</strong>&gt;&lt;/script&gt;
357 &lt;/script&gt;
358 &lt;/head&gt;
359 &lt;body&gt;
360 &lt;button&gt;Click for awesomeness!&lt;/button&gt;
361 &lt;/body&gt;
362 &lt;/html&gt;</pre>
363 <p>
364 </p><a name="H3-2"></a><h3>Only local script and and object resources are loaded </h3>
365 <p>
366 Script and object resources can only be loaded from the extension's
367 package, not from the web at large. This ensures that your extension only
368 executes the code you've specifically approved, preventing an active network
369 attacker from maliciously redirecting your request for a resource.
370 </p>
371 <p>
372 Instead of writing code that depends on jQuery (or any other library) loading
373 from an external CDN, consider including the specific version of jQuery in
374 your extension package. That is, instead of:
375 </p>
376 <pre>&lt;!doctype html&gt;
377 &lt;html&gt;
378 &lt;head&gt;
379 &lt;title&gt;My Awesome Popup!&lt;/title&gt;
380 &lt;script src="<strong>http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jq uery.min.js</strong>"&gt;&lt;/script&gt;
381 &lt;/script&gt;
382 &lt;/head&gt;
383 &lt;body&gt;
384 &lt;button&gt;Click for awesomeness!&lt;/button&gt;
385 &lt;/body&gt;
386 &lt;/html&gt;</pre>
387 <p>
388 Download the file, include it in your package, and write:
389 </p><p>
390 </p><pre>&lt;!doctype html&gt;
391 &lt;html&gt;
392 &lt;head&gt;
393 &lt;title&gt;My Awesome Popup!&lt;/title&gt;
394 &lt;script src="<strong>jquery.min.js</strong>"&gt;&lt;/script&gt;
395 &lt;/script&gt;
396 &lt;/head&gt;
397 &lt;body&gt;
398 &lt;button&gt;Click for awesomeness!&lt;/button&gt;
399 &lt;/body&gt;
400 &lt;/html&gt;</pre>
401 <a name="H2-3"></a><h2>Relaxing the default policy</h2>
402 <p>
403 There is no mechanism for relaxing the restriction against executing inline
404 JavaScript. In particular, setting a script policy that includes
405 <code>unsafe-inline</code> will have no effect. This is intentional.
406 </p>
407 <p>
408 If, on the other hand, you have a need for some external JavaScript or object
409 resources, you can relax the policy to a limited extent by whitelisting
410 specific HTTPS origins from which scripts should be accepted. Whitelisting
411 insecure HTTP resources will have no effect. This is intentional, because
412 we want to ensure that executable resources loaded with an extension's
413 elevated permissions is exactly the resource you expect, and hasn't been
414 replaced by an active network attacker. As <a href="http://en.wikipedia.org/wi ki/Man-in-the-middle_attack">man-in-the-middle
415 attacks</a> are both trivial and undetectable over HTTP, only HTTPS origins
416 will be accepted.
417 </p>
418 <p>
419 A relaxed policy definition which allows script resources to be loaded from
420 <code>example.com</code> over HTTPS might look like:
421 </p>
422 <pre>{
423 ...,
424 "content_security_policy": "script-src 'self' https://example.com; object-src 'self'",
425 ...
426 }</pre>
427 <p class="note">
428 Note that both <code>script-src</code> and <code>object-src</code> are defined
429 by the policy. Chrome will not accept a policy that doesn't limit each of
430 these values to (at least) <code>'self'</code>.
431 </p>
432 <p>
433 Making use of Google Analytics is the canonical example for this sort of
434 policy definition. It's common enough that we've provided an Analytics
435 boilerplate of sorts in the <a href="samples.html#analytics">Event Tracking
436 with Google Analytics</a> sample extension, and a
437 <a href="tut_analytics.html">brief tutorial</a> that goes into more detail.
438 </p>
439 <a name="H2-4"></a><h2>Tightening the default policy</h2>
440 <p>
441 You may, of course, tighten this policy to whatever extent your extension
442 allows in order to increase security at the expense of convenience. To specify
443 that your extension can only load resources of <em>any</em> type (images, etc)
444 from its own package, for example, a policy of <code>default-src 'self'</code>
445 would be appropriate. The <a href="samples.html#mappy">Mappy</a> sample
446 extension is a good example of an extension that's been locked down above and
447 beyond the defaults.
448 </p>
449 </div>
450 <!-- API PAGE -->
451 <!-- /apiPage -->
452 </div> <!-- /gc-pagecontent -->
453 </div> <!-- /g-section -->
454 </div> <!-- /codesiteContent -->
455 <div id="gc-footer" --="">
456 <div class="text">
457 <p>
458 Except as otherwise <a href="http://code.google.com/policies.html#restrictions ">noted</a>,
459 the content of this page is licensed under the <a rel="license" href="http://c reativecommons.org/licenses/by/3.0/">Creative Commons
460 Attribution 3.0 License</a>, and code samples are licensed under the
461 <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD Lic ense</a>.
462 </p>
463 <p>
464 ©2011 Google
465 </p>
466 <!-- begin analytics -->
467 <script src="https://www.google-analytics.com/urchin.js" type="text/javascript"> </script>
468 <script src="https://www.google-analytics.com/ga.js" type="text/javascript"></sc ript>
469 <script type="text/javascript">
470 // chrome doc tracking
471 try {
472 var engdocs = _gat._getTracker("YT-10763712-2");
473 engdocs._trackPageview();
474 } catch(err) {}
475 // code.google.com site-wide tracking
476 try {
477 _uacct="UA-18071-1";
478 _uanchor=1;
479 _uff=0;
480 urchinTracker();
481 }
482 catch(e) {/* urchinTracker not available. */}
483 </script>
484 <!-- end analytics -->
485 </div>
486 </div> <!-- /gc-footer -->
487 </div> <!-- /gc-container -->
488 </body></html>
OLDNEW
« no previous file with comments | « chrome/common/extensions/docs/build/generator.html ('k') | chrome/common/extensions/docs/contentSettings.html » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698