PAM authentication method

The HCL OneDB™ JDBC Driver, Version 2.21. JC5 and later, implements support for handling PAM (Pluggable Authentication Module)-enabled HCL OneDB server 9.40 and later servers. This implementation supports a challenge-response dialog between PAM and the end user. To facilitate this dialog, the JDBC developer must implement the com.informix.jdbc.IfmxPAM interface. The IfxPAM() method in the IfmxPAM interface acts as the gateway between PAM and the user.

The IfxPAM() method is called when the JDBC server encounters a PAM challenge method. The return value from the IfxPAM() method acts as the response to the challenge message and is sent to PAM.

The signature for the IfxPAM() method is:

public IfxPAMResponse IfxPAM(IfxPAMChallenge challengeMessage)

Two classes, IfxPAMChallenge and IfxPAMResponse, usher messages between the JDBC driver and PAM. The IfxPAMChallenge class contains the information that has been sent from PAM to the user.

The challenge message is obtained from the IfxPAMChallenge class by using the getChallenge() method. This message is what is sent directly from PAM running on HCL OneDB server to be routed to the end user. The challenge messages are listed in the following table.

Table 1. Types of challenge messages
Message	Description
PAM_PROMPT_ECHO_ON	The message is displayed to the user and the users response can be echoed back.
PAM_PROMPT_ECHO_OFF	The message is displayed to the user and the users response is hidden or masked (that is, when the user enters a password, asterisks are displayed instead of the exact characters the user types).
PAM_PROMPT_ERROR_MSG	The message is displayed to the user as an error, with no response required.
PAM_TEXT_INFO_MSG	The message is displayed to the user as an informational message, with no response required.

The challenge message type is governed by the PAM standard and can have vendor-specific values. See the PAM standard and vendor-specific information for possible values and interpretations.

The PAM standard defines the maximum size of a PAM message to be 512 bytes (IfxPAMChallenge.PAM_MAX_MESSAGE_SIZE).

The IfxPAMResponse class is similar to IfxPAMChallenge, but instead of being used by PAM to send a message to the user, the IfxPAMResponse class is used to send a message from the user to PAM. Use the IfxPAMResponse.setResponse() method to send the challenge-response string to PAM. However, set the response type (which is set by using the IfxPAMResponse.setResponseType() method) to zero, the default, as the response type is currently reserved for future use.

The challenge-response string is limited to the size of the challenge message: IfxPAMResponse.PAM_MAX_MESSAGE_SIZE or 512 bytes. If the response string exceeds this limit, an SQL exception is thrown.

Additionally, when the challenge message is of type PAM_INFO_TEXT or PAM_PROMPT_ERR_MSG (see PAM standards for meaning and integer values), PAM expects no user response. Thus, a null IfxPAMResponse object or one that has not been set with specific values can be returned to JDBC. The IfxPAMResponse class provides the following method to allow the JDBC developer to stop the connection attempt during a PAM session:

public void setTerminateConnection(boolean flag)

The value of the flag can be TRUE or FALSE. If the value of the parameter passed to setTerminateConnection is TRUE, then the connection to the PAM-enabled HCL OneDB server immediately terminates upon returning from IfxPAM(). If the value is set to FALSE, then the connection attempt to the PAM-enabled server continues as usual.