summaryrefslogtreecommitdiffstats
path: root/dom/docs/scriptSecurity/xray_vision.rst
diff options
context:
space:
mode:
Diffstat (limited to 'dom/docs/scriptSecurity/xray_vision.rst')
-rw-r--r--dom/docs/scriptSecurity/xray_vision.rst411
1 files changed, 411 insertions, 0 deletions
diff --git a/dom/docs/scriptSecurity/xray_vision.rst b/dom/docs/scriptSecurity/xray_vision.rst
new file mode 100644
index 0000000000..8a8a093201
--- /dev/null
+++ b/dom/docs/scriptSecurity/xray_vision.rst
@@ -0,0 +1,411 @@
+Xray Vision
+===========
+
+.. container:: summary
+
+ Xray vision helps JavaScript running in a privileged security context
+ safely access objects created by less privileged code, by showing the
+ caller only the native version of the objects.
+
+Gecko runs JavaScript from a variety of different sources and at a
+variety of different privilege levels.
+
+- The JavaScript code that along with the C++ core, implements the
+ browser itself is called *chrome code* and runs using system
+ privileges. If chrome-privileged code is compromised, the attacker
+ can take over the user's computer.
+- JavaScript loaded from normal web pages is called *content code*.
+ Because this code is being loaded from arbitrary web pages, it is
+ regarded as untrusted and potentially hostile, both to other websites
+ and to the user.
+- As well as these two levels of privilege, chrome code can create
+ sandboxes. The security principal defined for the sandbox determines
+ its privilege level. If an
+ Expanded Principal is used, the sandbox is granted certain privileges
+ over content code and is protected from direct access by content
+ code.
+
+| The security machinery in Gecko ensures that there's asymmetric access
+ between code at different privilege levels: so for example, content
+ code can't access objects created by chrome code, but chrome code can
+ access objects created by content.
+| However, even the ability to access content objects can be a security
+ risk for chrome code. JavaScript's a highly malleable language.
+ Scripts running in web pages can add extra properties to DOM objects
+ (also known as expando properties)
+ and even redefine standard DOM objects to do something unexpected. If
+ chrome code relies on such modified objects, it can be tricked into
+ doing things it shouldn't.
+| For example: ``window.confirm()`` is a DOM
+ API that's supposed to ask the user to confirm an action, and return a
+ boolean depending on whether they clicked "OK" or "Cancel". A web page
+ could redefine it to return ``true``:
+
+.. code:: JavaScript
+
+ window.confirm = function() {
+ return true;
+ }
+
+Any privileged code calling this function and expecting its result to
+represent user confirmation would be deceived. This would be very naive,
+of course, but there are more subtle ways in which accessing content
+objects from chrome can cause security problems.
+
+| This is the problem that Xray vision is designed to solve. When a
+ script accesses an object using Xray vision it sees only the native
+ version of the object. Any expandos are invisible, and if any
+ properties of the object have been redefined, it sees the original
+ implementation, not the redefined version.
+| So in the example above, chrome code calling the content's
+ ``window.confirm()`` would get the original version of ``confirm()``,
+ not the redefined version.
+
+.. note::
+
+ It's worth emphasizing that even if content tricks chrome into
+ running some unexpected code, that code does not run with chrome
+ privileges. So this is not a straightforward privilege escalation
+ attack, although it might lead to one if the chrome code is
+ sufficiently confused.
+
+.. _How_you_get_Xray_vision:
+
+How you get Xray vision
+-----------------------
+
+Privileged code automatically gets Xray vision whenever it accesses
+objects belonging to less-privileged code. So when chrome code accesses
+content objects, it sees them with Xray vision:
+
+.. code:: JavaScript
+
+ // chrome code
+ var transfer = gBrowser.contentWindow.confirm("Transfer all my money?");
+ // calls the native implementation
+
+.. note::
+
+ Note that using window.confirm() would be a terrible way to implement
+ a security policy, and is only shown here to illustrate how Xray
+ vision works.
+
+.. _Waiving_Xray_vision:
+
+Waiving Xray vision
+-------------------
+
+| Xray vision is a kind of security heuristic, designed to make most
+ common operations on untrusted objects simple and safe. However, there
+ are some operations for which they are too restrictive: for example,
+ if you need to see expandos on DOM objects. In cases like this you can
+ waive Xray protection, but then you can no longer rely on any
+ properties or functions being, or doing, what you expect. Any of them,
+ even setters and getters, could have been redefined by untrusted code.
+| To waive Xray vision for an object you can use
+ Components.utils.waiveXrays(object),
+ or use the object's ``wrappedJSObject`` property:
+
+.. code:: JavaScript
+
+ // chrome code
+ var waivedWindow = Components.utils.waiveXrays(gBrowser.contentWindow);
+ var transfer = waivedWindow.confirm("Transfer all my money?");
+ // calls the redefined implementation
+
+.. code:: JavaScript
+
+ // chrome code
+ var waivedWindow = gBrowser.contentWindow.wrappedJSObject;
+ var transfer = waivedWindow.confirm("Transfer all my money?");
+ // calls the redefined implementation
+
+Waivers are transitive: so if you waive Xray vision for an object, then
+you automatically waive it for all the object's properties. For example,
+``window.wrappedJSObject.document`` gets you the waived version of
+``document``.
+
+To undo the waiver again, call Components.utils.unwaiveXrays(waivedObject):
+
+.. code:: JavaScript
+
+ var unwaived = Components.utils.unwaiveXrays(waivedWindow);
+ unwaived.confirm("Transfer all my money?");
+ // calls the native implementation
+
+.. _Xrays_for_DOM_objects:
+
+Xrays for DOM objects
+---------------------
+
+The primary use of Xray vision is for DOM objects: that is, the
+objects that represent parts of the web page.
+
+In Gecko, DOM objects have a dual representation: the canonical
+representation is in C++, and this is reflected into JavaScript for the
+benefit of JavaScript code. Any modifications to these objects, such as
+adding expandos or redefining standard properties, stays in the
+JavaScript reflection and does not affect the C++ representation.
+
+The dual representation enables an elegant implementation of Xrays: the
+Xray just directly accesses the C++ representation of the original
+object, and doesn't go to the content's JavaScript reflection at all.
+Instead of filtering out modifications made by content, the Xray
+short-circuits the content completely.
+
+This also makes the semantics of Xrays for DOM objects clear: they are
+the same as the DOM specification, since that is defined using the
+`WebIDL <http://www.w3.org/TR/WebIDL/>`__, and the WebIDL also defines
+the C++ representation.
+
+.. _Xrays_for_JavaScript_objects:
+
+Xrays for JavaScript objects
+----------------------------
+
+Until recently, built-in JavaScript objects that are not part of the
+DOM, such as
+``Date``, ``Error``, and ``Object``, did not get Xray vision when
+accessed by more-privileged code.
+
+Most of the time this is not a problem: the main concern Xrays solve is
+with untrusted web content manipulating objects, and web content is
+usually working with DOM objects. For example, if content code creates a
+new ``Date`` object, it will usually be created as a property of a DOM
+object, and then it will be filtered out by the DOM Xray:
+
+.. code:: JavaScript
+
+ // content code
+
+ // redefine Date.getFullYear()
+ Date.prototype.getFullYear = function() {return 1000};
+ var date = new Date();
+
+.. code:: JavaScript
+
+ // chrome code
+
+ // contentWindow is an Xray, and date is an expando on contentWindow
+ // so date is filtered out
+ gBrowser.contentWindow.date.getFullYear()
+ // -> TypeError: gBrowser.contentWindow.date is undefined
+
+The chrome code will only even see ``date`` if it waives Xrays, and
+then, because waiving is transitive, it should expect to be vulnerable
+to redefinition:
+
+.. code:: JavaScript
+
+ // chrome code
+
+ Components.utils.waiveXrays(gBrowser.contentWindow).date.getFullYear();
+ // -> 1000
+
+However, there are some situations in which privileged code will access
+JavaScript objects that are not themselves DOM objects and are not
+properties of DOM objects. For example:
+
+- the ``detail`` property of a CustomEvent fired by content could be a JavaScript
+ Object or Date as well as a string or a primitive
+- the return value of ``evalInSandbox()`` and any properties attached to the
+ ``Sandbox`` object may be pure JavaScript objects
+
+Also, the WebIDL specifications are starting to use JavaScript types
+such as ``Date`` and ``Promise``: since WebIDL definition is the basis
+of DOM Xrays, not having Xrays for these JavaScript types starts to seem
+arbitrary.
+
+So, in Gecko 31 and 32 we've added Xray support for most JavaScript
+built-in objects.
+
+Like DOM objects, most JavaScript built-in objects have an underlying
+C++ state that is separate from their JavaScript representation, so the
+Xray implementation can go straight to the C++ state and guarantee that
+the object will behave as its specification defines:
+
+.. code:: JavaScript
+
+ // chrome code
+
+ var sandboxScript = 'Date.prototype.getFullYear = function() {return 1000};' +
+ 'var date = new Date(); ';
+
+ var sandbox = Components.utils.Sandbox("https://example.org/");
+ Components.utils.evalInSandbox(sandboxScript, sandbox);
+
+ // Date objects are Xrayed
+ console.log(sandbox.date.getFullYear());
+ // -> 2014
+
+ // But you can waive Xray vision
+ console.log(Components.utils.waiveXrays(sandbox.date).getFullYear());
+ // -> 1000
+
+.. note::
+
+ To test out examples like this, you can use the Scratchpad in
+ browser context
+ for the code snippet, and the Browser Console to see the expected
+ output.
+
+ Because code running in Scratchpad's browser context has chrome
+ privileges, any time you use it to run code, you need to understand
+ exactly what the code is doing. That includes the code samples in
+ this article.
+
+.. _Xray_semantics_for_Object_and_Array:
+
+Xray semantics for Object and Array
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The exceptions are ``Object``
+and ``Array``: their interesting state is in JavaScript, not C++. This
+means that the semantics of their Xrays have to be independently
+defined: they can't simply be defined as "the C++ representation".
+
+The aim of Xray vision is to make most common operations simple and
+safe, avoiding the need to access the underlying object except in more
+involved cases. So the semantics defined for ``Object`` and ``Array``
+Xrays aim to make it easy for privileged code to treat untrusted objects
+like simple dictionaries.
+
+Any value properties
+of the object are visible in the Xray. If the object has properties
+which are themselves objects, and these objects are same-origin with the
+content, then their value properties are visible as well.
+
+There are two main sorts of restrictions:
+
+- First, the chrome code might expect to rely on the prototype's
+ integrity, so the object's prototype is protected:
+
+ - the Xray has the standard ``Object`` or ``Array`` prototype,
+ without any modifications that content may have done to that
+ prototype. The Xray always inherits from this standard prototype,
+ even if the underlying instance has a different prototype.
+ - if a script has created a property on an object instance that
+ shadows a property on the prototype, the shadowing property is not
+ visible in the Xray
+
+- Second, we want to prevent the chrome code from running content code,
+ so functions and accessor properties
+ of the object are not visible in the Xray.
+
+These rules are demonstrated in the script below, which evaluates a
+script in a sandbox, then examines the object attached to the sandbox.
+
+.. note::
+
+ To test out examples like this, you can use the Scratchpad in
+ browser context for the code snippet, and the Browser Console
+ to see the expected output.
+
+ Because code running in Scratchpad's browser context has chrome
+ privileges, any time you use it to run code, you need to understand
+ exactly what the code is doing. That includes the code samples in
+ this article.
+
+.. code:: JavaScript
+
+ /*
+ The sandbox script:
+ * redefines Object.prototype.toSource()
+ * creates a Person() constructor that:
+ * defines a value property "firstName" using assignment
+ * defines a value property which shadows "constructor"
+ * defines a value property "address" which is a simple object
+ * defines a function fullName()
+ * using defineProperty, defines a value property on Person "lastName"
+ * using defineProperty, defines an accessor property on Person "middleName",
+ which has some unexpected accessor behavior
+ */
+
+ var sandboxScript = 'Object.prototype.toSource = function() {'+
+ ' return "not what you expected?";' +
+ '};' +
+ 'function Person() {' +
+ ' this.constructor = "not a constructor";' +
+ ' this.firstName = "Joe";' +
+ ' this.address = {"street" : "Main Street"};' +
+ ' this.fullName = function() {' +
+ ' return this.firstName + " " + this.lastName;'+
+ ' };' +
+ '};' +
+ 'var me = new Person();' +
+ 'Object.defineProperty(me, "lastName", {' +
+ ' enumerable: true,' +
+ ' configurable: true,' +
+ ' writable: true,' +
+ ' value: "Smith"' +
+ '});' +
+ 'Object.defineProperty(me, "middleName", {' +
+ ' enumerable: true,' +
+ ' configurable: true,' +
+ ' get: function() { return "wait, is this really a getter?"; }' +
+ '});';
+
+ var sandbox = Components.utils.Sandbox("https://example.org/");
+ Components.utils.evalInSandbox(sandboxScript, sandbox);
+
+ // 1) trying to access properties in the prototype that have been redefined
+ // (non-own properties) will show the original 'native' version
+ // note that functions are not included in the output
+ console.log("1) Property redefined in the prototype:");
+ console.log(sandbox.me.toSource());
+ // -> "({firstName:"Joe", address:{street:"Main Street"}, lastName:"Smith"})"
+
+ // 2) trying to access properties on the object that shadow properties
+ // on the prototype will show the original 'native' version
+ console.log("2) Property that shadows the prototype:");
+ console.log(sandbox.me.constructor);
+ // -> function()
+
+ // 3) value properties defined by assignment to this are visible:
+ console.log("3) Value property defined by assignment to this:");
+ console.log(sandbox.me.firstName);
+ // -> "Joe"
+
+ // 4) value properties defined using defineProperty are visible:
+ console.log("4) Value property defined by defineProperty");
+ console.log(sandbox.me.lastName);
+ // -> "Smith"
+
+ // 5) accessor properties are not visible
+ console.log("5) Accessor property");
+ console.log(sandbox.me.middleName);
+ // -> undefined
+
+ // 6) accessing a value property of a value-property object is fine
+ console.log("6) Value property of a value-property object");
+ console.log(sandbox.me.address.street);
+ // -> "Main Street"
+
+ // 7) functions defined on the sandbox-defined object are not visible in the Xray
+ console.log("7) Call a function defined on the object");
+ try {
+ console.log(sandbox.me.fullName());
+ }
+ catch (e) {
+ console.error(e);
+ }
+ // -> TypeError: sandbox.me.fullName is not a function
+
+ // now with waived Xrays
+ console.log("Now with waived Xrays");
+
+ console.log("1) Property redefined in the prototype:");
+ console.log(Components.utils.waiveXrays(sandbox.me).toSource());
+ // -> "not what you expected?"
+
+ console.log("2) Property that shadows the prototype:");
+ console.log(Components.utils.waiveXrays(sandbox.me).constructor);
+ // -> "not a constructor"
+
+ console.log("3) Accessor property");
+ console.log(Components.utils.waiveXrays(sandbox.me).middleName);
+ // -> "wait, is this really a getter?"
+
+ console.log("4) Call a function defined on the object");
+ console.log(Components.utils.waiveXrays(sandbox.me).fullName());
+ // -> "Joe Smith"
generated by cgit v1.2.3 (git 2.39.1) at 2024-06-07 23:21:52 +0000