Preparing for DigiCert G5 Certificate Migration

Steps

Timeline

Important Notice

Applications using default truststores or outdated GSKit versions may fail to connect after Db2 Warehouse SSL certificate update.

Why this matters?

The DigiCert G1 root CA will be distrusted on April 15, 2026. To avoid potential SSL connection issues, we will migrate from the current G1 certificate to the new DigiCert G5 certificate.

What’s changing and when?

• Certificate update window: From late February to March 2026, with expected completion in April 2026.
• Impact: Certificate update on backend is non-disruptive to Db2 workload but applications connecting to Db2 database needs to be ready for the new DigiCert G5 certificate.

Why you need to prepare?
The change may affect applications using SSL connections to Db2, depending on how SSL connection is implemented (e.g., JDBC or ODBC configuration).

Best Practices for SSL Connections

• Always use a custom truststore for production applications. Avoid relying on:
  • Default Java cacerts file
  • GSKit in-memory keystore
• Create a minimal truststore containing only the required root and intermediate certificates:
  • Use keytool (Java/JDBC) or gsk8capicmd (CLI/ODBC)
• Try not to modify system-wide truststores as they can be overwritten by system updates.

How to check if you use a custom truststore for SSL connection?

• ODBC/CLI: If you see SSLClientKeystoreDB setting in SSL connection string or in db2cli.ini/db2dsdriver.cfg, you use a custom truststore.
• JDBC: If you see sslTrustStoreLocation setting in SSL connection properties or in db2dsdriver.cfg, you use a custom truststore.
• CLP: If you see setting in "db2 get dbm cfg | grep -i SSL_CLNT_KEYDB", you use a custom truststore.

Customer Actions

1. If you already use a custom truststore (you followed best practice):

• Add the DigiCert G5 root certificate if it’s missing. As you already use a custom truststore, adding G5 root certificate to it will ensure your SSL connection works when the backend flips over to new G5 certificate.
• The G5 root certificate can be downloaded from DigiCert Digicert site. Search for "DigiCert TLS RSA4096 Root G5" and click "Download PEM" link. You can check the downloaded root certificate with: openssl x509 -noout -dates -issuer -subject -in DigiCertTLSRSA4096RootG5.crt.pem.
• Example commands to list and add/delete root certificates:

ODBC/CLI:

		$ gsk8capicmd_64 -cert -delete -db /ssl/keystore.kdb -pw changeit -label "DigiCert G5 TLS RSA4096 SHA384 2021 CA1" # this deletes an entry in keystore
		$ gsk8capicmd_64 -cert -add -db /ssl/keystore.kdb -pw changeit -label "DigiCert G5 TLS RSA4096 SHA384 2021 CA1" -file DigiCertTLSRSA4096RootG5.crt.pem  # this adds an entry in keystore
		$ gsk8capicmd_64 -cert -list -db /ssl/keystore.kdb -stashed  # this list all entries in keystore

JDBC:

		$ keytool -importcert -alias db2wh-g5 -keystore /ssl/jdbc_truststore.jks -storetype JKS -file DigiCertTLSRSA4096RootG5.crt.pem -storepass changeit
		$ keytool -list -v -keystore /ssl/jdbc_truststore.jks -storepass changeit | grep -e Issuer: -e Owner:
		Owner: CN=DigiCert TLS RSA SHA256 2020 CA1, O=DigiCert Inc, C=US
		Issuer: CN=DigiCert Global Root CA, OU=www.digicert.com, O=DigiCert Inc, C=US
		Owner: CN=DigiCert TLS RSA4096 Root G5, O="DigiCert, Inc.", C=US
		Issuer: CN=DigiCert TLS RSA4096 Root G5, O="DigiCert, Inc.", C=US
		$ keytool -delete -alias db2wh-g5 -keystore /ssl/jdbc_truststore.jks -storetype JKS -storepass changeit		
		

Error message if the root certificate is missing in the truststore:

		[IBM][CLI Driver] SQL30081N A communication error has been detected. Communication protocol being used: "SSL". Communication API being used: "SOCKETS". Location where the error was detected: "". Communication function detecting the error: "sqlccSSLSocketSetup". Protocol specific error code(s): "414", "", "". SQLSTATE=08001 SQLCODE=-30081

