com.tivoli.mts
Class PDPrincipal

java.lang.Object
  |
  +--com.tivoli.mts.PDPrincipal
All Implemented Interfaces:
java.io.Externalizable, java.security.Principal, com.ibm.security.auth.PrincipalComparator, java.io.Serializable

public class PDPrincipal
extends java.lang.Object
implements java.security.Principal, com.ibm.security.auth.PrincipalComparator, java.io.Externalizable

This class implements the Principal interface and represents general information about a Policy Director user.

Principals such as this PDPrincipal may be associated with a particular Subject to augment that Subject with an additional identity. Refer to the Subject class for more information on how to achieve this. Authorization decisions can then be based upon the Principals associated with a Subject.

See Also:
Principal, Subject, Serialized Form

Constructor Summary
PDPrincipal()
          Create a PDPrincipal for an unauthenticated user.
PDPrincipal(byte[] creds, java.net.URL configURL)
          Contructs an Access Manager PDPrincipal from a String PAC.
PDPrincipal(java.lang.String name)
          Create a PDPrincipal with an identifying name.
PDPrincipal(java.lang.String name, char[] password)
          Create a PDPrincipal with an identifying name.
PDPrincipal(java.lang.String name, char[] password, java.net.URL configURL)
          Create a PDPrincipal with an identifying name and the specified configuration.
PDPrincipal(java.lang.String name, java.lang.String creds, java.net.URL configURL)
          Create a PDPrincipal with an identifying name and the supplied credentials.
PDPrincipal(java.lang.String name, java.net.URL configURL)
          Create a PDPrincipal with an identifying name and the specified configuration.
PDPrincipal(java.net.URL configURL)
          Create a PDPrincipal for an unauthenticated user with the specified configuration.
 
Method Summary
 PDPrincipal addGroupMemberships(java.lang.String serviceID, java.lang.String[] groups)
          Return a new PDPrincipal that adds these group memberships to the current PDPrincipal
 boolean equals(java.lang.Object o)
          Compares the specified Object with this PDPrincipal for equality.
 com.tivoli.mts.PDAttrs getEntitlements(java.lang.String serviceID, com.tivoli.mts.PDAttrs attrsIn)
          Return all the objects to which this PDPrincipal has the specified access
 java.lang.String getName()
          Return a string name of this PDPrincipal.
 byte[] getPAC()
          Obtain an architecture and network independent encoding of the this principal.
 int hashCode()
          Return a hash code for this PDPrincipal.
 boolean implies(PDPermission perm)
          See if the current PDPrincipal has the specified PDPermission.
 boolean implies(PDPermission perm, com.tivoli.mts.PDAttrs attrsIn, com.tivoli.mts.PDAttrs attrsOut)
          See if the current PDPrincipal has the specified PDPermission.
 boolean implies(javax.security.auth.Subject subject)
          Check if the specified Subject is implied by this object.
 void readExternal(java.io.ObjectInput in)
          Read the state of the PDPrincipal instance from a stream.
 void setConfig(java.net.URL configURL)
          Relate this PDPrincipal to an Access Manager configuration.
 java.lang.String toString()
          Return a string representation of this PDPrincipal.
 void writeExternal(java.io.ObjectOutput out)
          Save the state of the PDPrincipal instance to a stream (that is, serialize it).
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

PDPrincipal

public PDPrincipal(java.lang.String name,
                   char[] password)
            throws java.lang.NullPointerException,
                   java.lang.IllegalArgumentException,
                   java.lang.IllegalStateException
Create a PDPrincipal with an identifying name. Since no URL is specified for a configuration, the default configuration will be used.

Parameters:
name - the identifying name.

password - the password for the identifying name.

Throws:
java.lang.NullPointerException - if the name or the password is null.
java.lang.IllegalArgumentException - if the name has zero length.
java.lang.SecurityException - if the caller does not have permission to create PDPrincipals.
java.lang.IllegalStateException - if Policy Director could not obtain this user's credentials

PDPrincipal

public PDPrincipal(java.lang.String name,
                   char[] password,
                   java.net.URL configURL)
            throws java.lang.NullPointerException,
                   java.lang.IllegalArgumentException,
                   java.lang.IllegalStateException
Create a PDPrincipal with an identifying name and the specified configuration.

Parameters:
name - the identifying name.

password - the password for the identifying name.

configURL - a URL specifying the configuration to use. If null is passed, the default configuration will be used.

