XPCNativeWrapper: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
No edit summary
Line 6: Line 6:
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.
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.


===Prelude===
===Prerequisite===
Before using XPCNativeWrapper, you need to import/reference the script to make it available for scripting. In your main XUL page or [[overlay]] page, add the following to the top of the page. For Firefox, add:
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, add:
<pre>
<pre>
<script type="application/x-javascript" src="chrome://global/content/XPCNativeWrapper.js"/>
<script type="application/x-javascript" src="chrome://global/content/XPCNativeWrapper.js"/>
Line 23: Line 25:
</pre>
</pre>


Notice how the desired properties are specified by their name and the desired methods are specified by their name followed a pair of empty brackets. The returned object can be used just like the untrusted object. Methods and properties can be called from it directly:
Notice how the desired properties are specified by their name and the desired methods are specified by their name followed by a pair of empty brackets. The returned object can be used just like the untrusted object in that methods and properties can be called on it directly:
<pre>
<pre>
var tt = doc2.title;
var tt = doc2.title;
var bd = doc2.getElementsByTagName('body')[0];
var bd = doc2.getElementsByTagName('body')[0];
</pre>
</pre>
====Careful====
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==
==Attack Scenarios==
To illustrate the importance of using XPCNativeWrapper, consider the following scenarios:
To illustrate the importance of using XPCNativeWrapper for security, consider the following scenarios:


===Scenario 1===
===Scenario 1===
An extension is written to modify the title property of the document.
Privileged code tries to modify the title property of the document:
<pre>
<pre>
document._content.document.title = 'Hello World';
document._content.document.title = 'Hello World';
Line 45: Line 50:


===Scenario 2===
===Scenario 2===
The same analogy applies to calling methods on an untrusted object. Consider an extension that tries to get access to the body element of a document.
The same analogy applies to calling methods on an untrusted object. Consider the case where privileged code tries to get access to the body element of a document.
<pre>
<pre>
var bd = document._content.document.getElementsByTagName('body')[0];
var bd = document._content.document.getElementsByTagName('body')[0];

Revision as of 10:14, 22 March 2005

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 is analogous to a sandbox.

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.

Prerequisite

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, 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"/>

Example

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

doc = window._content;
doc2 = new XPCNativeWrapper(doc, 'title', 'getElementsByTagName()');

Notice how the desired properties are specified by their name and the desired methods are specified by their name followed by a pair of empty brackets. The returned object can be used just like the untrusted object in that methods and properties can be called on it directly:

var tt = doc2.title;
var bd = doc2.getElementsByTagName('body')[0];

Careful

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 the importance of using XPCNativeWrapper for security, consider the following scenarios:

Scenario 1

Privileged code tries to modify the title property of the document:

document._content.document.title = 'Hello World';

On the surface it looks harmless enough. However, an attacker could execute malicious code if they added a getter to the title property:

document.title getter = function() {
  alert('code executed');  //malicious code...
};

Scenario 2

The same analogy applies to calling methods on an untrusted object. Consider the case where privileged code tries to get access to the body element of a document.

var bd = document._content.document.getElementsByTagName('body')[0];

It may also look harmless, but an attacker could execute malicious code if they overwrote the getElementsByTagName method with another:

document.getElementsByTagName = function() {
  alert('code executed');  //malicious code...
};

References

  1. XPCNativeWrapper.js