mozilla

Revision 43047 of Components.utils.Sandbox

  • Revision slug: Components.utils.Sandbox
  • Revision title: Components.utils.Sandbox
  • Revision id: 43047
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment one or more formatting changes

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.

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 two optional properties:

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.  The (By X-ray vision we mean exactly the same X-ray behavior that chrome code always gets, by default, when working wit 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 a sandbox JavaScript changing the object in surprising ways (for example, by replacing the object's JS 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 the raw JS object).  Furthermore, if wantXrays is true.

{{ gecko_callout_heading("2.0") }}

The syntax of this constructor changed in Gecko 2.0 {{ geckoRelease("2.0") }}. Previously, the optional parameters 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.</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 two optional properties:</p>
<dl> <dt><code>sandboxPrototype</code></dt> <dd>A prototype object for the sandbox. The sandbox will inherit the contents of this object if it's provided.</dd> <dt><code>wantXrays</code></dt> <dd>A Boolean value indicating whether code outside the sandbox wants X-ray vision with respect to objects inside the sandbox.  The (By X-ray vision we mean exactly the same X-ray behavior that chrome code always gets, by default, when working wit 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.) X-ray vision lets the code outside the sandbox use objects from inside the sandbox without worrying about the possibility of a sandbox JavaScript changing the object in surprising ways (for example, by replacing the object's JS 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 the raw JS object).  Furthermore, if wantXrays is <code>true</code>.</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 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