diff --git a/dom/docs/index.rst b/dom/docs/index.rst index 58576df9e24d..d0586cdd16ba 100644 --- a/dom/docs/index.rst +++ b/dom/docs/index.rst @@ -8,5 +8,7 @@ These linked pages contain design documents for the DOM implementation in Gecko. ipc/index navigation/index + scriptSecurity/index + scriptSecurity/xray_vision workersAndStorage/index webIdlBindings/index diff --git a/dom/docs/scriptSecurity/index.rst b/dom/docs/scriptSecurity/index.rst index 26130258d622..3aa11eb7214e 100644 --- a/dom/docs/scriptSecurity/index.rst +++ b/dom/docs/scriptSecurity/index.rst @@ -1,5 +1,5 @@ ---- title: Script security slug: Mozilla/Gecko/Script_security tags: - -Security --- +Script Security +=============== .. container:: summary @@ -8,8 +8,9 @@ Security --- Like any web browser, Gecko can load JavaScript from untrusted and potentially hostile web pages and run it on the user's computer. The -security model for web content is based on the `same-origin -policy `__, in which code +security model for web content is based on the `same-origin policy +`__, +in which code gets full access to objects from its origin but highly restricted access to objects from a different origin. The rules for determining whether an object is same-origin with another, and what access is allowed @@ -19,8 +20,7 @@ Gecko has an additional problem, though: while its core is written in C++, the front-end code is written in JavaScript. This JavaScript code, which is commonly referred to as c\ *hrome code*, runs with system privileges. If the code is compromised, the attacker can take over the -user's computer. Legacy `SDK extensions `__ also run -with chrome privileges. +user's computer. Legacy SDK extensions also run with chrome privileges. Having the browser front end in JavaScript has benefits: it can be much quicker to develop in JavaScript than in C++, and contributors do not @@ -43,22 +43,19 @@ Gecko implements the following security policy: from *https://example.org/* can access each other, and they can also access objects served from *https://example.org/foo*. - **Objects that are cross-origin** get highly restricted access to - each other, according to the `same-origin - policy `__. + each other, according to the same-origin policy. For example, code served from *https://example.org/* trying to access objects from *https://somewhere-else.org/* will have restricted access. - **Objects in a privileged scope** are allowed complete access to objects in a less privileged scope, but by default they see a - `restricted - view `__ + `restricted view <#privileged-to-unprivileged-code>`__ of such objects, designed to prevent them from being tricked by the untrusted code. An example of this scope is chrome-privileged JavaScript accessing web content. - **Objects in a less privileged scope** don't get any access to objects in a more privileged scope, unless the more privileged scope - `explicitly clones those - objects `__. + `explicitly clones those objects <#unprivileged-to-privileged-code>`__. An example of this scope is web content accessing objects in a chrome-privileged scope.  @@ -73,14 +70,11 @@ Gecko, there's a separate compartment for every global object. This means that each global object and the objects associated with it live in their own region of memory. -.. image:: https://mdn.mozillademos.org/files/9697/compartments.png +.. image:: images/compartments.png Normal content windows are globals, of course, but so are chrome -windows, `sandboxes `__, -`workers `__, the -``ContentFrameMessageManager`` in a `frame -script `__, -and so on. +windows, sandboxes, workers, the ``ContentFrameMessageManager`` in a frame +script, and so on. Gecko guarantees that JavaScript code running in a given compartment is only allowed to access objects in the same compartment. When code from @@ -88,7 +82,7 @@ compartment A tries to access an object in compartment B, Gecko gives it a *cross-compartment wrapper*. This is a proxy in compartment A for the real object, which lives in compartment B. -.. image:: https://mdn.mozillademos.org/files/9729/cross-compartment-wrapper.png +.. image:: images/cross-compartment-wrapper.png Inside the same compartment, all objects share a global and are therefore same-origin with each other. Therefore there's no need for any @@ -123,7 +117,7 @@ pages from the same protocol, port, and domain - they belong to two different compartments, and the caller gets a *transparent wrapper* to the target object. -.. image:: https://mdn.mozillademos.org/files/9735/same-origin-wrapper.png +.. image:: images/same-origin-wrapper.png Transparent wrappers allow access to all the target's properties: functionally, it's as if the target is in the caller's compartment. @@ -136,13 +130,12 @@ Cross-origin If the two compartments are cross-origin, the caller gets a *cross-origin wrapper*. -.. image:: https://mdn.mozillademos.org/files/9731/cross-origin-wrapper.png +.. image:: images/cross-origin-wrapper.png This denies access to all the object's properties, except for a few -properties of ```Window`` `__ and -```Location`` `__ objects, as defined by +properties of Window and Location objects, as defined by the `same-origin -policy `__. +policy `__. .. _Privileged_to_unprivileged_code: @@ -151,33 +144,26 @@ Privileged to unprivileged code The most obvious example of this kind of security relation is between system-privileged chrome code and untrusted web content, but there are -other examples in Gecko. The Add-on SDK runs `content -scripts `__ in -`sandboxes `__, which are -initialized with an `expanded -principal `__, +other examples in Gecko. The Add-on SDK runs content scripts in +sandboxes, which are initialized with an `expanded +principal <#expanded-principal>`__, giving them elevated privileges with respect to the web content they operate on, but reduced privileges with respect to chrome. If the caller has a higher privilege than the target object, the caller gets an *Xray wrapper* for the object. -.. image:: https://mdn.mozillademos.org/files/9737/xray-wrapper.png +.. image:: images/xray-wrapper.png Xrays are designed to prevent untrusted code from confusing trusted code by redefining objects in unexpected ways. For example, privileged code using an Xray to a DOM object sees only the original version of the DOM -object. Any -`expando `__ -properties are not visible, and if any native DOM properties have been +object. Any expando properties are not visible, and if any native DOM properties have been redefined, they are not visible in the Xray. -The privileged code is able to `waive -Xrays `__ if it wants -unfiltered access to the untrusted object. +The privileged code is able to waive Xrays if it wants unfiltered access to the untrusted object. -See `Xray vision `__ for much more information -on Xrays. +See `Xray vision `__ for much more information on Xrays. .. _Unprivileged_to_privileged_code: @@ -187,15 +173,14 @@ Unprivileged to privileged code If the caller has lower privileges than the target object, then the caller gets an *opaque wrapper.* -.. image:: https://mdn.mozillademos.org/files/9733/opaque-wrapper.png +.. image:: images/opaque-wrapper.png An opaque wrapper denies all access to the target object. However, the privileged target is able to copy objects and functions -into the less privileged scope using the -```exportFunction()`` `__ -and ```cloneInto()`` `__ -functions, and the less privileged scope is then able to use them. +into the less privileged scope using the ``exportFunction()`` and +``cloneInto()`` functions, and the less privileged scope is then able +to use them. .. _Security_checks: @@ -255,8 +240,7 @@ System principal The system principal passes all security checks. It subsumes itself and all other principals. Chrome code, by definition, runs with the system -principal, as do `frame -scripts `__. +principal, as do frame scripts. .. _Content_principal: @@ -264,8 +248,7 @@ Content principal ^^^^^^^^^^^^^^^^^ A content principal is associated with some web content and is defined -by the -`origin `__ +by the origin of the content. For example, a normal DOM window has a content principal defined by the window's origin. A content principal subsumes only other content principals with the same origin. It is subsumed by the system @@ -300,9 +283,8 @@ disabled for web content. Expanded principals are useful when you want to give code extra privileges, including cross-origin access, but don't want to give the code full system privileges. For example, expanded principals are used -in the `Add-on SDK `__ -to give content scripts `cross-domain privileges for a predefined set of -domains `__, +in the Add-on SDK to give content scripts cross-domain privileges for a predefined set of +domains, and to protect content scripts from access by untrusted web content, without having to give content scripts system privileges. @@ -326,7 +308,7 @@ The diagram below summarizes the relationships between the different principals. The arrow connecting principals A and B means "A subsumes B".  (A is the start of the arrow, and B is the end.) -.. image:: https://mdn.mozillademos.org/files/9799/principal-relationships.png +.. image:: images/principal-relationships.png .. _Computing_a_wrapper: @@ -337,4 +319,4 @@ The following diagram shows the factors that determine the kind of wrapper that compartment A would get when trying to access an object in compartment B. -.. image:: https://mdn.mozillademos.org/files/9801/computing-a-wrapper.png +.. image:: images/computing-a-wrapper.png diff --git a/dom/docs/scriptSecurity/xray_vision.rst b/dom/docs/scriptSecurity/xray_vision.rst index 3d7e3e1af694..1036d658f57a 100644 --- a/dom/docs/scriptSecurity/xray_vision.rst +++ b/dom/docs/scriptSecurity/xray_vision.rst @@ -1,5 +1,5 @@ ---- title: Xray vision slug: Mozilla/Tech/Xray_vision tags: - Gecko - -X-Ray Vision - XPCOM --- +Xray Vision +=========== .. container:: summary @@ -19,9 +19,8 @@ variety of different privilege levels. 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 + 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. @@ -33,12 +32,11 @@ variety of different privilege levels. | 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 `__) + (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 +| 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``: @@ -105,7 +103,7 @@ Waiving Xray vision 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)`` `__, + Components.utils.waiveXrays(object), or use the object's ``wrappedJSObject`` property: .. code:: brush: @@ -127,8 +125,7 @@ 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)`` `__: +To undo the waiver again, call Components.utils.unwaiveXrays(waivedObject): .. code:: brush: @@ -141,8 +138,7 @@ To undo the waiver again, call Xrays for DOM objects --------------------- -The primary use of Xray vision is for `DOM -objects `__: that is, the +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 @@ -167,8 +163,8 @@ the C++ representation. Xrays for JavaScript objects ---------------------------- -Until recently, `built-in JavaScript objects that are not part of the -DOM `__, such as +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. @@ -210,18 +206,10 @@ 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 +- 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 @@ -256,11 +244,9 @@ the object will behave as its specification defines: .. 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 + 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 @@ -273,8 +259,7 @@ the object will behave as its specification defines: Xray semantics for Object and Array ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The exceptions are -```Object`` `__ +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". @@ -285,8 +270,7 @@ 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 `__ +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. @@ -305,8 +289,7 @@ There are two main sorts of restrictions: visible in the Xray - Second, we want to prevent the chrome code from running content code, - so functions and `accessor - properties `__ + 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 @@ -314,12 +297,9 @@ 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. + 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