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

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

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.

See also