nsIPrincipal Interface

[uuid(fb9ddeb9-26f9-46b8-85d5-3978aaee05aa)]

Constants

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

const short ENABLE_DENIED = 1

const short ENABLE_UNKNOWN = 2

const short ENABLE_WITH_USER_PERMISSION = 3

const short ENABLE_GRANTED = 4

Attributes

 The codebase URI to which this principal pertains.  This is
 generally the document URI.

readonly attribute nsIURI URI

 The certificate associated with this principal, if any.  If there isn't
 one, this will return null.  Getting this attribute never throws.

readonly attribute nsISupports certificate

 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.

attribute nsIURI domain

 The fingerprint ID of this principal's certificate.
 Throws if there is no certificate associated with this principal.

readonly attribute AUTF8String fingerprint

 Whether this principal is associated with a certificate.

readonly attribute boolean hasCertificate

 Returns a hash value for the principal.

readonly attribute unsigned long hashValue

 The origin of this principal's domain, if non-null, or its
 codebase URI otherwise. An origin is defined as:
 scheme + host + port.

readonly attribute string origin

 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.

readonly attribute AUTF8String prettyName

 The domain security policy of the principal.

attribute voidPtr securityPolicy

 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 AUTF8String subjectName

Methods

short canEnableCapability(in string capability)

void disableCapability(in string capability, inout voidPtr annotation)

void enableCapability(in string capability, inout voidPtr annotation)

 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)

 Returns the JS equivalent of the principal.
 @see JSPrincipals.h

JSPrincipals getJSPrincipals(in JSContext cx)

 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.

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

boolean isCapabilityEnabled(in string capability, in voidPtr annotation)

void revertCapability(in string capability, inout voidPtr annotation)

void setCanEnableCapability(in string capability, in short canEnable)

 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 subsumes itself if it is equal to itself.

 The system principal subsumes itself and all other principals except
 the non-principal.

 The non-principal is not equal to itself or any other principal, and
 therefore does not subsume 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.

boolean subsumes(in nsIPrincipal other)