XPConnect Chrome Object Wrappers

Introduction

Chrome Object Wrappers, or COWs for short, allow privileged code to securely expose some subset of its functionality to untrusted or semi-trusted content.

The COW is actually the final step in an epic quest to make the interaction between chrome and content as natural and secure as possible by encasing JavaScript objects in "membranes" that mediate access between their object and the outside world. Before reading the rest of this document, you should be familiar with the story so far, which is explained in detail at XPConnect wrappers.

Usage

COWs are always created automatically as necessary whenever an object passes through a trust boundary. This is in keeping with the philosophy that "the default should be secure": if writing secure code is optional, developers are burdened because they always need to remember how to write securely.

Also in keeping with this philosophy, however, is the notion that we don't want to expose chrome data or functionality to untrusted code unless the developer explicitly provides permission to do so. This is lexically enforced through the use of metadata, as will be shown shortly.

COWs in Functions

Assume the following chrome-privileged code:

const Cu = Components.utils;

function foo(obj) {
  /* Do something here that requires chrome privileges. */
}
foo.__callableByContent__ = true;

var sandbox = Cu.Sandbox("http://www.mozilla.org");
sandbox.foo = foo;
var result = Cu.evalInSandbox("foo({bar: 5});");

In the above example, foo() is wrapped by a COW when accessed by sandboxed code executed via Components.utils.evalInSandbox(). The object {bar: 5} is wrapped in an XPCSafeJSObjectWrapper before being passed into foo().

The metadata attached to foo(), __callableByContent__, is used to explicitly declare that the function its attached to can be called from content. This is necessary for security purposes; if a function that's only ever intended to be called from trusted code ever accidentally "falls into the wrong hands", we don't want untrusted code to be able to exploit it.