Release Notes for IBM Informix JDBC Driver 2.21.JC5
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.
IBM Informix JDBC Driver 2.21.JC5 is supported with the following server versions:
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.
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.
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:
JDBC encryption CSM does not support desx cipher. Sun Cryptography Provider does not implement desx. Also, desx is not added to cipher list when using cipher[all] or cipher[allbut] tags.
When using cipher[all] or cipher[allbut]
tag, JDBC does not add bf3 cipher to the cipher list. If the application
wants to use bf3, it has to specifiy it explicitly in the cipher list.
For example:
cipher[all,bf3:cbc,bf3:cfb,bf3:ofb]
The cipher bf3 uses a 192 bit key. To be able to use a 192 bit key, you
must install unlimited Strength Java Cryptography Extension Policy
Files, which can be downloaded from Sun website, if it is legal
to do so in your country.
When specifying the default mac key file in the mac tag, JDBC supports keywords builtin and default. Either keyword may be used.
Application programmers need to be aware of performance overhead when using JDBC encryption CSM. When using encryption, the performance degradation observed in JDBC clients is significant as compared to performance of other clients. This is because JDBC encryption CSM uses Java Cryptography Provider, while other clients use OpenSSL libraries for encryption services. Java implementation of encryption algorithms is slower than C implementation.
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); |
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() |
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:
|
|
The message is meant to be displayed to the user and the user's response can be echoed back to the user. |
|
|
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). |
|
|
The message should be displayed to the user as an error, with no response required from the user. |
|
|
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.
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.
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:
import udtudrmgr.UDTManager;
import udtudrmgr.UDRManager;
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.
|
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. |
Please refer to the IBM Informix JDBC Driver Programmer's Guide, Version 2.21 for complete list of unsupported methods.
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).
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:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
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.
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.
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.
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.