com.tivoli.pd.jazn
Class PDPrincipal

java.lang.Object
  com.tivoli.pd.jutil.PDEnvironmentObject
      com.tivoli.pd.jazn.PDPrincipal

All Implemented Interfaces:

com.ibm.security.auth.PrincipalComparator, java.io.Externalizable, java.io.Serializable, java.security.Principal

public class PDPrincipal
extends com.tivoli.pd.jutil.PDEnvironmentObject
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.

Modes: Local,Remote

See Also:

Principal, Subject, Serialized Form

Constructor Summary

PDPrincipal()
Serialization use only.

PDPrincipal(PDAuthorizationContext ctxt)
Constructs a PDPrincipal for an unauthenticated user within the domain represented by the authorization context.

PDPrincipal(PDAuthorizationContext ctxt, byte[] creds)
Constructs an Security Access Manager PDPrincipal from a byte array PAC.

PDPrincipal(PDAuthorizationContext ctxt, java.lang.String name)
Constructs a PDPrincipal based on a userid within the domain represented by the authorization context.

PDPrincipal(PDAuthorizationContext ctxt, java.lang.String name, char[] password)
Constructs a PDPrincipal based on a userid-password authentication to the domain represented by the authorization context.

Method Summary

PDPrincipal	addAttribute(PDAuthorizationContext ctxt, java.lang.String name, PDAttrValueList values) Return a new PDPrincipal that contains the added credential attribute.
PDPrincipal	addAttrlist(PDAuthorizationContext ctxt, PDAttrs modList) Return a new PDPrincipal that contains the modified credential attribute list.
PDPrincipal	addGroupMemberships(PDAuthorizationContext ctxt, 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.
PDAttrValueList	getAttribute(PDAuthorizationContext ctxt, java.lang.String name) Return the values for a given attribute.
java.lang.String[]	getAttributeNames(PDAuthorizationContext ctxt) Return the attribute names in the credential attribute list.
java.lang.Object	getAttributeValue(PDAuthorizationContext ctxt, java.lang.String name) Return the value for a given attribute.
PDAttrs	getAttrlist(PDAuthorizationContext ctxt) Return a copy of the credential attribute list for this principal.
PDAttrs	getEntitlements(PDAuthorizationContext ctxt, java.lang.String serviceID, 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(PDAuthorizationContext ctxt) Obtain an architecture and network independent encoding of the this principal.
int	hashCode() Return a hash code for this PDPrincipal.
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.
PDPrincipal	removeAttribute(PDAuthorizationContext ctxt, java.lang.String name) Return a new PDPrincipal that does not contain the named attribute.
PDPrincipal	removeGroupMemberships(PDAuthorizationContext ctxt, java.lang.String serviceID, java.lang.String[] groups) Return a new PDPrincipal that removes these group memberships from the current PDPrincipal.
PDPrincipal	setAttribute(PDAuthorizationContext ctxt, java.lang.String name, PDAttrValueList values) Return a new PDPrincipal that contains the modified attribute.
PDPrincipal	setAttrlist(PDAuthorizationContext ctxt, PDAttrs modList) Return a new PDPrincipal that contains the modified credential attribute list.
void	setContext(PDAuthorizationContext ctxt) Set the authorization context of this PDPrincipal instance.
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 com.tivoli.pd.jutil.PDEnvironmentObject

getContext, setContext

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

PDPrincipal

public PDPrincipal(PDAuthorizationContext ctxt,
                   java.lang.String name,
                   char[] password)
            throws PDException

Constructs a PDPrincipal based on a userid-password authentication to the domain represented by the authorization context.

Parameters:

ctxt - the authorization context. The authorization context is the connection to the Security Access Manager domain.

name - the identifying name.

password - the password for the identifying name.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

PDPrincipal

public PDPrincipal(PDAuthorizationContext ctxt,
                   java.lang.String name)
            throws PDException

Constructs a PDPrincipal based on a userid within the domain represented by the authorization context.

This method requires the javax.security.auth.AuthPermission("createPDPrincipal") permission.

Parameters:

ctxt - the authorization context. The authorization context is the connection to the Security Access Manager domain.

name - the identifying name.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

PDPrincipal

public PDPrincipal(PDAuthorizationContext ctxt)
            throws PDException

Constructs a PDPrincipal for an unauthenticated user within the domain represented by the authorization context.

Parameters:

ctxt - the authorization context. The authorization context represents the connection to the Security Access Manager domain.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

PDPrincipal

public PDPrincipal(PDAuthorizationContext ctxt,
                   byte[] creds)
            throws PDException

Constructs an Security Access Manager PDPrincipal from a byte array PAC. The byte array must have been created with the PDPrincipal.getPAC() method of the Security Access Manager Authorization API for Java or the azn_creds_get_pac() interface of Security Access Manager Authorization C API.

Parameters:

ctxt - the authorization context. The authorization context represents the connection to the Security Access Manager domain.

creds - user credential byte array in PAC format.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

PDPrincipal

public PDPrincipal()
            throws PDException

Serialization use only. Constructs a PDPrincipal for use when deserializing a PDPrincipal instance. The instance cannot be used by applications.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

Method Detail

addGroupMemberships

public PDPrincipal addGroupMemberships(PDAuthorizationContext ctxt,
                                       java.lang.String serviceID,
                                       java.lang.String[] groups)
                                throws PDException

Return a new PDPrincipal that adds these group memberships to the current PDPrincipal

Parameters:

ctxt - the authorization context. The authorization context represents the connection to the Security Access Manager domain.

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:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

removeGroupMemberships

public PDPrincipal removeGroupMemberships(PDAuthorizationContext ctxt,
                                          java.lang.String serviceID,
                                          java.lang.String[] groups)
                                   throws PDException

Return a new PDPrincipal that removes these group memberships from the current PDPrincipal.

Attempting to remove an "invalid" group (i.e. the group does not exist) will fail.

Attempting to remove a "valid" group (i.e. the group does exist) that is not currently a member of this object's group memberships will not fail.

Having the same group in the groups array more than once is allowed.

Parameters:

ctxt - the authorization context. The authorization context represents the connection to the Security Access Manager domain.

serviceID - the credential modification service identifier. If null, the default credential modification service will be employed.

groups - the groups to be removed from the new PDPrincipal's credentials

Returns:

a new PDPrincipal that reflects the remaining group memberships

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

getEntitlements

public PDAttrs getEntitlements(PDAuthorizationContext ctxt,
                               java.lang.String serviceID,
                               PDAttrs attrsIn)
                        throws PDException

Return all the objects to which this PDPrincipal has the specified access. Note that this method results in a remote call to the pdacld server, irregardless of the mode.

Parameters:

ctxt - the authorization context. The authorization context represents the connection to the Security Access Manager domain.

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 permissible.

Returns:

a new PDAttrs with the objectnames and permissions for this PDPrincipal

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

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(PDAuthorizationContext ctxt)
              throws PDException

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.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

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

Throws:

java.io.IOException

java.lang.ClassNotFoundException

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

Throws:

java.io.IOException

setContext

public void setContext(PDAuthorizationContext ctxt)

Set the authorization context of this PDPrincipal instance.

Parameters:

ctxt - the PDAuthorizationContext to be set.

getAttrlist

public PDAttrs getAttrlist(PDAuthorizationContext ctxt)
                    throws PDException

Return a copy of the credential attribute list for this principal. The credential contains detailed information that describes the user, any group associations, and other security related identity attributes. It consists of attributes or name-value pairs and is represented by an attribute list PDAttrs.

Parameters:

ctxt - PDAuthorizationContext

Returns:

PDAttrs the attribute list in the credential

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

setAttrlist

public PDPrincipal setAttrlist(PDAuthorizationContext ctxt,
                               PDAttrs modList)
                        throws PDException

Return a new PDPrincipal that contains the modified credential attribute list.

Parameters:

ctxt - PDAuthorizationContext

modList - the modified attribute list. Any read-only attributes in the attrlist cannot be modified and are ignored. See PDStatics for the set of read-only attributes. Replace the existing attrlist with the modify list, except for the read-only attributes. Attribute names are not case sensitive. An empty or null modify list sets the credential attribute list with just read-only attributes.

Returns:

a new PDPrincipal that contains the modified credential attribute list. null if an error occurred.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

addAttrlist

public PDPrincipal addAttrlist(PDAuthorizationContext ctxt,
                               PDAttrs modList)
                        throws PDException

Return a new PDPrincipal that contains the modified credential attribute list.

Parameters:

ctxt - PDAuthorizationContext

modList - the modified attribute list. Any read-only attributes in the attrlist cannot be modified and are ignored. See PDStatics for the set of read-only attributes. Add the modify list to the existing list, except for the read-only attributes. Attribute names are not case sensitive.

Returns:

a new PDPrincipal that contains the modified credential attribute list. null if an error occurred.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

getAttribute

public PDAttrValueList getAttribute(PDAuthorizationContext ctxt,
                                    java.lang.String name)
                             throws PDException

Return the values for a given attribute. null if there are no values.

Parameters:

name - attribute name

Returns:

attribute values

Throws:

if - an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

PDException

setAttribute

public PDPrincipal setAttribute(PDAuthorizationContext ctxt,
                                java.lang.String name,
                                PDAttrValueList values)
                         throws PDException

Return a new PDPrincipal that contains the modified attribute. Return null if no changes were made. Use setAttrlist to change more than one attribute.

Parameters:

ctxt - PDAuthorizationContext

name - the name of the attribute to modify. If the attribute is read-only, it is ignored. If the attribute does not already exist, it is added. Otherwise, the attribute and its values are replaced. See PDStatics for the set of read-only attributes.

values - the attribute values. An empty or null values results in this attribute being removed.

Returns:

a new PDPrincipal that contains the modified attribute. null if no change was made.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

addAttribute

public PDPrincipal addAttribute(PDAuthorizationContext ctxt,
                                java.lang.String name,
                                PDAttrValueList values)
                         throws PDException

Return a new PDPrincipal that contains the added credential attribute. Use semanticist to add more than one attribute.

Parameters:

ctxt - PDAuthorizationContext

name - attribute name to add. If the attribute is read-only, it is ignored. See PDStatics for the set of read-only attributes.

values - attribute values to add

Returns:

a new PDPrincipal that contains the added attribute. null if no change was made.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

removeAttribute

public PDPrincipal removeAttribute(PDAuthorizationContext ctxt,
                                   java.lang.String name)
                            throws PDException

Return a new PDPrincipal that does not contain the named attribute.

Parameters:

ctxt - PDAuthorizationContext

name - the attribute to remove. If the attribute is read-only, it is ignored. See PDStatics for the set of read-only attributes.

Returns:

a new PDPrincipal that contains the modified credential attribute list. null if no change was made.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

getAttributeNames

public java.lang.String[] getAttributeNames(PDAuthorizationContext ctxt)
                                     throws PDException

Return the attribute names in the credential attribute list.

Parameters:

ctxt - PDAuthorizationContext

Returns:

String[] attribute names

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

getAttributeValue

public java.lang.Object getAttributeValue(PDAuthorizationContext ctxt,
                                          java.lang.String name)
                                   throws PDException

Return the value for a given attribute. Return the first value in the list if there are multiple values. Return null if there are no values.

Parameters:

name - attribute name

ctxt - PDAuthorizationContext

Returns:

Object attribute value

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.