com.ibm.as400.security.auth

Class AS400Credential

  • java.lang.Object
    • com.ibm.as400.security.auth.AS400Credential
  • All Implemented Interfaces:
    AS400SwappableCredential, java.io.Serializable
    Direct Known Subclasses:
    ProfileHandleCredential, ProfileTokenCredential


    public abstract class AS400Credential
    extends java.lang.Object
    implements java.io.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
    • Constructor Summary

      Constructors 
      Constructor and Description
      AS400Credential()
      Constructs an AS400Credential object.
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void addCredentialListener(AS400CredentialListener listener)
      Adds a listener to receive credential events.
      void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
      Adds a PropertyChangeListener.
      void addVetoableChangeListener(java.beans.VetoableChangeListener listener)
      Adds a VetoableChangeListener.
      java.lang.String[] basicAuthenticationPrompt()
      Returns text that can be displayed to prompt for the basic user and password information used to initialize the credential.
      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.
      java.lang.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(java.beans.PropertyChangeListener listener)
      Removes the specified listener from the internal list.
      void removeVetoableChangeListener(java.beans.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

      • 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

      • addPropertyChangeListener

        public void addPropertyChangeListener(java.beans.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(java.beans.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 java.lang.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 java.lang.Throwable
        Called when garbage collection determines that there are no more references to the object.
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable - If an error occurs.
      • getAutomaticRefreshFailure

        public java.lang.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.
      • removePropertyChangeListener

        public void removePropertyChangeListener(java.beans.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(java.beans.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 java.beans.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:
        java.beans.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 java.beans.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:
        java.beans.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:
        java.lang.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()
      • swap

        public void swap()
                  throws java.lang.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:
        java.lang.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