Release Notes for IBM Informix JDBC Driver 2.21.JC5

June 2003

Table of Contents

  1. Overview of Release Notes
  2. IBM Informix Dynamic Server Compatibility
  3. Configuration
  4. New Features
    1. Encryption (Wire) CSM
    2. MetaData Improvements
    3. PAM Authentication Method
    4. SQL Boolean Support
  5. JDBC Behavior with JDK 1.4
  6. Database Connections in the Demo Programs
  7. Fixed Problems
  8. Limitations
  9. XML Parser
  10. Acknowledgements

 

I. Overview of Release Notes

The purpose of these release notes is to make you aware of any special actions required to configure and use the IBM Informix JDBC Driver on your computer. This file also describes new features and feature differences from earlier versions of this product and other IBM Informix products and how these differences affect current products. This release notes document is not intended to be all inclusive; it should be used as an addendum to the IBM Informix JDBC Driver Programmer's Guide, Version 2.21, which provides thorough information about product features and behavior. These release notes are written for Java programmers who use the JDBC API to connect to IBM Informix databases via the IBM Informix JDBC Driver.

II. IBM Informix Server Compatibility

IBM Informix JDBC Driver 2.21.JC5 is supported with the following server versions:

 

III. Configuration

To use the IBM Informix JDBC Driver, you must have JDK 1.3 (or later) installed. Please refer to http://java.sun.com/products/jdbc/ for details.

IV. New Features

IBM Informix JDBC Driver, Version 2.21.JC5, includes four new features. These features are not yet documented in the IBM Informix JDBC Driver Programmer's Guide.

1. Encryption (Wire Protocol) CSM

Using JDBC encryption CSM

IBM Informix Dynamic Server, Version 9.4 and later, enables encryption of data transmitted over a network using an encryption communication support module. IBM Informix JDBC Driver, Version 2.21.JC5 and later, makes this feature available to all JDBC clients by adding a communication support module (CSM)  to the JDBC driver.
IBM Informix JDBC encryption module is a class (com.informix.jdbc.Crypto)  that is packaged in the IBM Informix JDBC .jar itself. IBM Informix JDBC encryption CSM is a pure java implementation, which uses services from Java Cryptography provider. Please refer to the JCE Security package section in the IBM Informix JDBC Programmer's Guide for information about configuring a Java Cryptography provider.
IBM Informix JDBC Driver, Version 2.21.JC5 and later, supports environment variable CSM, which allows client applications to specify that CSM be used and the parameters be passed to the CSM. Following is the format to be used with the CSM variable:

CSM=(CLASSNAME=csm-module-class-name,csm-options)

where csm-module-class-name is name of the class that is to be used as CSM and csm-options is a list of CSM configuration parameters that are passed on to the CSM by JDBC driver.Note that csm-options are separated from csm-module-class-name by a comma.
To enable encryption, encryption CSM must be specified, using the CSM variable. The CLASSNAME for encryption CSM is "com.informix.jdbc.Crypto".

(Note that C from Crypto is uppercase. However, CLASSNAME and CSM keywords as well as any of the csm-options being passed to the JDBC encryption CSM are not case sensitive.)
The options that can be passed on to the encryption CSM are the same as the encryption parameters that are specified in CSM configuration file used by the server or CSDK. The format for specifying the options for JDBC encryption CSM is the same as the format used by server CSM configuration files to specify the encryption CSM initialization string:
cipher[options],mac[options], switch[options]
The parameters (major tags) that make up the option string used to configure the JDBC encryption CSM are listed as follows:

cipher Defines all ciphers that can be used by the session
mac Defines which MAC keys can be used by the session
switch Defines the cipher and key change frequencies

Each major tag has a parameter list that is enclosed by square brackets ([ ]).

The general format of the parameter list is:

minor_tag:value

If there can be multiple values for a minor tag, the list must be enclosed within angle brackets (<>).The parameters are negotiated during the connect phase. If no common solution is obtained for the mac or cipher options, the connection attempt will fail.

