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

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: 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 unified diff | Download patch | Annotate | Revision Log
« no previous file with comments | « no previous file | chrome/common/extensions/docs/examples/tutorials/analytics.zip » ('j') | no next file with comments »
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 In order to mitigate a large class of potental cross-site scripting issues,
387 368 Chrome's extension system has incorporated the general concept of
388 <h2 id="toc-requirements">Requirements</h2> 369 <a href="http://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specif ication.dev.html">
389 <p> 370 <strong>Content Security Policy (CSP)</strong>
390 This tutorial expects that you have some familiarity writing extensions for 371 </a>. This introduces some fairly strict policies that will make extensions
391 Google Chrome. If you need information on how to write an extension, please 372 more secure by default, and provides you with the ability to create and
392 read the <a href="gettingstarted.html">Getting Started tutorial</a>. 373 enforce rules governing the types of content that can be loaded and executed
393 </p> 374 by your extensions and applications.
394 375 </p>
395 <p> 376
396 You will also need a <a href="http://www.google.com/analytics">Google 377 <p>
397 Analytics account</a> set up to track your extension. Note that when setting 378 In general, CSP works as a black/whitelisting mechanism for resources loaded
398 up the account, you can use any value in the Website's URL field, as your 379 or executed by your extensions. Defining a reasonable policy for your
399 extension will not have an URL of its own. 380 extension enables you to carefully consider the resources that your extension
400 </p> 381 requires, and to ask the browser to ensure that those are the only resources
401 382 your extension has access to. These policies provide security over and above
402 <p style="text-align: center"> 383 the <a href="manifest.html#permissions">host permissions</a> your extension
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 requests; they're an additional layer of protection, not a replacement.
404 </p> 385 </p>
405 386
406 <p> 387 <p>
407 Also note that Google Analytics requires version <strong>4.0.302.2</strong> 388 On the web, such a policy is defined via an HTTP header or <code>meta</code>
408 of Google Chrome to work correctly. Users with an earlier version of Google 389 element. Inside Chrome's extension system, neither is an appropriate
409 Chrome will not show up on your Google Analytics reports. View 390 mechanism. Instead, an extension's policy is defined via the extension's
410 <a href="faq.html#faq-dev-14">this FAQ entry</a> to learn how to check which 391 <a href="manifest.html"><code>manifest.json</code></a> file as follows:
411 version of Google Chrome is deployed to which platform. 392 </p>
412 </p> 393
413 394 <pre>{
414 <h2 id="toc-installing">Installing the tracking code</h2> 395 ...,
415 396 "content_security_policy": "[POLICY STRING GOES HERE]"
416 <p> 397 ...
417 The standard Google Analytics tracking code snippet fetches a file named 398 }</pre>
418 <code>ga.js</code> from an SSL protected URL if the current page 399
419 was loaded using the <code>https://</code> protocol. <strong>It is strongly 400 <p class="note">
420 advised to use the SSL protected ga.js in an extension</strong>, 401 For full details regarding CSP's syntax, please take a look at
421 but Google Chrome extension 402 <a href="http://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specif ication.dev.html#syntax">
422 pages are hosted under <code>chrome-extension://</code> URLs, so the tracking 403 the Content Security Policy specification
423 snippet must be modified slightly to pull <code>ga.js</code> directly from 404 </a>.
424 <code>https://ssl.google-analytics.com/ga.js</code> instead of the default 405 </p>
425 location. 406
426 </p> 407 <a name="H2-0"></a><h2>Default Policy Restrictions</h2>
427 408
428 <p> 409 <p>
429 Below is a modified snippet for the 410 By default, Chrome defines a content security policy of:
430 <a href="http://code.google.com/apis/analytics/docs/tracking/asyncTracking.htm l">asynchronous 411 </p>
431 tracking API</a> (the modified line is bolded): 412
432 </p> 413 <pre>script-src 'self'; object-src 'self'</pre>
433 414
434 <pre>(function() { 415 <p>
435 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.asy nc = true; 416 This policy limits extensions in two ways:
436 <strong>ga.src = 'https://ssl.google-analytics.com/ga.js';</strong> 417 </p>
437 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore( ga, s); 418
438 })(); 419 <a name="H3-1"></a><h3>Inline JavaScript will not be executed</h3>
439 </pre> 420
440 421 <p>
441 <p> 422 Inline JavaScript, as well as dangerous string-to-JavaScript methods like
442 Here is a background page which loads the asynchronous tracking code and 423 <code>eval</code>, will not be executed. This restriction bans both inline
443 tracks a single page view: 424 <code>&lt;script&gt;</code> blocks <strong>and</strong> inline event handlers
444 </p> 425 (e.g. <code>&lt;button onclick="..."&gt;</code>).
445 426 </p>
446 <pre>&lt;!DOCTYPE html&gt; 427
447 &lt;html&gt; 428 <p>
448 &lt;head&gt; 429 The first restriction wipes out a huge class of cross-site scripting attacks
449 ... 430 by making it impossible for you to accidentally execute script provided by a
450 &lt;/head&gt; 431 malicious third-party. It does, however, require you to write your code with a
451 &lt;body&gt; 432 clean separation between content and behavior (which you should of course do
452 &lt;script&gt; 433 anyway, right?). An example might make this clearer. You might try to write a
453 var _gaq = _gaq || []; 434 <a href="browserAction.html#popups">Browser Action's popup</a> as a single
454 _gaq.push(['_setAccount', 'UA-XXXXXXXX-X']); 435 <code>popup.html</code> containing:
455 _gaq.push(['_trackPageview']); 436 </p>
456 437
457 (function() { 438 <pre>&lt;!doctype html&gt;
458 var ga = document.createElement('script'); ga.type = 'text/javascript'; g a.async = true; 439 &lt;html&gt;
459 ga.src = 'https://ssl.google-analytics.com/ga.js'; 440 &lt;head&gt;
460 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBe fore(ga, s); 441 &lt;title&gt;My Awesome Popup!&lt;/title&gt;
461 })(); 442 &lt;script&gt;
462 &lt;/script&gt; 443 function awesome() {
463 444 // do something awesome!
464 ... 445 }
465 &lt;/body&gt; 446
466 &lt;/html&gt; 447 function totallyAwesome() {
467 </pre> 448 // do something TOTALLY awesome!
468 449 }
469 <p> 450
470 Keep in mind that the string <code>UA-XXXXXXXX-X</code> should be replaced 451 function clickHandler(element) {
471 with your own Google Analytics account number. 452 setTimeout(<strong>"awesome(); totallyAwesome()"</strong>, 1000);
472 </p> 453 }
473 454 &lt;/script&gt;
474 <h2 id="toc-tracking-pageviews">Tracking page views</h2> 455 &lt;/head&gt;
475 456 &lt;body&gt;
476 <p> 457 &lt;button <strong>onclick="clickHandler(this)"</strong>&gt;
477 The <code>_gaq.push(['_trackPageview']);</code> code will track a single 458 Click for awesomeness!
478 page view. This code may be used on any page in your extension. When 459 &lt;/button&gt;
479 placed on a background page, it will register a view once per browser 460 &lt;/body&gt;
480 session. When placed on a popup, it will register a view once every time 461 &lt;/html&gt;</pre>
481 the popup is opened. 462
482 </p> 463 <p>
483 464 Three things will need to change in order to make this work the way you expect
484 <p> 465 it to:
485 By looking at the page view data for each page in your extension, you can 466 </p>
486 get an idea of how many times your users interact with your extension per 467
487 browser session: 468 <ul>
488 </p> 469 <li>
489 470 The <code>clickHandler</code> definition needs to move into an external
490 <p style="text-align: center"> 471 JavaScript file (<code>popup.js</code> would be a good target).
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 </li>
492 </p> 473 <li>
493 474 The inline event handler definition must be rewritten in terms of
494 <h2 id="toc-debugging">Monitoring analytics requests</h2> 475 <code>addEventListener</code> and extracted into <code>popup.js</code>.
495 476 </li>
496 <p> 477 <li>
497 To ensure that tracking data from your extension is being sent to Google 478 The <code>setTimeout</code> call will need to be rewritten to avoid
498 Analytics, you can inspect the pages of your extension in the 479 converting the string <code>"awesome(); totallyAwesome()"</code> into
499 Developer Tools window (see the 480 JavaScript for execution.
500 <a href="tut_debugging.html">debugging tutorial</a> for more information). 481 </li>
501 As the following figure shows, you should see requests for a file named 482 </ul>
502 <strong>__utm.gif</strong> if everything is set up correctly. 483
503 </p> 484 <p>
504 485 Those changes might look something like the following:
505 <p style="text-align: center"> 486 </p>
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 <pre>popup.js:
508 489 =========
509 <h2 id="toc-tracking-events">Tracking events</h2> 490
510 491 function awesome() {
511 <p> 492 // Do something awesome!
512 By configuring event tracking, you can determine which parts of your 493 }
513 extension your users interact with the most. For example, if you have 494
514 three buttons users may click: 495 function totallyAwesome() {
515 </p> 496 // do something TOTALLY awesome!
516 497 }
517 <pre> &lt;button&gt;Button 1&lt;/button&gt; 498
518 &lt;button&gt;Button 2&lt;/button&gt; 499 <strong>
519 &lt;button&gt;Button 3&lt;/button&gt; 500 function awesomeTask() {
520 </pre> 501 awesome();
521 502 totallyAwesome();
522 <p> 503 }
523 Write a function that sends click events to Google Analytics: 504 </strong>
524 </p> 505
525 506 function clickHandler(e) {
526 <pre> function trackButton(button_id) { 507 setTimeout(<strong>awesomeTask</strong>, 1000);
527 _gaq.push(['_trackEvent', 'button' + button_id, 'clicked']); 508 }
528 }; 509
529 </pre> 510 // Add event listeners once the DOM has fully loaded by listening for the
530 511 // `DOMContentLoaded` event on the document, and adding your listeners to
531 <p> 512 // specific elements when it triggers.
532 And call it when each button is pressed: 513 document.addEventListener('DOMContentLoaded', function () {
533 </p> 514 document.querySelector('button').addEventListener('click', clickHandler);
534 515 });
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 popup.html:
537 &lt;button onclick="trackButton(3);"&gt;Button 3&lt;/button&gt; 518 ===========
538 </pre> 519
539 520 &lt;!doctype html&gt;
540 <p> 521 &lt;html&gt;
541 The Google Analytics event tracking overview page will give you metrics 522 &lt;head&gt;
542 regarding how many times each individual button is clicked: 523 &lt;title&gt;My Awesome Popup!&lt;/title&gt;
543 </p> 524 &lt;script <strong>src="popup.js"</strong>&gt;&lt;/script&gt;
544 525 &lt;/script&gt;
545 <p style="text-align: center"> 526 &lt;/head&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;button&gt;Click for awesomeness!&lt;/button&gt;
548 529 &lt;/body&gt;
549 <p> 530 &lt;/html&gt;</pre>
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 <p>
552 redesigns or additional functionality to implement. 533
553 </p> 534
554 535 </p><a name="H3-2"></a><h3>Only local script and and object resources are loaded </h3>
555 <p> 536
556 For more information about using the event tracking API, see the 537 <p>
557 Google Analytics 538 Script and object resources can only be loaded from the extension's
558 <a href="http://code.google.com/apis/analytics/docs/tracking/eventTrackerOverv iew.html">developer 539 package, not from the web at large. This ensures that your extension only
559 documentation</a>. 540 executes the code you've specifically approved, preventing an active network
560 </p> 541 attacker from maliciously redirecting your request for a resource.
561 542 </p>
562 <h2 id="toc-samplecode">Sample code</h2> 543
563 544 <p>
564 <p> 545 Instead of writing code that depends on jQuery (or any other library) loading
565 A sample extension that uses these techniques is 546 from an external CDN, consider including the specific version of jQuery in
566 available in the Chromium source tree: 547 your extension package. That is, instead of:
567 </p> 548 </p>
568 549
569 <blockquote> 550 <pre>&lt;!doctype html&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;html&gt;
571 </blockquote> 552 &lt;head&gt;
572 <p></p> 553 &lt;title&gt;My Awesome Popup!&lt;/title&gt;
554 &lt;script src="<strong>http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jq uery.min.js</strong>"&gt;&lt;/script&gt;
555 &lt;/script&gt;
556 &lt;/head&gt;
557 &lt;body&gt;
558 &lt;button&gt;Click for awesomeness!&lt;/button&gt;
559 &lt;/body&gt;
560 &lt;/html&gt;</pre>
561
562 <p>
563 Download the file, include it in your package, and write:
564 </p><p>
565
566 </p><pre>&lt;!doctype html&gt;
567 &lt;html&gt;
568 &lt;head&gt;
569 &lt;title&gt;My Awesome Popup!&lt;/title&gt;
570 &lt;script src="<strong>jquery.min.js</strong>"&gt;&lt;/script&gt;
571 &lt;/script&gt;
572 &lt;/head&gt;
573 &lt;body&gt;
574 &lt;button&gt;Click for awesomeness!&lt;/button&gt;
575 &lt;/body&gt;
576 &lt;/html&gt;</pre>
577
578 <a name="H2-3"></a><h2>Relaxing the default policy</h2>
579
580 <p>
581 There is no mechanism for relaxing the restriction against executing inline
582 JavaScript. In particular, setting a script policy that includes
583 <code>unsafe-inline</code> will have no effect. This is intentional.
584 </p>
585
586 <p>
587 If, on the other hand, you have a need for some external JavaScript or object
588 resources, you can relax the policy to a limited extent by whitelisting
589 specific HTTPS origins from which scripts should be accepted. Whitelisting
590 insecure HTTP resources will have no effect. This is intentional, because
591 we want to ensure that executable resources loaded with an extension's
592 elevated permissions is exactly the resource you expect, and hasn't been
593 replaced by an active network attacker. As <a href="http://en.wikipedia.org/wi ki/Man-in-the-middle_attack">man-in-the-middle
594 attacks</a> are both trivial and undetectable over HTTP, only HTTPS origins
595 will be accepted.
596 </p>
597
598 <p>
599 A relaxed policy definition which allows script resources to be loaded from
600 <code>example.com</code> over HTTPS might look like:
601 </p>
602
603 <pre>{
604 ...,
605 "content_security_policy": "script-src 'self' https://example.com; object-src 'self'",
606 ...
607 }</pre>
608
609 <p class="note">
610 Note that both <code>script-src</code> and <code>object-src</code> are defined
611 by the policy. Chrome will not accept a policy that doesn't limit each of
612 these values to (at least) <code>'self'</code>.
613 </p>
614
615 <p>
616 Making use of Google Analytics is the canonical example for this sort of
617 policy definition. It's common enough that we've provided an Analytics
618 boilerplate of sorts in the <a href="samples.html#analytics">Event Tracking
619 with Google Analytics</a> sample extension, and a
620 <a href="tut_analytics.html">brief tutorial</a> that goes into more detail.
621 </p>
622
623 <a name="H2-4"></a><h2>Tightening the default policy</h2>
624
625 <p>
626 You may, of course, tighten this policy to whatever extent your extension
627 allows in order to increase security at the expense of convenience. To specify
628 that your extension can only load resources of <em>any</em> type (images, etc)
629 from its own package, for example, a policy of <code>default-src 'self'</code>
630 would be appropriate. The <a href="samples.html#mappy">Mappy</a> sample
631 extension is a good example of an extension that's been locked down above and
632 beyond the defaults.
633 </p>
573 </div> 634 </div>
574 635
575 <!-- API PAGE --> 636 <!-- API PAGE -->
576 <div class="apiPage" style="display: none; "> 637 <div class="apiPage" style="display: none; ">
577 <a name="apiReference"></a> 638 <a name="apiReference"></a>
578 <h2>API reference: chrome.apiname </h2> 639 <h2>API reference: chrome.apiname </h2>
579 640
580 <!-- PROPERTIES --> 641 <!-- PROPERTIES -->
581 <div class="apiGroup"> 642 <div class="apiGroup">
582 <a name="properties"></a> 643 <a name="properties"></a>
(...skipping 195 matching lines...) Expand 10 before | Expand all | Expand 10 after
778 _uff=0; 839 _uff=0;
779 urchinTracker(); 840 urchinTracker();
780 } 841 }
781 catch(e) {/* urchinTracker not available. */} 842 catch(e) {/* urchinTracker not available. */}
782 </script> 843 </script>
783 <!-- end analytics --> 844 <!-- end analytics -->
784 </div> 845 </div>
785 </div> <!-- /gc-footer --> 846 </div> <!-- /gc-footer -->
786 </div> <!-- /gc-container --> 847 </div> <!-- /gc-container -->
787 </body></html> 848 </body></html>
OLDNEW
« 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