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

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