| OLD | NEW |
|---|
| (Empty) | |
| 1 <h1 class="page_title">Using eval in Chrome Extensions. Safely.</h1> |
| 2 <div id="pageData-showTOC" class="pageData">true</div> |
| 3 <p> |
| 4 Chrome's extension system enforces a fairly strict default |
| 5 <a href='contentSecurityPolicy.html'> |
| 6 <strong>Content Security Policy (CSP)</strong> |
| 7 </a>. The policy restrictions are straightforward: script must be moved |
| 8 out-of-line into separate JavaScript files, inline event handlers must be |
| 9 converted to use <code>addEventListener</code>, and <code>eval()</code> is |
| 10 disabled. Chrome Apps have an |
| 11 <a href='http://developer.chrome.com/trunk/apps/app_csp.html'>even more strict |
| 12 policy</a>, and we're quite happy with the security properties these policies |
| 13 provide. |
| 14 </p> |
| 15 <p> |
| 16 We recognize, however, that a variety of libraries use <code>eval()</code> and |
| 17 <code>eval</code>-like constructs such as <code>new Function()</code> for |
| 18 performance optimization and ease of expression. Templating libraries are |
| 19 especially prone to this style of implementation. While some (like |
| 20 <a href='http://angularjs.org/'>Angular.js</a>) support CSP out of the box, |
| 21 many popular frameworks haven't yet updated to a mechanism that is compatible |
| 22 with extensions' <code>eval</code>-less world. Removing support for that |
| 23 functionality has therefore proven <a href='http://crbug.com/107538'>more |
| 24 problematic than expected</a> for developers. |
| 25 </p> |
| 26 <p> |
| 27 This document introduces sandboxing as a safe mechanism to include these |
| 28 libraries in your projects without compromising on security. For brevity, |
| 29 we'll be using the term <em>extensions</em> throughout, but the concept |
| 30 applies equally to applications. |
| 31 </p> |
| 32 <h2>Why sandbox?</h2> |
| 33 <p> |
| 34 <code>eval</code> is dangerous inside an extension because the code it |
| 35 executes has access to everything in the extension's high-permission |
| 36 environment. A slew of powerful <code>chrome.*</code> APIs are available that |
| 37 could severely impact a user's security and privacy; simple data exfiltration |
| 38 is the least of our worries. The solution on offer is a sandbox in which |
| 39 <code>eval</code> can execute code without access either to the extension's |
| 40 data or the extension's high-value APIs. No data, no APIs, no problem. |
| 41 </p> |
| 42 <p> |
| 43 We accomplish this by listing specific HTML files inside the extension package |
| 44 as being sandboxed. Whenever a sandboxed page is loaded, it will be moved to a |
| 45 <a href='http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.
html#sandboxed-origin-browsing-context-flag'>unique origin</a>, |
| 46 and will be denied access to <code>chrome.*</code> APIs. If we load this |
| 47 sandboxed page into our extension via an <code>iframe</code>, we can pass it |
| 48 messages, let it act upon those messages in some way, and wait for it to pass |
| 49 us back a result. This simple messaging mechanism gives us everything we need |
| 50 to safely include <code>eval</code>-driven code in our extension's workflow. |
| 51 </p> |
| 52 <h2>Creating and using a sandbox.</h2> |
| 53 <p> |
| 54 If you'd like to dive straight into code, please grab the |
| 55 <a href='http://code.google.com/chrome/extensions/samples.html#3c6dfba67f6a748
0d931b5a4a646c151ad1a049b'>sandboxing |
| 56 sample extension and take off</a>. It's a working example of a tiny messaging |
| 57 API built on top of the <a href='http://handlebarsjs.com'>Handlebars</a> |
| 58 templating library, and it should give you everything you need to get going. |
| 59 For those of you who'd like a little more explanation, let's walk through that |
| 60 sample together here. |
| 61 </p> |
| 62 <h3>List files in manifest</h3> |
| 63 <p> |
| 64 Each file that ought to be run inside a sandbox must be listed in the |
| 65 extension manifest by adding a <code>sandbox</code> property. This is a |
| 66 critical step, and it's easy to forget, so please double check that your |
| 67 sandboxed file is listed in the manifest. In this sample, we're sandboxing the |
| 68 file cleverly named "sandbox.html". The manifest entry looks like this: |
| 69 </p> |
| 70 <pre>{ |
| 71 ..., |
| 72 "sandbox": { |
| 73 "pages": ["sandbox.html"] |
| 74 }, |
| 75 ... |
| 76 }</pre> |
| 77 <h3>Load the sandboxed file</h3> |
| 78 <p> |
| 79 In order to do something interesting with the sandboxed file, we need to load |
| 80 it in a context where it can be addressed by the extension's code. Here, |
| 81 <a href='http://code.google.com/chrome/extensions/examples/howto/sandbox/sandb
ox.html'>sandbox.html</a> |
| 82 has been loaded into the extension's <a href='http://code.google.com/chrome/ex
tensions/dev/event_pages.html'>Event |
| 83 Page</a> (<a href='http://code.google.com/chrome/extensions/examples/howto/san
dbox/eventpage.html'>eventpage.html</a>) |
| 84 via an <code>iframe</code>. <a href='http://code.google.com/chrome/extensions/
examples/howto/sandbox/eventpage.js'>eventpage.js</a> |
| 85 contains code that sends a message into the sandbox whenever the browser |
| 86 action is clicked by finding the <code>iframe</code> on the page, and |
| 87 executing the <code>postMessage</code> method on its |
| 88 <code>contentWindow</code>. The message is an object containing two |
| 89 properties: <code>context</code> and <code>command</code>. We'll dive into |
| 90 both in a moment. |
| 91 </p> |
| 92 <pre>chrome.browserAction.onClicked.addListener(function() { |
| 93 var iframe = document.getElementById('theFrame'); |
| 94 var message = { |
| 95 command: 'render', |
| 96 context: {thing: 'world'} |
| 97 }; |
| 98 iframe.contentWindow.postMessage(message, '*'); |
| 99 });</pre> |
| 100 <p class="note"> |
| 101 For general information about the <code>postMessage</code> API, take a look at |
| 102 the <a href="https://developer.mozilla.org/en/DOM/window.postMessage"> |
| 103 <code>postMessage</code> documentation on MDN |
| 104 </a>. It's quite complete and worth reading. In particular, note that data can |
| 105 only be passed back and forth if it's serializable. Functions, for instance, |
| 106 are not. |
| 107 </p> |
| 108 <h3>Do something dangerous</h3> |
| 109 <p> |
| 110 When <code>sandbox.html</code> is loaded, it loads the Handlebars library, and |
| 111 creates and compiles an inline template in the way Handlebars suggests: |
| 112 </p> |
| 113 <pre><script src="handlebars-1.0.0.beta.6.js"></script> |
| 114 <script id="hello-world-template" type="text/x-handlebars-template"> |
| 115 <div class="entry"> |
| 116 <h1>Hello, {{thing}}!</h1> |
| 117 </div> |
| 118 </script> |
| 119 <script> |
| 120 var templates = []; |
| 121 var source = document.getElementById('hello-world-template').innerHTML; |
| 122 templates['hello'] = Handlebars.compile(source); |
| 123 </script></pre> |
| 124 <p> |
| 125 This doesn't fail! Even though <code>Handlebars.compile</code> ends up using |
| 126 <code>new Function</code>, things work exactly as expected, and we end up with |
| 127 a compiled template in <code>templates[‘hello']</code>. |
| 128 </p> |
| 129 <h3>Pass the result back</h3> |
| 130 <p> |
| 131 We'll make this template available for use by setting up a message listener |
| 132 that accepts commands from the Event Page. We'll use the <code>command</code> |
| 133 passed in to determine what ought to be done (you could imagine doing more |
| 134 than simply rendering; perhaps creating templates? Perhaps managing them in |
| 135 some way?), and the <code>context</code> will be passed into the template |
| 136 directly for rendering. The rendered HTML will be passed back to the Event |
| 137 Page so the extension can do something useful with it later on: |
| 138 </p> |
| 139 <pre>window.addEventListener('message', function(event) { |
| 140 var command = event.data.command; |
| 141 var name = event.data.name || 'hello'; |
| 142 switch(command) { |
| 143 case 'render': |
| 144 event.source.postMessage({ |
| 145 name: name, |
| 146 html: templates[name](event.data.context) |
| 147 }, event.origin); |
| 148 break; |
| 149 // case 'somethingElse': |
| 150 // ... |
| 151 } |
| 152 });</pre> |
| 153 <p> |
| 154 Back in the Event Page, we'll receive this message, and do something |
| 155 interesting with the <code>html</code> data we've been passed. In this case, |
| 156 we'll just echo it out via a <a href='http://code.google.com/chrome/extensions
/notifications.html'>Desktop |
| 157 Notification</a>, but it's entirely possible to use this HTML safely as part |
| 158 of the extension's UI. Inserting it via <code>innerHTML</code> doesn't pose a |
| 159 significant security risk, as even a complete compromise of the sandboxed code |
| 160 through some clever attack would be unable to inject dangerous script or |
| 161 plugin content into the high-permission extension context. |
| 162 </p> |
| 163 <p> |
| 164 This mechanism makes templating straightforward, but it of course isn't |
| 165 limited to templating. Any code that doesn't work out of the box under a |
| 166 strict Content Security Policy can be sandboxed; in fact, it's often useful |
| 167 to sandbox components of your extensions that <em>would</em> run correctly in |
| 168 order to restrict each piece of your program to the smallest set of privileges |
| 169 necessary for it to properly execute. The |
| 170 <a href="http://www.youtube.com/watch?v=GBxv8SaX0gg">Writing Secure Web Apps |
| 171 and Chrome Extensions</a> presentation from Google I/O 2012 gives some good |
| 172 examples of these technique in action, and is worth 56 minutes of your time. |
| 173 </p> |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 10832042:
Extensions Docs Server: Doc conversion script (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src