JSPrincipals

This article is in need of a technical review.

Define security information for an object or script.

Properties

Name Type Description
refcount mozilla::Atomic<int32_t> Reference count. Use JS_HoldPrincipals and JS_DropPrincipals.
codebase char * Pointer to the codebase for the principal. Obsolete since JSAPI 13
getPrincipalArray void * (*)(JSContext *, JSPrincipals *) Pointer to the function that returns an array of principal definitions. Obsolete since JSAPI 12
globalPrivilegesEnabled JSBool (*)(JSContext *, JSPrincipals *) Flag indicating whether principals are enabled globally. Obsolete since JSAPI 12
destroy void (*)(JSContext *, JSPrincipals *) Pointer to the function that decrements the reference count and possibly frees the principals if they are no longer in use. Obsolete since JSAPI 13

Methods

Name Description
void dump() This is not defined by the JS engine but should be provided by the embedding. Added in SpiderMonkey 17

Description

JSPrincipals is the abstract base class of all principals objects, the objects that identify the source of a function or script and are used to determine its privileges. A principals object is like a Java CodeSource.

JSPrincipals could be passed into the JS engine through the JS_NewGlobalObject function.

JSPrincipals has refcount property that is the reference count. This is used for memory management. Each time an object is referenced, refcount must be increased by one. Each time an object is dereferenced, refcount must be decremented by one. When refcount reaches zero, the principals are no longer in use and are destroyed. Use the JS_HoldPrincipals to increment refcount, and use JS_DropPrincipals to decrement refcount.

Obsolete.

The data content of a principals object is defined by the application, which creates instances of JSPrincipals, initializes their refcount fields to 1, and passes them into the engine through the JS_...ForPrincipals functions. Some examples of security-enhanced API call are JS_CompileScriptForPrincipals, JS_CompileFunctionForPrincipals, and JS_EvaluateScriptForPrincipals. These functions ensure that the given JSPrincipals object is indelibly associated not only with the script being compiled or evaluated, but with all functions ever created by that script or code eval()-ed by it.

codebase points to the common codebase for this object or script. Only objects and scripts that share a common codebase can interact.

getPrincipalArray is a pointer to the function that retrieves the principals for this object or script.

globalPrivilegesEnabled is a flag that indicates whether principals are enabled globally.

refcount is the reference count. This is used for memory management. Each time an object is referenced, refcount must be increased by one. Each time an object is dereferenced, refcount must be decremented by one. When refcount reaches zero, the principals are no longer in use and are destroyed. Use the JSPRINCIPALS_HOLD macro to increment refcount, and use JSPRINCIPALS_DROP to decrement refcount.

See Also

Document Tags and Contributors

Contributors to this page: kscarfone, arai, fscholz, Jorend, Nickolay, MMondor, Callek, Dria
Last updated by: kscarfone,
Hide Sidebar