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