JS_SetObjectPrincipalsFinder

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_SetObjectPrincipalsFinder
  • Revision title: JS_SetObjectPrincipalsFinder
  • Revision id: 138874
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment 21 words added

Revision Content

{{ deprecated_header() }}

Set the runtime-wide object-principals-finder callback. This function is deprecated. In SpiderMonkey 1.8.1 or later, use JS_SetRuntimeSecurityCallbacks instead.

Syntax

JSObjectPrincipalsFinder JS_SetObjectPrincipalsFinder(JSRuntime *rt,
                                                      JSObjectPrincipalsFinder fop);
Name Type Description
rt JSRuntime * The runtime to configure.
fop JSObjectPrincipalsFinder The new object-principals-finder callback, described below.

Callback syntax

typedef JSPrincipals * (*JSObjectPrincipalsFinder)(JSContext *cx, JSObject *obj);
Name Type Description
cx JSContext * The context in which to find principals.
obj JSObject * The object whose principals are needed.

Description

JS_SetObjectPrincipalsFinder allows the application to set a callback that the JavaScript engine uses to obtain an object's principals. The engine calls this callback to obtain principals for a JSPrincipals.subsume check.

For example, when a watchpoint triggers, the engine calls the callback, passing the watchpoint handler, to ensure that watchpoint handlers are invoked only when the watcher is permitted to watch the currently executing script.

Another example: when the Function constructor is called, the JavaScript engine calls the object principals finder callback to obtain principals for the local scope object, to check that the caller has access to that object.

The two debugger functions JS_StackFramePrincipals and JS_EvalFramePrincipals also use this callback. Since it is very common for JSObjectOps.checkAccess or JSClass.checkAccess hooks to call these functions, the object principals finder callback is a key security feature.

The callback returns a pointer to the principals associated with obj, possibly via the immutable parent chain leading from obj to a top-level container (such as a window object in the DOM). If there are no principals associated with obj, return NULL. Therefore NULL does not mean an error was reported; in no event should an error be reported or an exception be thrown by this callback's implementation.

The callback should not call JSPRINCIPALS_HOLD.

JS_SetObjectPrincipalsFinder returns the previous object-principals-finder callback.

{{ LXRSearch("ident", "i", "JS_SetObjectPrincipalsFinder") }}

Revision Source

<p>{{ deprecated_header() }}</p>
<p>Set the runtime-wide object-principals-finder callback. This function is deprecated. In SpiderMonkey 1.8.1 or later, use <a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JS_GetSecurityCallbacks" rel="internal" title="en/SpiderMonkey/JSAPI Reference/JS GetSecurityCallbacks"><code>JS_SetRuntimeSecurityCallbacks</code></a> instead.</p>
<h2 name="Syntax">Syntax</h2>
<pre class="eval">JSObjectPrincipalsFinder <strong>JS_SetObjectPrincipalsFinder</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSRuntime</a> *rt,
                                                      JSObjectPrincipalsFinder fop);
</pre>
<table class="fullwidth-table"> <tbody> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> <tr> <td><code>rt</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSRuntime</a> *</code></td> <td>The runtime to configure.</td> </tr> <tr> <td><code>fop</code></td> <td><code>JSObjectPrincipalsFinder</code></td> <td>The new object-principals-finder callback, described below.</td> </tr> </tbody>
</table>
<h2 name="Callback_syntax">Callback syntax</h2>
<pre class="eval">typedef <a href="/en/SpiderMonkey/JSAPI_Reference/JSPrincipals" title="en/JSPrincipals">JSPrincipals</a> * (*<strong>JSObjectPrincipalsFinder</strong>)(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *obj);
</pre>
<table class="fullwidth-table"> <tbody> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> <tr> <td><code>cx</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *</code></td> <td>The context in which to find principals.</td> </tr> <tr> <td><code>obj</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *</code></td> <td>The object whose principals are needed.</td> </tr> </tbody>
</table>
<h2 name="Description">Description</h2>
<p><code>JS_SetObjectPrincipalsFinder</code> allows the application to set a callback that the JavaScript engine uses to obtain an object's principals. The engine calls this callback to obtain principals for a <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSPrincipals" title="en/JSPrincipals">JSPrincipals</a>.subsume</code> check.</p>
<p>For example, when a watchpoint triggers, the engine calls the callback, passing the watchpoint handler, to ensure that watchpoint handlers are invoked only when the watcher is permitted to watch the currently executing script.</p>
<p>Another example: when the <code>Function</code> constructor is called, the JavaScript engine calls the object principals finder callback to obtain principals for the local scope object, to check that the caller has access to that object.</p>
<p>The two debugger functions <code><a href="/en/JS_StackFramePrincipals" title="en/JS_StackFramePrincipals">JS_StackFramePrincipals</a></code> and <code><a href="/en/JS_EvalFramePrincipals" title="en/JS_EvalFramePrincipals">JS_EvalFramePrincipals</a></code> also use this callback. Since it is very common for <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSObjectOps.checkAccess" title="en/JSObjectOps.checkAccess">JSObjectOps.checkAccess</a></code> or <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSClass.checkAccess" title="en/JSClass.checkAccess">JSClass.checkAccess</a></code> hooks to call these functions, the object principals finder callback is a key security feature.</p>
<p>The callback returns a pointer to the principals associated with <code>obj</code>, possibly via the immutable parent chain leading from <code>obj</code> to a top-level container (such as a <code>window</code> object in the DOM). If there are no principals associated with <code>obj</code>, return <code>NULL</code>. Therefore <code>NULL</code> does not mean an error was reported; in no event should an error be reported or an exception be thrown by this callback's implementation.</p>
<p>The callback should not call <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSPRINCIPALS_HOLD" title="en/JSPRINCIPALS_HOLD">JSPRINCIPALS_HOLD</a></code>.</p>
<p><code>JS_SetObjectPrincipalsFinder</code> returns the previous object-principals-finder callback.</p>
<p>{{ LXRSearch("ident", "i", "JS_SetObjectPrincipalsFinder") }}</p>
Revert to this revision