nsIPrincipal

caps/nsIPrincipal.idlScriptable

Provides the interface to a principal, which represents a security context. On the web, for example, a typical principal is comprised of an URL scheme, host, and port.

Inherits from: nsISerializable Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

For details on principals, how they work, and how to get the appropriate one, see Security check basics.

Method overview

short canEnableCapability(in string capability); Native code only!

void checkMayLoad(in nsIURI uri, in boolean report);

void disableCapability(in string capability, inout voidPtr annotation); Native code only!

void enableCapability(in string capability, inout voidPtr annotation); Native code only!

boolean equals(in nsIPrincipal other);

JSPrincipals getJSPrincipals(in JSContext cx); Native code only!

void getPreferences(out string prefBranch, out string id, out string subjectName, out string grantedList, out string deniedList, out boolean isTrusted);

boolean isCapabilityEnabled(in string capability, in voidPtr annotation); Native code only!

void revertCapability(in string capability, inout voidPtr annotation); Native code only!

void setCanEnableCapability(in string capability, in short canEnable); Native code only!

boolean subsumes(in nsIPrincipal other);

Attributes

Attribute	Type	Description
`certificate`	`nsISupports`	The `certificate` associated with this principal, if any. If there isn't one, this will return `null`. Getting this attribute never throws. Read only.
`certificateID`	`string`	The `fingerprint` ID of this principal's `certificate`. Throws if there is no `certificate` associated with this principal. Read only. Obsolete since Gecko 1.8
`commonName`	`string`	The common name for the `certificate`. This pertains to the `certificate` authority organization. Throws if there is no `certificate` associated with this principal. Obsolete since Gecko 1.8
`csp`	`nsIContentSecurityPolicy`	A Content Security Policy associated with this principal. Native code only!
`domain`	`nsIURI`	The `domain` `URI` to which this principal pertains. This is congruent with HTMLDocument.`domain`, and may be `null`. Setting this has no effect on the `URI`. Native code only!
`fingerprint`	`AUTF8String`	The `fingerprint` ID of this principal's `certificate`. Throws if there is no `certificate` associated with this principal. Read only.
`hasCertificate`	`boolean`	Whether this principal is associated with a `certificate`. Read only.
`hashValue`	`unsigned long`	Returns a hash value for the principal. Read only. Native code only!
`origin`	`string`	The `origin` of this principal's codebase `URI`. An `origin` is defined as: scheme + host + port. Read only.
`prettyName`	`AUTF8String`	The pretty name for the `certificate`. This sort of (but not really) identifies the subject of the `certificate` (the entity that stands behind the `certificate`). Note that this may be empty; prefer to get the `certificate` itself and get this information from it, since that may provide more information. Throws if there is no `certificate` associated with this principal. Read only.
`securityPolicy`	`voidPtr`	The `domain` security policy of the principal. Native code only!
`subjectName`	`AUTF8String`	The subject name for the `certificate`. This actually identifies the subject of the `certificate`. This may well not be a string that would mean much to a typical user on its own (e.g. it may have a number of different names all concatenated together with some information on what they mean in between). Throws if there is no `certificate` associated with this principal. Read only.
`URI`	`nsIURI`	The codebase `URI` to which this principal pertains. This is generally the document `URI`. Read only. Note: This wasn't accessible by scripts prior to Gecko 2.0.

Constants

Principal capability constants

These values indicate the capabilities of a principal. The order is significant; if an operation is performed on a set of capabilities, the minimum is computed.

Constant	Value	Description
`ENABLE_DENIED`	`1`
`ENABLE_UNKNOWN`	`2`
`ENABLE_WITH_USER_PERMISSION`	`3`
`ENABLE_GRANTED`	`4`

Methods

Native code only!

canEnableCapability

short canEnableCapability(
  in string capability
);

Parameters

capability: Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception: Missing Description

Requires Gecko 1.9 (Firefox 3)

checkMayLoad()

Checks whether this principal is allowed to load the network resource located at the given URI under the same-origin policy. This means that codebase principals are only allowed to load resources from the same domain, the system principal is allowed to load anything, and null principals are not allowed to load anything.

Note: Prior to Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1), this was not available to scripts.

If the load is allowed this function does nothing. If the load is not allowed the function throws NS_ERROR_DOM_BAD_URI.

