By Jim Pickel, Gayathiri Chandran, Sarbinder Kallar, and Paul McWilliams.
With the release of IBM Data Server Driver for JDBC version 4.33, which ships with the IBM Db2 Connect 11.5.9 Java driver, the default security mechanism is changed to require encryption of credentials by default. Earlier releases use clear text user IDs and password by default. As a result, Db2 for z/OS development recommends that you review your IBM Data Server JDBC installations and Db2 for z/OS subsystems to prepare for the new security requirements.
For more information on the available JDBC driver and Db2 Connect levels, see Db2 JDBC Driver Versions and Downloads.
securityMechanism and encryptionAlgorithm property changes
If the securityMechanism property, and the encryptionAlgorithm property if used, are explicitly specified in your application environment, your applications are unaffected by the changes. However, it’s important to note that several methods can be used to specify these properties in your application environment. If used in combination they are applied in a specific priority order. For more information, see Properties for the IBM Data Server Driver for JDBC and SQLJ.
If the securityMechanism property is not explicitly specified, applications will now use the securityMechanism=Encrypted UserID and Encrypted Password (9) property, instead of the previous default, which was securityMechanism=Clear Text Userid and Password (3).
The default encrpyptionAlgorithm property is also changed to encryptionAlgorithm=2, instead of the previous default, which was encryptionAlgorithm=1. That is, if your application environment specifies one of following the securityMechanism property values, but it does not explicitly specify the encryptionAlgorithm property, applications will now use encryptionAlgorithm=2 by default.
- User ID, encrypted password (7)
- Encrypted user ID and password (9)
With encryptionAlgorithm=2, user IDs and passwords are protected on the network with 256-bit AES encryption.
For more information about these property values, see IBM Data Server Driver for JDBC and SQLJ configuration properties.
If your application uses one or more of the new default property values mentioned above for securityMechanism or encryptionAlgorithm, the change might be transparent to your Db2 environment. However, if the server and the driver are not set up to use 256-bit AES encryption, applications can start failing.
New default security requires ICSF
To support the new default security mechanism and algorithm, the Integrated Cryptographic Service Facility (ICSF) must be configured and started on each Db2 for z/OS subsystem. ICSF is a software element of z/OS. ICSF works with the hardware cryptographic features and the Security Server (RACF element) to provide secure, high-speed cryptographic services in the z/OS environment.
In this post, we summarize some of the items you should review to ensure a smooth deployment of this new level of the JCC driver. For example, the following situations will cause connections to fail.
- If ICSF is not started
- If the JDK used is enabled with FIPS 140-3
- If the JDK policy files expired
If ICSF is not started, you need to ensure the ICSF component is properly configured and started on all members. The crypto coprocessor requirement varies based on the z/OS version.
For more information, see ICSF Version and FMID Cross Reference. Db2 for z/OS uses the following ICSF functions that might require cryptographic hardware. For more information, about the hardware requirements, see the ICSF product documentation.
If the JDK is enabled with FIPS 140-3, you can revert to the old default, which is the clear text user ID and password security mechanism that flows credentials in clear text, by setting the driver to use the User ID and password (3) security mechanism. Another approach is to configure TLS on both the driver instance and the Db2 subsystems. For more information, see Configuring connections under the IBM Data Server Driver for JDBC and SQLJ to use SSL.
If the JDK policy files are expired, you must update the JDK security policy files. The IBM SDK provides both limited and unlimited strength JCE jurisdiction policy files. You can control which policy files to use. Policy files are used by the SecurityManager class to grant access to Java permissions. When you run a Java application with a security manager, if access to a resource is required but is not defined by a policy file, access is denied. For more information, see SDK Security policy files.
Examples of specifying the securityMechanism
If connections are failing, your application can explicitly set the desired securityMechanism property, and the encryptionAlgorithm property if applicable, instead of using the defaults. You can also continue with the previous behavior until you are ready for the new default security mechanism by explicitly specifying the driver properties as shown in the following examples.
Example 1: explicitly specifying the securityMechanism property in the driver properties configuration file
This example shows how to specify the previous default behavior in the JDBC driver configuration properties file. For more information, see Customization of IBM Data Server Driver for JDBC and SQLJ configuration properties.
db2.jcc.securityMechanism=3
Example 2: explicitly specifying securityMechanism in the driver configuration file
This example shows how to explicitly specify the previous default behavior in the global property configuration file.
<parameter name="securityMechanism" value="3"/>
The sample IBM data server driver configuration file, named db2dsdriver.cfg.sample, is included with IBM data server products. For more information, see securityMechanism IBM data server driver configuration keyword.
Example 3: explicitly specifying the securityMechanism with the DataSource interface
This example uses Data Source to explicitly specify clear text security in the securityMechanism property. See line 6 in the following example. For more information, see Connecting to a data source using the DataSource interface.
import java.sql.*; // JDBC base
import javax.sql.*; // Additional methods for JDBC
import com.ibm.db2.jcc.*; // IBM Data Server Driver for JDBC and SQLJ 1
// interfaces
DB2SimpleDataSource dbds=new DB2SimpleDataSource(); 2
dbds.setServerName("myhost"); 3
// Assign the server name
dbds.setPortNumber(5021); 4
// Assign the port number
dbds.setDatabaseName("mydb"); 5
// Assign the location name
dbds.setSecurityMechanism(DB2BaseDataSource.CLEAR_TEXT_PASSWORD_SECURITY); 6
// Specify desired security mechanism
dbds.setUser("dbadm");
// Assign the user ID
dbds.setPassword("dbadm");
// Assign the password
Connection con=dbds.getConnection(); 7
// Create a Connection object
Example 4: Specifying securityMechanism in the connection URL
The following example uses the driver manager specifies securityMechanism=3 in a URL for type 4 connectivity. For more information, see Connecting to a data source using the DriverManager interface with the IBM Data Server Driver for JDBC and SQLJ.
String url =
"jdbc:db2://sysmvs1.stl.ibm.com:5021/STLEC1" +
":user=dbadm;password=dbadm;securityMechanism=3;" ;
// Set URL for data source
Connection con =
java.sql.DriverManager.getConnection(url);
Troubleshooting common error situations
If the application fails with the following error, the failure might be due to restrictions on AES key size:
java.security.InvalidKeyException: Illegal key size
Try these solutions:
- Use OpenJDK (Java 9 or higher)
- If using Java 8, upgrade to Java 8 u162, or download and use the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for Oracle and IBM Java from the following links:
https://www.oracle.com/java/technologies/javase-jce-all-downloads.html
https://www.ibm.com/marketing/iwm/iwm/web/preLogin.do?source=jcesdk
https://docs.oracle.com/cd/E84221_01/doc.8102/E84237/index.htm?toc.htm?212338.htm
If the application fails with one of below error messages on z/OS console, it could be due to lack of ICSF setup:
DSNL045I - DSNLCICF ICSF CSNFPKE FUNCTION FAILED WITH RETCODE='0000000C'X AND RSNCODE='00002B34'X
DSNL046I - DSNLTSEC ICSF NOT ENABLED
Try the following solutions:
#Db2Znews
#Db2forz/OS
#JDBC