Throws:
java.lang.NullPointerException - if the name or the password is null.
java.lang.IllegalArgumentException - if the name has zero length.
java.lang.SecurityException - if the caller does not have permission to create PDPrincipals.
java.lang.IllegalStateException - if Policy Director could not obtain this user's credentials

PDPrincipal

public PDPrincipal(java.lang.String name)
            throws java.lang.NullPointerException,
                   java.lang.IllegalArgumentException,
                   java.lang.IllegalStateException
Create a PDPrincipal with an identifying name. Since no URL is specified for a configuration, the default configuration will be used.

Parameters:
name - the identifying name.

Throws:
java.lang.NullPointerException - if the name is null.
java.lang.IllegalArgumentException - if the name has zero length.
java.lang.SecurityException - if the caller does not have permission to create PDPrincipals.
java.lang.IllegalStateException - if Policy Director could not obtain this user's credentials

PDPrincipal

public PDPrincipal(java.lang.String name,
                   java.net.URL configURL)
            throws java.lang.NullPointerException,
                   java.lang.IllegalArgumentException,
                   java.lang.IllegalStateException
Create a PDPrincipal with an identifying name and the specified configuration.

Parameters:
name - the identifying name.

configURL - a URL specifying the configuration to use. If null is passed, the default configuration will be used.

Throws:
java.lang.NullPointerException - if the name is null.
java.lang.IllegalArgumentException - if the name has zero length.
java.lang.SecurityException - if the caller does not have permission to create PDPrincipals.
java.lang.IllegalStateException - if Policy Director could not obtain this user's credentials

PDPrincipal

public PDPrincipal()
            throws java.lang.IllegalStateException
Create a PDPrincipal for an unauthenticated user. Since no URL is specified for a configuration, the default configuration will be used.

Throws:
java.lang.IllegalStateException - if Policy Director could not obtain the "unauth" credentials

PDPrincipal

public PDPrincipal(java.net.URL configURL)
            throws java.lang.IllegalStateException
Create a PDPrincipal for an unauthenticated user with the specified configuration.
Parameters:
configURL - a URL specifying the configuration to use. If null is passed, the default configuration will be used.

Throws:
java.lang.IllegalStateException - if Policy Director could not obtain the "unauth" credentials

PDPrincipal

public PDPrincipal(byte[] creds,
                   java.net.URL configURL)
            throws java.lang.NullPointerException
Contructs an Access Manager PDPrincipal from a String PAC. The String must have been created with the getPAC() method of the Access Manager Java Authorization API or the azn_creds_get_pac() interface of Access Manager Authorization C API.
Parameters:
cred - user credential byte array in PAC format.

creds - the user credential associated with the given name.

Throws:
java.lang.NullPointerException - if the name or creds is null.

PDPrincipal

public PDPrincipal(java.lang.String name,
                   java.lang.String creds,
                   java.net.URL configURL)
            throws java.lang.NullPointerException,
                   java.lang.IllegalArgumentException,
                   java.lang.IllegalStateException
Create a PDPrincipal with an identifying name and the supplied credentials.

Parameters:
name - the identifying name.

creds - the String form of the user credential associated with the given name. This string can either be just the Base64-encoded credentials that come from azn_cred_get_pac, or the string that comes from the iv-creds HTTP header, which is currently in the form of "Version=1, b64creds". No other format will work correctly.

configURL - a URL specifying the configuration to associate with the PDPrincipal.

Throws:
java.lang.NullPointerException - if the name or creds are null.
java.lang.IllegalArgumentException - if the name has zero length, or if the configURL was invalid.
java.lang.NullPointerException - if the cred is null.
Method Detail

addGroupMemberships

public PDPrincipal addGroupMemberships(java.lang.String serviceID,
                                       java.lang.String[] groups)
                                throws java.lang.NullPointerException
Return a new PDPrincipal that adds these group memberships to the current PDPrincipal
Parameters:
serviceID - the credential modification service identifier. If null, the default credential modification service will be employed.
groups - the groups to be added to the new PDPrincipal's credentials
Returns:
a new PDPrincipal that reflects the additional group memberships
Throws:
java.lang.NullPointerException - if no groups are passed in
java.lang.IllegalStateException - on remote errors

getEntitlements

public com.tivoli.mts.PDAttrs getEntitlements(java.lang.String serviceID,
                                              com.tivoli.mts.PDAttrs attrsIn)
                                       throws java.lang.NullPointerException,
                                              java.lang.IllegalArgumentException,
                                              java.lang.IllegalStateException
