Security check basics

  • Revision slug: Security_check_basics
  • Revision title: Security check basics
  • Revision id: 73336
  • Created:
  • Creator: Sheppy
  • Is current revision? Yes
  • Comment minor cleanup; 14 words added, 6 words removed

Revision Content

This document outlines the basic concepts on which the Gecko security model is based.

Basic definitions

The Gecko security model is designed to answer questions of the form "Can A do V to O?" Answering such a question requires knowing something about the entity performing the action (in this case A for "actor"), the action being performed (in this case V for "verb") and the object the action is being performed on (in this case O for "object").

In Gecko, there is a limited set of verbs: "get property X", "set property X", "call function F", etc.

Both the actor and the object are represented by principals. In Gecko, these are implemented using the {{ interface("nsIPrincipal") }} interface.

Principals

A principal represents a security context. For example, on the web a typical principal is a scheme + host + port combination.

When asking the question, "Can A do V to O?", A (the entity performing the action) is called the subject principal. O (the object being operated on) is called the object principal.

Special principals

There are two special principals:

The system principal (whose contract ID is @mozilla.org/systemprincipal;1) passes all security checks. It subsumes itself and all other principals, which means it can operate on any principal, regardless of its security settings.

The null principal (whose contract ID is @mozilla.org/nullprincipal;1) fails almost all security checks. It has no privileges and can't be accessed by anything but itself and chrome. They aren't same-origin with anything but themselves.

You can create these principals using createInstance, e.g.:

var systemPrincipal = Components.classes["@mozilla.org/systemprincipal;1"]
                      .createInstance(Components.interfaces.nsIPrincipal); 

You can also get the system principal from the security manager using {{ ifmethod("nsIScriptSecurityManager", "getSystemPrincipal") }}.

Other ways to obtain principals

You can get the principal for a document using the document.nodePrincipal property.

You can get the codebase principal for a given URI using {{ ifmethod("nsIScriptSecurityManager", "getCodebasePrincipal") }}.

Determining the subject principal

