src/chrome/common/extensions/docs/templates/articles/manifest/sandbox.html

   1 <h1 id="sandbox">Manifest - Sandbox</h1>
   2
   3 <p>
   4 Defines an collection of app or extension pages that are to be served
   5 in a sandboxed unique origin, and optionally a Content Security Policy to use
   6 with them. Being in a sandbox has two implications:
   7 </p>
   8
   9 <ol>
  10 <li>A sandboxed page will not have access to extension or app APIs, or
  11 direct access to non-sandboxed pages (it may communicate with them via
  12 <code>postMessage()</code>).</li>
  13 <li>
  14   <p>A sandboxed page is not subject to the
  15   <a href="http://developer.chrome.com/extensions/contentSecurityPolicy.html">Content Security Policy
  16   (CSP)</a> used by the rest of the app or extension (it has its own separate
  17   CSP value). This means that, for example, it can use inline script and
  18   <code>eval</code>.</p>
  19
  20   <p>For example, here's how to specify that two extension pages are to be
  21   served in a sandbox with a custom CSP:</p>
  22
  23   <pre data-filename="manifest.json">
  24 {
  25   ...
  26   "sandbox": {
  27     "pages": [
  28       "page1.html",
  29       "directory/page2.html"
  30     ]
  31     // content_security_policy is optional.
  32     "content_security_policy":
  33         "sandbox allow-scripts; script-src https://www.google.com"
  34   ],
  35   ...
  36 }
  37 </pre>
  38
  39   <p>
  40   If not specified, the default <code>content_security_policy</code> value is
  41   <code>sandbox allow-scripts allow-forms</code>. You can specify your CSP
  42   value to restrict the sandbox even further, but it must have the <code>sandbox</code>
  43   directive and may not have the <code>allow-same-origin</code> token (see
  44   <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-iframe-element.html#attr-iframe-sandbox">the
  45   HTML5 specification</a> for possible sandbox tokens).
  46   </p>
  47 </li>
  48 </ol>
  49
  50 <p>
  51 Note that you only need to list pages that you expected to be loaded in
  52 windows or frames. Resources used by sandboxed pages (e.g. stylesheets or
  53 JavaScript source files) do not need to appear in the
  54 <code>sandboxed_page</code> list, they will use the sandbox of the page
  55 that embeds them.
  56 </p>
  57
  58 <p>
  59 <a href="http://developer.chrome.com/extensions/sandboxingEval.html">"Using eval in Chrome Extensions. Safely."</a>
  60 goes into more detail about implementing a sandboxing workflow that enables use
  61 of libraries that would otherwise have issues executing under extension's
  62 <a href="http://developer.chrome.com/extensions/contentSecurityPolicy.html">default Content Security
  63 Policy</a>.
  64 </p>
  65
  66 <p>
  67 Sandboxed page may only be specified when using
  68 <a href="http://developer.chrome.com/extensions/manifest.html#manifest_version"><code>manifest_version</code></a> 2 or above.
  69 </p>