Configuring MLz to connect to Db2 using an SSL secure port

Determining the Db2 secure port

To identify the secure port used by Db2:

From the SSDF System Command Extension, enter the following command:
```
-<Db2 subsystem> DISPLAY DDF
```

Review the command output. A sample is shown below:

DSNL080I -D200 DSNLTDDF DISPLAY DDF REPORT FOLLOWS:DSNL081I
STATUS=STARTD
DSNL082I LOCATION LUNAME GENERICLU
DSNL084I TCPPORT=446 SECPORT=9446 RESPORT=5003 IPNAME=-NONE
DSNL085I IPADDR=::127.0.0.1

Note: The value of SECPORT is the SSL secure port.

Using a certificate signed by a trusted certificate authority

If the Db2 certificate is signed by a trusted certificate authority, then only one additional JDBC property must be added to the JDBC URL:

sslConnection=true

Note: The port number must be changed to use the secure port.

Using a self-signed certificate

If the Db2 certificate is self‑signed, you must specify additional JDBC properties. You can work with a self‑signed certificate in multiple ways, such as adding the Java JVM cacerts file. This topic describes System z options. One option is to use JCERACFKS, a software‑based RACF keyring.

To use JCERACFKS, update the IBM_JAVA_OPTIONS property in the .profile file to include the required provider:

IBM_JAVA_OPTIONS="-Dfile.encoding=UTF-8  -Djava.protocol.handler.pkgs=com.ibm.crypto.zsecurity.provider"

Add the following JDBC properties using the MLz UI System Configuration page or the command line tool $IML_INSTALL_DIR/alnsamp/aln-sysconfig.sh:

sslTrustStoreType=JCERACFKS;
sslConnection=true;
sslTrustStorePassword=password;
sslTrustStoreLocation=safkeyring://SETUP/DB2RING;

Note:

password is a placeholder when using a SAF keyring.
The value for sslTrustStoreLocation is a placeholder.

Table 1. JCERACFKS Properties
Property	Value	Description
sslTrustStoreType	JCERACFKS	Software-based RACF keyring.
sslTrustStorePassword	password	Required placeholder value. Must be password.
sslTrustStoreLocation	safkeyring://SETUP/DB2RING	URL of the RACF keyring used by Db2 for SSL.
sslConnection	true	Enables SSL.

Connecting with hardware-based certificates

To use a hardware-based RACF keyring:

Add the CCA hardware provider to the ~/.profile . For example,

IBM_JAVA_OPTIONS="-Dfile.encoding=UTF-8 -
Djava.protocol.handler.pkgs=com.ibm.crypto.hdwrCCA.provider"

Use the following JDBC properties:

Table 2. JDBC properties
Property	Value	Description
sslTrustStoreType	JCECCARACFKS	Hardware-based RACF keyring.
sslTrustStorePassword	password	Required placeholder value. Must be password.
sslTrustStoreLocation	safkeyringhw://SETUP/DB2RING	URL of hardware-based SAF keyring.
sslConnection	true	Enables SSL.

Using Cloud Data Access

The JDBC URL that is updated in this process and the one in the Cloud Data Access (CDA) must match host, port, and location. However, the CDA version must not include optional parameters.

Example full JDBC URL in deploy.cfg

jdbc_url=jdbc:db2://host.company.com:9446/LOCATION1:currentSchema=USER1;sslTrustStoreType=JCERACFKS;sslConnection=true;sslTrustStorePassword=password;sslTrustStoreLocation=safkeyring://SETUP/DB2RING;

Example: CDA file entry in ~/gdk/gdkkeyf.json

Only include the base JDBC URL:


{ 
 "Credentials": [    
  {     
    "MVSUserID": "USER1",     
    "cloud provider": {       
      "ALN": [         
        {           
          "keylabelID": "A00000",           
          "name": "jdbc:db2://host.company.com:9446/LOCATION1",           
          "userid": "2334DD…",           
          "password": "9B2A…",           
          "timestamp": "2025-11-03 21:02:04"         
         }       
        ]     
       }   
      } 
    ]
   }

Updating JDBC properties from the command line

The $IML_INSTALL_DIR/alnsamp directory includes the aln-sysconfig.sh utility for updating Db2 JDBC configuration.

Usage

./aln-sysconfig.sh --jdbc_port  \ <port>  \
--jdbc_host <host name> \
--jdbc_options  "<JDBC options>" \ 
--jdbc_special_registers <registers>

You can specify each option individually.

Examples for configuring SSL secure port


./aln-sysconfig.sh --jdbc_port 9443
./aln-sysconfig.sh --jdbc_host myhost.mycompany.com
./aln-sysconfig.sh --jdbc_options
"sslTrustStoreType=JCERACFKS;sslConnection=true;sslTrustStorePassword=password
;sslTrustStoreLocation=safkeyring://SETUP/KEYRING"

Note: For the JDBC host name, specify the host name. Do not use an IP address.

When executed, the utility validates the Db2 connection, allowing you to quickly confirm both JDBC and CDA settings.

Obtaining certificates from Db2

Use the following command to display certificates used by the Db2 secure port:


openssl s_client -connect <hostname>:<secure port> -showcerts

For each certificate, copy the text between:

-----BEGIN CERTIFICATE-----
...certificate data...
-----END CERTIFICATE-----

You can:

Import the certificate into the Java cacerts file:
keytool -import -alias example -cacerts -file <path>
Or add it to a RACF keyring

RACF commands for Db2 certificates

Use the following RACF commands to grant access to the keyring used by Db2 for SSL:


RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID() ACCESS(READ)
SETROPTS RACLIST(FACILITY) REFRESH
RDEFINE RDATALIB userID..LST UACC(NONE)
PERMIT userID..LST CLASS(RDATALIB) ID(mlz_setup_userid) ACCESS(UPDATE)
SETROPTS CLASSACT(RDATALIB) RACLIST(RDATALIB)
SETROPTS RACLIST(RDATALIB) REFRESH