Components.utils.Sandbox

  • Revision slug: Components.utils.Sandbox
  • Revision title: Components.utils.Sandbox
  • Revision id: 43056
  • Created:
  • Creator: nnethercote
  • Is current revision? No
  • Comment 23 words added

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 that contains up to three 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, 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 code outside the sandbox wants X-ray vision with respect to objects inside the sandbox. Default: true.

“X-ray vision” means exactly the same X-ray behavior that chrome code always gets, by default, when working with content DOM objects. See Safely accessing content DOM from chrome, or read on for a brief summary.

X-ray vision lets the code outside the sandbox use objects from inside the sandbox without worrying about the possibility of sandbox code changing the object in surprising ways (for example, by replacing the object's JavaScript methods). Code outside the sandbox will see right through those possibly malicious changes. When code outside the sandbox calls a method of a sandbox object, it has the standard behavior. This is more secure, so the default is true.

More technically: if wantXrays is omitted or true, then the new sandbox object is an XrayWrapper, and calls to evalInSandbox will return XrayWrappers if the sandbox has a non-chrome principal. Furthermore, if wantXrays is false and the sandboxPrototype is itself an XrayWrapper, then the underlying object it wraps is used as the actual prototype.

{{ 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.

For example, to specify a prototype:

var mySandbox = Components.utils.Sandbox("http://www.example.com/", { sandboxPrototype: protoObj });

And if you want to specify a prototype and give up the safety of x-ray vision:

var mySandbox = Components.utils.Sandbox("http://www.example.com/", { sandboxPrototype: protoObj, wantXrays: false });

Methods available on the Sandbox object

dump() - Similar to window.dump().
debug()
importFunction() - Allows for the secure importing of chrome functions into the Sandbox context.  For an example of its use, see nsProxyAutoConfig.js.

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

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>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 window ({{ interface("nsIDOMWindow") }}, such as returned by the DOM {{ domxref("window") }} property.</p>
<p>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.</p>
<p>In any case, the context you specify represents the origin for security purposes while executing the script. For example, passing a URI 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 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>Optional parameter</h3>
<p>The constructor accepts an optional parameter. This parameter is an object that contains up to three 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.  As of Gecko 13, 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 code outside the sandbox wants X-ray vision with respect to objects inside the sandbox. Default: <code>true</code>.</p> <p>“X-ray vision” means exactly the same X-ray behavior that chrome code always gets, by default, when working with content DOM objects. 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>, or read on for a brief summary.</p> <p>X-ray vision lets the code outside the sandbox use objects from inside the sandbox without worrying about the possibility of sandbox code changing the object in surprising ways (for example, by replacing the object's JavaScript methods). Code outside the sandbox will see right through those possibly malicious changes. When code outside the sandbox calls a method of a sandbox object, it has the standard behavior. This is more secure, so the default is <code>true</code>.</p> <p>More technically: if <code>wantXrays</code> is omitted or <code>true</code>, then the new sandbox object is an XrayWrapper, and calls to <code>evalInSandbox</code> will return XrayWrappers if the sandbox has a non-chrome principal. Furthermore, if <code>wantXrays</code> is <code>false</code> and the <code>sandboxPrototype</code> is itself an XrayWrapper, then the underlying object it wraps is used as the actual prototype.</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>
<p>For example, to specify a prototype:</p>
<pre>var mySandbox = Components.utils.Sandbox("<span class="plain">http://www.example.com/</span>", { sandboxPrototype: protoObj });
</pre>
<p>And if you want to specify a prototype and give up the safety of x-ray vision:</p>
<pre>var mySandbox = Components.utils.Sandbox("<span class="plain">http://www.example.com/</span>", { sandboxPrototype: protoObj, wantXrays: false });
</pre>
<h2>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><br> <code>importFunction()</code> - Allows for the secure importing of chrome functions into the Sandbox context.  For an example of its use, see <a class="external" href="http://mxr.mozilla.org/mozilla/source/netwerk/base/src/nsProxyAutoConfig.js" title="http://mxr.mozilla.org/mozilla/source/netwerk/base/src/nsProxyAutoConfig.js">nsProxyAutoConfig.js</a>.</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/src/xpconnect/src/xpccomponents.cpp" title="http://mxr.mozilla.org/mozilla-central/source/js/src/xpconnect/src/xpccomponents.cpp">the source code</a>.</p>
<h2>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