Package com.ibm.as400.security.auth

Class AS400Credential

java.lang.Object

com.ibm.as400.security.auth.AS400Credential

All Implemented Interfaces:

AS400SwappableCredential, Serializable

Direct Known Subclasses:

ProfileHandleCredential, ProfileTokenCredential

public abstract class AS400Credential
extends Object
implements Serializable, AS400SwappableCredential

Provides an abstract superclass for representations of IBM i system security-related attributes.

Credentials may be used for authenticating to system services, or may simply enable certain actions to be performed.

Typical IBM i system credentials include, but are not limited to, profile tokens.

This abstract class must be subclassed to provide specific credential functions. Each subclass can contain credential data that may be security-sensitive. It is the responsibility of each class to provide appropriate access controls to sensitive data.

AS400Credential objects generate the following events:

• AS400CredentialEvent
  • CR_CREATE
  • CR_DESTROY
  • CR_REFRESH
  • CR_SWAP
• PropertyChangeEvent
• VetoableChangeEvent

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static int	CR_AUTO_REFRESH_FAILED	ID indicating that automatic refresh has failed.
static int	CR_AUTO_REFRESH_NOT_VALID	ID indicating that automatic refresh is not a valid operation.
static int	CR_AUTO_REFRESH_STARTED	ID indicating that automatic refresh is started.
static int	CR_AUTO_REFRESH_STOPPED	ID indicating that automatic refresh is stopped.
protected AS400Principal	principal_
protected AS400	system_

Constructor Summary

Constructors

Constructor	Description
AS400Credential()	Constructs an AS400Credential object.

Method Summary

Modifier and Type	Method	Description
void	addCredentialListener(AS400CredentialListener listener)	Adds a listener to receive credential events.
void	addPropertyChangeListener(PropertyChangeListener listener)	Adds a PropertyChangeListener.
void	addVetoableChangeListener(VetoableChangeListener listener)	Adds a VetoableChangeListener.
String[]	basicAuthenticationPrompt()	Returns text that can be displayed to prompt for the basic user and password information used to initialize the credential.
static void	clearArray(char[] passwordChars)	Clears out character array by inserting hexadecimal zeros.
void	destroy()	Destroys the credential by destroying or clearing sensitive information for the credential.
protected void	finalize()	Called when garbage collection determines that there are no more references to the object.
Throwable	getAutomaticRefreshFailure()	Returns the exception resulting from failure of the most recent auto-refresh attempt.
int	getAutomaticRefreshStatus()	Returns the current status of automatic refresh activity for the credential.
AS400Principal	getPrincipal()	Returns the AS400Principal associated with the credential.
AS400	getSystem()	Returns the AS400 system object for the credential.
int	getTimeToExpiration()	Returns the number of seconds before the credential is due to expire.
boolean	isCurrent()	Indicates if a timed credential is still considered valid for authenticating to associated IBM i system services or performing related actions.
boolean	isDestroyed()	Indicates if the credential has been destroyed.
boolean	isPrivate()	Indicates whether the credential is considered private.
boolean	isRenewable()	Indicates if the credential can be refreshed.
boolean	isTimed()	Indicates if the credential will expire based on time.
void	refresh()	Updates or extends the validity period for the credential.
void	removeCredentialListener(AS400CredentialListener listener)	Removes the specified listener from the internal list.
void	removePropertyChangeListener(PropertyChangeListener listener)	Removes the specified listener from the internal list.
void	removeVetoableChangeListener(VetoableChangeListener listener)	Removes the specified listener from the internal list.
void	setPrincipal(AS400Principal p)	Sets the principal associated with the credential.
void	setSystem(AS400 system)	Sets the AS400 system object for the credential.
void	startAutomaticRefresh(int refreshInterval, int maxRefreshes)	Starts automatic refresh for the credential.
void	stopAutomaticRefresh()	Stops and clears the state of any automatic refresh in progress for the credential.
void	swap()	Attempts to swap the current thread identity based on this credential.
AS400Credential	swap(boolean returnCredential)	Attempts to swap the current thread identity based on this credential.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

system_

protected AS400 system_

principal_

protected AS400Principal principal_

CR_AUTO_REFRESH_FAILED

public static final int CR_AUTO_REFRESH_FAILED

ID indicating that automatic refresh has failed.

See Also:

Constant Field Values

CR_AUTO_REFRESH_NOT_VALID

public static final int CR_AUTO_REFRESH_NOT_VALID

ID indicating that automatic refresh is not a valid operation.

See Also:

Constant Field Values

CR_AUTO_REFRESH_STARTED

public static final int CR_AUTO_REFRESH_STARTED

ID indicating that automatic refresh is started.

See Also:

Constant Field Values

CR_AUTO_REFRESH_STOPPED

public static final int CR_AUTO_REFRESH_STOPPED

ID indicating that automatic refresh is stopped.

See Also:

Constant Field Values

Constructor Detail

AS400Credential

public AS400Credential()

Constructs an AS400Credential object.

Method Detail

addCredentialListener

public void addCredentialListener(AS400CredentialListener listener)

Adds a listener to receive credential events.

Parameters:

listener - The AS400CredentialListener.

See Also:

removeCredentialListener(com.ibm.as400.security.auth.AS400CredentialListener)

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)

Adds a PropertyChangeListener.

The specified listener's propertyChange method will be called each time the value of a bound property is changed.

Parameters:

listener - The PropertyChangeListener.

See Also:

removePropertyChangeListener(java.beans.PropertyChangeListener)

addVetoableChangeListener

public void addVetoableChangeListener(VetoableChangeListener listener)

Adds a VetoableChangeListener.

The specified listener's vetoableChange method will be called each time the value of a constrained property is changed.

Parameters:

listener - The VetoableChangeListener.

See Also:

removeVetoableChangeListener(java.beans.VetoableChangeListener)

basicAuthenticationPrompt

public String[] basicAuthenticationPrompt()

Returns text that can be displayed to prompt for the basic user and password information used to initialize the credential.

Returns:

An array of two Strings. The first string is the text to prompt for the user name; the second is the text to prompt for the password.

destroy

public void destroy()
             throws AS400SecurityException

Destroys the credential by destroying or clearing sensitive information for the credential.

Throws:

AS400SecurityException - If an IBM i system security or authentication error occurs.

finalize

protected void finalize()
                 throws Throwable

Called when garbage collection determines that there are no more references to the object.

Overrides:

finalize in class Object

Throws:

Throwable - If an error occurs.

getAutomaticRefreshFailure

public Throwable getAutomaticRefreshFailure()

Returns the exception resulting from failure of the most recent auto-refresh attempt.

Available when the automatic refresh status is CR_AUTO_REFRESH_FAILED.

Returns:

The exception; null if not available.

See Also:

getAutomaticRefreshStatus()

getAutomaticRefreshStatus

public int getAutomaticRefreshStatus()

Returns the current status of automatic refresh activity for the credential.

Possible identifiers are defined as fields on this class:

• CR_AUTO_REFRESH_STARTED
• CR_AUTO_REFRESH_STOPPED
• CR_AUTO_REFRESH_FAILED
• CR_AUTO_REFRESH_NOT_VALID

Automatic refresh is not valid if the credential cannot be programmatically updated or extended, or if the associated AS400 system object is not set or not allowed to start additional threads.

If automatic refresh fails, the associated exception is available from the getAutomaticRefreshFailure() method.

Returns:

The integer identifier representing the status.

See Also:

startAutomaticRefresh(int, int), stopAutomaticRefresh(), getAutomaticRefreshFailure()

getPrincipal

public AS400Principal getPrincipal()

Returns the AS400Principal associated with the credential.

Returns:

The principal associated with the credential; null if not assigned.

getSystem

public AS400 getSystem()

Returns the AS400 system object for the credential.

Returns:

The AS400 system for the credential; null if not assigned.

getTimeToExpiration

public int getTimeToExpiration()
                        throws AS400SecurityException

Returns the number of seconds before the credential is due to expire.

Returns:

The number of seconds before expiration; zero (0) if already expired or if the credential is not identified as expiring based on time.

Throws:

AS400SecurityException - If an IBM i system security or authentication error occurs.

isCurrent

public boolean isCurrent()

Indicates if a timed credential is still considered valid for authenticating to associated IBM i system services or performing related actions.

Returns:

true if valid or not timed; false if not valid or if the operation fails.

isDestroyed

public boolean isDestroyed()

Indicates if the credential has been destroyed.

The credential is considered destroyed if the contained information is no longer sufficient to access host information for or take action against the credential.

Returns:

true if destroyed; otherwise false.

isPrivate

public boolean isPrivate()

Indicates whether the credential is considered private.

This value can be referenced by authentication services as an indication of when to check permissions or otherwise protect access to sensitive credentials.

Returns:

true if private; false if public.

isRenewable

public boolean isRenewable()

Indicates if the credential can be refreshed.

Returns:

true if the validity period of the credential can be programmatically updated or extended using refresh(); otherwise false.

See Also:

refresh()

isTimed

public boolean isTimed()

Indicates if the credential will expire based on time.

Returns:

true if the credential has been identified as expiring at the end of a predetermined time interval; otherwise false.

refresh

public void refresh()
             throws AS400SecurityException

Updates or extends the validity period for the credential.

