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

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

• Security check basics