Adding upstream version 115.8.0esr.upstream/115.8.0esr

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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"