OLD | NEW |
(Empty) | |
| 1 <div id="pageData-name" class="pageData">Content Security Policy (CSP)</div> |
| 2 <div id="pageData-showTOC" class="pageData">true</div> |
| 3 |
| 4 <p> |
| 5 In order to mitigate a large class of potental cross-site scripting issues, |
| 6 Chrome's extension system has incorporated the general concept of |
| 7 <a href="http://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specif
ication.dev.html"> |
| 8 <strong>Content Security Policy (CSP)</strong> |
| 9 </a>. This introduces some fairly strict policies that will make extensions |
| 10 more secure by default, and provides you with the ability to create and |
| 11 enforce rules governing the types of content that can be loaded and executed |
| 12 by your extensions and applications. |
| 13 </p> |
| 14 |
| 15 <p> |
| 16 In general, CSP works as a black/whitelisting mechanism for resources loaded |
| 17 or executed by your extensions. Defining a reasonable policy for your |
| 18 extension enables you to carefully consider the resources that your extension |
| 19 requires, and to ask the browser to ensure that those are the only resources |
| 20 your extension has access to. These policies provide security over and above |
| 21 the <a href="manifest.html#permissions">host permissions</a> your extension |
| 22 requests; they're an additional layer of protection, not a replacement. |
| 23 </p> |
| 24 |
| 25 <p> |
| 26 On the web, such a policy is defined via an HTTP header or <code>meta</code> |
| 27 element. Inside Chrome's extension system, neither is an appropriate |
| 28 mechanism. Instead, an extension's policy is defined via the extension's |
| 29 <a href="manifest.html"><code>manifest.json</code></a> file as follows: |
| 30 </p> |
| 31 |
| 32 <pre>{ |
| 33 ..., |
| 34 "content_security_policy": "[POLICY STRING GOES HERE]" |
| 35 ... |
| 36 }</pre> |
| 37 |
| 38 <p class="note"> |
| 39 For full details regarding CSP's syntax, please take a look at |
| 40 <a href="http://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specif
ication.dev.html#syntax"> |
| 41 the Content Security Policy specification |
| 42 </a>. |
| 43 </p> |
| 44 |
| 45 <h2>Default Policy Restrictions</h2> |
| 46 |
| 47 <p> |
| 48 By default, Chrome defines a content security policy of: |
| 49 </p> |
| 50 |
| 51 <pre>script-src 'self'; object-src 'self'</pre> |
| 52 |
| 53 <p> |
| 54 This policy limits extensions in two ways: |
| 55 </p> |
| 56 |
| 57 <h3>Inline JavaScript will not be executed</h3> |
| 58 |
| 59 <p> |
| 60 Inline JavaScript, as well as dangerous string-to-JavaScript methods like |
| 61 <code>eval</code>, will not be executed. This restriction bans both inline |
| 62 <code><script></code> blocks <strong>and</strong> inline event handlers |
| 63 (e.g. <code><button onclick="..."></code>). |
| 64 </p> |
| 65 |
| 66 <p> |
| 67 The first restriction wipes out a huge class of cross-site scripting attacks |
| 68 by making it impossible for you to accidentally execute script provided by a |
| 69 malicious third-party. It does, however, require you to write your code with a |
| 70 clean separation between content and behavior (which you should of course do |
| 71 anyway, right?). An example might make this clearer. You might try to write a |
| 72 <a href="browserAction.html#popups">Browser Action's popup</a> as a single |
| 73 <code>popup.html</code> containing: |
| 74 </p> |
| 75 |
| 76 <pre><!doctype html> |
| 77 <html> |
| 78 <head> |
| 79 <title>My Awesome Popup!</title> |
| 80 <script> |
| 81 function awesome() { |
| 82 // do something awesome! |
| 83 } |
| 84 |
| 85 function totallyAwesome() { |
| 86 // do something TOTALLY awesome! |
| 87 } |
| 88 |
| 89 function clickHandler(element) { |
| 90 setTimeout(<strong>"awesome(); totallyAwesome()"</strong>, 1000); |
| 91 } |
| 92 </script> |
| 93 </head> |
| 94 <body> |
| 95 <button <strong>onclick="clickHandler(this)"</strong>> |
| 96 Click for awesomeness! |
| 97 </button> |
| 98 </body> |
| 99 </html></pre> |
| 100 |
| 101 <p> |
| 102 Three things will need to change in order to make this work the way you expect |
| 103 it to: |
| 104 </p> |
| 105 |
| 106 <ul> |
| 107 <li> |
| 108 The <code>clickHandler</code> definition needs to move into an external |
| 109 JavaScript file (<code>popup.js</code> would be a good target). |
| 110 </li> |
| 111 <li> |
| 112 The inline event handler definition must be rewritten in terms of |
| 113 <code>addEventListener</code> and extracted into <code>popup.js</code>. |
| 114 </li> |
| 115 <li> |
| 116 The <code>setTimeout</code> call will need to be rewritten to avoid |
| 117 converting the string <code>"awesome(); totallyAwesome()"</code> into |
| 118 JavaScript for execution. |
| 119 </li> |
| 120 </ul> |
| 121 |
| 122 <p> |
| 123 Those changes might look something like the following: |
| 124 </p> |
| 125 |
| 126 <pre>popup.js: |
| 127 ========= |
| 128 |
| 129 function awesome() { |
| 130 // Do something awesome! |
| 131 } |
| 132 |
| 133 function totallyAwesome() { |
| 134 // do something TOTALLY awesome! |
| 135 } |
| 136 |
| 137 <strong> |
| 138 function awesomeTask() { |
| 139 awesome(); |
| 140 totallyAwesome(); |
| 141 } |
| 142 </strong> |
| 143 |
| 144 function clickHandler(e) { |
| 145 setTimeout(<strong>awesomeTask</strong>, 1000); |
| 146 } |
| 147 |
| 148 // Add event listeners once the DOM has fully loaded by listening for the |
| 149 // `DOMContentLoaded` event on the document, and adding your listeners to |
| 150 // specific elements when it triggers. |
| 151 document.addEventListener('DOMContentLoaded', function () { |
| 152 document.querySelector('button').addEventListener('click', clickHandler); |
| 153 }); |
| 154 |
| 155 popup.html: |
| 156 =========== |
| 157 |
| 158 <!doctype html> |
| 159 <html> |
| 160 <head> |
| 161 <title>My Awesome Popup!</title> |
| 162 <script <strong>src="popup.js"</strong>></script> |
| 163 </script> |
| 164 </head> |
| 165 <body> |
| 166 <button>Click for awesomeness!</button> |
| 167 </body> |
| 168 </html></pre> |
| 169 |
| 170 <p> |
| 171 |
| 172 |
| 173 <h3>Only local script and and object resources are loaded</h3> |
| 174 |
| 175 <p> |
| 176 Script and object resources can only be loaded from the extension's |
| 177 package, not from the web at large. This ensures that your extension only |
| 178 executes the code you've specifically approved, preventing an active network |
| 179 attacker from maliciously redirecting your request for a resource. |
| 180 </p> |
| 181 |
| 182 <p> |
| 183 Instead of writing code that depends on jQuery (or any other library) loading |
| 184 from an external CDN, consider including the specific version of jQuery in |
| 185 your extension package. That is, instead of: |
| 186 </p> |
| 187 |
| 188 <pre><!doctype html> |
| 189 <html> |
| 190 <head> |
| 191 <title>My Awesome Popup!</title> |
| 192 <script src="<strong>http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jq
uery.min.js</strong>"></script> |
| 193 </script> |
| 194 </head> |
| 195 <body> |
| 196 <button>Click for awesomeness!</button> |
| 197 </body> |
| 198 </html></pre> |
| 199 |
| 200 <p> |
| 201 Download the file, include it in your package, and write: |
| 202 <p> |
| 203 |
| 204 <pre><!doctype html> |
| 205 <html> |
| 206 <head> |
| 207 <title>My Awesome Popup!</title> |
| 208 <script src="<strong>jquery.min.js</strong>"></script> |
| 209 </script> |
| 210 </head> |
| 211 <body> |
| 212 <button>Click for awesomeness!</button> |
| 213 </body> |
| 214 </html></pre> |
| 215 |
| 216 <h2>Relaxing the default policy</h2> |
| 217 |
| 218 <p> |
| 219 There is no mechanism for relaxing the restriction against executing inline |
| 220 JavaScript. In particular, setting a script policy that includes |
| 221 <code>unsafe-inline</code> will have no effect. This is intentional. |
| 222 </p> |
| 223 |
| 224 <p> |
| 225 If, on the other hand, you have a need for some external JavaScript or object |
| 226 resources, you can relax the policy to a limited extent by whitelisting |
| 227 specific HTTPS origins from which scripts should be accepted. Whitelisting |
| 228 insecure HTTP resources will have no effect. This is intentional, because |
| 229 we want to ensure that executable resources loaded with an extension's |
| 230 elevated permissions is exactly the resource you expect, and hasn't been |
| 231 replaced by an active network attacker. As <a |
| 232 href="http://en.wikipedia.org/wiki/Man-in-the-middle_attack">man-in-the-middle |
| 233 attacks</a> are both trivial and undetectable over HTTP, only HTTPS origins |
| 234 will be accepted. |
| 235 </p> |
| 236 |
| 237 <p> |
| 238 A relaxed policy definition which allows script resources to be loaded from |
| 239 <code>example.com</code> over HTTPS might look like: |
| 240 </p> |
| 241 |
| 242 <pre>{ |
| 243 ..., |
| 244 "content_security_policy": "script-src 'self' https://example.com; object-src
'self'", |
| 245 ... |
| 246 }</pre> |
| 247 |
| 248 <p class="note"> |
| 249 Note that both <code>script-src</code> and <code>object-src</code> are defined |
| 250 by the policy. Chrome will not accept a policy that doesn't limit each of |
| 251 these values to (at least) <code>'self'</code>. |
| 252 </p> |
| 253 |
| 254 <p> |
| 255 Making use of Google Analytics is the canonical example for this sort of |
| 256 policy definition. It's common enough that we've provided an Analytics |
| 257 boilerplate of sorts in the <a href="samples.html#analytics">Event Tracking |
| 258 with Google Analytics</a> sample extension, and a |
| 259 <a href="tut_analytics.html">brief tutorial</a> that goes into more detail. |
| 260 </p> |
| 261 |
| 262 <h2>Tightening the default policy</h2> |
| 263 |
| 264 <p> |
| 265 You may, of course, tighten this policy to whatever extent your extension |
| 266 allows in order to increase security at the expense of convenience. To specify |
| 267 that your extension can only load resources of <em>any</em> type (images, etc) |
| 268 from its own package, for example, a policy of <code>default-src 'self'</code> |
| 269 would be appropriate. The <a href="samples.html#mappy">Mappy</a> sample |
| 270 extension is a good example of an extension that's been locked down above and |
| 271 beyond the defaults. |
| 272 </p> |
OLD | NEW |