Note: Other policies might override this, such as the Access-Control specification.

Note: The 'domain' attribute has no effect on the behaviour of this function.

void checkMayLoad(
  in nsIURI uri,
  in boolean report
);

Parameters

uri: Missing Description
report: If true, will report a warning to the console service if the load is not allowed.

Exceptions thrown

NS_ERROR_DOM_BAD_URI: The load is not permitted.

Native code only!

disableCapability

void disableCapability(
  in string capability,
  inout voidPtr annotation
);

Parameters

capability: Missing Description
annotation: Missing Description

Native code only!

enableCapability

void enableCapability(
  in string capability,
  inout voidPtr annotation
);

Parameters

capability: Missing Description
annotation: Missing Description

equals()

Returns whether the other principal is equivalent to this principal. Principals are considered equal if they are the same principal, they have the same origin, or have the same certificate fingerprint ID.

boolean equals(
  in nsIPrincipal other
);

Parameters

other: The other principal to compare against.

Return value

true if the two principals are equivalent; otherwise false.

Native code only!

getJSPrincipals

Returns the JS equivalent of the principal.

JSPrincipals getJSPrincipals(
  in JSContext cx
);

Parameters

cx: Missing Description

Return value

Missing Description

getPreferences()

Returns the security preferences associated with this principal.

void getPreferences(
  out string prefBranch,
  out string id,
  out string subjectName,
  out string grantedList,
  out string deniedList,
  out boolean isTrusted
);

Parameters

prefBranch: On return, contains the preference branch to which the preferences pertain.
id: A semi-unique ID relating to either the fingerprint or the origin.
subjectName: A name identifying the entity the principal represents; this may be an empty string.
grantedList: Space-delineated list of capabilities which are explicitly granted by a preference.
deniedList: Space-delineated list of capabilities which are explicitly denied by a preference.
isTrusted: true if the certificate is a codebase trusted one.

Native code only!

isCapabilityEnabled

boolean isCapabilityEnabled(
  in string capability,
  in voidPtr annotation
);

Parameters

capability: Missing Description
annotation: Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception: Missing Description

Native code only!

revertCapability

void revertCapability(
  in string capability,
  inout voidPtr annotation
);

Parameters

capability: Missing Description
annotation: Missing Description

Exceptions thrown

Missing Exception: Missing Description

Native code only!

setCanEnableCapability

void setCanEnableCapability(
  in string capability,
  in short canEnable
);

Parameters

capability: Missing Description
canEnable: Missing Description

Exceptions thrown

Missing Exception: Missing Description

Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

subsumes()

Returns whether the other principal is equal to or weaker than this principal. Principals are equal if they are the same object, they have the same origin, or they have the same certificate ID. A principal always subsumes itself.

Note: Prior to Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1), this was not available to scripts.

The system principal subsumes itself and all other principals.

A null principal (corresponding to an unknown, hence assumed minimally privileged, security context) is not equal to any other principal (including other null principals), and therefore does not subsume anything but itself.

Both codebase and certificate principals are subsumed by the system principal, but no codebase or certificate principal yet subsumes() any other codebase or certificate principal. This may change in a future release; note that nsIPrincipal is unfrozen, not slated to be frozen.

XXXbz except see bug 147145!

Note: For the future: Perhaps we should consider a certificate principal for a given URI subsuming a codebase principal for the same URI? Not sure what the immediate benefit would be, but I think the setup could make some code (e.g. MaybeDowngradeToCodebase) clearer.

boolean subsumes(
  in nsIPrincipal other
);

Parameters

other: Missing Description

Return value

true if this principal subsumes the specified principal; otherwise false.

Method overview

Attributes

Constants

Principal capability constants

Methods

canEnableCapability

Parameters

Return value

Exceptions thrown

checkMayLoad()

Parameters

Exceptions thrown

disableCapability

Parameters

enableCapability

Parameters

equals()

Parameters

Return value

getJSPrincipals

Parameters

Return value

getPreferences()

Parameters

isCapabilityEnabled

Parameters

Return value

Exceptions thrown

revertCapability

Parameters

Exceptions thrown

setCanEnableCapability

Parameters

Exceptions thrown

subsumes()

Parameters

Return value

See also

Document Tags and Contributors