Public Member Functions | Public Attributes

nsIPrincipal Interface Reference

import "nsIPrincipal.idl";

Inheritance diagram for nsIPrincipal:
Collaboration diagram for nsIPrincipal:

List of all members.

Public Member Functions

void getPreferences (out string prefBranch, out string id, out string subjectName, out string grantedList, out string deniedList, out boolean isTrusted)
 Returns the security preferences associated with this principal.
boolean equals (in nsIPrincipal other)
 Returns whether the other principal is equivalent to this principal.
JSPrincipals getJSPrincipals (in JSContext cx)
 Returns the JS equivalent of the principal.
short canEnableCapability (in string capability)
void setCanEnableCapability (in string capability, in short canEnable)
boolean isCapabilityEnabled (in string capability, in voidPtr annotation)
void enableCapability (in string capability, inout voidPtr annotation)
void revertCapability (in string capability, inout voidPtr annotation)
void disableCapability (in string capability, inout voidPtr annotation)
boolean subsumes (in nsIPrincipal other)
 Returns whether the other principal is equal to or weaker than this principal.
void checkMayLoad (in nsIURI uri, in boolean report)
 Checks whether this principal is allowed to load the network resource located at the given URI under the same-origin policy.

Public Attributes

const short ENABLE_DENIED = 1
 Values of capabilities for each principal.
const short ENABLE_UNKNOWN = 2
const short ENABLE_WITH_USER_PERMISSION = 3
const short ENABLE_GRANTED = 4
readonly attribute unsigned long hashValue
 Returns a hash value for the principal.
attribute voidPtr securityPolicy
 The domain security policy of the principal.
readonly attribute nsIURI URI
 The codebase URI to which this principal pertains.
attribute nsIURI domain
 The domain URI to which this principal pertains.
readonly attribute string origin
 The origin of this principal's codebase URI.
readonly attribute boolean hasCertificate
 Whether this principal is associated with a certificate.
readonly attribute AUTF8String fingerprint
 The fingerprint ID of this principal's certificate.
readonly attribute AUTF8String prettyName
 The pretty name for the certificate.
readonly attribute AUTF8String subjectName
 The subject name for the certificate.
readonly attribute nsISupports certificate
 The certificate associated with this principal, if any.
attribute nsIContentSecurityPolicy csp
 A Content Security Policy associated with this principal.

Member Function Documentation

short nsIPrincipal::canEnableCapability ( in string  capability  ) 
void nsIPrincipal::checkMayLoad ( in nsIURI  uri,
in boolean  report 
)

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.

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.

Parameters:
uri The URI about to be loaded.
report If true, will report a warning to the console service if the load is not allowed.
Exceptions:
NS_ERROR_DOM_BAD_URI if the load is not allowed.
void nsIPrincipal::disableCapability ( in string  capability,
inout voidPtr  annotation 
)
void nsIPrincipal::enableCapability ( in string  capability,
inout voidPtr  annotation 
)
boolean nsIPrincipal::equals ( in nsIPrincipal  other  ) 

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

JSPrincipals nsIPrincipal::getJSPrincipals ( in JSContext  cx  ) 

Returns the JS equivalent of the principal.

See also:
JSPrincipals.h
void nsIPrincipal::getPreferences ( out string  prefBranch,
out string  id,
out string  subjectName,
out string  grantedList,
out string  deniedList,
out boolean  isTrusted 
)

Returns the security preferences associated with this principal.

prefBranch will be set to the pref branch to which these preferences pertain. id is a pseudo-unique identifier, pertaining to either the fingerprint or the origin. subjectName is a name that identifies the entity this principal represents (may be empty). grantedList and deniedList are space-separated lists of capabilities which were explicitly granted or denied by a pref. isTrusted is a boolean that indicates whether this is a codebaseTrusted certificate.

boolean nsIPrincipal::isCapabilityEnabled ( in string  capability,
in voidPtr  annotation 
)
void nsIPrincipal::revertCapability ( in string  capability,
inout voidPtr  annotation 
)
void nsIPrincipal::setCanEnableCapability ( in string  capability,
in short  canEnable 
)
boolean nsIPrincipal::subsumes ( in nsIPrincipal  other  ) 

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.

Thus 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!

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.


Member Data Documentation

The certificate associated with this principal, if any.

If there isn't one, this will return null. Getting this attribute never throws.

A Content Security Policy associated with this principal.

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.

const short nsIPrincipal::ENABLE_DENIED = 1

Values of capabilities for each principal.

Order is significant: if an operation is performed on a set of capabilities, the minimum is computed.

readonly attribute AUTF8String nsIPrincipal::fingerprint

The fingerprint ID of this principal's certificate.

Throws if there is no certificate associated with this principal.

Whether this principal is associated with a certificate.

readonly attribute unsigned long nsIPrincipal::hashValue

Returns a hash value for the principal.

readonly attribute string nsIPrincipal::origin

The origin of this principal's codebase URI.

An origin is defined as: scheme + host + port.

readonly attribute AUTF8String nsIPrincipal::prettyName

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.

attribute voidPtr nsIPrincipal::securityPolicy

The domain security policy of the principal.

readonly attribute AUTF8String nsIPrincipal::subjectName

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.

readonly attribute nsIURI nsIPrincipal::URI

The codebase URI to which this principal pertains.

This is generally the document URI.


The documentation for this interface was generated from the following file: