Package com.ibm.as400.security.auth

Class ProfileTokenCredential

java.lang.Object

com.ibm.as400.security.auth.AS400Credential

com.ibm.as400.security.auth.ProfileTokenCredential

All Implemented Interfaces:

AS400BasicAuthenticationCredential, AS400SwappableCredential, Serializable

public final class ProfileTokenCredential
extends AS400Credential
implements AS400BasicAuthenticationCredential

The ProfileTokenCredential class represents an IBM i system profile token.

A profile token provides a timed credential representing an authenticated system user profile and password. A profile token can be established in either a remote (not running on the target system) or local (running on the target system) context. Once created, it may be serialized or distributed as required by the application.

When referenced from a running process on the associated IBM i system, a profile token can be used to modify or swap the thread identity and perform a specific task or tasks on behalf of the authenticated user. However, a profile token generated on one IBM i system cannot be used to swap thread identity on any other system.

An application of this support would be in a single tier application running on the system when a designated operation must be run under the system authorities and permissions of a specific user profile. A profile token can be used to swap identity prior to performing the operation. Support is also provided to swap back to the original identity upon completion.

Another application of this support might be in a two tier application, with authentication of a user profile and password being performed by a graphical user interface on the first tier (i.e. a PC) and work being performed for that user on the second tier (the IBM i system). By utilizing ProfileTokenCredentials, the application can avoid directly passing the user ID and password over the network. The profile token can be distributed as required to the program on the second tier, which can perform the swap() and run designated operations under the system authorities and permissions assigned to the user.

Note: While inherently more secure than passing a user profile and password due to limited life span, profile tokens should still be considered sensitive information by the application and handled accordingly. Since the token represents an authenticated user and password, it could potentially be exploited by a hostile application to perform work on behalf of that user. It is ultimately the responsibility of the application to ensure that credentials are accessed in a secure manner.

Profile tokens are only supported for IBM i systems at release V4R5M0 or greater.

The following example demonstrates the use of a ProfileTokenCredential when run on the local IBM i system. (Note: swap() is an unsupported remote operation.)

 // Prepare to work with the local IBM i system.
 AS400 system = new AS400("localhost", "*CURRENT", "*CURRENT");

 // Create a single-use ProfileTokenCredential with a 60 second timeout.
 // A valid user ID and password must be substituted.
 ProfileTokenCredential pt = new ProfileTokenCredential();
 pt.setSystem(system);
 pt.setTimeoutInterval(60);
 pt.setTokenType(ProfileTokenCredential.TYPE_SINGLE_USE);
 pt.setTokenExtended("USERID", "PASSWORD");

 // Swap the thread identity, retrieving a credential to
 // later swap back to the original identity.
 AS400Credential cr = pt.swap(true);

 // Perform work under the swapped identity at this point.
 // Newly-connected AS400 objects will run under the new (swapped-to) identity.
 AS400 swapped = new AS400("localhost", "*CURRENT", "*CURRENT");

 // Swap back to the original thread identity.
 cr.swap();

 // Clean up the credentials.
 cr.destroy();
 pt.destroy();
 

General restrictions:

• Creating a token updates the last-used date for the associated user and group profiles.
• Creating a token resets the 'signon attempts not valid' count to zero for the user profile.
• If security-related events are being audited, creating a token adds an entry to the AUDJRN audit journal.
• The maximum number of profile tokens that can be generated is approximately 2,000,000; after that, the space to store them is full. Message CPF4AAA is sent to the caller, and no more profile tokens can be generated until one is removed.
• You cannot obtain a profile token for the following system-supplied user profiles:
  • QAUTPROF
  • QFNC
  • QNETSPLF
  • QSPLJOB
  • QDBSHR
  • QGATE
  • QNFSANON
  • QSYS
  • QDFTOWN
  • QLPAUTO
  • QRJE
  • QTCP
  • QDIRSRV
  • QLPINSTALL
  • QSNADS
  • QTFTP
  • QDOC
  • QMSF
  • QSPL
  • QTSTRQS
  • QDSNX

Guidelines and restrictions for generating profile tokens based on a specified user profile name and password:

• On level 10 systems, only the user ID is validated because no passwords are required.
• If a provided password is not correct, the incorrect password count for the user profile is increased. (The QMAXSIGN system value contains the maximum number of incorrect attempts to sign on.)
• If the QMAXSGNACN system value is set to disable user profiles, repeated attempts to validate an incorrect password disables the user ID. This keeps applications from methodically determining user passwords.
• Considerations when specifying a password of *NOPWD or *NOPWDCHK:
  • To obtain a profile token for a profile that does not have a password, specify *NOPWD or *NOPWDCHK for the password parameter.
  • The user requesting the profile token must have *USE authority to the user profile.
  • *NOPWD is not allowed if the user profile name is the name of the currently running user profile.
  • If the password is *NOPWDCHK and the user requesting the profile token has *ALLOBJ and *SECADM special authorities, a profile token will be generated even when the status of the profile is disabled or its password is expired.
  • No profile token is created in the following situations:
    • The user profile is disabled and *NOPWDCHK is not specified for the password parameter, or *NOPWDCHK was specified but the user requesting the profile token does not have *ALLOBJ or *SECADM special authority.
    • The password is expired and *NOPWDCHK is not specified for the password parameter, or *NOPWDCHK was specified but the user requesting the profile token does not have *ALLOBJ or *SECADM special authority.
    • The password is *NONE, and *NOPWD or *NOPWDCHK is not specified for the password parameter.

