Back to index

lightning-sunbird  0.9+nobinonly
Classes | Public Types | Public Member Functions | Public Attributes | Static Public Attributes | Protected Member Functions | Protected Attributes | Static Protected Attributes
nsPrincipal Class Reference

#include <nsPrincipal.h>

Inheritance diagram for nsPrincipal:
Inheritance graph
[legend]
Collaboration diagram for nsPrincipal:
Collaboration graph
[legend]

List of all members.

Classes

struct  Certificate

Public Types

enum  AnnotationValue { AnnotationEnabled = 1, AnnotationDisabled }

Public Member Functions

 nsPrincipal ()
NS_DECL_NSIPRINCIPAL
NS_DECL_NSISERIALIZABLE
nsresult 
Init (const nsACString &aCertFingerprint, const nsACString &aSubjectName, const nsACString &aPrettyName, nsISupports *aCert, nsIURI *aCodebase)
nsresult InitFromPersistent (const char *aPrefName, const nsCString &aFingerprint, const nsCString &aSubjectName, const nsACString &aPrettyName, const char *aGrantedList, const char *aDeniedList, nsISupports *aCert, PRBool aIsCert, PRBool aTrusted)
nsresult EnsureCertData (const nsACString &aSubjectName, const nsACString &aPrettyName, nsISupports *aCert)
void SetURI (nsIURI *aURI)
nsresult SetCapability (const char *capability, void **annotation, AnnotationValue value)
void getPreferences (out string prefBranch, out string id, out string subjectName, out string grantedList, out string deniedList)
 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 read (in nsIObjectInputStream aInputStream)
 Initialize the object implementing nsISerializable, which must have been freshly constructed via CreateInstance.
void write (in nsIObjectOutputStream aOutputStream)
 Serialize the object implementing nsISerializable to aOutputStream, by writing each data member that must be recovered later to reconstitute a working replica of this object, in a canonical member and byte order, to aOutputStream.

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.

Static Public Attributes

static const char sInvalid [] = "Invalid"

Protected Member Functions

virtual ~nsPrincipal ()
nsresult SetCertificate (const nsACString &aFingerprint, const nsACString &aSubjectName, const nsACString &aPrettyName, nsISupports *aCert)

Protected Attributes

nsJSPrincipals mJSPrincipals
nsVoidArray mAnnotations
nsHashtable mCapabilities
nsCString mPrefName
nsAutoPtr< CertificatemCert
DomainPolicymSecurityPolicy
nsCOMPtr< nsIURImCodebase
nsCOMPtr< nsIURImDomain
PRPackedBool mTrusted
PRPackedBool mInitialized

Static Protected Attributes

static PRInt32 sCapabilitiesOrdinal = 0

Detailed Description

Definition at line 52 of file nsPrincipal.h.


Member Enumeration Documentation

Enumerator:
AnnotationEnabled 
AnnotationDisabled 

Definition at line 93 of file nsPrincipal.h.


Constructor & Destructor Documentation

nsPrincipal::~nsPrincipal ( void  ) [protected, virtual]

Definition at line 147 of file nsPrincipal.cpp.

{
  mAnnotations.EnumerateForwards(deleteElement, nsnull);
  SetSecurityPolicy(nsnull); 
}

Here is the call graph for this function:


Member Function Documentation

short nsIPrincipal::canEnableCapability ( in string  capability) [inherited]
void nsIPrincipal::disableCapability ( in string  capability,
inout voidPtr  annotation 
) [inherited]
void nsIPrincipal::enableCapability ( in string  capability,
inout voidPtr  annotation 
) [inherited]
nsresult nsPrincipal::EnsureCertData ( const nsACString &  aSubjectName,
const nsACString &  aPrettyName,
nsISupports *  aCert 
)

Definition at line 673 of file nsPrincipal.cpp.

{
  NS_ENSURE_STATE(mCert);

  if (!mCert->subjectName.IsEmpty() &&
      !mCert->subjectName.Equals(aSubjectName)) {
    return NS_ERROR_INVALID_ARG;
  }

  mCert->subjectName = aSubjectName;
  mCert->prettyName = aPrettyName;
  mCert->cert = aCert;
  return NS_OK;
}
boolean nsIPrincipal::equals ( in nsIPrincipal  other) [inherited]

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

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 
) [inherited]

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.

nsresult nsPrincipal::Init ( const nsACString &  aCertFingerprint,
const nsACString &  aSubjectName,
const nsACString &  aPrettyName,
nsISupports *  aCert,
nsIURI aCodebase 
)

