From MozillaZine Knowledge Base

This page is part of the extension development documentation project.

Ask your questions in MozillaZine Forums. Also try browsing example code.

Note: development documentation is in process of being moved to Mozilla Development Center (MDC).

XPCNativeWrapper is a JavaScript object that should be used whenever privileged code is used to access unprivileged code. It is used to create a security wrapper that guarantees that the "native" methods/properties of an object will be called (and not the methods overriden by the webpage).

Note: This is supposed to be fixed in Firefox 1.0.3, Mozilla Suite 1.7.7 and future versions. However extensions that are compatible with previous versions of Firefox or Mozilla Suite should still be using XPCNativeWrapper.


Basic Usage

Using XPCNativeWrapper is very simple. You create an instance of XPCNativeWrapper with the untrusted object as the first parameter and the desired properties and methods of the untrusted object as the additional parameters.


Before using XPCNativeWrapper, you need to import/reference the script file to make it available. In your main XUL page or overlay page, add the following to the top of the page.

For Firefox or Thunderbird, add:

<script type="application/x-javascript" src="chrome://global/content/XPCNativeWrapper.js"/>

For the Mozilla Suite, add:

<script type="application/x-javascript" src="chrome://communicator/content/XPCNativeWrapper.js"/>


This example creates a wrapper around the document object so that it can safely modify the title of the document and call one of its methods:

var contentWrapper = new XPCNativeWrapper(window._content, 'doc');
var docWrapper = new XPCNativeWrapper(contentWrapper.document, 'title', 'write()');

Notice how the desired properties are specified by their name only and the desired methods are specified by their name followed by a pair of empty brackets. Each property or method should be specified in its own separate parameter. The returned object can then be used just like the untrusted object, in that methods and properties can be called on it directly:

docWrapper.title = s;


In most cases, XPCNativeWrapper can be used effortlessly and without much modification to existing code. However one area to beware of is when using a wrapped object with the instanceof check and typeof check. Wrapped objects are no longer instances of the untrusted object and may also be of a different type.

Attack Scenarios

To illustrate how using XPCNativeWrapper can improve security, consider the following two scenarios:

Scenario 1

Certain chrome code wants to read the selection on the content page. It does the following:

var text = window._content.getSelection().toString();

On the surface it looks correct. However, webpage may declare its own getSelection method, returning wrong string or running arbitrary code, albeit without chrome privileges:

function getSelection() {
  return "You can't read the selection on this page!";

Scenario 2

In earlier versions of Mozilla it was possible to redefine a method with an eval, which could lead to execution of malcious code with elevated priviledges [1]. For example, consider this chrome code:

doc = window._content.document;

It may also look harmless, but an attacker could execute malicious code if they overwrote the appendChild and createElement methods with their own methods:

document.createElement = function() {
  return "alert('code executed');";
document.appendChild = eval;