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 |
|
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 |
|
A Content Security Policy associated with this principal. Native code only! |
domain |
|
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 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 associated with this principal. Read only. |
URI |
|
The codebase
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
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.
If the load is allowed this function does nothing. If the load is not allowed the function throws NS_ERROR_DOM_BAD_URI
.
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.
disableCapability
void disableCapability( in string capability, inout voidPtr annotation );
Parameters
-
capability
- Missing Description
-
annotation
- Missing Description
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
.
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.
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
revertCapability
void revertCapability( in string capability, inout voidPtr annotation );
Parameters
-
capability
- Missing Description
-
annotation
- Missing Description
Exceptions thrown
-
Missing Exception
- Missing Description
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.
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!
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
.