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