Describing the `sandbox` workflow for extension developers.

chrome/common/extensions/docs/static/sandboxingEval.html

Index: chrome/common/extensions/docs/static/sandboxingEval.html
diff --git a/chrome/common/extensions/docs/static/sandboxingEval.html b/chrome/common/extensions/docs/static/sandboxingEval.html
new file mode 100644
index 0000000000000000000000000000000000000000..0bef1ef29a37cd49325cdb35d3ad15d90ead7262
--- /dev/null
+++ b/chrome/common/extensions/docs/static/sandboxingEval.html
@@ -0,0 +1,191 @@
+<div id="pageData-name" class="pageData">Using eval in Chrome Extensions. Safely.</div>
+<div id="pageData-showTOC" class="pageData">true</div>
+
+<p>
+  Chrome's extension system enforces a fairly strict default
+  <a href='contentSecurityPolicy.html'>
+    <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='http://developer.chrome.com/trunk/apps/app_csp.html'>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.com/'>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>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>Creating and using a sandbox.</h2>
+
+<p>
+  If you'd like to dive straight into code, please grab the
+  <a href='#TODO'>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 it together here.
+</p>
+
+<h3>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>{
+  ...,
+  "sandbox": {
+     "pages": ["sandbox.html"]
+  },
+  ...
+}</pre>
+
+<h3>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='#TODO'>sandbox.html</a> has been loaded into the extension's
+  <a href='http://code.google.com/chrome/extensions/dev/event_pages.html'>Event
+  Page</a> (<a href='#TODO'>eventpage.html</a>) via an <code>iframe</code>.
+  <a href='#TODO'>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>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>Do something dangerous</h3>
+
+<p>
+  When <a href='#TODO'>sandbox.html</a> is loaded, it loads the Handlebars
+  library, and creates and compiles an inline template in the way Handlebars
+  suggests:
+</p>
+
+<pre>&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, {{thing}}!&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>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>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':
+    //   ...
+  }
+});</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='notifications.html'>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
+  security risk, as we're protected in this context from unintentional execution
+  of inline script.
+</p>
+
+<p>
+  This mechanism makes templating straightforward, but it of course isn't
+  limited to templating. For example, the
+  <a href='https://github.com/GoogleChrome/chrome-app-samples/blob/master/regex-tester/'>Regex Tester</a>

[Mihai Parparita -not on Chrome, 2012/07/26 17:51:57]

https://github.com/GoogleChrome/chrome-app-samples/tree/master/eval-in-iframe is
my sample. It does basically what your sample does, except in a less
nice/structured way, so I'm not sure it's worth pointing out.

[Mike West, 2012/07/27 07:58:57]

Alright. Thanks. :)

I'll point to Jorge's I/O talk instead. The document viewer is a good example
not only of sandboxing, but also least privilege.

+  application uses <code>eval</code> to dynamically generate and test regular
+  expressions. It's built similarly, and would also be good for you to take a
+  look at before building your own sandboxed application or extension.
+</p>