Please refer to IBM Informix Dynamic Server Administrator's Guide for more details about
these configuration parameters. The following are examples of a URL that specifies that encryption CSM is to be used:

   String    URL =
   
   "jdbc:informixsqli://158.58.10.171:1664:user=myname;”+“password=mypassword;"+
   
   "CSM=(classname=com.informix.jdbc.Crypto,cipher[all],mac[<builtin>]);"+
   
   +
   "INFORMIXSERVER=myserver;"
   
   String URL =
   
   "jdbc:informix-sqli://158.58.10.171:1664:user=myname;"+
   
   "password=mypassword;INFORMIXSERVER=myserver;"+
   
   "CSM=(classname=com.informix.jdbc.Crypto,+ 
   
              "cipher[des:cbc,des3:ofb],"    +
   
   "mac[levels:<high,low>,files:</usr/local/bin/mac1.dat,builtin>],"+
   
   "switch[cipher:120,key:15]);"
   
   
   

Please note that encryption CSM option parameters are separated by a comma and not by a semicolon. When using a DataSource, getIfxCSM() setIfxCSM() methods may be used to get and set CSM property. When setting CSM as a property make sure that you do not enclose the option string in parenthesis. Following is an example that correctly sets the CSM as a property:

connProperties.put("CSM","classname=com.informix.jdbc.Crypto,cipher[all],mac[<builtin>]");

IBM Informix JDBC encryption CSM has been tested with the Sun Java Cryptography provider. The following is a list of ciphers supported by JDBC Encryption CSM.

Cipher

Mode

Supported

des

ecb,cbc,cfb,ofb

Supported

ede

ecb,cbc,cfb,ofb

Supported by IDS 9.40.UC2 and later

bf1

ecb,cbc,cfb,ofb

Supported by IDS 9.40.UC2 and later

bf2

ecb,cbc,cfb,ofb

Supported by IDS 9.40.UC2 and later

bf3

ecb,cbc,cfb,ofb

Supported by IDS 9.40.UC2 and later

bf-1

ecb,cbc,cfb,ofb

Supported

bf-2

ecb,cbc,cfb,ofb

Supported

bf-3

ecb,cbc,cfb,ofb

Supported

des3

ecb,cbc,cfb,ofb

Supported

desx

cbc

Not Supported

Also note that JDBC encryption CSM behavior differs from the encryption CSM as used by CSDK or server in the following ways:

Also note that encryption over the network and password encryption should not be used together. Thus, password encryption should not be enabled with the SECURITY environment variable when using JDBC encryption CSM. JDBC Encryption CSM does encrypt passwords before sending them over the network.

Configuring the encryption CSM in the Server

To be able to connect to IBM Informix database servers on an encrypted port, the JDBC client must use JDBC encryption CSM. Also note that when using JDBC encryption CSM, attempts to connect to IBM Informix database servers on a non-encrypted port will fail. An instance of IBM Informix Database server may be configured to listen in on encrypted and non-encrypted ports at the same time.Please refer to IBM Informix Dynamic Server Administrator's Guide for details regarding configuring IDS to use encryption CSM.


JCE Security Package

The section on the JCE security package IBM Informix JDBC Programmer's Guide should be modified to include the following information:

To use the SECURITY=PASSWORD option or to use JDBC encryption CSM, you must install a JDK Java cryptography extension (JCE) compliant security package on the JDBC client and include the installation directory of the security package in the CLASSPATH variable. If you are using JDK 1.3, you can download the Sun JCE 1.2.2 or later security package from the following web site: http://java.sun.com/products/jce.

Sun JCE has been integrated into the J2SDK, Version 1.4 . Sun JCE is available only in the U.S. or Canada. If your site does not comply with this or other Sun JCE licensing restrictions, you can try using IBM Informix JDBC Driver with other JCE-certified security package providers. However, these packages have not been tested and certified to work with Informix database servers configured to use the SPWDCSM CSM option or the encryption CSM. Sun JCE provider comes bundled with JDK1.4. If using JDK1.3 to install the Sun JCE package, download the Sun JCE distribution, extract the .jar file containing the Sun JCE provider packages, and copy them to jre/lib/ext directory where the JDK is installed. If you opt to keep Sun JCE provider jar files at some other location, make sure that the CLASSPATH environment variable includes the extracted JAR filename.

Edit the lib/security/java.security file from JDK installation to include the following two lines:

security.provider.1=sun.security.provider.Sun
security.provider.2=com.sun.crypto.provider.SunJCE

