Magic-Mirror/gecko-dev
1
0
Fork 0
mirror of https://github.com/mozilla/gecko-dev.git synced 2024-11-24 13:21:05 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Bug 1722754 - Fix up links and formating. r=mccr8

Browse Source 
Differential Revision: https://phabricator.services.mozilla.com/D121115
This commit is contained in:
Bobby Holley 2021-07-29 15:22:45 +00:00
parent 0f3e29f15d
commit de34e147c2
3 changed files with 60 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
dom/docs/index.rst
View File

@ -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

86
dom/docs/scriptSecurity/index.rst
View File

@ -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 </en-US/docs/Web/Security/Same-origin_policy>`__, in which code
security model for web content is based on the `same-origin policy
<https://developer.mozilla.org/en-US/docs/Web/Security/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 </en-US/Add-ons/SDK>`__ 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 </en-US/docs/Web/Security/Same-origin_policy#Cross-origin_script_API_access>`__.
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 </en-US/docs/Mozilla/Gecko/Script_security#Privileged_to_unprivileged_code>`__
`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 </en-US/docs/Mozilla/Gecko/Script_security#Unprivileged_to_privileged_code>`__.
`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 </en-US/docs/Components.utils.Sandbox>`__,
`workers </en-US/docs/Web/API/Worker>`__, the
``ContentFrameMessageManager`` in a `frame
script </en-US/Firefox/Multiprocess_Firefox/Frame_script_environment>`__,
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`` </en-US/docs/Web/API/Window>`__ and
```Location`` </en-US/docs/Web/API/Location>`__ objects, as defined by
properties of Window and Location objects, as defined by
the `same-origin
policy </en-US/docs/Web/Security/Same-origin_policy#Cross-origin_script_API_access>`__.
policy <https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy#cross-origin_script_api_access>`__.
.. _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 </en-US/Add-ons/SDK/Guides/Content_Scripts>`__ in
`sandboxes </en-US/docs/Components.utils.Sandbox>`__, which are
initialized with an `expanded
principal </en-US/docs/Mozilla/Gecko/Script_security#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 <https://developer.mozilla.org/en-US/docs/Glossary/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 </en-US/docs/Components.utils.waiveXrays>`__ 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 </en-US/docs/Xray_vision>`__ for much more information
on Xrays.
See `Xray vision <xray_vision.html>`__ 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()`` </en-US/docs/Components.utils.exportFunction>`__
and ```cloneInto()`` </en-US/docs/Components.utils.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 </en-US/Firefox/Multiprocess_Firefox/Frame_script_environment>`__.
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 </en-US/docs/Web/Security/Same-origin_policy#Definition_of_an_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 <https://developer.mozilla.org/en-US/Add-ons/SDK>`__
to give content scripts `cross-domain privileges for a predefined set of
domains <https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts/Cross_Domain_Content_Scripts>`__,
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

68
dom/docs/scriptSecurity/xray_vision.rst
View File

@ -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 </en-US/docs/Components.utils.Sandbox>`__. The `security
principal </en-US/docs/Components.utils.Sandbox#Sandbox_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 </en-US/docs/Glossary/Expando>`__)
(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()`` </en-US/docs/Web/API/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)`` </en-US/docs/Components.utils.waiveXrays>`__,
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)`` </en-US/docs/Components.utils.unwaiveXrays>`__:
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 </en-US/docs/Web/API/Document_Object_Model>`__: 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 </en-US/docs/Web/JavaScript/Reference/Global_Objects>`__, 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`` </en-US/docs/Web/API/CustomEvent>`__ fired by
content could be a JavaScript
```Object`` </en-US/docs/Web/JavaScript/Reference/Global_Objects/Object>`__
or
```Date`` </en-US/docs/Web/JavaScript/Reference/Global_Objects/Date>`__
as well as a string or a primitive
- the return value of
```evalInSandbox()`` </en-US/docs/Components.utils.evalInSandbox>`__
and any properties attached to the
```Sandbox`` </en-US/docs/Components.utils.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 </en-US/docs/Tools/Scratchpad#Running_Scratchpad_in_the_browser_context>`__
for the code snippet, and the `Browser
Console </en-US/docs/Tools/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`` </en-US/docs/Web/JavaScript/Reference/Global_Objects/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 </en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty>`__
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 </en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty>`__
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 </en-US/docs/Tools/Scratchpad#Running_Scratchpad_in_the_browser_context>`__
for the code snippet, and the `Browser
Console </en-US/docs/Tools/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