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

Issues Search
    My Issues | Starred     Open | Closed | All

Side by Side 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: Adding note about setTimeout and strings. 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 unified diff | Download patch | Annotate | Revision Log
« no previous file with comments | « no previous file | chrome/common/extensions/docs/examples/tutorials/analytics.zip » ('j') | chrome/common/extensions/docs/static/contentSecurityPolicy.html » ('J')
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 <!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note: 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 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 3 across api docs and should be edited only with knowledge of the
4 templating mechanism. 4 templating mechanism.
5 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a 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 6 browser, it will be re-generated from the template, json schema and
7 authored overview content. 7 authored overview content.
8 4) The <body>.innerHTML is also generated by an offline step so that this 8 4) The <body>.innerHTML is also generated by an offline step so that this
9 page may easily be indexed by search engines. 9 page may easily be indexed by search engines.
10 --><html xmlns="http://www.w3.org/1999/xhtml"><head> 10 --><html xmlns="http://www.w3.org/1999/xhtml"><head>
11 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 11 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
12 <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css"> 12 <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css">
13 <link href="css/print.css" rel="stylesheet" type="text/css" media="print"> 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"> 14 <script type="text/javascript" src="../../../third_party/jstemplate/jstempla te_compiled.js">
15 </script> 15 </script>
16 <script type="text/javascript" src="js/api_page_generator.js"></script> 16 <script type="text/javascript" src="js/api_page_generator.js"></script>
17 <script type="text/javascript" src="js/bootstrap.js"></script> 17 <script type="text/javascript" src="js/bootstrap.js"></script>
18 <script type="text/javascript" src="js/sidebar.js"></script> 18 <script type="text/javascript" src="js/sidebar.js"></script>
19 <title>Tutorial: Google Analytics - Google Chrome Extensions - Google Code</ti tle></head> 19 <title>Content Security Policy (CSP) - Google Chrome Extensions - Google Code< /title></head>
20 <body> <div id="devModeWarning" class="displayModeWarning"> 20 <body> <div id="devModeWarning" class="displayModeWarning">
21 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. 21 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.
22 </div> 22 </div>
23 <div id="branchWarning" class="displayModeWarning"> 23 <div id="branchWarning" class="displayModeWarning">
24 <span>WARNING: This is the <span id="branchName">BETA</span> documentation. 24 <span>WARNING: This is the <span id="branchName">BETA</span> documentation.
25 It may not work with the stable release of Chrome.</span> 25 It may not work with the stable release of Chrome.</span>
26 <select id="branchChooser"> 26 <select id="branchChooser">
27 <option>Choose a different version... 27 <option>Choose a different version...
28 </option><option value="">Stable 28 </option><option value="">Stable
29 </option><option value="beta">Beta 29 </option><option value="beta">Beta
(...skipping 240 matching lines...) Expand 10 before | Expand all | Expand 10 after
270 <li><a href="hosting.html">Hosting</a></li> 270 <li><a href="hosting.html">Hosting</a></li>
271 <li><a href="external_extensions.html">Other Deployment Option s</a></li> 271 <li><a href="external_extensions.html">Other Deployment Option s</a></li>
272 </ul> 272 </ul>
273 </li> 273 </li>
274 </ul> 274 </ul>
275 </li> 275 </li>
276 <li><h2><a href="apps.html">Packaged Apps</a></h2></li> 276 <li><h2><a href="apps.html">Packaged Apps</a></h2></li>
277 <li><h2><a href="tutorials.html">Tutorials</a></h2> 277 <li><h2><a href="tutorials.html">Tutorials</a></h2>
278 <ul> 278 <ul>
279 <li><a href="tut_debugging.html">Debugging</a></li> 279 <li><a href="tut_debugging.html">Debugging</a></li>
280 <li class="leftNavSelected">Google Analytics</li> 280 <li><a href="tut_analytics.html">Google Analytics</a></li>
281 <li><a href="tut_oauth.html">OAuth</a></li> 281 <li><a href="tut_oauth.html">OAuth</a></li>
282 </ul> 282 </ul>
283 </li> 283 </li>
284 <li><h2>Reference</h2> 284 <li><h2>Reference</h2>
285 <ul> 285 <ul>
286 <li>Formats 286 <li>Formats
287 <ul> 287 <ul>
288 <li><a href="manifest.html">Manifest Files</a></li> 288 <li><a href="manifest.html">Manifest Files</a></li>
289 <li><a href="match_patterns.html">Match Patterns</a></li> 289 <li><a href="match_patterns.html">Match Patterns</a></li>
290 </ul> 290 </ul>
(...skipping 13 matching lines...) Expand all
304 </ul> 304 </ul>
305 </li> 305 </li>
306 </ul> 306 </ul>
307 </div> 307 </div>
308 <script> 308 <script>
309 initToggles(); 309 initToggles();
310 </script> 310 </script>
311 311
312 <div class="g-unit" id="gc-pagecontent"> 312 <div class="g-unit" id="gc-pagecontent">
313 <div id="pageTitle"> 313 <div id="pageTitle">
314 <h1 class="page_title">Tutorial: Google Analytics</h1> 314 <h1 class="page_title">Content Security Policy (CSP)</h1>
315 </div> 315 </div>
316 <!-- TABLE OF CONTENTS --> 316 <!-- TABLE OF CONTENTS -->
317 <div id="toc"> 317 <div id="toc">
318 <h2>Contents</h2> 318 <h2>Contents</h2>
319 <ol> 319 <ol>
320 <li> 320 <li>
321 <a href="#toc-requirements">Requirements</a> 321 <a href="#H2-0">Default Policy Restrictions</a>
322 <ol>
323 <li>
324 <a href="#H3-1">Inline JavaScript will not be executed</a>
325 </li><li>
326 <a href="#H3-2">Only local script and and object resources are loaded</a>
327 </li>
328 </ol>
329 </li><li>
330 <a href="#H2-3">Relaxing the default policy</a>
322 <ol> 331 <ol>
323 <li style="display: none; "> 332 <li style="display: none; ">
324 <a>h3Name</a> 333 <a>h3Name</a>
325 </li> 334 </li>
326 </ol> 335 </ol>
327 </li><li> 336 </li><li>
328 <a href="#toc-installing">Installing the tracking code</a> 337 <a href="#H2-4">Tightening the default policy</a>
329 <ol> 338 <ol>
330 <li style="display: none; "> 339 <li style="display: none; ">
331 <a>h3Name</a> 340 <a>h3Name</a>
332 </li>
333 </ol>
334 </li><li>
335 <a href="#toc-tracking-pageviews">Tracking page views</a>
336 <ol>
337 <li style="display: none; ">
338 <a>h3Name</a>
339 </li>
340 </ol>
341 </li><li>
342 <a href="#toc-debugging">Monitoring analytics requests</a>
343 <ol>
344 <li style="display: none; ">
345 <a>h3Name</a>
346 </li>
347 </ol>
348 </li><li>
349 <a href="#toc-tracking-events">Tracking events</a>
350 <ol>
351 <li style="display: none; ">
352 <a>h3Name</a>
353 </li>
354 </ol>
355 </li><li>
356 <a href="#toc-samplecode">Sample code</a>
357 <ol>
358 <li style="display: none; ">
359 <a>h3Name</a>
360 </li> 341 </li>
361 </ol> 342 </ol>
362 </li> 343 </li>
363 <li style="display: none; "> 344 <li style="display: none; ">
364 <a href="#apiReference">API reference</a> 345 <a href="#apiReference">API reference</a>
365 <ol> 346 <ol>
366 <div></div> 347 <div></div>
367 <div></div> 348 <div></div>
368 <div></div> 349 <div></div>
369 <div></div> 350 <div></div>
370 </ol> 351 </ol>
371 </li> 352 </li>
372 </ol> 353 </ol>
373 </div> 354 </div>
374 <!-- /TABLE OF CONTENTS --> 355 <!-- /TABLE OF CONTENTS -->
375 356
376 <!-- Standard content lead-in for experimental API pages --> 357 <!-- Standard content lead-in for experimental API pages -->
377 <p id="classSummary" style="display: none; "> 358 <p id="classSummary" style="display: none; ">
378 For information on how to use experimental APIs, see the <a href="expe rimental.html">chrome.experimental.* APIs</a> page. 359 For information on how to use experimental APIs, see the <a href="expe rimental.html">chrome.experimental.* APIs</a> page.
379 </p> 360 </p>
380 361
381 <!-- STATIC CONTENT PLACEHOLDER --> 362 <!-- STATIC CONTENT PLACEHOLDER -->
382 <div id="static"><div id="pageData-name" class="pageData">Tutorial: Goog le Analytics</div> 363 <div id="static"><div id="pageData-name" class="pageData">Content Securi ty Policy (CSP)</div>
383 <div id="pageData-showTOC" class="pageData">true</div> 364 <div id="pageData-showTOC" class="pageData">true</div>
384 365
385 <p>This tutorial demonstrates using Google Analytics to track the usage of your 366 <p>
386 extension.</p> 367 Content Security Policy is a language used to describe restrictions on the
387 368 content that can be loaded and executed by your extension. In order to
388 <h2 id="toc-requirements">Requirements</h2> 369 mitigate a large class of potental cross-site scripting issues, Chrome's
389 <p> 370 extension system enforces a fairly strict <strong>Content Security Policy
390 This tutorial expects that you have some familiarity writing extensions for 371 (CSP)</strong> that has a few impacts on the way you build extensions and
391 Google Chrome. If you need information on how to write an extension, please 372 applications.
392 read the <a href="gettingstarted.html">Getting Started tutorial</a>. 373 </p>
393 </p> 374
394 375 <p>
395 <p> 376 In general, CSP works as a black/whitelisting mechanism for resources loaded
396 You will also need a <a href="http://www.google.com/analytics">Google 377 or execute by your extensions. Defining a reasonable policy for your extension
397 Analytics account</a> set up to track your extension. Note that when setting 378 enables you to carefully consider the resources that your extension requires,
398 up the account, you can use any value in the Website's URL field, as your 379 and to ask the browser to ensure that those are the only resources your
399 extension will not have an URL of its own. 380 extension has access to. These policies provide security over and above the
400 </p> 381 <a href="manifest.html#permissions">host permissions</a> your extension
401 382 requests; they're an additional layer of protection, not a replacement.
402 <p style="text-align: center"> 383 </p>
403 <img src="images/tut_analytics/screenshot01.png" style="width:400px;height:82p x;" alt="The analytics setup with info for a chrome extension filled out."> 384
404 </p> 385 <p>
405 386 On the web, such a policy is defined via an HTTP header or <code>meta</code>
406 <p> 387 element. Inside Chrome's extension system, neither is an appropriate
407 Also note that Google Analytics requires version <strong>4.0.302.2</strong> 388 mechanism. Instead, an extension's policy is defined via the extension's
408 of Google Chrome to work correctly. Users with an earlier version of Google 389 <a href="manifest.html"><code>manifest.json</code></a> file as follows:
409 Chrome will not show up on your Google Analytics reports. View 390 </p>
410 <a href="faq.html#faq-dev-14">this FAQ entry</a> to learn how to check which 391
411 version of Google Chrome is deployed to which platform. 392 <pre>{
412 </p> 393 ...,
413 394 "content_security_policy": "[POLICY STRING GOES HERE]"
414 <h2 id="toc-installing">Installing the tracking code</h2> 395 ...
415 396 }</pre>
416 <p> 397
417 The standard Google Analytics tracking code snippet fetches a file named 398 <p class="note">
418 <code>ga.js</code> from an SSL protected URL if the current page 399 For full details regarding CSP's syntax, please take a look at
419 was loaded using the <code>https://</code> protocol. <strong>It is strongly 400 <a href="http://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specif ication.dev.html">
420 advised to use the SSL protected ga.js in an extension</strong>, 401 the Content Security Policy specification
421 but Google Chrome extension 402 </a>.
422 pages are hosted under <code>chrome-extension://</code> URLs, so the tracking 403 </p>
423 snippet must be modified slightly to pull <code>ga.js</code> directly from 404
424 <code>https://ssl.google-analytics.com/ga.js</code> instead of the default 405 <a name="H2-0"></a><h2>Default Policy Restrictions</h2>
425 location. 406
426 </p> 407 <p>
427 408 By default, Chrome defines a content security policy of:
428 <p> 409 </p>
429 Below is a modified snippet for the 410
430 <a href="http://code.google.com/apis/analytics/docs/tracking/asyncTracking.htm l">asynchronous 411 <pre>script-src 'self'; object-src 'self'</pre>
431 tracking API</a> (the modified line is bolded): 412
432 </p> 413 <p>
433 414 This policy limits extensions in two ways:
434 <pre>(function() { 415 </p>
435 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.asy nc = true; 416
436 <strong>ga.src = 'https://ssl.google-analytics.com/ga.js';</strong> 417 <a name="H3-1"></a><h3>Inline JavaScript will not be executed</h3>
437 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore( ga, s); 418
438 })(); 419 <p>
439 </pre> 420 Inline JavaScript, as well as dangerous string-to-JavaScript methods like
440 421 <code>eval</code>, will not be executed. This restriction bans both inline
441 <p> 422 <code>&lt;script&gt;</code> blocks <strong>and</strong> inline event handlers
442 Here is a background page which loads the asynchronous tracking code and 423 (e.g. <code>&lt;button onclick="..."&gt;</code>).
443 tracks a single page view: 424 </p>
444 </p> 425
445 426 <p>
446 <pre>&lt;!DOCTYPE html&gt; 427 The first restriction wipes out a huge class of cross-site scripting attacks
447 &lt;html&gt; 428 by making it impossible for you to accidentally execute script provided by a
448 &lt;head&gt; 429 malicious third-party. It does, however, require you to write your code with a
449 ... 430 clean separation between content and behavior (which you should of course do
450 &lt;/head&gt; 431 anyway, right?). An example might make this clearer. You might try to write a
451 &lt;body&gt; 432 <a href="browserAction.html#popups">Browser Action's popup</a> as a single
452 &lt;script&gt; 433 <code>popup.html</code> containing:
453 var _gaq = _gaq || []; 434 </p>
454 _gaq.push(['_setAccount', 'UA-XXXXXXXX-X']); 435
455 _gaq.push(['_trackPageview']); 436 <pre>&lt;!doctype html&gt;
456 437 &lt;html&gt;
457 (function() { 438 &lt;head&gt;
458 var ga = document.createElement('script'); ga.type = 'text/javascript'; g a.async = true; 439 &lt;title&gt;My Awesome Popup!&lt;/title&gt;
459 ga.src = 'https://ssl.google-analytics.com/ga.js'; 440 &lt;script&gt;
460 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBe fore(ga, s); 441 function awesome() {
461 })(); 442 // do something awesome!
462 &lt;/script&gt; 443 }
463 444
464 ... 445 function totallyAwesome() {
465 &lt;/body&gt; 446 // do something TOTALLY awesome!
466 &lt;/html&gt; 447 }
467 </pre> 448
468 449 function clickHandler(element) {
469 <p> 450 setTimeout(<strong>"awesome(); totallyAwesome()"</strong>, 1000);
470 Keep in mind that the string <code>UA-XXXXXXXX-X</code> should be replaced 451 }
471 with your own Google Analytics account number. 452 &lt;/script&gt;
472 </p> 453 &lt;/head&gt;
473 454 &lt;body&gt;
474 <h2 id="toc-tracking-pageviews">Tracking page views</h2> 455 &lt;button <strong>onclick="clickHandler(this)"</strong>&gt;
475 456 Click for awesomeness!
476 <p> 457 &lt;/button&gt;
477 The <code>_gaq.push(['_trackPageview']);</code> code will track a single 458 &lt;/body&gt;
478 page view. This code may be used on any page in your extension. When 459 &lt;/html&gt;</pre>
479 placed on a background page, it will register a view once per browser 460
480 session. When placed on a popup, it will register a view once every time 461 <p>
481 the popup is opened. 462 Three things will need to change in order to make this work the way you expect
482 </p> 463 it to:
483 464 </p>
484 <p> 465
485 By looking at the page view data for each page in your extension, you can 466 <ul>
486 get an idea of how many times your users interact with your extension per 467 <li>
487 browser session: 468 The <code>clickHandler</code> definition needs to move into an external
488 </p> 469 JavaScript file (<code>popup.js</code> would be a good target).
489 470 </li>
490 <p style="text-align: center"> 471 <li>
491 <img src="images/tut_analytics/screenshot02.png" style="width:300px;height:119 px;" alt="Analytics view of the top content for a site."> 472 The inline event handler definition must be rewritten in terms of
492 </p> 473 <code>addEventListener</code> and extracted into <code>popup.js</code>.
493 474 </li>
494 <h2 id="toc-debugging">Monitoring analytics requests</h2> 475 <li>
495 476 The <code>setTimeout</code> call will need to be rewritten to avoid
496 <p> 477 converting the string <code>"awesome(); totallyAwesome()"</code> into
497 To ensure that tracking data from your extension is being sent to Google 478 JavaScript for execution.
498 Analytics, you can inspect the pages of your extension in the 479 </li>
499 Developer Tools window (see the 480 </ul>
500 <a href="tut_debugging.html">debugging tutorial</a> for more information). 481
501 As the following figure shows, you should see requests for a file named 482 <p>
502 <strong>__utm.gif</strong> if everything is set up correctly. 483 Those changes might look something like the following:
503 </p> 484 </p>
504 485
505 <p style="text-align: center"> 486 <pre>popup.js:
506 <img src="images/tut_analytics/screenshot04.png" style="width:683px;height:418 px;" alt="Developer Tools window showing the __utm.gif request"> 487 =========
507 </p> 488
508 489 function awesome() {
509 <h2 id="toc-tracking-events">Tracking events</h2> 490 // Do something awesome!
510 491 }
511 <p> 492
512 By configuring event tracking, you can determine which parts of your 493 function totallyAwesome() {
513 extension your users interact with the most. For example, if you have 494 // do something TOTALLY awesome!
514 three buttons users may click: 495 }
515 </p> 496
516 497 <strong>
517 <pre> &lt;button&gt;Button 1&lt;/button&gt; 498 function awesomeTask() {
518 &lt;button&gt;Button 2&lt;/button&gt; 499 awesome();
519 &lt;button&gt;Button 3&lt;/button&gt; 500 totallyAwesome();
520 </pre> 501 }
521 502 </strong>
522 <p> 503
523 Write a function that sends click events to Google Analytics: 504 function clickHandler(e) {
524 </p> 505 setTimeout(<strong>awesomeTask</strong>, 1000);
525 506 }
526 <pre> function trackButton(button_id) { 507
527 _gaq.push(['_trackEvent', 'button' + button_id, 'clicked']); 508 // Add event listeners once the DOM has fully loaded by listening for the
528 }; 509 // `DOMContentLoaded` event on the docuent, and adding your listeners to
529 </pre> 510 // specific elements when it triggers.
530 511 document.addEventListener('DOMContentLoaded', function () {
531 <p> 512 document.querySelector('button').addEventListener('click', clickHandler);
532 And call it when each button is pressed: 513 });
533 </p> 514
534 515 popup.html:
535 <pre> &lt;button onclick="trackButton(1);"&gt;Button 1&lt;/button&gt; 516 ===========
536 &lt;button onclick="trackButton(2);"&gt;Button 2&lt;/button&gt; 517
537 &lt;button onclick="trackButton(3);"&gt;Button 3&lt;/button&gt; 518 &lt;!doctype html&gt;
538 </pre> 519 &lt;html&gt;
539 520 &lt;head&gt;
540 <p> 521 &lt;title&gt;My Awesome Popup!&lt;/title&gt;
541 The Google Analytics event tracking overview page will give you metrics 522 &lt;script <strong>src="popup.js"</strong>&gt;&lt;/script&gt;
542 regarding how many times each individual button is clicked: 523 &lt;/script&gt;
543 </p> 524 &lt;/head&gt;
544 525 &lt;body&gt;
545 <p style="text-align: center"> 526 &lt;button&gt;Click for awesomeness!&lt;/button&gt;
546 <img src="images/tut_analytics/screenshot03.png" style="width:300px;height:482 px;" alt="Analytics view of the event tracking data for a site."> 527 &lt;/body&gt;
547 </p> 528 &lt;/html&gt;</pre>
548 529
549 <p> 530 <p>
550 By using this approach, you can see which parts of your extension are 531
551 under-or-overutilized. This information can help guide decisions about UI 532
552 redesigns or additional functionality to implement. 533 </p><a name="H3-2"></a><h3>Only local script and and object resources are loaded </h3>
553 </p> 534
554 535 <p>
555 <p> 536 Script and object resources can only be loaded from the extension's
556 For more information about using the event tracking API, see the 537 package, not from the web at large. This ensures that your extension only
557 Google Analytics 538 executes the code you've specifically approved, preventing an active network
558 <a href="http://code.google.com/apis/analytics/docs/tracking/eventTrackerOverv iew.html">developer 539 attacker from maliciously redirecting your request for a resource.
559 documentation</a>. 540 </p>
560 </p> 541
561 542 <p>
562 <h2 id="toc-samplecode">Sample code</h2> 543 Instead of writing code that depends on jQuery (or any other library) loading
563 544 from an external CDN, consider including the specific version of jQuery in
564 <p> 545 your extension package. That is, instead of:
565 A sample extension that uses these techniques is 546 </p>
566 available in the Chromium source tree: 547
567 </p> 548 <pre>&lt;!doctype html&gt;
568 549 &lt;html&gt;
569 <blockquote> 550 &lt;head&gt;
570 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensi ons/docs/examples/tutorials/analytics/">.../examples/tutorials/analytics/</a> 551 &lt;title&gt;My Awesome Popup!&lt;/title&gt;
571 </blockquote> 552 &lt;script src="<strong>http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jq uery.min.js</strong>"&gt;&lt;/script&gt;
572 <p></p> 553 &lt;/script&gt;
554 &lt;/head&gt;
555 &lt;body&gt;
556 &lt;button&gt;Click for awesomeness!&lt;/button&gt;
557 &lt;/body&gt;
558 &lt;/html&gt;</pre>
559
560 <p>
561 Download the file, include it in your package, and write:
562 </p><p>
563
564 </p><pre>&lt;!doctype html&gt;
565 &lt;html&gt;
566 &lt;head&gt;
567 &lt;title&gt;My Awesome Popup!&lt;/title&gt;
568 &lt;script src="<strong>jquery.min.js</strong>"&gt;&lt;/script&gt;
569 &lt;/script&gt;
570 &lt;/head&gt;
571 &lt;body&gt;
572 &lt;button&gt;Click for awesomeness!&lt;/button&gt;
573 &lt;/body&gt;
574 &lt;/html&gt;</pre>
575
576 <a name="H2-3"></a><h2>Relaxing the default policy</h2>
577
578 <p>
579 There is no mechanism for relaxing the restriction against executing inline
580 JavaScript. In particular, setting a script policy that includes
581 <code>unsafe-inline</code> will have no effect. This is intentional.
582 </p>
583
584 <p>
585 If, on the other hand, you have a need for some external JavaScript or object
586 resources, you can relax the policy to a limited extent by whitelisting
587 specific HTTPS origins from which scripts should be accepted. Whitelisting
588 insecure HTTP resources will have no effect. This is intentional, because
589 we want to ensure that executable resources loaded with an extension's
590 elevated permissions is exactly the resource you expect, and hasn't been
591 replaced by an active network attacker. As <a href="http://en.wikipedia.org/wi ki/Man-in-the-middle_attack">man-in-the-middle
592 attacks</a> are both trivial and undetectable over HTTP, only HTTPS origins
593 will be accepted.
594 </p>
595
596 <p>
597 A relaxed policy definition which allows script resources to be loaded from
598 <code>https://example.com/</code> might look like:
599 </p>
600
601 <pre>{
602 ...,
603 "content_security_policy": "script-src 'self' https://example.com; object-src 'self'",
604 ...
605 }</pre>
606
607 <p class="note">
608 Note that both <code>script-src</code> and <code>object-src</code> are defined
609 by the policy. Chrome will not accept a policy that doesn't limit each of
610 these values to (at least) <code>'self'</code>.
611 </p>
612
613 <p>
614 Making use of Google Analytics is the canonical example for this sort of
615 policy definition. It's common enough that we've provided an Analytics
616 boilerplate of sorts in the <a href="samples.html#analytics">Event Tracking
617 with Google Analytics</a> sample extension, and a
618 <a href="tut_analytics.html">brief tutorial</a> that goes into more detail.
619 </p>
620
621 <a name="H2-4"></a><h2>Tightening the default policy</h2>
622
623 <p>
624 You may, of course, tighten this policy to whatever extent your extension
625 allows in order to increase security at the expense of convinience. To specify
626 that your extension can only load resources of <em>any</em> type (images, etc)
627 from its own package, for example, a policy of <code>default-src 'self'</code>
628 would be appropriate. The <a href="samples.html#mappy">Mappy</a> sample
629 extension is a good example of an extension that's been locked down above and
630 beyond the defaults.
631 </p>
573 </div> 632 </div>
574 633
575 <!-- API PAGE --> 634 <!-- API PAGE -->
576 <div class="apiPage" style="display: none; "> 635 <div class="apiPage" style="display: none; ">
577 <a name="apiReference"></a> 636 <a name="apiReference"></a>
578 <h2>API reference: chrome.apiname </h2> 637 <h2>API reference: chrome.apiname </h2>
579 638
580 <!-- PROPERTIES --> 639 <!-- PROPERTIES -->
581 <div class="apiGroup"> 640 <div class="apiGroup">
582 <a name="properties"></a> 641 <a name="properties"></a>
(...skipping 195 matching lines...) Expand 10 before | Expand all | Expand 10 after
778 _uff=0; 837 _uff=0;
779 urchinTracker(); 838 urchinTracker();
780 } 839 }
781 catch(e) {/* urchinTracker not available. */} 840 catch(e) {/* urchinTracker not available. */}
782 </script> 841 </script>
783 <!-- end analytics --> 842 <!-- end analytics -->
784 </div> 843 </div>
785 </div> <!-- /gc-footer --> 844 </div> <!-- /gc-footer -->
786 </div> <!-- /gc-container --> 845 </div> <!-- /gc-container -->
787 </body></html> 846 </body></html>
OLDNEW
« no previous file with comments | « no previous file | chrome/common/extensions/docs/examples/tutorials/analytics.zip » ('j') | chrome/common/extensions/docs/static/contentSecurityPolicy.html » ('J')

Powered by Google App Engine
This is Rietveld 408576698