Merge 159156 - Extensions Docs Server: Fix headings with no IDs

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='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
@@ skipping 15 matching lines @@
   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>
+<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>Creating and using a sandbox.</h2>
+<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='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>
+<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>{
   ...,
   "sandbox": {
      "pages": ["sandbox.html"]
   },
   ...
 }</pre>
 
-<h3>Load the sandboxed file</h3>
+<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='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
@@ skipping 14 matching lines @@
 
 <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>
+<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>&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>Pass the result back</h3>
+<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>
@@ skipping 29 matching lines @@
   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>