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

<h1>Using eval in Chrome Extensions. Safely.</h1>


<p>
  Chrome's extension system enforces a fairly strict default
  <a href='../extensions/contentSecurityPolicy'>
    <strong>Content Security Policy (CSP)</strong>
  </a>. The policy restrictions are straightforward: script must be moved
  out-of-line into separate JavaScript files, inline event handlers must be
  converted to use <code>addEventListener</code>, and <code>eval()</code> is
  disabled. Chrome Apps have an
  <a href='contentSecurityPolicy'>even more strict
  policy</a>, and we're quite happy with the security properties these policies
  provide.
</p>

<p>
  We recognize, however, that a variety of libraries use <code>eval()</code> and
  <code>eval</code>-like constructs such as <code>new Function()</code> for
  performance optimization and ease of expression. Templating libraries are
  especially prone to this style of implementation. While some (like
  <a href='http://angularjs.org/'>Angular.js</a>) support CSP out of the box,
  many popular frameworks haven't yet updated to a mechanism that is compatible
  with extensions' <code>eval</code>-less world. Removing support for that
  functionality has therefore proven <a href='http://crbug.com/107538'>more
  problematic than expected</a> for developers.
</p>

<p>
  This document introduces sandboxing as a safe mechanism to include these
  libraries in your projects without compromising on security. For brevity,
  we'll be using the term <em>extensions</em> throughout, but the concept
  applies equally to applications.
</p>

<h2 id="why_sandbox">Why sandbox?</h2>

<p>
  <code>eval</code> is dangerous inside an extension because the code it
  executes has access to everything in the extension's high-permission
  environment. A slew of powerful <code>chrome.*</code> APIs are available that
  could severely impact a user's security and privacy; simple data exfiltration
  is the least of our worries. The solution on offer is a sandbox in which
  <code>eval</code> can execute code without access either to the extension's
  data or the extension's high-value APIs. No data, no APIs, no problem.
</p>

<p>
  We accomplish this by listing specific HTML files inside the extension package
  as being sandboxed. Whenever a sandboxed page is loaded, it will be moved to a
  <a href='http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#sandboxed-origin-browsing-context-flag'>unique origin</a>,
  and will be denied access to <code>chrome.*</code> APIs. If we load this
  sandboxed page into our extension via an <code>iframe</code>, we can pass it
  messages, let it act upon those messages in some way, and wait for it to pass
  us back a result. This simple messaging mechanism gives us everything we need
  to safely include <code>eval</code>-driven code in our extension's workflow.
</p>

<h2 id="creating_and_using">Creating and using a sandbox.</h2>

<p>
  If you'd like to dive straight into code, please grab the
  <a href='/extensions/samples#sandboxed-frame'>sandboxing
  sample extension and take off</a>. It's a working example of a tiny messaging
  API built on top of the <a href='http://handlebarsjs.com'>Handlebars</a>
  templating library, and it should give you everything you need to get going.
  For those of you who'd like a little more explanation, let's walk through that
  sample together here.
</p>

<h3 id="list_files">List files in manifest</h3>

<p>
  Each file that ought to be run inside a sandbox must be listed in the
  extension manifest by adding a <code>sandbox</code> property. This is a
  critical step, and it's easy to forget, so please double check that your
  sandboxed file is listed in the manifest. In this sample, we're sandboxing the
  file cleverly named "sandbox.html". The manifest entry looks like this:
</p>

<pre data-filename="manifest.json">
{
  ...,
  "sandbox": {
     "pages": ["sandbox.html"]
  },
  ...
}
</pre>

<h3 id="load_file">Load the sandboxed file</h3>

<p>
  In order to do something interesting with the sandboxed file, we need to load
  it in a context where it can be addressed by the extension's code. Here,
  <a href='/extensions/examples/howto/sandbox/sandbox.html'>sandbox.html</a>
  has been loaded into the extension's <a href='event_pages'>Event
  Page</a> (<a href='/extensions/examples/howto/sandbox/eventpage.html'>eventpage.html</a>)
  via an <code>iframe</code>. <a href='/extensions/examples/howto/sandbox/eventpage.js'>eventpage.js</a>
  contains code that sends a message into the sandbox whenever the browser
  action is clicked by finding the <code>iframe</code> on the page, and
  executing the <code>postMessage</code> method on its
  <code>contentWindow</code>. The message is an object containing two
  properties: <code>context</code> and <code>command</code>. We'll dive into
  both in a moment.