When asked to perform a security check, the security manager needs to determine the current subject principal (the actor performing the action that's being security-checked). As of Gecko 1.9 the security manager asks XPConnect for the "current {{ Jsapixref("JSContext") }}" from a stack that XPConnect maintains. This JSContext has a pointer to the JavaScript callstack for the script running on it.

  • If there's no JavaScript on the stack, then the subject principal is "system" (the all-powerful principal)
  • If there's JavaScript on the stack, the stack is walked from the top down until a scripted function is encountered. There's always a principal associated with a scripted function (when you create one of those, you have to tell it who's creating it). This is the subject principal.

Determining the object principal

To determine the object principal of a particular JavaScript object, Gecko starts at that object and walks the __parent__ chain until it gets to an object that knows its own object principal (typically a Window or Document). This is then used as the object principal for the object in question.

Scripted and native JavaScript functions

In JavaScript, there are two types of {{ Jsapixref("JSFunction") }}s:

  • the first type just holds a pointer to a C function and when invoked, calls that C function, passing to it the this object it was invoked on, the arguments, etc. An example of native function is Array.sort. When called, it calls a C sorting function and passes it the Array object that sort() was called on.
  • the second type is what's called a "scripted" function, which comes about from a JavaScript function keyword or the appropriate JSAPI calls. Calling such a function executes some JavaScript in the JavaScript interpreters.

For security purposes, the main difference between the two types of functions is that scripted functions have principals compiled into them. That is, they know the principal of the page in whose context the script that defined them was executed.

Revision Source

<p>This document outlines the basic concepts on which the Gecko security model is based.</p>
<h2 id="Basic_definitions">Basic definitions</h2>
<p>The Gecko security model is designed to answer questions of the form "Can <strong>A</strong> do <strong>V</strong> to <strong>O</strong>?" Answering such a question requires knowing something about the entity performing the action (in this case <strong>A</strong> for "actor"), the action being performed (in this case <strong>V</strong> for "verb") and the object the action is being performed on (in this case <strong>O</strong> for "object").</p>
<p>In Gecko, there is a limited set of verbs: "get property X", "set property X", "call function F", etc.</p>
<p>Both the actor and the object are represented by <a href="#Principals">principals</a>. In Gecko, these are implemented using the {{ interface("nsIPrincipal") }} interface.</p>
<h3 id="Principals">Principals</h3>
<p>A <strong>principal</strong> represents a security context. For example, on the web a typical principal is a scheme + host + port combination.</p>
<p>When asking the question, "Can <strong>A</strong> do <strong>V</strong> to <strong>O</strong>?", <strong>A</strong> (the entity performing the action) is called the <strong>subject principal</strong>. <strong>O</strong> (the object being operated on) is called the <strong>object principal</strong>.</p>
<h4 id="Special_principals">Special principals</h4>
<p>There are two special principals:</p>
<p>The <strong>system principal</strong> (whose contract ID is <code>@mozilla.org/systemprincipal;1</code>) passes all security checks. It subsumes itself and all other principals, which means it can operate on any principal, regardless of its security settings.</p>
<p>The <strong>null principal</strong> (whose contract ID is <code>@mozilla.org/nullprincipal;1</code>) fails almost all security checks. It has no privileges and can't be accessed by anything but itself and chrome. They aren't same-origin with anything but themselves.</p>
<p>You can create these principals using <code>createInstance</code>, e.g.:</p>
<pre>var systemPrincipal = Components.classes["@mozilla.org/systemprincipal;1"]
                      .createInstance(Components.interfaces.nsIPrincipal); 
</pre>
<p>You can also get the system principal from the security manager using {{ ifmethod("nsIScriptSecurityManager", "getSystemPrincipal") }}.</p>
<h4 id="Other_ways_to_obtain_principals">Other ways to obtain principals</h4>
<p>You can get the principal for a document using the <a href="/en/DOM/document.nodePrincipal" title="en/DOM/document.nodePrincipal"><code>document.nodePrincipal</code></a> property.</p>
<p>You can get the codebase principal for a given URI using {{ ifmethod("nsIScriptSecurityManager", "getCodebasePrincipal") }}.</p>
<h4 id="Determining_the_subject_principal">Determining the subject principal</h4>
<p>When asked to perform a security check, the security manager needs to determine the current subject principal (the actor performing the action that's being security-checked). As of Gecko 1.9 the security manager asks XPConnect for the "current {{ Jsapixref("JSContext") }}" from a stack that XPConnect maintains. This <code>JSContext</code> has a pointer to the JavaScript callstack for the script running on it.</p>
<ul> <li>If there's no JavaScript on the stack, then the subject principal is "<strong>system</strong>" (the all-powerful principal)</li> <li>If there's JavaScript on the stack, the stack is walked from the top down until a <a href="#Scripted_and_native_JavaScript_functions"><em>scripted function</em></a> is encountered. There's always a principal associated with a scripted function (when you create one of those, you have to tell it who's creating it). This is the subject principal.</li>
</ul>
<h4 id="Determining_the_object_principal">Determining the object principal</h4>
<p>To determine the object principal of a particular JavaScript object, Gecko starts at that object and walks the <code>__parent__</code> chain until it gets to an object that knows its own object principal (typically a <code>Window</code> or <code>Document</code>). This is then used as the object principal for the object in question.</p>
<h2 id="Scripted_and_native_JavaScript_functions">Scripted and native JavaScript functions</h2>
<p>In JavaScript, there are two types of {{ Jsapixref("JSFunction") }}s:</p>
<ul> <li>the first type just holds a pointer to a C function and when invoked, calls that C function, passing to it the <code>this</code> object it was invoked on, the arguments, etc. An example of native function is <code>Array.sort</code>. When called, it calls a C sorting function and passes it the <a href="/en/JavaScript/Reference/Global_Objects/Array" title="en/JavaScript/Reference/Global Objects/Array"><code>Array</code></a> object that <code>sort()</code> was called on.</li> <li>the second type is what's called a "scripted" function, which comes about from a JavaScript <code>function</code> keyword or the appropriate JSAPI calls. Calling such a function executes some JavaScript in the JavaScript interpreters.</li>
</ul>
<p>For security purposes, the main difference between the two types of functions is that scripted functions have principals compiled into them. That is, they know the principal of the page in whose context the script that defined them was executed.</p>
Revert to this revision