2. If you do NOT use a custom truststore (it's time to follow best practice to prepare for G5 certificate migration):

• Update your application to use one and include both G1 and G5 root certificates to support both certificates.
• Update your SSL connection string or configuration file to include the custom truststore location and credential.
• Example for SSL connection string with custom truststore using Python Db2 driver:

Python code:

		keystore_file = "/ssl_keystore/keystore.kdb"
		keystash_file = "/ssl_keystore/keystore.sth"

		conn_str = (
			f"DATABASE={database};"
			f"HOSTNAME={hostname};"
			f"PORT={port};"
			f"PROTOCOL=TCPIP;"
			f"UID={user};"
			f"PWD={password};"
			f"SECURITY=SSL;"
			f"SSLClientKeystoredb={keystore_file};"
			f"SSLClientKeyStash={keystash_file};"
		)

• Examples for ODBC, JDBC, and CLP connection:

ODBC/CLI:

		$ gsk8capicmd_64 -keydb -create -db "/ssl/keystore.kdb" -pw "changeit" -stash
		$ gsk8capicmd_64 -cert -add -db /ssl/keystore.kdb -pw changeit -label "DigiCert G5 TLS RSA4096 SHA384 2021 CA1" -file DigiCertCA.crt
		$ gsk8capicmd_64 -cert -list -db /ssl/keystore.kdb -stashed
		$ cat dsdriver/cfg/db2cli.ini # Use DNS alias for ODBC connection "DSN=BLUDB_SSL;UID=bluadmin;PWD=xxx;"
		[BLUDB_SSL]
		Database=bludb
		Protocol=tcpip
		Hostname=db2w-xxxxxxx.us-south.dev.db2w.cloud.ibm.com
		ServiceName=50001
		Security=SSL
		Authentication=SERVER
		SSLClientKeystoredb=/ssl/keystore.kdb # truststore location
		SSLClientKeyStash=/ssl/keystore.sth   # truststore credential

JDBC:

		$ keytool -importcert -alias db2wh-g5 -keystore /ssl/jdbc_truststore.jks -storetype JKS -file DigiCertCA-G5.crt -storepass changeit
		$ keytool -list -v -keystore /ssl/jdbc_truststore.jks -storepass changeit | grep -e Issuer: -e Owner:
		Owner: CN=DigiCert TLS RSA SHA256 2020 CA1, O=DigiCert Inc, C=US
		Issuer: CN=DigiCert Global Root CA, OU=www.digicert.com, O=DigiCert Inc, C=US
		Owner: CN=DigiCert TLS RSA4096 Root G5, O="DigiCert, Inc.", C=US
		Issuer: CN=DigiCert TLS RSA4096 Root G5, O="DigiCert, Inc.", C=US
		$ cat dsdriver/cfg/db2dsdriver.cfg # Use DSN alias in JDBC connection "jdbc:db2:MYBLU"
		<dsn alias="MYBLUDB" name="BLUDB" host="db2w-xxxxxxx.us-south.dev.db2w.cloud.ibm.com" port="50001">
    		<!-- Enable SSL -->
    		<parameter name="SecurityTransportMode" value="SSL"/>
    		<parameter name="sslTrustStoreLocation" value="/ssl/jdbc_truststore.jks"/> # truststore location
    		<parameter name="sslTrustStorePassword" value="changeit"/>                 # truststore credential
		</dsn>

CLP:

		Ensure SSL_CLNT_KEYDB is set, and both G1 and G5 root certificate are included in the keystore.
		$ db2 get dbm cfg | grep SSL_CLNT_KEYDB
		SSL client keydb file (SSL_CLNT_KEYDB) = /ssl/keystore.kdb
		$ gsk8capicmd_64 -cert -list -db /ssl/keystore.kdb -stashed
		Certificates found
		default, - personal, ! trusted, # secret key
		! "DigiCert G5 TLS RSA4096 SHA384 2021 CA1"
		! "CN=DigiCert G5 TLS RSA4096 SHA384 2021 CA1,O=DigiCert, Inc.,C=US"
		! "DigiCert TLS RSA SHA256 2020 CA1"
		! "CN=DigiCert Global Root CA,OU=www.digicert.com,O=DigiCert Inc,C=US"

• Test the change for the new custom truststore with gsk8capicmd_64 or keytool:
  Following steps ensure your SSL connection works with the new custom truststore.
  • Verify SSL connection works with G1 root certificate in truststore (currently backend has G1 certificate).
  • Verify SSL connection fails (negative test) if you remove G1 root certificate from the truststore.
  • After finishing testing, add back both G1 and G5 root certificates to the truststore and list the truststore to check both G1 and G5 root certificates are included.  This ensures your SSL connection works with both G1 and G5 certificates on backend.

3. If you rely on system-wide truststores (not recommended):

• For JDBC, ensure cacerts contains the G5 certificate. If not, add it to cacerts keystore: keytool -import -trustcacerts -alias digicerttlsrsa4096rootg5 -file /tmp/rootca -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit.

  Example check for JDBC cacerts keystore:

		$ keytool -list -v -keystore cacerts -storepass changeit | grep 'DigiCert TLS RSA4096 Root G5'
		Owner: CN=DigiCert TLS RSA4096 Root G5, O="DigiCert, Inc.", C=US
		Issuer: CN=DigiCert TLS RSA4096 Root G5, O="DigiCert, Inc.", C=US

• For ODBC/CLI, update DSDriver with the latest version in Fix Central.
• For CLP, update Client with the latest version in Fix Central.
• To download DSDriver or Client packages which support G5 certificate from IBM Fix Central:
  
  For Db2 v11.5.9:
  
  Platform: linuxamd64
  dsdriver
  odbc_cli
  client
  
  Platform: ntx64
  dsdriver
  odbc_cli
  client
  
  For Db2 v12.1.2 (select latest version):
  
  dsdriver
  client

4. Browser trust:

• Most browsers already include the DigiCert G5 root certificate. If not, add it manually or update your browser to the latest version.
  Example of Firefox:
  

5. REST API calls with private link

If you use REST APIs for database operations with AWS private link, please make sure that current G1 intermediate certificate specified in REST API call is replaced with G5 intermediate certificate after Console backend certificate is updated to G5 certificate. 

Example:

curl -v --cacert /tmp/cert-intermediate-g5.crt -X POST https://v3-staging-aws-lobster-console.eu-gb.dev.db2w.cloud.ibm.com/dbapi/v5/auth/tokens -H 'content-type: application/json' -H 'x-deployment-id: crn:bluemix:dashdb:us-south:a/fed38c86ec949101fd7b50edf9d6879b:v3-staging-aws-lobster::' -d '{"userid":"user1","password":"xxx"}'

Where cert-intermediate-g5.crt above contains G5 intermediate certificate.

The G5 intermediate certificate can be downloaded from DigiCert Digicert site. Search for "DigiCert G5 TLS RSA4096 SHA384 2021 CA1" and click "Download PEM" link. You can check the downloaded intermediate certificate with: openssl x509 -noout -dates -issuer -subject -in DigiCertG5TLSRSA4096SHA3842021CA1-1.crt.pem.

For certificate hostname validation to pass, the domain part of hostname in the URL above must match the domain in backend certificate (eu-gb.dev.db2w.cloud.ibm.com in above example).

6. Third-Party Tools

If you use third-party tools to connect to your database, ensure that their trust stores are updated to include the G5 root CA certificate so they can validate the new certificate chain. If custom trust store does not exist, add one so that the database connection in your third-party tool works for both G1 and G5 backend certificates.

Example of configuring DBeaver tool using one of the following methods (make sure correct trust store settings are applied for JDBC, ODBC, or CLP). Different third-party tools might have different naming for connection properties, but they should be similar for adding custom trust store settings. For instance, DBeaver uses 'Driver properties' and 'Cognos uses 'Advanced properties' in database connection settings.

• Add truststore settings in connection string/URL.
  
• Add truststore settings in driver properties.
  

7. Db2 Warehouse instance with G5 certificate for SSL connection testing

You can use this instance to test your custom truststore readiness.

hostname: v3-staging-lb-portrange.us-south.dev.db2w.cloud.ibm.com
port: 31193
user: any
password: any

Example:

db2cli validate -connstring "Database=bludb;Hostname=v3-staging-lb-portrange.us-south.dev.db2w.cloud.ibm.com;Port=31193;Security=SSL;SSLClientKeystoredb=/ssl_keystore/keystore-g5.kdb;SSLClientKeyStash=/ssl_keystore/keystore.sth;" -connect -user foo -passwd foo

• If you get invalid user/password error, it means your custom truststore passes certificate validation and it is good.

[FAILED]: [IBM][CLI Driver] SQL30082N Security processing failed with reason "24" ("USERNAME AND/OR PASSWORD INVALID"). SQLSTATE=08001

• If you get protocol error such as 414, it means the truststore does not have G5 root cert.  If you get 408 error, it means the truststore is not accessible.

[FAILED]: [IBM][CLI Driver] SQL30081N A communication error has been detected. Communication protocol being used: "SSL". Communication API being used: "SOCKETS". Location where the error was detected: "". Communication function detecting the error: "sqlccSSLSocketSetup". Protocol specific error code(s): "414", "", "". SQLSTATE=08001

8. Add custom truststore and configure the setting for federation

If you use Db2 federation, here are the steps to ensure it works with G5 and G1 certificates on backend:

• Create custom GSKit truststore containing both G1 and G5 root certificates on Db2 server where you created federated servers. For example:
  /mnt/blumeta0/ssl_keystore/keystore.kdb
/mnt/blumeta0/ssl_keystore/keystore.sth
  Make sure you have correct file permissions that allow DB2 instance user to read.
  Note: If the federated server is created in a Db2 Warehouse on Cloud instance, please open a ticket so that our support team can help with the truststore setup.
• Add SSL_KEYSTASH and SSL_KEYSTORE settings in federation server. For example:
  SELECT OPTION, SETTING FROM SYSCAT.SERVEROPTIONS WHERE SERVERNAME='SERVER_NAME';
ALTER SERVER SERVER_NAME OPTIONS (set SSL_KEYSTASH '/mnt/blumeta0/ssl_keystore/keystore.sth', set SSL_KEYSTORE '/mnt/blumeta0/ssl_keystore/keystore.kdb');