See Also:

AS400Credential, Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static int	CREATOR_NATIVE_API	ID indicating the creator of token is a native API
static int	CREATOR_SIGNON_SERVER	ID indicating the creator of token the file server
static int	CREATOR_UNKNOWN	ID indicating the creator of token is not known
static String	DEFAULT_VERIFICATION_ID	Default verification ID that is used when generating a profile token is "QIBM_OS400_JT400".
static int	MAX_ADDITIONALAUTHENTICATIONFACTOR_LENGTH	Maximum length of additional authentication factor
static int	MAX_IPADDRESS_LENGTH	Maximum length of IP address.
static int	MAX_VERIFICATIONID_LENGTH	Maximum length of verification ID.
static int	PW_NOPWD	Password special value indicating that the current password is not verified.
static int	PW_NOPWDCHK	Password special value indicating that a profile token can be generated for a profile that is disabled or has an expired password.
static int	TOKEN_LENGTH	Indicates the length of a profile token (in bytes)
static int	TYPE_MULTIPLE_USE_NON_RENEWABLE	ID indicating a multiple use token that cannot be regenerated.
static int	TYPE_MULTIPLE_USE_RENEWABLE	ID indicating a multiple use token that can be regenerated.
static int	TYPE_SINGLE_USE	ID indicating a single use token.

Fields inherited from class com.ibm.as400.security.auth.AS400Credential

CR_AUTO_REFRESH_FAILED, CR_AUTO_REFRESH_NOT_VALID, CR_AUTO_REFRESH_STARTED, CR_AUTO_REFRESH_STOPPED, principal_, system_

Constructor Summary

Constructors

Constructor	Description
ProfileTokenCredential()	Constructs a ProfileTokenCredential object.
ProfileTokenCredential(AS400 system, byte[] token, int tokenType, int timeoutInterval)	Constructs and initializes a ProfileTokenCredential object.
ProfileTokenCredential(AS400 system, byte[] token, int tokenType, int timeoutInterval, String verificationID, String remoteIPAddress, int remotePort, String localIPAddress, int localPort)	Constructs and initializes a ProfileTokenCredential object.

Method Summary

Modifier and Type	Method	Description
void	allowRefresh()	Notify the wait thread to refresh profile token credential.
boolean	equals(Object o)	Compares the specified Object with the credential for equality.
int	getAuthenticationIndicator()	Returns the authentication indicator.
ProfileTokenEnhancedInfo	getEnhancedInfo()
String	getLocalIPAddress()	Returns the local IP address associated with the profile token.
int	getLocalPort()	Returns the local port of the network connection associated with the profile token request.
String	getRemoteIPAddress()	Returns the remote IP address associated with the profile token.
int	getRemotePort()	Returns the remote port of the network connection associated with the profile token request.
int	getTimeoutInterval()	Returns the number of seconds to expiration assigned when the token was last initialized or refreshed.
byte[]	getToken()	Returns the actual bytes for the token as it exists on the IBM i system.
int	getTokenCreator()	Returns an integer indicating how profile token was created.
int	getTokenType()	Returns an integer indicating the type assigned when the token was last initialized or refreshed.
String	getVerificationID()	Returns the verification ID associated with an enhanced profile token.
int	hashCode()	Returns a hash code for this credential.
void	initialize(AS400BasicAuthenticationPrincipal principal, char[] password, boolean isPrivate, boolean isReusable, boolean isRenewable, int timeoutInterval)	Initializes and validates a credential for the local IBM i system.
void	initialize(AS400BasicAuthenticationPrincipal principal, char[] password, char[] additionalAuthFactor, int authenticationIndicator, boolean isPrivate, boolean isReusable, boolean isRenewable, int timeoutInterval, ProfileTokenEnhancedInfo enhancedInfo)	Initializes and validates a credential for the local IBM i system.
void	initialize(AS400BasicAuthenticationPrincipal principal, String password, boolean isPrivate, boolean isReusable, boolean isRenewable, int timeoutInterval)	Deprecated.
boolean	isEnhancedProfileToken()	Return true if the profile token was created as an enhancedProfileToken This can only be set when the profile token is set.
boolean	isRenewable()	Indicates if the credential can be refreshed.
boolean	isReusable()	Indicates if the credential can be used multiple times prior to expiration.
void	preventRefresh()	Block the thread to refresh profile token credential.
void	refresh()	Updates or extends the validity period for the credential.
void	refresh(int type, int timeoutInterval)	Updates or extends the validity period for the credential.
void	setAuthenticationIndicator(int authenticationIndicator)	Set the authentication indicator.
void	setEnhancedInfo(ProfileTokenEnhancedInfo enhancedInfo)
void	setLocalIPAddress(String localIPAddress)	Set the local IP address to be associated with the profile token.
void	setLocalPort(int localPort)	Set the local port of the network connection associated with the profile token request.
void	setRemoteIPAddress(String remoteIPAddress)	Set the remote IP address to be associated with the profile token.
void	setRemotePort(int remotePort)	Set the remote port of the network connection associated with the profile token request.
void	setTimeoutInterval(int seconds)	Sets the number of seconds to expiration when the token is generated or refreshed.
void	setToken(byte[] bytes)	Sets the actual bytes for the token as it exists on the IBM i system.
void	setToken(byte[] bytes, ProfileTokenEnhancedInfo enhancedInfo)	Sets the actual bytes for the enhanced profile token as it exists on the IBM i system.
void	setToken(AS400Principal principal, int passwordSpecialValue)	Sets the token bytes based on the provided principal and special value for a password.
void	setToken(AS400Principal principal, String password)	Deprecated. As of V5R3, replaced by setTokenExtended(AS400Principal,String) for password strings or setToken(AS400Principal,int) for password special values.
void	setToken(String name, int passwordSpecialValue)	Sets the token bytes based on the provided user profile and special value for a password.
void	setToken(String name, String password)	Deprecated. As of V5R3, replaced by setTokenExtended(String,String) for password strings or setToken(String,int) for password special values.
void	setTokenCreator(int tokenCreator)	Sets the token creator.
void	setTokenExtended(AS400Principal principal, char[] password)	Sets the token bytes based on the provided principal and password.
void	setTokenExtended(AS400Principal principal, char[] password, char[] additionalAuthenticationFactor)	Sets the token bytes based on the provided principal, password, and additionalAuthenticationFactor
void	setTokenExtended(AS400Principal principal, String password)	Deprecated. Use setTokenExtended(AS400Principal principal, char[] password) instead
void	setTokenExtended(String name, char[] password)	Sets the token bytes based on the provided user profile and password.
void	setTokenExtended(String name, char[] password, char[] additionalAuthenticationFactor)	Sets the token bytes based on the provided user profile and password.
void	setTokenExtended(String name, String password)	Deprecated. Use setTokenExtended(String name, char[] password) instead.
void	setTokenType(int type)	Sets the type of token.
void	setVerificationID(String verificationID)	Set the verification ID to be associated with the profile token.
int	superHashCode()	Returns the hashcode for the super class
String	toString()
static boolean	useEnhancedProfileTokens()	Return whether enhanced profile token should be used based on whether the JVM property com.ibm.as400.access.AS400.useEnhancedProfileTokens.

