Extensions Docs Server: Doc conversion script

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

Index: chrome/common/extensions/docs/server2/templates/articles/sandboxingEval.html
diff --git a/chrome/common/extensions/docs/server2/templates/articles/sandboxingEval.html b/chrome/common/extensions/docs/server2/templates/articles/sandboxingEval.html
new file mode 100644
index 0000000000000000000000000000000000000000..ee26ea062650afbed1961bef5d04f12dee408998
--- /dev/null
+++ b/chrome/common/extensions/docs/server2/templates/articles/sandboxingEval.html
@@ -0,0 +1,198 @@
+<h1>Using eval in Chrome Extensions. Safely.</h1>
+
+
+<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.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>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='http://code.google.com/chrome/extensions/samples.html#3c6dfba67f6a7480d931b5a4a646c151ad1a049b'>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>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='http://code.google.com/chrome/extensions/examples/howto/sandbox/sandbox.html'>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='http://code.google.com/chrome/extensions/examples/howto/sandbox/eventpage.html'>eventpage.html</a>)
+  via an <code>iframe</code>. <a href='http://code.google.com/chrome/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>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 <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>&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='http://code.google.com/chrome/extensions/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
+  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>