Definition at line 105 of file nsPrincipal.cpp.

{
  NS_ENSURE_STATE(!mInitialized);
  NS_ENSURE_ARG(!aCertFingerprint.IsEmpty() || aCodebase); // better have one of these.

  mInitialized = PR_TRUE;

  mCodebase = aCodebase;

  nsresult rv;
  if (!aCertFingerprint.IsEmpty()) {
    rv = SetCertificate(aCertFingerprint, aSubjectName, aPrettyName, aCert);
    if (NS_SUCCEEDED(rv)) {
      rv = mJSPrincipals.Init(this, mCert->fingerprint.get());
    }
  }
  else {
    nsCAutoString spec;
    rv = mCodebase->GetSpec(spec);
    if (NS_SUCCEEDED(rv)) {
      rv = mJSPrincipals.Init(this, spec.get());
    }
  }

  NS_WARN_IF_FALSE(NS_SUCCEEDED(rv), "nsPrincipal::Init() failed");

  return rv;
}

Here is the call graph for this function:

nsresult nsPrincipal::InitFromPersistent ( const char *  aPrefName,
const nsCString aFingerprint,
const nsCString aSubjectName,
const nsACString &  aPrettyName,
const char *  aGrantedList,
const char *  aDeniedList,
nsISupports *  aCert,
PRBool  aIsCert,
PRBool  aTrusted 
)

Definition at line 609 of file nsPrincipal.cpp.

{
  NS_PRECONDITION(mCapabilities.Count() == 0,
                  "mCapabilities was already initialized?");
  NS_PRECONDITION(mAnnotations.Count() == 0,
                  "mAnnotations was already initialized?");
  NS_PRECONDITION(!mInitialized, "We were already initialized?");

  mInitialized = PR_TRUE;

  nsresult rv;
  if (aIsCert) {
    rv = SetCertificate(aToken, aSubjectName, aPrettyName, aCert);
    
    if (NS_FAILED(rv)) {
      return rv;
    }
  }
  else {
    rv = NS_NewURI(getter_AddRefs(mCodebase), aToken, nsnull);
    if (NS_FAILED(rv)) {
      NS_ERROR("Malformed URI in capability.principal preference.");
      return rv;
    }

    mTrusted = aTrusted;
  }

  rv = mJSPrincipals.Init(this, aToken.get());
  NS_ENSURE_SUCCESS(rv, rv);

  //-- Save the preference name
  mPrefName = aPrefName;

  const char* ordinalBegin = PL_strpbrk(aPrefName, "1234567890");
  if (ordinalBegin) {
    PRIntn n = atoi(ordinalBegin);
    if (sCapabilitiesOrdinal <= n) {
      sCapabilitiesOrdinal = n + 1;
    }
  }

  //-- Store the capabilities
  rv = NS_OK;
  if (aGrantedList) {
    rv = SetCanEnableCapability(aGrantedList, nsIPrincipal::ENABLE_GRANTED);
  }

  if (NS_SUCCEEDED(rv) && aDeniedList) {
    rv = SetCanEnableCapability(aDeniedList, nsIPrincipal::ENABLE_DENIED);
  }

  return rv;
}

Here is the call graph for this function:

boolean nsIPrincipal::isCapabilityEnabled ( in string  capability,
in voidPtr  annotation 
) [inherited]
void nsISerializable::read ( in nsIObjectInputStream  aInputStream) [inherited]

Initialize the object implementing nsISerializable, which must have been freshly constructed via CreateInstance.

All data members that can't be set to default values must have been serialized by write, and should be read from aInputStream in the same order by this method.

void nsIPrincipal::revertCapability ( in string  capability,
inout voidPtr  annotation 
) [inherited]
void nsIPrincipal::setCanEnableCapability ( in string  capability,
in short  canEnable 
) [inherited]
nsresult nsPrincipal::SetCapability ( const char *  capability,
void **  annotation,
AnnotationValue  value 
)

Definition at line 455 of file nsPrincipal.cpp.

{
  if (*annotation == nsnull) {
    *annotation = new nsHashtable(5);
    if (!*annotation) {
       return NS_ERROR_OUT_OF_MEMORY;
     }

    // This object owns its annotations. Save them so we can release
    // them when we destroy this object.
    mAnnotations.AppendElement(*annotation);
  }

  const char *start = capability;
  for(;;) {
    const char *space = PL_strchr(start, ' ');
    int len = space ? space - start : strlen(start);
    nsCAutoString capString(start, len);
    nsCStringKey key(capString);
    nsHashtable *ht = (nsHashtable *) *annotation;
    ht->Put(&key, (void *) value);
    if (!space) {
      break;
    }

    start = space + 1;
  }

  return NS_OK;
}

