Technical Blog Post
Abstract
Do we need to restart Db2 after renewing the SSL certificate?
Body
When an SSL certificate used within Db2 is about to expire or has already expired, and you create a new one, database manager configuration options must be updated to have the new certificate take effect. The process to update the certificate depends on how the certificate is being used within Db2.
SSL Communication between a Db2 client and Db2 server
The SSL_SVR_LABEL database manager configuration parameter must be updated for the Db2 to recognize the new certificate and use the certificate for client/server communications.
In Db2 11.5.2 and later, refreshing the certificate used for client/server communications can be done without restarting the instance. To perform an online update, it is necessary to attach to the instance and update the value of SSL_SVR_LABEL:
db2 attach to <instance name>
db2 update dbm cfg using SSL_SVR_LABEL <new label>
Note: Db2 does not automatically refresh the certificate when the on-disk files change. If the new certificate uses the same label as the old certificate, it is still mandatory to run UPDATE DBM CFG. Running UPDATE DBM CFG with the current value of the SSL_SVR_LABEL parameter refreshes the certificate served by Db2. This step must be taken for the online update to occur.
Support for refreshing the certificate while the instance is running is also available in Db2 11.1.4.5 or later. To enable online update of SSL_SVR_LABEL in Db2 11.1 releases, the registry variable DB2_DYNAMIC_SSL_LABEL must be set to "ON". Updating the registry variable can be done while the instance is running with the -immediate option of db2set:
db2set -immediate DB2_DYNAMIC_SSL_LABEL=ON
Releases of Db2 before 11.1 Mod 4 Fix Pack 5 and 11.5.2 require Db2 to be recycled (db2stop/db2start) for the updated value of SSL_SVR_LABEL to take effect.
If the online update of SSL_SVR_LABEL was successful, the following message is returned.
DB20000I The UPDATE DATABASE MANAGER CONFIGURATION command completed
successfully.
If the update was not successful, an SQL1378N error message is returned. Check the diagnostic log for a message from sqlccSSLValidateServerCertificate for more information on why the certificate update failed. The following is an example message.
SQL1378N One or more of the parameters submitted for immediate modification
could not be changed dynamically and have been rolled back.
2022-01-16-13.35.26.142866-300 I26831E1107 LEVEL: Error
PID : 13542 TID : 139857036830464 PROC : db2sysc
INSTANCE: db2srv NODE : 000 DB :
APPHDL : 0-7 APPID: *LOCAL.db2srv.220116182918
AUTHID : DB2SRV HOSTNAME: db2srv
EDUID : 24 EDUNAME: db2agent (instance)
FUNCTION: DB2 UDB, common communication, sqlccSSLValidateServerCertificate, probe:4980
MESSAGE : Unable to update SSL_SVR_LABEL
DATA #1 : String, 61 bytes
rc, sslrc, sslFunction, errMsg, newLabel, notBefore, notAfter
DATA #2 : unsigned integer, 4 bytes
54
DATA #3 : unsigned integer, 4 bytes
407
DATA #4 : String, 21 bytes
gsk_get_cert_by_label
DATA #5 : String, 88 bytes
The specified certificate is not present in the SSL key store: myselfsigned_doesnt_exist
DATA #6 : String, 25 bytes
myselfsigned_doesnt_exist
DATA #7 : String, 0 bytes
Object not dumped: Address: 0x00007F3300FFAE90 Size: 0 Reason: Zero-length data
DATA #8 : String, 0 bytes
Object not dumped: Address: 0x00007F3300FFAF00 Size: 0 Reason: Zero-length data
If the online update feature is not enabled, or the current level of Db2 does not support the feature, an SQL1362W warning is returned by the command. Only the on-disk value of SSL_SVR_LABEL is updated in this scenario. The in-memory value of SSL_SVR_LABEL and the SSL certificate is changed the next time DB2 is restarted.
DB20000I The UPDATE DATABASE MANAGER CONFIGURATION command completed
successfully.
SQL1362W One or more of the parameters submitted for immediate modification
were not changed dynamically. Client changes will not be effective until the
next time the application is started or the TERMINATE command has been issued.
Server changes will not be effective until the next DB2START command.
To verify that the certificate update was successful, run db2 get dbm cfg show detail and ensure the Current Value (in-memory) and the Delayed Value (on-disk) of SSL_SVR_LABEL are identical.
$ db2 get dbm cfg show detail
Database Manager Configuration
Node type = Database Server with local clients
Description Parameter Current Value Delayed Value
------------------------------------------------------------------------------------------------------
...
SSL server certificate label (SSL_SVR_LABEL) = myselfsigned myselfsigned
A tool like openssl can also be used to check the certificate served by Db2. Replace <host> with the hostname or IP address of the Db2 server, and <port> with the port number corresponding to the SSL_SVCENAME database manager configuration parameter.
$ openssl s_client -connect <host>:<port> | openssl x509 -noout -text
depth=0 /CN=test2
verify error:num=18:self signed certificate
verify return:1
depth=0 /CN=test2
verify return:1
DONE
Certificate:
Data:
Version: 3 (0x2)
Serial Number:
52:8c:dd:84:0a:19:fd:f9
Signature Algorithm: sha256WithRSAEncryption
Issuer: CN=test2
Validity
Not Before: Jan 15 18:28:48 2022 GMT
Not After : Jan 16 18:28:48 2023 GMT
Subject: CN=test2
Documentation link for the SSL_SVR_LABEL database manager configuration parameter:
ssl_svr_label - Label in the key file for incoming SSL connections at the server configuration parameter
Step by step instructions:
Encryption of data in transit
SSL Communication between a Db2 server and a KMIP Key Manager
The SSL_KMIP_CLIENT_CERTIFICATE_LABEL parameter of the KMIP keystore configuration file must be updated for Db2 to use a new certificate for authentication to a KMIP key manager.
The Db2 instance must be recycled (db2stop/db2start) for the updated value of SSL_KMIP_CLIENT_CERTIFICATE_LABEL to take effect.
The Db2 instance must also be recycled for a new certificate to take effect if the new certificate uses the same label as the old certificate, and hence the same value of SSL_KMIP_CLIENT_CERTIFICATE_LABEL.
Documentation links for KMIP configuration:
Setting up a centralized KMIP keystore
Creating a KMIP keystore configuration file
UID
ibm11140274