Please refer to the comments in the default java.security file, which comes with the JDK, for more details regarding configuring cryptography providers. If you intend to use bf3 cipher with JDBC encryption CSM, you need to download and install unlimited Strength Java Cryptography Extension Policy Files from from Sun website, if it is legal to do so in your country.

The following two methods are available, in addition to the ones listed in Appendix B of the IBM Informix JDBC Programmer's guide.

CSM

public String getIfxCSM();

public void setIfxCSM(String value);

2. MetaData Improvements

The following new methods in DatabaseMetaData have been added for JDBC 3.0 compliance. The new methods are:

getSuperTypes()
getSuperTables()
getAttributes()
getResultSetHoldability()
getDatabaseMajorVersion()
getDatabaseMinorVersion()
getJDBCMajorVersion()
getJDBCMinorVersion()
getSQLStateType()
locatorsUpdateCopy()
supportsGetGeneratedKeys()
supportsMultipleOpenResults()
supportsNamedParameters()
supportsResultSetHoldability
supportsSavepoints()
supportsStatementPooling()


3. PAM Authentication Method

The JDBC 2.21.JC5 driver has implemented support for handling PAM (Pluggable Authentication Module)-enabled IDS 9.40 servers.  This implementation supports a challenge-response dialog between PAM and the end user. To facilitate this dialog, a Java JDBC developer must implement the com.informix.jdbc.IfmxPAM interface. The method named IfxPAM() 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 - will be used to usher messages to and from the JDBC driver and PAM. The IfxPAMChallenge Class will contain the information that has been sent from PAM and is meant to be displayed/presented to the user. The challenge message is obtained from the IfxPAMChallenge class using the getChallenge() method. This message is what is sent directly from PAM running on the IDS server to be routed to the end user.  There are 4 (four types of challenge messages:

PAM_PROMPT_ECHO_ON

The message is meant to be displayed to the user and the user's response can be echoed back to the user.

PAM_PROMPT_ECHO_OFF

The message is meant to be displayed to the user and the user's response should be hidden or masked (that is, when entering a password, '*' can be displayed instead of the exact characters the user is typing).

PAM_PROMPT_ERROR_MSG

The message should be displayed to the user as an error, with no response required from the user.

PAM_TEXT_INFO_MSG

The message should be displayed to the user as an informational type message, with no response required.

 

Note: The challenge message type is governed by the PAM standard and may have vendor-specific values.  Please refer to the PAM standard and vendor-specific information for possible values and interpretations.

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

The IfxPAMResponse class will be very 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. The challenge-response string that is sent from the user to PAM is set by using the IfxPAMResponse.setResponse() method. The type of the challenge response can be set using the IfxPAMResponse.setResponseType() method. However, the response type is currently reserved for future use and should always be set to zero (the default).

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, in the case when the challenge message is of type PAM_INFO_TEXT or PAM_PROMPT_ERR_MSG (see PAM standards for meaning and integer values), PAM is not expecting any 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 abort the connection attempt during a PAM session:

public void setTerminateConnection(boolean flag)

If the value of the parameter passed to setTerminateConnection is TRUE, then the connection to the PAM enabled IDS server will immediately be terminated upon returning from IfxPAM().  If the value is set to FALSE, then the connection attempt to the PAM-enabled IDS server will continue as usual. The value of FALSE is the default value.


Using PAM in JDBC

In order for a Java developer using JDBC to use PAM to communicate with a PAM-enabled IDS server, they must implement the com.informix.jdbc.IfmxPAM interface. This is accomplished by putting the following on the class declaration line in a Java class file:

implements IfmxPAM

That Java class must then implement the IfmxPAM interface conforming to Java standards and the details provided above.

The next step is to inform the JDBC driver what Java class has implemented the IfmxPAM interface. There are two ways the Java developer can do this.

 

 

Java JDBC Developers have a wide range of latitude on how they choose to implement the IfmxPAM interface. The JDBC driver, when detecting that it is communicating with a PAM enabled server, will contact the Java developer's IfxPAM() method (the method declared in the IfmxPAM interface) and pass to it a IfxPAMChallenge object containing the PAM's challenge question. The Java developer will present a GUI window with a text question containing the challenge message that was sent by PAM. The response is obtained from the user, packaged into an IfxPAMResponse object, and returned to the JDBC driver by exiting the IfxPAM() method returing the IfxPAMResponse object.

When PAM receives the response from the challenge question, it may either decide to authorize the user, deny access to the user, or issue another challenge question, in which case the above process is repeated.  This entire process continues until either the user is authorized or the user is denied access.  The Java developer or user can terminate the PAM authorization sequence by calling the IfxPAMResponse.setTerminateConnection() method with a value of TRUE.

 

4. SQL Boolean Support

 

The JDBC 3.0 Specification and JDK 1.4 API added the BOOLEAN JDBC types; that is, java.sql.Types.BOOLEAN (value = 16) was defined.  Prior to JDBC 3.0, java type boolean corresponded to JDBC type java.sql.Types.BIT.  In the JDBC 3.0 specification, java type boolean can correspond to JDBC types java.sql.Types.BIT or java.sql.Types.BOOLEAN.  (For purposes of this discussion, no distinction is made between java primitive data type boolean and java.lang.Boolean class. Both are referred to as java type boolean.)

BIT was mapped to the SQL (database specific or IBM-Informix) type CHAR.  However, Informix type BOOLEAN was mapped to JDBC type java.sql.Types.OTHER.

This feature clarifies the handling of boolean with the IDS servers 9.x and complies with the JDBC 3.0 specification.  Informix type BOOLEAN now corresponds to JDBC type java.sql.Types.BOOLEAN.  Java type boolean can correspond to either JDBC type BIT or BOOLEAN.  ResultSet getter methods and setObject methods now support the JDBC type BOOLEAN (including support for conversions).

Additionally, java.sql.Type.BIT now maps to SQL type BOOLEAN. If the runtime Java version is not 1.4 or higher, this feature is suppressed and the old behavior occurs.

V. JDBC Behavior with JDK 1.4

Due to a Sun Microsystems Java (TM) Bug 4361575 fix in JDK 1.4, UDT/UDR manager helper classes included in the ifxtools.jar in the JDBC driver are not accessible from a packaged class. In previous releases, JDBC driver UDT/UDR manager helper classes from ifxtools.jar were not part of any package/named namespace, thus users with JDK 1.4 will not be able to use these classes from any packaged class or named namespace.
As a part of a fix, the following change was made in the 2.21.JC3 release of JDBC driver. All the helper classes for UDT/UDR in ifxtools.jar have been made part of the namespace / package called udtudrmgr. The unpackaged version of these classes is also included for backward compatibility with JDK 1.3 and JDK1.2. Users trying to use UDT/UDR manager classes in JDK 1.4 from the packaged class will need to use following kind of import statements in their programs:

 

VI. Database Connections in the Demo Programs

Except for the pickaseat demo, the examples listed in the IBM Informix JDBC Driver Programmer's Guide, Version 2.21, use the DriverManager.getConnection() method to get a database connection. Sun Microsystems recommends using a DataSource object instead. For more information, refer to the Sun documentation and to the README.TXT file in the demo/pickaseat directory.

VII. Fixed Problems

PTS #
Problem Short Description
158866 JDBC NEEDS TO ADD SUPPORT FOR SQL BOOLEAN FOR JDBC 3.0 SPEC COMPLIANCE
159361 JDBC DRIVER, JDBC CLIENT HANGS WHEN USING MULTISET DATA TYPE AS OUT PARAMETER : JDBC TRACKING BUG FOR SERVER DEFECT : 118951
160075 JDBC 2.21.JC3 INSTALL THROUGH 9.30.UC4 BUNDLE FOR HP-32BIT GIVES AN INSTALLSHIELD WARNING, THERE IS NO WARNING IF SILENT INSTALL IS DONE MANUAL
160266 SILENT INSTALL DOES NOT INSTALL JDBC 2.21, IF JDBC 1.5 IS PREVIOUSLY INSTALLED IN THAT DIRECTORY
161139 GETPROCEDURECOLUMNS() OF DATABASEMETADATA RETURNS DUPLICATED ENTRIES FOR OVERLOADED PROCEDURES - INFORMIX.SYSPROCEDURE
161492 BOOLEAN SUPPORT - DESCRIBE PARAM OF A BOOLEAN COLUMN RETURNS THE PARAM TYPE AS OTHER INSTEAD OF BOOLEAN.
161951 JDBC INSTALL.TXT AND PROGRAMMER'S GUIDE MUST BE MODIFIED TO REFLECT THE CHANGES IN INSTALLING IN CONSOLE MODE DUE TO INSTALL SHIELD CHANGES.
161954 PERFORMING A LOGGED GUI INSTALL W/O SPECIFYING THE FILENAME DOES NOT CREATE ANY DEFAULT LOG FILE AS SPECIFIED IN INSTALL.TXT. NEED BETTER DOC
162046 THE SCHEMAPATTERN IN GETSUPERTYPES DOES NOT MATCH TABLE NAMES AS STATED IN THE FUNCTIONAL SPEC. INSTEAD IT MATCHES THE USER NAME.
162069 GETATTRIBUTES IS STILL DISPLAYING TABLE NAME FOR "TYPE_SCHEM" ATTRIBUTE DESCRIPTION. IT SHOULD DISPLAY OWNER NAME INSTEAD.
162071 DATABASE METADATA GETXXX METHODS MUST NOT DISPLAY ANY ROWS WHEN AN INVALID OWNER NAME IS USED FOR SCHEMAPATTERN PARAMETER
161944 REGRESSION: CONSOLE MODE INSTALL OF 2.21.JC5N065 DOES NOT DISPLAY THE LICENSE AGREEMENT.
161879 REGRESSION: TEST /VOBS/JDBC-QA/JDBCTESTS/JDBCBFV/BUG158348 FAILS AGAINST PAM ENABLED 9.4 (UC2) SERVER USING DRIVER 2.21.JC5N056
161650 USING A PREPARED STATEMENT WITH EXECUTEBATCH METHOD, APPLICATION HANGS WHEN BATCH HAS MORE THAN 4826 RECORDS TO INSERT, CLIENT WINNT SERVER UNIX.
160371 USING JDBC 2.21.JC3, TRYING TO USE DBANSIWARN TO SUPPRESS ANSI MESSAGES FROM THE DATABASE, STILL GETTING 01I06 ERROR, WHICH IS AN ANSI WARN MESSAGE
160207 INSTALL CALCULATES INSTALL DIR FREE SPACE INCORRECTLY IF THE DIR IS A SYM LINK.
160133 VARCHAR PROCESSING SLOWED DOWN IN 9.2X
158851 JDBC DRIVER NEEDS TO SUPPORT PAM FEATURE THAT IS GOING INTO THE IDS 9.40 SERVER
158199 JDBC DRIVER RETURNS NULLABLE=1 FOR SERIAL AND SERIAL8 DATATYPES. SERIAL AND SERIAL8 DATA TYPES CANNOT BE NULL. SO NULLABLE MUST BE 0.
161562 ARRAY.GETBASETYPENAME (IFXARRAY.JAVA) DOES NOT RETURN THE SQL TYPE (DATABASE SPECIFIC TYPE) AS REQUIRED BY JDBC SPECIFICATION.
161888 CODE CONVERSION OF HANKAKU-KAN(1 BYTE JAPANESE) IS NOT PERFORMED SJIS TO EUC WHICH DATA IS HANKAKU-KANA, EVEN IF IFX_CODESETLOB IS DEFINED.
162277 JDBC RESULTSET.ISNULLABLE IS NOT ACCURATE. THE METHOD RETURNS 1 EVEN IF A COLUMN IS NOT NULLABLE IN IDS.

VIII. Limitations

Please refer to the IBM Informix JDBC Driver Programmer's Guide, Version 2.21 for complete list of unsupported methods.

IX. XML Parser

IBM Informix JDBC Driver bundles xerces.jar along with the other driver jar files. This xerces.jar is part of the IBM XML4J version 3.2.1 parser and is developed by Apache Software Foundation (http://www.apache.org).

X. Acknowledgements

This product includes software developed by the Apache Software Foundation (http://www.apache.org/). The Apache software includes xerces.jar. The Apache copyright notice follows in its entirety.

The Apache Software License, Version 1.1 Copyright (c) 1999 The Apache Software Foundation. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.

  4. The names "Xerces" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org.

  5. Products derived from this software may not be called "Apache," nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation and was originally based on software copyright (c) 1999, International Business Machines, Inc., http://www.ibm.com. For more information on the Apache Software Foundation, please see http://www.apache.org.


Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.


Licensed Material.  Property of IBM.
© Copyright International Business Machines Corporation 2003. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.