Here is the call graph for this function:

nsresult nsPrincipal::SetCertificate ( const nsACString &  aFingerprint,
const nsACString &  aSubjectName,
const nsACString &  aPrettyName,
nsISupports *  aCert 
) [protected]

Definition at line 511 of file nsPrincipal.cpp.

{
  NS_ENSURE_STATE(!mCert);

  if (aFingerprint.IsEmpty()) {
    return NS_ERROR_INVALID_ARG;
  }

  mCert = new Certificate(aFingerprint, aSubjectName, aPrettyName, aCert);
  if (!mCert) {
    return NS_ERROR_OUT_OF_MEMORY;
  }

  return NS_OK;
}

Here is the caller graph for this function:

Definition at line 504 of file nsPrincipal.cpp.

{
  mCodebase = aURI;
}

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.

void nsISerializable::write ( in nsIObjectOutputStream  aOutputStream) [inherited]

Serialize the object implementing nsISerializable to aOutputStream, by writing each data member that must be recovered later to reconstitute a working replica of this object, in a canonical member and byte order, to aOutputStream.

NB: a class that implements nsISerializable must also implement nsIClassInfo, in particular nsIClassInfo::GetClassID.

Here is the caller graph for this function:


Member Data Documentation

readonly attribute nsISupports nsIPrincipal::certificate [inherited]

The certificate associated with this principal, if any.

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

Definition at line 205 of file nsIPrincipal.idl.

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.

Definition at line 134 of file nsIPrincipal.idl.

const short nsIPrincipal::ENABLE_DENIED = 1 [inherited]

Values of capabilities for each principal.

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

Definition at line 62 of file nsIPrincipal.idl.

const short nsIPrincipal::ENABLE_GRANTED = 4 [inherited]

Definition at line 65 of file nsIPrincipal.idl.

const short nsIPrincipal::ENABLE_UNKNOWN = 2 [inherited]

Definition at line 63 of file nsIPrincipal.idl.

Definition at line 64 of file nsIPrincipal.idl.

readonly attribute AUTF8String nsIPrincipal::fingerprint [inherited]

The fingerprint ID of this principal's certificate.

Throws if there is no certificate associated with this principal.

Definition at line 157 of file nsIPrincipal.idl.

Whether this principal is associated with a certificate.

Definition at line 149 of file nsIPrincipal.idl.

readonly attribute unsigned long nsIPrincipal::hashValue [inherited]

Returns a hash value for the principal.

Definition at line 90 of file nsIPrincipal.idl.

Definition at line 103 of file nsPrincipal.h.

nsHashtable nsPrincipal::mCapabilities [protected]

Definition at line 104 of file nsPrincipal.h.

Definition at line 135 of file nsPrincipal.h.

Definition at line 139 of file nsPrincipal.h.

Definition at line 140 of file nsPrincipal.h.

Definition at line 142 of file nsPrincipal.h.

Definition at line 102 of file nsPrincipal.h.

Definition at line 105 of file nsPrincipal.h.

Definition at line 137 of file nsPrincipal.h.

Definition at line 141 of file nsPrincipal.h.

readonly attribute string nsIPrincipal::origin [inherited]

The origin of this principal's codebase URI.

An origin is defined as: scheme + host + port. (or the full URI for hostless schemes)

Definition at line 144 of file nsIPrincipal.idl.

readonly attribute AUTF8String nsIPrincipal::prettyName [inherited]

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.

Definition at line 168 of file nsIPrincipal.idl.

PRInt32 nsPrincipal::sCapabilitiesOrdinal = 0 [static, protected]

Definition at line 106 of file nsPrincipal.h.

The domain security policy of the principal.

Definition at line 111 of file nsIPrincipal.idl.

const char nsPrincipal::sInvalid = "Invalid" [static]

Definition at line 99 of file nsPrincipal.h.

readonly attribute AUTF8String nsIPrincipal::subjectName [inherited]

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.

Definition at line 199 of file nsIPrincipal.idl.

readonly attribute nsIURI nsIPrincipal::URI [inherited]

The codebase URI to which this principal pertains.

This is generally the document URI.

Definition at line 127 of file nsIPrincipal.idl.


The documentation for this class was generated from the following files: