Configuring TLS for the communication between primary and standby HADR servers

Transport Layer Security (TLS) is supported between the HADR primary and standby servers on environments that do not use IBM® Db2® pureScale®.

Before you begin

Configuring TLS on all instances

To use TLS for the transmission of transaction logs between HADR primary and standby, you need to configure Transport Layer Security (TLS) on all instances in HADR environment. The procedures are similar to the ones described in Configuring TLS support in a Db2 instance. In particular, the steps that describe how to set up your TLS key database and certificate must be done for all the instances. The steps for configuring the HADR environment by using a self-signed certificate are described in the following section.

Considerations for implementing TLS for HADR:

It is recommended to set SSL_VERSIONS and SSL_CIPHERSPECS configuration parameters to the same values on all HADR hosts. In particular, if SSL_VERSIONS is set to TLS 1.3 on any host, it is required that SSL_VERSIONS is set to TLS 1.3 on all hosts. This requirement is related to the use of certificates with SHA1 signature algorithms and it is not required if you are using SHA256 or later.
HADR peers that are running Db2 11.5.8 and later can make outbound TLS encrypted connections that support both TLS 1.2 and TLS 1.3. The TLS version that is chosen for the HADR connection is determined by the value that is set for the Database Manager configuration parameter SSL_VERSIONS on the HADR peer that is accepting the connection. While TLS 1.2 continues to be the default version, setting the SSL_VERSIONS value to TLS 1.1 or earlier resolves to TLS 1.2. This behavior is different in client/server TLS, where TLS 1.1 is the default and lowest version.
For more information about SSL_VERSIONS, see ssl_versions - Supported SSL versions at the server configuration parameter..
TLS 1.3 deprecates the use of SHA1 certificates unless it is for backwards compatibility. For this reason, SHA1 certificates are deprecated for HADR TLS when TLS 1.3 is enabled. SHA1 certificates continue to be supported in 11.5.8 when TLS 1.3 is enabled, but might not be supported in a future release. In addition, SHA224 certificates are no longer allowed.
It is possible to implement TLS via a shared key database. For example, the SSL_SVR_KEYDB and SSL_SVR_STASH configuration parameters on all instances are set to a shared location. When implementing TLS via a shared key database, it is important that the shared key database itself is also highly available to avoid having a single point of failure.
It is also possible to implement TLS on each instance via a separate key database. This can be done either by executing the same set of commands on each instance to set up TLS key database and certificate, or by creating the TLS key database and certificate on the first instance then copy them to the other instance(s).
When implementing TLS on each instance as a separate key database, it is important to have completed all certificate updates to the key databases on all instances prior to making use of those certifications in Db2.

An activated connection concentrator does not inhibit the use of TLS for HADR communications.

Prior to configuring TLS support, perform the following steps on each primary and standby in the HADR configuration

Ensure that the path to the IBM Global Security Kit (GSKit) libraries appear in the LIBPATH, SHLIB_PATH, or LD_LIBRARY_PATH environment variables on Linux® and UNIX operating systems. GSKit is automatically included when you install a Db2 database server product.

On UNIX and Linux operating systems, the GSKit libraries are located in sqllib/lib/gskit. On Linux platforms, the GSKit is installed locally when Db2 is installed. The GSKit libraries are located in sqllib/lib/gskit or sqllib/lib64/gskit. It is unnecessary to have another copy of GSKit installed in a global location to start the instance. If a global copy of GSKit does exist, keep the version of the global GSKit at the same version of the local GSKit.

For information about the GSKit tool GSKCapiCmd, see the GSKCapiCmd User Guide.

About this task

Configuring TLS support

The general steps for configuring TLS support are:

Create a key database on the primary and each standby instance to manage your digital certificates. These certificates and encryption keys are used for establishing the TLS connections.
Configure the Db2 instance for TLS support. This step is done by Db2 instance owner.
Configured TLS for the particular database for which TLS is to be used.

The procedure section details this configuration process for the communication between primary and standby HADR servers.

Restrictions

Table 1. TLS support between the HADR primary and standby servers:
Platform	Supported starting in Db2 Version
Linux on AMD64 and Intel EM64T	11.1.1.1
All other platforms	11.1.3.3

Procedure

Create a key database and set up your digital certificates on the primary and standby instances.
1. Use the gskcapicmd command to create your key database. The key database must be of a Certificate Management System (CMS) type (extension .kdb) or a Public-Key Cryptography Standards #12 (PKCS12) type (extension .p12). GSKCapiCmd is a non Java™ based command-line tool, and Java does not need to be installed on your system to use this tool.
  The gskcapicmd command is described in the GSKCapiCmd User's Guide. The path for the command is sqllib/gskit/bin on Linux and UNIX operating systems. On Linux and UNIX, ensure that the LIBPATH, SHLIB_PATH, or LD_LIBRARY_PATH environment variables include the proper GSKit library path, such as sqllib/lib64/gskit.
  
  For example, the following command creates a key database that is called myprimary.kdb and a stash file that is called myprimary.sth:
```
gsk8capicmd_64 -keydb -create -db "primary.kdb" -pw "myPrimaryPassw0rdpw0" -stash
```
  The -stash option creates a stash file at the same path as the key database, with a file extension of .sth. At instance start-up, GSKit uses the stash file to obtain the password to the key database.
  
  When you create a key database, it is automatically populated with signer certificates from a few certificate authorities (CAs), such as Verisign.
  Note: You should use strong file system protection on the stash file. By default, only the instance owner has read and write access to this file. Since this file is a user-managed file, it is not to be stored in the Db2 sqllib directory. Create a keystore directory under each instance's home directory to store the key database and stash files. For example,
  mkdir /home/test/keystore
2. Add a certificate for your primary instance to your key database. The standby instance sends this certificate to the primary instance during the TLS handshake to provide authentication for the standby instance. To obtain a certificate, you can either use the gskcapicmd command to create a new certificate request and submit it to a CA to be signed, or you can create a self-signed certificate. The following examples are for a self-signed certificate:
  To create a self-signed certificate with a label of myPrimarysigned, use the following gskcapicmd:
```
gsk8capicmd_64 -cert -create -db "primary.kdb" -pw "myPrimaryPassw0rdpw0" -label "myPrimarysigned" 
   -dn "CN=myhost.mycompany.com,O=myOrganization,OU=myOrganizationUnit,L=myLocation,ST=ON,C=CA"
```
  To use a CA signed certificate, you must obtain one, as described in Configuring TLS Support in a Db2 Server using a CA-signed certificate.
3. Extract the certificate that you created to a file so that you can distribute it to each standby instance.
  For example, the following gskcapicmd command extracts the certificate to a file called primary.arm:
```
gsk8capicmd_64 -cert -extract -db "primary.kdb" -pw "myPrimaryPassw0rdpw0" -label "myPrimarysigned" 
   -target "primary.arm" -format ascii 
```
4. Repeat steps 1.a through 1.c on each standby database.
  To create a keydb on the standby:
```
gsk8capicmd_64 -keydb -create -db "standby1.kdb" -pw "myStandby1Passw0rdpw0" -stash
```
  Create the certificate on the standby:
```
gsk8capicmd_64 -cert -create -db "standby1.kdb" -pw "myStandby1Passw0rdpw0" -label "myStandby1signed" 
   -dn "CN=myhost.mycompany.com,O=myOrganization,OU=myOrganizationUnit,L=myLocation,ST=ON,C=CA"
```
  Extract the standby certificate into a file called standby1.arm:
```
gsk8capicmd_64 -cert -extract -db "standby1.kdb" -pw "myStandby1Passw0rdpw0" -label "myStandby1signed" 
   -target "standby1.arm" -format ascii 
```
5. Repeat steps 1.a through 1.c on each standby database.
  To create a keydb on the standby:
```
gsk8capicmd_64 -keydb -create -db "standby1.kdb" -pw "myStandby1Passw0rdpw0" -stash
```
  Create the certificate on the standby:
```
gsk8capicmd_64 -cert -create -db "standby1.kdb" -pw "myStandby1Passw0rdpw0" -label "myStandby1signed" 
   -dn "CN=myhost.mycompany.com,O=myOrganization,OU=myOrganizationUnit,L=myLocation,ST=ON,C=CA"
```
  Extract the standby certificate into a file called standby1.arm:
```
gsk8capicmd_64 -cert -extract -db "standby1.kdb" -pw "myStandby1Passw0rdpw0" -label "myStandby1signed" 
   -target "standby1.arm" -format ascii 
```
Add the primary and standby certificates to the key database at each primary and standby instance.
1. FTP the file that contains the primary instance's certificate to the standby instance. This file was extracted in a previous step into a file called primary.arm. Also, FTP the file that contains the standby instance's certificate, standby1.arm, to the primary instance. Place these files into the directory where you created your key database on each instance.
2. Add the primary instance's certificate into the standby's key database.
  For example, the following gsk8capicmd command imports the certificate from the file primary.arm into the key database called standby1.kdb:
```
gsk8capicmd_64 -cert -add -db "standby1.kdb" -pw "myStandby1Passw0rdpw0" -label "myPrimarysigned" 
   -file "primary.arm" -format ascii 
```
3. On the primary instance, add the standby's certificate into the primary's key database.
  For example, the following gsk8capicmd command imports the certificate from the file standby1.arm into the key database called primary.kdb.
```
gsk8capicmd_64 -cert -add -db "primary.kdb" -pw "myPrimaryPassw0rdpw0" -label "myStandby1signed" 
   -file "standby1.arm" -format ascii 
```
4. If multiple standby databases exist, the certificate from each instance in the HADR configuration must be imported into the key database of each instance, in the same manner described in steps 2.a through 2.c.
Set up your Db2 instances for TLS support.
To set up your Db2 instances for TLS support, log in as the Db2 instance owner and set the following configuration parameters. This step must be done on the Db2 instance of the primary and all standby databases.
1. Set the ssl_svr_keydb configuration parameter to the fully qualified path of the key database file on the instance. For example, on the primary instance:
```
db2 update dbm cfg using SSL_SVR_KEYDB /home/test/keystore/primary.kdb
```
  On the standby instance:
```
db2 update dbm cfg using SSL_SVR_KEYDB /home/test/keystore/standby1.kdb
```
  If ssl_svr_keydb is null (unset) on any instance in the HADR configuration, TLS support fails.
  
  The paths do not have to be the same on the primary and each standby.
2. Set the ssl_svr_stash configuration parameter to the fully qualified path of the stash file. For example, on the primary instance:
```
db2 update dbm cfg using SSL_SVR_STASH /home/test/keystore/primary.sth
```
  On the standby instance:
```
db2 update dbm cfg using SSL_SVR_STASH /home/test/keystore/standby1.sth
```
  If ssl_svr_stash is null (unset) on any instance in the HADR configuration, TLS support fails.
  
  The paths do not have to be the same on the primary and each standby.
3. Restart each primary and standby Db2 instance.
```
db2stop
```
```
db2start
```
Optional: Set the TLS version. With Db2 11.5.8 and later, customers can choose between TLS 1.2 and TLS 1.3 for HADR by setting the value of the SSL_VERSIONS DBM configuration parameter. By default, HADR uses TLS 1.2. TLS 1.3 can be enabled in HADR by setting SSL_VERSIONS to the following value:
```
db2 update dbm cfg using SSL_VERSIONS TLSV13
```
For additional considerations when using TLS 1.3, see First steps in enabling TLS in Db2 servers and clients.
Enable TLS communications for each primary and standby database.
On the primary and each standby database, set the hadr_ssl_label database configuration parameter to the label of the digital certificate, which you added in steps 1 and 2. For example, on the primary database:
```
db2 update db cfg for db2db using HADR_SSL_LABEL myPrimarysigned
```
Where db2db is the database name and myPrimarysigned is the label that is created in step 1.

On the secondary database:
```
db2 update db cfg for db2db using HADR_SSL_LABEL myStandby1signed
```
If hadr_ssl_label is set for one primary or standby, then it must be set for all primary and standby databases in the configuration. If hadr_ssl_label is not set for all databases, then some HADR connections between primary and standby databases fail.

The label does not have to be the same on each primary and standby.

If the hadr_ssl_label is set, then both the ssl_svr_keydb and ssl_svr_stash must be set. If not, then HADR cannot be started, or some HADR connections between primary and standby databases fail.