Does nothing if the credential cannot be programmatically updated or extended.

Throws:

AS400SecurityException - If an IBM i system security or authentication error occurs.

removeCredentialListener

public void removeCredentialListener(AS400CredentialListener listener)

Removes the specified listener from the internal list.

Does nothing if the listener is not in the list.

Parameters:

listener - The AS400CredentialListener.

See Also:

addCredentialListener(com.ibm.as400.security.auth.AS400CredentialListener)

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)

Removes the specified listener from the internal list.

Does nothing if the listener is not in the list.

Parameters:

listener - The PropertyChangeListener.

See Also:

addPropertyChangeListener(java.beans.PropertyChangeListener)

removeVetoableChangeListener

public void removeVetoableChangeListener(VetoableChangeListener listener)

Removes the specified listener from the internal list.

Does nothing if the listener is not in the list.

Parameters:

listener - The VetoableChangeListener.

See Also:

addVetoableChangeListener(java.beans.VetoableChangeListener)

setPrincipal

public void setPrincipal(AS400Principal p)
                  throws PropertyVetoException

Sets the principal associated with the credential.

This property cannot be changed once a request initiates a connection for the object to the IBM i system (for example, refresh).

Parameters:

p - The principal.

Throws:

PropertyVetoException - If the change is vetoed.

ExtendedIllegalStateException - If the property cannot be changed due to the current state.

setSystem

public void setSystem(AS400 system)
               throws PropertyVetoException

Sets the AS400 system object for the credential.

This property cannot be changed once a request initiates a connection for the object to the IBM i system (for example, refresh).

Parameters:

system - The AS400 system object.

Throws:

PropertyVetoException - If the change is vetoed.

ExtendedIllegalStateException - If the property cannot be changed due to the current state.

startAutomaticRefresh

public void startAutomaticRefresh(int refreshInterval,
                                  int maxRefreshes)

Starts automatic refresh for the credential.

While this action is designed to automatically refresh the credential at the specified interval, this is subject to current workload and scheduling of the underlying Java Virtual Machine. Calling applications should take this into consideration when defining the refresh interval in relation to the credential's time to expiration, as it may not be possible to revive a credential once it has expired.

Parameters:

refreshInterval - The number of seconds between refresh attempts. The first refresh will occur immediately; the second will occur this many seconds after the first, and so on.

maxRefreshes - The maximum number of times to refresh the credential. A value of negative one (-1) indicates no maximum.

Throws:

IllegalStateException - If automatic refresh has already been started or is not a valid operation for the credential. Automatic refresh is not valid if the credential cannot be programmatically updated or extended, or if the associated AS400 system object is not allowed to start additional threads.

ExtendedIllegalArgumentException - If a parameter value is out of range.

See Also:

refresh(), getAutomaticRefreshStatus(), stopAutomaticRefresh()

stopAutomaticRefresh

public void stopAutomaticRefresh()

Stops and clears the state of any automatic refresh in progress for the credential.

Does nothing if automatic refresh is not active.

See Also:

startAutomaticRefresh(int, int), getAutomaticRefreshStatus()

swap

public void swap()
          throws Exception

Attempts to swap the current thread identity based on this credential.

No return credential is generated.

Note: This method affects the running user profile for subsequent native code invocations and any further requests against the assigned IBM i system. Any currently existing AS400 instances, even if defined for the local host and current user, are not affected if connections have been established under the old identity.

Note: swap() is supported only when running natively on IBM i. It is unsupported as a remote operation.

Specified by:

swap in interface AS400SwappableCredential

Throws:

Exception - If an exception occurs.

See Also:

Swapper

swap

public AS400Credential swap(boolean returnCredential)
                     throws AS400SecurityException

Attempts to swap the current thread identity based on this credential.

Note: This method affects the running user profile for subsequent native code invocations and any further requests against the assigned IBM i system. Any currently existing AS400 instances, even if defined for the local host and current user, are not affected if connections have been established under the old identity.

Note: swap() is supported only when running natively on IBM i. It is unsupported as a remote operation.

Parameters:

returnCredential - Indicates whether a credential should be returned that is capable of swapping back to the original thread identity. Not generating a return credential optimizes performance and avoids any potential problems in generating the return value. This parameter is ignored by credentials not supporting the ability to swap back to the original thread identity.

Returns:

A credential capable of swapping back to the original thread identity; classes not supporting this capability will return null. This value will also be null if returnCredential is false.

Throws:

AS400SecurityException - If an IBM i system security or authentication error occurs.

See Also:

Swapper

clearArray

public static void clearArray(char[] passwordChars)

Clears out character array by inserting hexadecimal zeros.

Parameters:

passwordChars - Array to be cleared.