src/chrome/common/extensions/docs/templates/articles/app_csp.html

   1 <h1>Content Security Policy</h1>
   2
   3
   4 <p>
   5 If you're not familiar with Content Security Policy (CSP),
   6 <a href="http://www.html5rocks.com/en/tutorials/security/content-security-policy/">An Introduction to Content Security Policy</a>
   7 is a good starting point.
   8 That document covers the broader web platform view of CSP;
   9 Chrome App CSP isn't as flexible.
  10 You should also read the
  11 <a href="/extensions/contentSecurityPolicy.html">Chrome extension Content Security Policy</a>,
  12 as it's the foundation for the Chrome App CSP.
  13 For brevity's sake,
  14 we don't repeat the same information here.
  15 </p>
  16
  17 <p>
  18 CSP is a policy to mitigate against cross-site scripting issues,
  19 and we all know that cross-site scripting is bad.
  20 We aren’t going to try and convince you
  21 that CSP is a warm-and-fuzzy new policy.
  22 There's work involved;
  23 you'll need to learn how to do fundamental tasks differently.
  24 </p>
  25
  26 <p>
  27 The purpose of this document is to tell you
  28 exactly what the CSP policy is for Chrome Apps,
  29 what you need to do to comply with it,
  30 and how you can still do those fundamental tasks
  31 in a way that is CSP&ndash;compliant.
  32 </p>
  33
  34 <h2 id="what">What is the CSP for Chrome Apps?</h2>
  35
  36 <p>The content security policy for Chrome Apps restricts
  37 you from doing the following:</p>
  38
  39 <ul>
  40         <li>You can’t use inline scripting in your Chrome App pages.
  41                 The restriction bans both &lt;script> blocks and
  42                 event handlers (&lt;button onclick="...">).</li>
  43         <li>You can’t reference any external resources in any of your app files
  44                 (except for video and audio resources).
  45                 You can’t embed external resources in an iframe.</li>
  46         <li>You can’t use string-to-JavaScript methods like
  47                 <code>eval()</code> and <code>new Function()</code>.</li>
  48 </ul>
  49
  50 <p>This is implemented via the following policy value:</p>
  51
  52 <pre>
  53 default-src 'self';
  54 connect-src *;
  55 style-src 'self' data: chrome-extension-resource: 'unsafe-inline';
  56 img-src 'self' data: chrome-extension-resource:;
  57 frame-src 'self' data: chrome-extension-resource:;
  58 font-src 'self' data: chrome-extension-resource:;
  59 media-src *;
  60 </pre>
  61
  62 <p>
  63 Your Chrome App can only refer to scripts and objects
  64 within your app, with the exception of media files
  65 (apps can refer to video and audio outside the package).
  66 Chrome extensions will let you relax the default Content Security Policy;
  67 Chrome Apps won’t.
  68 </p>
  69
  70 <h2 id="how">How to comply with CSP</h2>
  71
  72 <p>
  73 All JavaScript and all resources should be local
  74 (everything gets packaged in your Chrome App).
  75 </p>
  76
  77 <h2 id="but">"But then how do I..."</h2>
  78
  79 <p>
  80 It's very possible that you are using templating libraries
  81 and many of these won’t work with CSP.
  82 You may also want to access external resources in your app
  83 (external images, content from websites).
  84 </p>
  85
  86 <h3 id="templating">Use templating libraries</h3>
  87
  88 <p>
  89 Use a library that offers precompiled templates
  90 and you’re all set.
  91 You can still use a library that doesn’t offer precompilation,
  92 but it will require some work on your part and there are restrictions.
  93 </p>
  94
  95 <p>
  96 You will need to use sandboxing to isolate any content
  97 that you want to do ‘eval’ things to.
  98 Sandboxing lifts CSP on the content that you specify.
  99 If you want to use the very powerful Chrome APIs in your Chrome App,
 100 your sandboxed content can't directly interact with these APIs
 101 (see <a href="app_external.html#sandboxing">Sandbox local content</a>).
 102 </p>
 103
 104 <h3 id="remote_resources">Access remote resources</h3>
 105
 106 <p>
 107 You can fetch remote resources via <code>XMLHttpRequest</code>
 108 and serve them via <code>blob:</code>, <code>data:</code>,
 109 or <code>filesystem:</code> URLs
 110 (see <a href="app_external.html#external">Referencing external resources</a>).
 111 </p>
 112
 113 <p>
 114 Video and audio can be loaded from remote services
 115 because they have good fallback behavior when offline or under spotty connectivity.
 116 </p>
 117
 118 <h3 id="embed_content">Embed web content</h3>
 119
 120 <p>
 121 Instead of using an iframe,
 122 you can call out to an external URL using an object tag
 123 (see <a href="app_external.html#webview">Embed external web pages</a>).
 124 </p>
 125
 126 <p class="backtotop"><a href="#top">Back to top</a></p>