</p>

<pre data-filename="eventpage.js">
chrome.browserAction.onClicked.addListener(function() {
 var iframe = document.getElementById('theFrame');
 var message = {
   command: 'render',
   context: {thing: 'world'}
 };
 iframe.contentWindow.postMessage(message, '*');
});
</pre>

<p class="note">
  For general information about the <code>postMessage</code> API, take a look at
  the <a href="https://developer.mozilla.org/en/DOM/window.postMessage">
    <code>postMessage</code> documentation on MDN
  </a>. It's quite complete and worth reading. In particular, note that data can
  only be passed back and forth if it's serializable. Functions, for instance,
  are not.
</p>

<h3 id="do_something">Do something dangerous</h3>

<p>
  When <code>sandbox.html</code> is loaded, it loads the Handlebars library, and
  creates and compiles an inline template in the way Handlebars suggests:
</p>

<pre data-filename="sandbox.html">
&lt;script src="handlebars-1.0.0.beta.6.js"&gt;&lt;/script&gt;
&lt;script id="hello-world-template" type="text/x-handlebars-template"&gt;
  &lt;div class="entry"&gt;
    &lt;h1&gt;Hello, &#123&#123thing&#125&#125!&lt;/h1&gt;
  &lt;/div&gt;
&lt;/script&gt;
&lt;script&gt;
  var templates = [];
  var source = document.getElementById('hello-world-template').innerHTML;
  templates['hello'] = Handlebars.compile(source);
&lt;/script&gt;
</pre>

<p>
  This doesn't fail! Even though <code>Handlebars.compile</code> ends up using
  <code>new Function</code>, things work exactly as expected, and we end up with
  a compiled template in <code>templates[‘hello']</code>.
</p>

<h3 id="pass_result">Pass the result back</h3>

<p>
  We'll make this template available for use by setting up a message listener
  that accepts commands from the Event Page. We'll use the <code>command</code>
  passed in to determine what ought to be done (you could imagine doing more
  than simply rendering; perhaps creating templates? Perhaps managing them in
  some way?), and the <code>context</code> will be passed into the template
  directly for rendering. The rendered HTML will be passed back to the Event
  Page so the extension can do something useful with it later on:
</p>

<pre data-filename="sandbox.html">
&lt;script&gt;
  window.addEventListener('message', function(event) {
    var command = event.data.command;
    var name = event.data.name || 'hello';
    switch(command) {
      case 'render':
        event.source.postMessage({
          name: name,
          html: templates[name](event.data.context)
        }, event.origin);
        break;
  
      // case 'somethingElse':
      //   ...
    }
  });
&lt;/script&gt;
</pre>

<p>
  Back in the Event Page, we'll receive this message, and do something
  interesting with the <code>html</code> data we've been passed. In this case,
  we'll just echo it out via a <a href='desktop_notifications'>Desktop
  Notification</a>, but it's entirely possible to use this HTML safely as part
  of the extension's UI. Inserting it via <code>innerHTML</code> doesn't pose a
  significant security risk, as even a complete compromise of the sandboxed code
  through some clever attack would be unable to inject dangerous script or
  plugin content into the high-permission extension context.
</p>

<p>
  This mechanism makes templating straightforward, but it of course isn't
  limited to templating. Any code that doesn't work out of the box under a
  strict Content Security Policy can be sandboxed; in fact, it's often useful
  to sandbox components of your extensions that <em>would</em> run correctly in
  order to restrict each piece of your program to the smallest set of privileges
  necessary for it to properly execute. The
  <a href="http://www.youtube.com/watch?v=GBxv8SaX0gg">Writing Secure Web Apps
  and Chrome Extensions</a> presentation from Google I/O 2012 gives some good
  examples of these technique in action, and is worth 56 minutes of your time.
</p>