Return all the objects to which this PDPrincipal has the specified access
Parameters:
serviceID - the entitlements service identifier. If null, the default entitlements service will be employed.
attrsIn - the names of objects to be reported on and the type(s) of access. The default entitlements server supports passing in multiple places in the objectspace by mechanisms like
 attrsIn.add(PDStatics.AZN_ENT_SVC_PD_POBJ_PATH, "/Management/GSO");
 attrsIn.add(PDStatics.AZN_ENT_SVC_PD_POBJ_PATH, "/Management/Policy");
 
but attempts to pass in multiple separate permissions to search on will result in an IllegalArgumentException. A single string that contains multiple permissions is acceptable. Thus,
 attrsIn.add(PDStatics.AZN_ENT_SVC_PD_POBJ_REQD_OPS, "T");
 attrsIn.add(PDStatics.AZN_ENT_SVC_PD_POBJ_REQD_OPS, "r");
 
is not currently allowed, but
 attrsIn.add(PDStatics.AZN_ENT_SVC_PD_POBJ_REQD_OPS, "Tr");
 
is permissable.
Returns:
a new PDAttrs with the objectnames and permissions for this PDPrincipal
Throws:
java.lang.NullPointerException - if no type is passed in
java.lang.IllegalArgumentException - on argument errors
java.lang.IllegalStateException - on remote errors

implies

public boolean implies(PDPermission perm)
See if the current PDPrincipal has the specified PDPermission.
Parameters:
perm - the PDPermission in question.
Returns:
true if the current PDPrincipal has the specified PDPermission and false otherwise.

implies

public boolean implies(PDPermission perm,
                       com.tivoli.mts.PDAttrs attrsIn,
                       com.tivoli.mts.PDAttrs attrsOut)
See if the current PDPrincipal has the specified PDPermission. Report any resulting attributes from the server.
Parameters:
perm - the PDPermission in question.
attrsIn - the input attribute list.
attrsOut - the output attribute list.
Returns:
true if the current PDPrincipal has the specified PDPermission and false otherwise.

getName

public java.lang.String getName()
Return a string name of this PDPrincipal.

Specified by:
getName in interface java.security.Principal
Returns:
a string name of this PDPrincipal

getPAC

public byte[] getPAC()
              throws java.lang.IllegalStateException
Obtain an architecture and network independent encoding of the this principal.
Returns:
a byte array containing the principal represented by this PDPrincipal, or null on error.

setConfig

public void setConfig(java.net.URL configURL)
Relate this PDPrincipal to an Access Manager configuration. This would be used after deserialization. When PDPrincipal objects are serialized, the config URL is remembered. When deserialization happens, we attempt to re-establish the same config file, but that may not work, as the file may have been moved, or the PDPrincipal object may now be on a different machine. This method allows the invoker to set the configuration file to be used after the deserialization of the object has completed.
Parameters:
configURL - the config URL used in SvrSslCfg
Since:
Access Manager 4.1

toString

public java.lang.String toString()
Return a string representation of this PDPrincipal.

Specified by:
toString in interface java.security.Principal
Overrides:
toString in class java.lang.Object
Returns:
a string representation of this PDPrincipal.

equals

public boolean equals(java.lang.Object o)
Compares the specified Object with this PDPrincipal for equality. Returns true if the given object is also a PDPrincipal and the two PDPrincipals have the same String representation.

Specified by:
equals in interface java.security.Principal
Overrides:
equals in class java.lang.Object
Parameters:
o - Object to be compared for equality with this PDPrincipal.
Returns:
true if the specified Object is equal to this PDPrincipal.

hashCode

public int hashCode()
Return a hash code for this PDPrincipal.

Specified by:
hashCode in interface java.security.Principal
Overrides:
hashCode in class java.lang.Object
Returns:
a hash code for this PDPrincipal.

implies

public boolean implies(javax.security.auth.Subject subject)
Check if the specified Subject is implied by this object.

Specified by:
implies in interface com.ibm.security.auth.PrincipalComparator
Parameters:
subject - a Subject to check for implication.
Returns:
true if the specified Subject is implied by this object, or false otherwise.

readExternal

public void readExternal(java.io.ObjectInput in)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException
Read the state of the PDPrincipal instance from a stream.
Specified by:
readExternal in interface java.io.Externalizable

writeExternal

public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException
Save the state of the PDPrincipal instance to a stream (that is, serialize it).
Specified by:
writeExternal in interface java.io.Externalizable