Components.utils.Sandbox

  • Revision slug: Components.utils.Sandbox
  • Revision title: Components.utils.Sandbox
  • Revision id: 349799
  • Created:
  • Creator: jimb@red-bean.com
  • Is current revision? No
  • Comment

Revision Content

Components.utils.Sandbox is used to create a sandbox object for use by evalInSandbox().

Creating a sandbox

The Components.utils.Sandbox constructor has one required parameter—the context in which to execute the script. This can be specified either as a URI or, preferably, using a DOM window ({{ interface("nsIDOMWindow") }}, such as returned by the DOM {{ domxref("window") }} property.

Starting in Gecko 1.9 {{ geckoRelease("1.9") }}, you can also use an {{ interface("nsIPrincipal") }} to specify the execution context. You can get the principal for a window using the {{ domxref("document.nodePrincipal") }} property.

In any case, the context you specify represents the origin for security purposes while executing the script. For example, passing a URI of http://www.example.com/ lets the code evaluated in the sandbox make AJAX requests from that domain. If the script running in the sandbox sets {{ domxref("document.domain") }} to change the same-origin security checks, you should use a DOM window or {{ interface("nsIPrincipal") }} for the origin instead of a URI.

To create a sandbox using a URI, simply do this:

var mySandbox = Components.utils.Sandbox("http://www.example.com/");

The created sandbox is simply an empty JavaScript object marked as having been created by the restricted privilege principal. You can then use it with evalInSandbox() to make it the global scope object for specified script.

Optional parameter

The constructor accepts an optional parameter. This parameter is an object with the following optional properties:

sandboxName {{ gecko_minversion_inline("9.0") }}

A string value which identifies the sandbox in about:memory (and possibly other places in the future). This property is optional, but very useful for tracking memory usage of add-ons and other JavaScript compartments. A recommended value for this property is an absolute path to the script responsible for creating the sandbox.  As of Gecko 13 {{ geckoRelease("13.0") }}, if you don't specify a sandbox name it will default to the caller's filename.

sandboxPrototype

A prototype object for the sandbox. The sandbox will inherit the contents of this object if it's provided.

wantXrays

A Boolean value indicating whether the sandbox wants X-ray vision with respect to same-origin objects outside the sandbox. Default: true.

“X-ray vision” is exactly the same X-ray behavior that script always gets, by default, when working with DOM objects across origin boundaries. This is primarily visible for chrome code accessing content. However, it also occurs during cross-origin access between two content pages, since each page sees a "vanilla" view of the other. The protection is bidirectional: the caller sees the bonafide DOM objects without being confused by sneakily-redefined properties, and the target receives appropriate privacy from having its expandos inspected by untrusted callers. In situations where only unidirectional protection is needed, callers have the option to waive the Xray behavior using wrappedJSObject or XPCNativeWrapper.unwrap().

In general, when accessing same-origin content, script gets a Transparent wrapper rather than an Xray wrapper. However, sandboxes are often used when chrome wants to run script as another origin, possibly to interact with the page. In this case, same-origin Xrays and be desirable, and wantXrays should be set to true. This is also the default (for historical reasons).

See Safely accessing content DOM from chrome for more details.

wantComponents {{ gecko_minversion_inline("15.0") }}

A Boolean indicating whether the Components object is available or not in the sandbox. Default: true.

wantXHRConstructor {{ gecko_minversion_inline("16.0") }}

A Boolean indicating whether the XMLHttpRequest object is available or not in the sandbox. Default: false.

{{ gecko_callout_heading("2.0") }}

The syntax of this constructor changed in Gecko 2.0 {{ geckoRelease("2.0") }}. Previously, the optional parameters sandboxProperty and wantXrays were passed directly to the constructor instead of being properties of the optional parameters object; they were passed directly in the order listed above.

Methods available on the Sandbox object

dump() - Similar to window.dump().
debug()

For more information on the built-in Sandbox functions, please consult the source code.

Importing functions or objects into the Sandbox

You can import functions or objects into the sandbox simply by assigning them to the sandbox object.  For example:

mysandbox.doSomething = function() { ... };

Obviously you still need to consider the security implications of the functions you import, but it is no longer necessary to use sandbox.importFunction() to securely import chrome functions into the Sandbox context - see bug 756514 for more or the Firefox socialapi code for an example.  This technique isn't limited to functions - it can be used to import objects or values.

See also

{{ languages( { "pl": "pl/Components.utils.Sandbox" } ) }}

Revision Source

<p><code>Components.utils.Sandbox</code> is used to create a sandbox object for use by <a href="/en/Components.utils.evalInSandbox" title="en/Components.utils.evalInSandbox"><code>evalInSandbox()</code></a>.</p>
<h2 id="Creating_a_sandbox">Creating a sandbox</h2>
<p>The <code>Components.utils.Sandbox</code> constructor has one required parameter—the context in which to execute the script. This can be specified either as a URI or, preferably, using a DOM&nbsp;window ({{ interface("nsIDOMWindow") }}, such as returned by the DOM&nbsp;{{ domxref("window") }} property.</p>
<p>Starting in Gecko 1.9 {{ geckoRelease("1.9") }}, you can also use an {{ interface("nsIPrincipal") }}&nbsp;to specify the execution context. You can get the principal for a window using the {{ domxref("document.nodePrincipal") }} property.</p>
<p>In any case, the context you specify represents the origin for security purposes while executing the script. For example, passing a URI&nbsp;of <span class="nowiki">http://www.example.com/</span> lets the code evaluated in the sandbox make AJAX requests from that domain. If the script running in the sandbox sets {{ domxref("document.domain") }} to change the same-origin security checks, you should use a DOM&nbsp;window or {{ interface("nsIPrincipal") }} for the origin instead of a URI.</p>
<p>To create a sandbox using a URI, simply do this:</p>
<pre>
var mySandbox = Components.utils.Sandbox("<span class="plain">http://www.example.com/</span>");
</pre>
<p>The created sandbox is simply an empty JavaScript object marked as having been created by the restricted privilege principal. You can then use it with <a href="/en/Components.utils.evalInSandbox" title="en/Components.utils.evalInSandbox"><code>evalInSandbox()</code></a> to make it the global scope object for specified script.</p>
<h3 id="Optional_parameter">Optional parameter</h3>
<p>The constructor accepts an optional parameter. This parameter is an object with the following optional properties:</p>
<dl>
  <dt>
    <code>sandboxName</code> {{ gecko_minversion_inline("9.0") }}</dt>
  <dd>
    <p>A string value which identifies the sandbox in about:memory (and possibly other places in the future). This property is optional, but very useful for tracking memory usage of add-ons and other JavaScript compartments. A recommended value for this property is an absolute path to the script responsible for creating the sandbox.&nbsp; As of Gecko 13 {{ geckoRelease("13.0") }}, if you don't specify a sandbox name it will default to the caller's filename.</p>
  </dd>
  <dt>
    <code>sandboxPrototype</code></dt>
  <dd>
    <p>A prototype object for the sandbox. The sandbox will inherit the contents of this object if it's provided.</p>
  </dd>
  <dt>
    <code>wantXrays</code></dt>
  <dd>
    <p>A Boolean value indicating whether the sandbox wants X-ray vision with respect to same-origin objects outside the sandbox. Default: <code>true</code>.</p>
    <p>“X-ray vision” is exactly the same X-ray behavior that script always gets, by default, when working with DOM objects across origin boundaries. This is primarily visible for chrome code accessing content. However, it also occurs during cross-origin access between two content pages, since each page sees a "vanilla" view of the other. The protection is bidirectional: the caller sees the bonafide DOM objects without being confused by sneakily-redefined properties, and the target receives appropriate privacy from having its expandos inspected by untrusted callers. In situations where only unidirectional protection is needed, callers have the option to waive the Xray behavior using <code>wrappedJSObject </code>or<code> XPCNativeWrapper.unwrap().</code></p>
    <p>In general, when accessing same-origin content, script gets a Transparent wrapper rather than an Xray wrapper. However, sandboxes are often used when chrome wants to run script as another origin, possibly to interact with the page. In this case, same-origin Xrays and be desirable, and <code>wantXrays </code>should be set to<code> </code><code>true</code>. This is also the default (for historical reasons).</p>
    <p>See <a href="/en/Safely_accessing_content_DOM_from_chrome" title="en/Safely accessing content DOM from chrome">Safely accessing content DOM from chrome</a> for more details.</p>
  </dd>
  <dt>
    <code>wantComponents</code> {{ gecko_minversion_inline("15.0") }}</dt>
  <dd>
    <p>A Boolean indicating whether the <code>Components</code> object is available or not in the sandbox. Default: <code>true</code>.</p>
  </dd>
  <dt>
    <code>wantXHRConstructor</code> {{ gecko_minversion_inline("16.0") }}</dt>
  <dd>
    <p>A Boolean indicating whether the <code>XMLHttpRequest</code> object is available or not in the sandbox. Default: <code>false</code>.</p>
  </dd>
</dl>
<div class="geckoVersionNote">
  <p>{{ gecko_callout_heading("2.0") }}</p>
  <p>The syntax of this constructor changed in Gecko 2.0 {{ geckoRelease("2.0") }}. Previously, the optional parameters <code>sandboxProperty</code> and <code>wantXrays</code> were passed directly to the constructor instead of being properties of the optional parameters object; they were passed directly in the order listed above.</p>
</div>
<h2 id="Methods_available_on_the_Sandbox_object">Methods available on the Sandbox object</h2>
<p style="margin-left: 40px;"><code>dump()</code> - Similar to <a class="internal" href="/en/DOM/window.dump" title="En/DOM/Window.dump">window.dump()</a>.<br />
  <code>debug()</code></p>
<p>For more information on the built-in Sandbox functions, please consult <a class="external" href="http://mxr.mozilla.org/mozilla-central/source/js/xpconnect/src/XPCComponents.cpp" title="http://mxr.mozilla.org/mozilla-central/source/js/xpconnect/src/XPCComponents.cpp">the source code</a>.</p>
<h2 id="Importing_functions_or_objects_into_the_Sandbox">Importing functions or objects into the Sandbox</h2>
<p>You can import functions or objects into the sandbox simply by assigning them to the sandbox object.&nbsp; For example:</p>
<pre>
mysandbox.doSomething = function() { ... };</pre>
<p>Obviously you still need to consider the security implications of the functions you import, but it is no longer necessary to use sandbox.importFunction() to securely import chrome functions into the Sandbox context - see <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=756514" title="https://bugzilla.mozilla.org/show_bug.cgi?id=756514">bug 756514</a> for more or the <a href="http://mxr.mozilla.org/mozilla-central/search?string=sandbox._postMessage&amp;tree=mozilla-central" title="http://mxr.mozilla.org/mozilla-central/search?string=sandbox._postMessage&amp;tree=mozilla-central">Firefox socialapi code for an example</a>.&nbsp; This technique isn't limited to functions - it can be used to import objects or values.</p>
<h2 id="See_also">See also</h2>
<ul>
  <li><a href="/en/Components.utils.evalInSandbox" title="en/Components.utils.evalInSandbox"><code>Components.utils.evalInSandbox</code></a></li>
</ul>
<p>{{ languages( { "pl": "pl/Components.utils.Sandbox" } ) }}</p>
Revert to this revision