Methods inherited from class com.ibm.as400.security.auth.AS400Credential

addCredentialListener, addPropertyChangeListener, addVetoableChangeListener, basicAuthenticationPrompt, clearArray, destroy, finalize, getAutomaticRefreshFailure, getAutomaticRefreshStatus, getPrincipal, getSystem, getTimeToExpiration, isCurrent, isDestroyed, isPrivate, isTimed, removeCredentialListener, removePropertyChangeListener, removeVetoableChangeListener, setPrincipal, setSystem, startAutomaticRefresh, stopAutomaticRefresh, swap, swap

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.ibm.as400.security.auth.AS400BasicAuthenticationCredential

basicAuthenticationPrompt, isPrivate

Field Detail

MAX_ADDITIONALAUTHENTICATIONFACTOR_LENGTH

public static final int MAX_ADDITIONALAUTHENTICATIONFACTOR_LENGTH

Maximum length of additional authentication factor

See Also:

Constant Field Values

MAX_VERIFICATIONID_LENGTH

public static final int MAX_VERIFICATIONID_LENGTH

Maximum length of verification ID.

See Also:

Constant Field Values

MAX_IPADDRESS_LENGTH

public static final int MAX_IPADDRESS_LENGTH

Maximum length of IP address.

See Also:

Constant Field Values

TYPE_SINGLE_USE

public static final int TYPE_SINGLE_USE

ID indicating a single use token.

See Also:

Constant Field Values

TYPE_MULTIPLE_USE_NON_RENEWABLE

public static final int TYPE_MULTIPLE_USE_NON_RENEWABLE

ID indicating a multiple use token that cannot be regenerated.

See Also:

Constant Field Values

TYPE_MULTIPLE_USE_RENEWABLE

public static final int TYPE_MULTIPLE_USE_RENEWABLE

ID indicating a multiple use token that can be regenerated.

See Also:

Constant Field Values

TOKEN_LENGTH

public static final int TOKEN_LENGTH

Indicates the length of a profile token (in bytes)

See Also:

Constant Field Values

CREATOR_UNKNOWN

public static final int CREATOR_UNKNOWN

ID indicating the creator of token is not known

See Also:

Constant Field Values

CREATOR_SIGNON_SERVER

public static final int CREATOR_SIGNON_SERVER

ID indicating the creator of token the file server

See Also:

Constant Field Values

CREATOR_NATIVE_API

public static final int CREATOR_NATIVE_API

ID indicating the creator of token is a native API

See Also:

Constant Field Values

PW_NOPWD

public static final int PW_NOPWD

Password special value indicating that the current password is not verified.

The user requesting the profile token must have *USE authority to the user profile.

This value is not allowed if the name of the currently running profile is specified for the user profile name parameter.

See Also:

Constant Field Values

PW_NOPWDCHK

public static final int PW_NOPWDCHK

Password special value indicating that a profile token can be generated for a profile that is disabled or has an expired password.

The user requesting the profile token must have *USE authority to the user profile.

If the profile is disabled, the user requesting the profile token must have *ALLOBJ and *SECADM special authorities to get a token.

If the password is expired, the user requesting the profile token must have *ALLOBJ and *SECADM special authorities to get a token.

If the requesting user does not have *ALLOBJ and *SECADM special authorities, then the request will be handled as if they had indicated *NOPWD.

See Also:

Constant Field Values

DEFAULT_VERIFICATION_ID

public static final String DEFAULT_VERIFICATION_ID

Default verification ID that is used when generating a profile token is "QIBM_OS400_JT400".

See Also:

Constant Field Values

Constructor Detail

ProfileTokenCredential

public ProfileTokenCredential()

Constructs a ProfileTokenCredential object.

The system and token must be set prior to accessing host information or taking action against the credential.

ProfileTokenCredential

public ProfileTokenCredential(AS400 system,
                              byte[] token,
                              int tokenType,
                              int timeoutInterval)

Constructs and initializes a ProfileTokenCredential object.

This method allows a credential to be constructed based on an existing token (i.e. previously created using the QSYGENPT system API). It is the responsibility of the application to ensure the token attributes, such as the tokenType and timeoutInterval, are consistent with the specified token value. This deprecated method cannot be used with an enhanced profile token.

Parameters:

system - The system associated with the credential.

token - The actual bytes for the token as it exists on the IBM i system.

tokenType - The type of token provided. Possible types are defined as fields on this class:

• TYPE_SINGLE_USE
• TYPE_MULTIPLE_USE_NON_RENEWABLE
• TYPE_MULTIPLE_USE_RENEWABLE

timeoutInterval - The number of seconds to expiration, used as the default value when the token is refreshed (1-3600).

ProfileTokenCredential

public ProfileTokenCredential(AS400 system,
                              byte[] token,
                              int tokenType,
                              int timeoutInterval,
                              String verificationID,
                              String remoteIPAddress,
                              int remotePort,
                              String localIPAddress,
                              int localPort)

Constructs and initializes a ProfileTokenCredential object.

This method allows a credential to be constructed based on an existing token (i.e. previously created using the QSYGENPT system API). It is the responsibility of the application to ensure the token attributes, such as tokenType and timeoutInterval, are consistent with the specified token value. If the token was created as an enhanced profile token, then the verificationId, remoteIpAddress, remotePort, localIpAddress, localPort parameter must be specified.

Parameters:

system - The system associated with the credential.

token - The actual bytes for the token as it exists on the IBM i system.

tokenType - The type of token provided. Possible types are defined as fields on this class:

• TYPE_SINGLE_USE
• TYPE_MULTIPLE_USE_NON_RENEWABLE
• TYPE_MULTIPLE_USE_RENEWABLE

timeoutInterval - The number of seconds to expiration, used as the default value when the token is refreshed (1-3600).

verificationID - For an enhanced profile token, the verification ID is the label that identifies the specific application, service, or action associated with the profile handle request. This value must be 30-characters or less. This value will be passed to the authentication exit program registered under the QIBM_QSY_AUTH exit point if the specified user profile has *REGFAC as an authentication method. The authentication exit program may use the verification ID as a means to restrict the use of the user profile. If running on an IBM i, the verification ID should be the DCM application ID or a similar value that identifies the application or service. If an enhance profile token is not used, then null should be passed.

remoteIPAddress - For an enhanced profile token, if the API is used by a server to provide access to a the system, the remote IP address should be obtained from the socket connection (i.e. using Socket.getInetAddress). Otherwise, null should be passed.

remotePort - For an enhanced profile token, if the API is used by a server to provide access to a the system, the remote port should be obtained from the socket connection (i.e. using Socket.getPort ). Otherwise, use 0 if there is not an associated connection.

localIPAddress - For an enhanced profile token, if the API is used by a server to provide access to a the system, the local IP address should be obtained from the socket connection (i.e. using Socket.getLocalAddress). Otherwise, null should be passed.

localPort - For an enhanced profile token, if the API is used by a server to provide access to a the system, the local port should be obtained from the socket connection (Socket.getLocalPort). Otherwise, use 0 if there is not an associated connection.

Method Detail

equals

public boolean equals(Object o)

Compares the specified Object with the credential for equality.

Overrides:

equals in class Object

Parameters:

o - Object to be compared for equality.

Returns:

true if equal; otherwise false.

getTimeoutInterval

public int getTimeoutInterval()

Returns the number of seconds to expiration assigned when the token was last initialized or refreshed.

This value also provides the default value for subsequent refresh attempts.

The default value is 3600 (1 hour).

Returns:

The number of seconds.

getToken

public byte[] getToken()

Returns the actual bytes for the token as it exists on the IBM i system.

Returns:

The token bytes; null if not set.

getTokenType

public int getTokenType()

Returns an integer indicating the type assigned when the token was last initialized or refreshed.

This value also provides the default value for subsequent refresh attempts.

The default is TYPE_SINGLE_USE.

Returns:

The type of token. Possible types are defined as fields on this class:

• TYPE_SINGLE_USE
• TYPE_MULTIPLE_USE_NON_RENEWABLE
• TYPE_MULTIPLE_USE_RENEWABLE

superHashCode

public int superHashCode()

Returns the hashcode for the super class

Returns:

hashcode for super class

hashCode

public int hashCode()

Returns a hash code for this credential.

Overrides:

hashCode in class Object

Returns:

a hash code for this credential.

initialize

@Deprecated
public void initialize(AS400BasicAuthenticationPrincipal principal,
                       String password,
                       boolean isPrivate,
                       boolean isReusable,
                       boolean isRenewable,
                       int timeoutInterval)
                throws Exception

Deprecated.

Description copied from interface: AS400BasicAuthenticationCredential

Initializes and validates a credential for the local IBM i system.

Specified by:

initialize in interface AS400BasicAuthenticationCredential

Parameters:

principal - The principal identifying the authenticated user.

password - The password for the authenticated user.

isPrivate - Indicates whether the credential is considered private.

isReusable - true if the credential can be used to swap thread identity multiple times; otherwise false.

isRenewable - true if the validity period of the credential can be programmatically updated or extended; otherwise false.

timeoutInterval - The number of seconds to expiration when the credential is initially created; ignored if the credential does not expire based on time.

Throws:

Exception - If an exception occurs.

initialize

public void initialize(AS400BasicAuthenticationPrincipal principal,
                       char[] password,
                       boolean isPrivate,
                       boolean isReusable,
                       boolean isRenewable,
                       int timeoutInterval)
                throws Exception

Description copied from interface: AS400BasicAuthenticationCredential

Initializes and validates a credential for the local IBM i system.

Specified by:

initialize in interface AS400BasicAuthenticationCredential

Parameters:

principal - The principal identifying the authenticated user.

password - The password for the authenticated user.

isPrivate - Indicates whether the credential is considered private.

isReusable - true if the credential can be used to swap thread identity multiple times; otherwise false.

isRenewable - true if the validity period of the credential can be programmatically updated or extended; otherwise false.

timeoutInterval - The number of seconds to expiration when the credential is initially created; ignored if the credential does not expire based on time.

Throws:

Exception - If an exception occurs.

initialize

public void initialize(AS400BasicAuthenticationPrincipal principal,
                       char[] password,
                       char[] additionalAuthFactor,
                       int authenticationIndicator,
                       boolean isPrivate,
                       boolean isReusable,
                       boolean isRenewable,
                       int timeoutInterval,
                       ProfileTokenEnhancedInfo enhancedInfo)
                throws Exception

Description copied from interface: AS400BasicAuthenticationCredential

Initializes and validates a credential for the local IBM i system.

Specified by:

initialize in interface AS400BasicAuthenticationCredential

Parameters:

principal - The principal identifying the authenticated user.

password - The password for the authenticated user.

additionalAuthFactor - The additional authentication factor for the user

authenticationIndicator - Indicates how the caller authenticated the user. Ignored for IBM i 7.5 and older releases. @see com.ibm.as400.access.AuthenticationIndicator

isPrivate - Indicates whether the credential is considered private.

isReusable - true if the credential can be used to swap thread identity multiple times; otherwise false.

isRenewable - true if the validity period of the credential can be programmatically updated or extended; otherwise false.

timeoutInterval - The number of seconds to expiration when the credential is initially created; ignored if the credential does not expire based on time.

enhancedInfo - Contains the information needed to create an enhanced profile token. This parameter is ignored for 7.5 and older releases. It includes the following information. verificationID The verification ID is the label that identifies the specific application, service, or action associated with the profile handle request. This value must be 30-characters or less. This value will be passed to the authentication exit program registered under the QIBM_QSY_AUTH exit point if the specified user profile has *REGFAC as an authentication method. The authentication exit program may use the verification ID as a means to restrict the use of the user profile. If running on an IBM i, the verification ID should be the DCM application ID or a similar value that identifies the application or service. remoteIPAddress If the API is used by a server to provide access to a the system, the remote IP address should be obtained from the socket connection (i.e. using Socket.getInetAddress). Otherwise, null should be passed. remotePort If the API is used by a server to provide access to a the system, the remote port should be obtained from the socket connection (i.e. using Socket.getPort ). Otherwise, use 0 if there is not an associated connection. localIPAddress If the API is used by a server to provide access to a the system, the local IP address should be obtained from the socket connection (i.e. using Socket.getLocalAddress). Otherwise, null should be passed. localPort If the API is used by a server to provide access to a the system, the local port should be obtained from the socket connection (Socket.getLocalPort). Otherwise, use 0 if there is not an associated connection.

Throws:

Exception - If an exception occurs.

setEnhancedInfo

public void setEnhancedInfo(ProfileTokenEnhancedInfo enhancedInfo)

isRenewable

public boolean isRenewable()

Description copied from class: AS400Credential

Indicates if the credential can be refreshed.

Overrides:

isRenewable in class AS400Credential

Returns:

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

See Also:

AS400Credential.refresh()

isReusable

public boolean isReusable()

Indicates if the credential can be used multiple times prior to expiration.

Returns:

true if the credential can be used to swap thread identity multiple times; otherwise false.

refresh

public void refresh()
             throws AS400SecurityException

Description copied from class: AS400Credential

Updates or extends the validity period for the credential.

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

Overrides:

refresh in class AS400Credential

Throws:

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

refresh

public void refresh(int type,
                    int timeoutInterval)
             throws AS400SecurityException

Updates or extends the validity period for the credential.

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

Otherwise, generates a new profile token based on the previously established token with the given type and timeoutInterval.

If successful, the specified type and interval become the default values for future refresh attempts.

This method is provided to handle cases where it is desirable to allow for a more restrictive type of token or a different timeout interval when a new token is generated during the refresh.

Parameters:

type - The type of token. Possible types are defined as fields on this class:

• TYPE_SINGLE_USE
• TYPE_MULTIPLE_USE_NON_RENEWABLE
• TYPE_MULTIPLE_USE_RENEWABLE

timeoutInterval - The number of seconds before expiration (1-3600).

Throws:

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

ExtendedIllegalArgumentException - If a parameter value is out of range.

setTimeoutInterval

public void setTimeoutInterval(int seconds)
                        throws PropertyVetoException

Sets the number of seconds to expiration when the token is generated or refreshed.

It is the application's responsibility to maintain consistency between explicitly set token values (those not generated from a user and password) and the tokenType and timeoutInterval.

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

Parameters:

seconds - The number of seconds to expiration (1-3600).

Throws:

PropertyVetoException - If the change is vetoed.

ExtendedIllegalArgumentException - If the provided value is out of range.

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

setToken

public void setToken(byte[] bytes)
              throws PropertyVetoException

Sets the actual bytes for the token as it exists on the IBM i system.

This method allows a credential to be constructed based on an existing token (i.e. previously created using the QSYGENPT system API). It is the responsibility of the application to ensure the token attributes, such as the tokenType and timeoutInterval, are consistent with the specified token value. This method should only be called if the token is not an enhanced profile token.

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

Parameters:

bytes - The token bytes.

Throws:

PropertyVetoException - If the change is vetoed.

ExtendedIllegalArgumentException - If the provided value is not the correct length.

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

setToken

public void setToken(byte[] bytes,
                     ProfileTokenEnhancedInfo enhancedInfo)
              throws PropertyVetoException

Sets the actual bytes for the enhanced profile token as it exists on the IBM i system.

This method allows a credential to be constructed based on an existing token (i.e. previously created using the QSYGENPT system API). It is the responsibility of the application to ensure the token attributes, such as the tokenType and timeoutInterval, are consistent with the specified token value. This method should only be called if the token is an enhanced profile token.

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

Parameters:

bytes - The token bytes.

Throws:

PropertyVetoException - If the change is vetoed.

ExtendedIllegalArgumentException - If the provided value is not the correct length.

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

setToken

@Deprecated
public void setToken(AS400Principal principal,
                     String password)
              throws PropertyVetoException,
                     AS400SecurityException

Deprecated.

As of V5R3, replaced by setTokenExtended(AS400Principal,String) for password strings or setToken(AS400Principal,int) for password special values.

Sets the token bytes based on the provided principal and password.

The system property must be set prior to invoking this method.

If successful, this method results in a new token being created on the IBM i system. The new token is generated using the previously established tokenType and timeoutInterval settings.

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

Parameters:

principal - The principal identifying the user profile for which the token is to be generated.

password - The user profile password. The following special values are allowed:

• *NOPWD - The password is not verified. This value is not allowed if the name of the currently running profile is specified for the name parameter. If specified, the user requesting the profile token must have *USE authority to the user profile.
• *NOPWDCHK - The password is not verified. This value allows a profile token to be generated for a profile that is disabled or has an expired password. If disabled or expired, the user requesting the profile token must have *ALLOBJ and *SECADM special authority.

Throws:

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

PropertyVetoException - If the change is vetoed.

ExtendedIllegalArgumentException - If errors occur during parameter validation.

ExtendedIllegalStateException - If the token cannot be initialized due to the current state.

setToken

@Deprecated
public void setToken(String name,
                     String password)
              throws PropertyVetoException,
                     AS400SecurityException

Deprecated.

As of V5R3, replaced by setTokenExtended(String,String) for password strings or setToken(String,int) for password special values.

Sets the token bytes based on the provided user profile and password.

The system property must be set prior to invoking this method.

If successful, this method results in a new token being created on the IBM i system. The new token is generated using the previously established tokenType and timeoutInterval settings.

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

Parameters:

name - The name of the user profile for which the token is to be generated.

password - The user profile password. The following special values are allowed:

• *NOPWD - The password is not verified. This value is not allowed if the name of the currently running profile is specified for the name parameter. If specified, the user requesting the profile token must have *USE authority to the user profile.
• *NOPWDCHK - The password is not verified. This value allows a profile token to be generated for a profile that is disabled or has an expired password. If disabled or expired, the user requesting the profile token must have *ALLOBJ and *SECADM special authority.

Throws:

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

PropertyVetoException - If the change is vetoed.

ExtendedIllegalArgumentException - If errors occur during parameter validation.

ExtendedIllegalStateException - If the token cannot be initialized due to the current state.

setToken

public void setToken(AS400Principal principal,
                     int passwordSpecialValue)
              throws PropertyVetoException,
                     AS400SecurityException

Sets the token bytes based on the provided principal and special value for a password.

This method requires a special value to be specified for the user password parameter. If you need to validate a user password, see the setTokenExtended(AS400Principal, String).

The system property must be set prior to invoking this method.

If successful, this method results in a new token being created on the IBM i system. The new token is generated using the previously established tokenType and timeoutInterval settings.

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

Parameters:

principal - The principal identifying the user profile for which the token is to be generated.

passwordSpecialValue - The special value for the user profile password. The following special values are allowed:

• PW_NOPWD - The password is not verified. This value is not allowed if the name of the currently running profile is specified for the name parameter. If specified, the user requesting the profile token must have *USE authority to the user profile.
• PW_NOPWDCHK - The password is not verified. This value allows a profile token to be generated for a profile that is disabled or has an expired password. If specified, the user requesting the profile token must have *USE authority to the user profile. If disabled or expired, the user requesting the profile token must have *ALLOBJ and *SECADM special authority.

Throws:

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

PropertyVetoException - If the change is vetoed.

ExtendedIllegalArgumentException - If errors occur during parameter validation.

ExtendedIllegalStateException - If the token cannot be initialized due to the current state.

setToken

public void setToken(String name,
                     int passwordSpecialValue)
              throws PropertyVetoException,
                     AS400SecurityException

Sets the token bytes based on the provided user profile and special value for a password.

This method requires a special value to be specified for the user password parameter. If you need to validate a user password, see the setTokenExtended(String, String).

The system property must be set prior to invoking this method.

If successful, this method results in a new token being created on the IBM i system. The new token is generated using the previously established tokenType and timeoutInterval settings.

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

Parameters:

name - The name of the user profile for which the token is to be generated.

passwordSpecialValue - The special value for the user profile password. The following special values are allowed:

• PW_NOPWD - The password is not verified. This value is not allowed if the name of the currently running profile is specified for the name parameter. If specified, the user requesting the profile token must have *USE authority to the user profile.
• PW_NOPWDCHK - The password is not verified. This value allows a profile token to be generated for a profile that is disabled or has an expired password. If specified, the user requesting the profile token must have *USE authority to the user profile. If disabled or expired, the user requesting the profile token must have *ALLOBJ and *SECADM special authority.

Throws:

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

PropertyVetoException - If the change is vetoed.

ExtendedIllegalArgumentException - If errors occur during parameter validation.

ExtendedIllegalStateException - If the token cannot be initialized due to the current state.

setTokenExtended

@Deprecated
public void setTokenExtended(AS400Principal principal,
                             String password)
                      throws PropertyVetoException,
                             AS400SecurityException

Deprecated.

Use setTokenExtended(AS400Principal principal, char[] password) instead

Sets the token bytes based on the provided principal and password.

The system property must be set prior to invoking this method.

If successful, this method results in a new token being created on the IBM i system. The new token is generated using the previously established tokenType and timeoutInterval settings.

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

Parameters:

principal - The principal identifying the user profile for which the token is to be generated.

password - The user profile password.

Throws:

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

PropertyVetoException - If the change is vetoed.

ExtendedIllegalArgumentException - If errors occur during parameter validation.

ExtendedIllegalStateException - If the token cannot be initialized due to the current state.

setTokenExtended

public void setTokenExtended(AS400Principal principal,
                             char[] password)
                      throws PropertyVetoException,
                             AS400SecurityException

Sets the token bytes based on the provided principal and password.

The system property must be set prior to invoking this method.

If successful, this method results in a new token being created on the IBM i system. The new token is generated using the previously established tokenType and timeoutInterval settings.

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

Parameters:

principal - The principal identifying the user profile for which the token is to be generated.

password - The user profile password.

Throws:

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

PropertyVetoException - If the change is vetoed.

ExtendedIllegalArgumentException - If errors occur during parameter validation.

ExtendedIllegalStateException - If the token cannot be initialized due to the current state.

setTokenExtended

public void setTokenExtended(AS400Principal principal,
                             char[] password,
                             char[] additionalAuthenticationFactor)
                      throws PropertyVetoException,
                             AS400SecurityException

Sets the token bytes based on the provided principal, password, and additionalAuthenticationFactor

The system property must be set prior to invoking this method.

If successful, this method results in a new token being created on the IBM i system. The new token is generated using the previously established tokenType and timeoutInterval settings.

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

Parameters:

principal - The principal identifying the user profile for which the token is to be generated.

password - The user profile password.

additionalAuthenticationFactor - The additional authentication factor

Throws:

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

PropertyVetoException - If the change is vetoed.

ExtendedIllegalArgumentException - If errors occur during parameter validation.

ExtendedIllegalStateException - If the token cannot be initialized due to the current state.

setTokenExtended

@Deprecated
public void setTokenExtended(String name,
                             String password)
                      throws PropertyVetoException,
                             AS400SecurityException

Deprecated.

Use setTokenExtended(String name, char[] password) instead.

Sets the token bytes based on the provided user profile and password.

The system property must be set prior to invoking this method.

If successful, this method results in a new token being created on the IBM i system. The new token is generated using the previously established tokenType and timeoutInterval settings.

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

Parameters:

name - The name of the user profile for which the token is to be generated.

password - The user profile password.

Throws:

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

PropertyVetoException - If the change is vetoed.

ExtendedIllegalArgumentException - If errors occur during parameter validation.

ExtendedIllegalStateException - If the token cannot be initialized due to the current state.

setTokenExtended

public void setTokenExtended(String name,
                             char[] password)
                      throws PropertyVetoException,
                             AS400SecurityException

Sets the token bytes based on the provided user profile and password.

The system property must be set prior to invoking this method.

If successful, this method results in a new token being created on the IBM i system. The new token is generated using the previously established tokenType and timeoutInterval settings.

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

Parameters:

name - The name of the user profile for which the token is to be generated.

password - The user profile password.

Throws:

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

PropertyVetoException - If the change is vetoed.

ExtendedIllegalArgumentException - If errors occur during parameter validation.

ExtendedIllegalStateException - If the token cannot be initialized due to the current state.

setTokenExtended

public void setTokenExtended(String name,
                             char[] password,
                             char[] additionalAuthenticationFactor)
                      throws PropertyVetoException,
                             AS400SecurityException

Sets the token bytes based on the provided user profile and password.

The system property must be set prior to invoking this method.

If successful, this method results in a new token being created on the IBM i system. The new token is generated using the previously established tokenType and timeoutInterval settings.

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

Parameters:

name - The name of the user profile for which the token is to be generated.

password - The user profile password.

additionalAuthenticationFactor - The additional authentication factor used to authenticate.

Throws:

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

PropertyVetoException - If the change is vetoed.

ExtendedIllegalArgumentException - If errors occur during parameter validation.

ExtendedIllegalStateException - If the token cannot be initialized due to the current state.

setTokenType

public void setTokenType(int type)
                  throws PropertyVetoException

Sets the type of token.

It is the application's responsibility to maintain consistency between explicitly set token values (those not generated from a user and password) and the tokenType and timeoutInterval.

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

Parameters:

type - The type of token. Possible types are defined as fields on this class:

• TYPE_SINGLE_USE
• TYPE_MULTIPLE_USE_NON_RENEWABLE
• TYPE_MULTIPLE_USE_RENEWABLE

Throws:

PropertyVetoException - If the change is vetoed.

ExtendedIllegalArgumentException - If the provided value is out of range.

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

toString

public String toString()

Overrides:

toString in class Object

preventRefresh

public void preventRefresh()
                    throws InterruptedException

Block the thread to refresh profile token credential.

Throws:

InterruptedException

allowRefresh

public void allowRefresh()

Notify the wait thread to refresh profile token credential.

useEnhancedProfileTokens

public static boolean useEnhancedProfileTokens()

Return whether enhanced profile token should be used based on whether the JVM property com.ibm.as400.access.AS400.useEnhancedProfileTokens. By default, enhanced profile tokens will be used. Set the property to false if enhanced profile tokens should not be used.

Returns:

true if enhanced profile tokens should be used; otherwise, false.

setVerificationID

public void setVerificationID(String verificationID)
                       throws PropertyVetoException

Set the verification ID to be associated with the profile token. The verification ID is the label that identifies the specific application, service, or action associated with the profile token request.

Parameters:

verificationID - The verification ID.

Throws:

PropertyVetoException

getVerificationID

public String getVerificationID()

Returns the verification ID associated with an enhanced profile token.

Returns:

The verification ID. If this is not an enhanced profile token then "*NOUSE" is returned. If the value is not set to a value, the default verification ID of "QIBM_OS400_JT400" will be returned.

setLocalIPAddress

public void setLocalIPAddress(String localIPAddress)
                       throws PropertyVetoException

Set the local IP address to be associated with the profile token. Note that the method does not validate the value to ensure it is a valid IP address.

Parameters:

localIPAddress - The local IP address.

Throws:

PropertyVetoException

getLocalIPAddress

public String getLocalIPAddress()

Returns the local IP address associated with the profile token.

Returns:

The client IP address. The value can be null if it has not been set.

setRemoteIPAddress

public void setRemoteIPAddress(String remoteIPAddress)
                        throws PropertyVetoException

Set the remote IP address to be associated with the profile token. Note that the method does not validate the value to ensure it is a valid IP address.

Parameters:

remoteIPAddress - IP address.

Throws:

PropertyVetoException

getRemoteIPAddress

public String getRemoteIPAddress()

Returns the remote IP address associated with the profile token.

Returns:

The remote IP address. The value can be null if it has not been set.

setRemotePort

public void setRemotePort(int remotePort)
                   throws PropertyVetoException

Set the remote port of the network connection associated with the profile token request. A value of 0 indicates that the remote port is not specified.

Parameters:

remotePort - The remote port.

Throws:

PropertyVetoException

getRemotePort

public int getRemotePort()

Returns the remote port of the network connection associated with the profile token request.

Returns:

The remote port. A value of 0 indicates that the remote port is not specified.

setLocalPort

public void setLocalPort(int localPort)
                  throws PropertyVetoException

Set the local port of the network connection associated with the profile token request. A value of 0 indicates that the local port is not specified.

Parameters:

localPort - the local Port.

Throws:

PropertyVetoException

getLocalPort

public int getLocalPort()

Returns the local port of the network connection associated with the profile token request.

Returns:

The local port. A value of 0 indicates that the local port is not specified.

setAuthenticationIndicator

public void setAuthenticationIndicator(int authenticationIndicator)
                                throws PropertyVetoException

Set the authentication indicator. The default value for the authentication indicator is AuthenticationIndicator.APPLICATION_AUTHENTICATION. @see com.ibm.as400.access.AuthenticationIndicator for further information.

Parameters:

authenticationIndicator - Indicates how the caller authenticated the user.

Throws:

PropertyVetoException

getAuthenticationIndicator

public int getAuthenticationIndicator()

Returns the authentication indicator. @see com.ibm.as400.access.AuthenticationIndicator for further information.

Returns:

The authentication indicator.

getTokenCreator

public int getTokenCreator()

Returns an integer indicating how profile token was created.

Returns:

The creator of token. Possible values are defined as fields on this class:

• CREATOR_UNKNOWN
• CREATOR_SIGNON_SERVER
• CREATOR_NATIVE_API

setTokenCreator

public void setTokenCreator(int tokenCreator)
                     throws PropertyVetoException

Sets the token creator.

It is the application's responsibility to maintain consistency between explicitly set token values (those not generated from a user and password) and token attributes, such as the tokenType, timeoutInterval, and tokenCreator.

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

Parameters:

tokenCreator - The creator of the token. Possible values are defined as fields on this class:

• CREATOR_UNKNOWN
• CREATOR_SIGNON_SERVER
• CREATOR_NATIVE_API

Throws:

PropertyVetoException - If the change is vetoed.

ExtendedIllegalArgumentException - If the provided value is out of range.

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

isEnhancedProfileToken

public boolean isEnhancedProfileToken()

Return true if the profile token was created as an enhancedProfileToken This can only be set when the profile token is set.

Returns:

getEnhancedInfo

public ProfileTokenEnhancedInfo getEnhancedInfo()