IBM Support

How can I generate my own 'tdsserverkey.kdb' keystore for TLSv12 communication and use it in a Rational Directory Server (Tivoli) deployment?

Question & Answer


Question

How can I generate my own tdsserverkey.kdb keystore for TLSv12 communication and use it in an IBM Rational Directory Server (Tivoli) deployment?

Cause

When you install Rational Directory Server and Rational DOORS, the keystores installed by default are the same for all installations anywhere in the world. To prevent any security threat due to the same keystore being shared across the world, you can generate your own keystore tdsserverkey.kdb and deploy it on your Rational Directory Server and Rational DOORS setup.

For TLS communications between a server and a client, a keystore with the certificates is necessary for a client-server handshake. These keystores tdsserverkey.kdb and tdsclientkey.kdb are located in the server and client locations. Both these keystores are provided as a part of Rational Directory Server and Rational DOORS installers and are installed in the Rational Directory Server and Rational DOORS installation locations. These keystores are the same for all installations that use Rational Directory Server and Rational DOORS.
  • RDS Tivoli variant (RDS 5.2.1 iFix11 onwards) is installed
  • GSKIT (GSKit 8.0.14.27 onwards) is installed
  • Tivoli Directory Server (TDS 6.3.0.34 onwards) or Security Directory Server (6.4.0.0 onwards) is installed

Answer

Generating your own keystore to use with a Rational Directory Server installation consists of the following:
  1. Generating a new tdsserverkey.kdb file
  2. Replace the above generated tdsserverkey.kdb with existing tdsserverkey.kdb
  3. Importing the server certificate to the tdsclientkey.kdb file
  4. Troubleshooting
A. Generating a new tdsserverkey.kdb file

To create the new .kdb keystore, you must execute the gsk#capicmd or gsk#cmd script.
These scripts are written in C and Java programming languages.

Note: The examples used in this document refer to the gsk#capicmd script but you can also use the gsk#cmd java script for all these operations.

The default location of the gsk#capicmd is as follows:
  • On Windows:  \Program Files\IBM\GSKIT#\bin\
  • On UNIX and Linux: /opt/ibm/GSKI#/bin

Procedure:
  1. Create a key database (CMS) to obtain the server certificate and private and public keys of the server.

    Note:If the command does not run successfully, review the Troubleshooting section.

    gsk#capicmd -keydb -create -populate [optional] -db <PATH\tdsserverkey.kdb> -pw <Server_password>  -type cms -stash [optional]

    where:
    PATH: Location where tdsserverkey.kdb is to be created
    Populate: Populates the key database with a number of predefined trusted CA certificates
    Server_password: Password that is to be set for the new keystore

    On successful completion of the command, the following four files are created:
    tdsserverkey.kdb: File that is the key database itself
    tdsserverkey.rdb: File used to store certificate requests
    tdsserverkey.crl: File used to hold the certificate revocation list
    tdsserverkey.sth: File stores encrypted version of the password

  2. Create a self-signed certificate.
    gsk#capicmd -cert -create -db <PATH/tdsserverkey.kdb> -pw <Server_password> -label TDSSRV_CERT -dn "CN=<HOSTNAME>" -default_cert yes -sigalg SHA256WithRSA -expire <Days> -size 2048

    where:
    TDSSRV_CERT: Label for Self-signed certificate. This name must not be changed
    HOSTNAME: To be updated with the Rational Directory Server server FQDN
    Days: Number of days for which the certificate is valid
    size: Indicates the size in bits for the encryption keys. The minimum recommended size is 2048
    sigalg: The hashing algorithm to be used during the creation of the self-signed certificate

  3. Verify that the TDSSRV_CERT certificate exists in keydb. 
    gsk#capicmd -cert -list -db <PATH/tdsserverkey.kdb> -pw <Server_password>

    Sample output:
    Entrust.net Secure Server Certification Authority
    Entrust.net Certification Authority (2048)
    Entrust.net Client Certification Authority
    Entrust.net Global Client Certification Authority
    Entrust.net Global Secure Server Certification Authority
    Entrust.net Certification Authority (2048) 29
    Entrust Root Certification Authority - EC1
    Entrust Root Certification Authority - EV
    Entrust Root Certification Authority - G2
    VeriSign Class 1 Public Primary Certification Authority
    VeriSign Class 2 Public Primary Certification Authority
    VeriSign Class 3 Public Primary Certification Authority
    VeriSign Class 1 Public Primary Certification Authority - G2
    VeriSign Class 2 Public Primary Certification Authority - G2
    VeriSign Class 3 Public Primary Certification Authority - G2
    VeriSign Class 4 Public Primary Certification Authority - G2
    VeriSign Class 1 Public Primary Certification Authority - G3
    VeriSign Class 2 Public Primary Certification Authority - G3
    VeriSign Class 3 Public Primary Certification Authority - G3
    VeriSign Class 4 Public Primary Certification Authority - G3
    Thawte Primary Root CA
    Thawte Primary Root CA - G2 ECC
    Thawte Server CA
    Thawte Premium Server CA
    Thawte Personal Basic CA
    Thawte Personal Freemail CA
    Thawte Personal Premium CA
    TDSSRV_CERT
  4. Extract the certificate and make it available on all client systems that securely communicate with the server.
    gsk#capicmd -cert -extract -db <PATH/tdsserverkey.kdb> -pw <Server_password> –label TDSSRV_CERT -target <Extract_Path/serverkey.arm> –format binary

    where:
    Extract_Path: Path where the serverkey.arm is to be extracted.

B. Replace the generated tdsserverkey.kdb file with the existing tdsserverkey.kdb file

Procedure:
  1. Make sure that the Rational Directory Server is running with the existing tdsserverkey.kdb file.
    The default location of the file is as follows:
    • On Windows: \Program Files\LDAP\V6.X\lib64\
    • On UNIX and Linux: /opt/ibm/ldap/V6.X/lib64/
  2. Rename existing tdsserverkey.kdb file to tdsserverkey_old.kdb.
  3. Copy the new tdsserverkey.kdb file in the lib64 directory.
  4. Create a registerpwd.ldif file with the following content:
    dn: cn=SSL,cn=Configuration
    changetype: modify
    replace:ibm-slapdsslkeydatabasepw
    ibm-slapdsslkeydatabasepw:<    PASSWORD>

    where:
    ​​​​​PASSWORD: Server_password specified when creating the keystore earlier (see step 1 in section A of this article).

  5. Register the password on Rational Directory Server by running the ldapmodify script.

    The default location of the ldapmodify script is as follows:

    • On Windows: \Program Files\LDAP\V6.X\bin\
    • On UNIX and Linux: /opt/ibm/ldap/V6.X/bin/
    ldapmodify -D "uid=tdsadmin,ou=people,dc=telelogic,dc=com" -w <Password> -i <Ldif_file_location> -p <PORT> -h <RDS_host_details>
    where:
    Password: tdsadmin password
    Ldif_File_location: location of the registerpwd.ldif file
    PORT: Rational Directory Server non-secure port number (default 1389)
    RDS_Host_Details: IP address of the host machine where the Rational Directory Server is installed

    After the command runs successfully, the following response is displayed:
    execution result:
    Operation 0 modifying entry cn=SSL,cn=Configuration
     
  6. Restart the Rational Directory Server.
  7. Store the registerpwd.ldif file to another location as security measure.
C. Importing the server certificate to the tdsclientkey.kdb file
For  Rational DOORS to communicate with Rational Directory Server in TLS mode, the tdsclientkey.kdb file is used as the client key. To use the existing client kdb file (tdsclientkey.kdb), delete the existing (older) TDSSRV_CERT certificate from the tdsclientkey.kdb file and import the TDSSERV_CERT certificate generated earlier (see section A of this article) to tdsclientkey.kdb file.

The default location of the tdsclientkey.kdb file is as follows:
\Program Files\IBM\Rational\DOORS\9.x\certdb\

Note: The password for the tdsclientkey.kdb file is fixed, that is tdskey4client.
For the  Rational DOORS and Rational Directory Server TLS to work correctly, this password must not be changed.

Procedure:
  1. Delete the existing certificate from the tdsclientkey.kdb file.
    gsk#capicmd -cert -delete -db <PATH/tdsclientkey.kdb> -pw tdskey4client -label TDSSRV_CERT
  2. Confirm that TDSSRV_CERT certificate is removed by listing the existing certificates in the tdsclientkey.kdb file.
    gsk#capicmd -cert -list -db <PATH/tdsclientkey.kdb> -pw tdskey4client
  3. Import the self-signed server certificate as a trusted signer into the client key database.
    gsk#capicmd -cert -add -db <PATH/tdsclientkey.kdb> -pw tdskey4client -label TDSSRV_CERT -file <Cert_Path/serverkey.arm>
    where:
    Cert_Path: Path is where the exported server certificate (serverkey.arm) is placed.
  4. List the certificates in the tdsclientkey.kdb file to verify that the new TDSSRV_CERT certificate is imported.
    gsk#capicmd -cert -list -db <PATH/tdsclientkey.kdb> -pw tdskey4client
    Sample output:
    Certificates in database: tdsclientkey.kdb
    TDSSRV_CERT
    Entrust.net Global Secure Server Certification Authority
    Entrust.net Global Client Certification Authority
    Entrust.net Client Certification Authority
    Entrust.net Certification Authority (2048)
    Entrust.net Secure Server Certification Authority
    VeriSign Class 3 Secure Server CA
    VeriSign Class 3 Public Primary Certification Authority
    VeriSign Class 2 Public Primary Certification Authority
    VeriSign Class 1 Public Primary Certification Authority
    VeriSign Class 4 Public Primary Certification Authority - G2
    VeriSign Class 3 Public Primary Certification Authority - G2
    VeriSign Class 2 Public Primary Certification Authority - G2
    VeriSign Class 1 Public Primary Certification Authority - G2
    VeriSign Class 4 Public Primary Certification Authority - G3
    VeriSign Class 3 Public Primary Certification Authority - G3
    VeriSign Class 2 Public Primary Certification Authority - G3
    VeriSign Class 1 Public Primary Certification Authority - G3
    Thawte Personal Premium CA
    Thawte Personal Freemail CA
    Thawte Personal Basic CA
    Thawte Premium Server CA
    Thawte Server CA
  5. Configure Rational DOORS to communicate with Rational Directory Server in TLS mode and ensure the Rational DOORS with Rational Directory Server communication is successful.
D. Troubleshooting
  • gsk#capicmd execution fails with the following error:

    The application has failed to start because gsk8km.dll was not found. Re-installing the application would resolve the problem.

    Resolution: Update the PATH
    • On Windows: Add <GSKIT install location>\gsk8\lib to the environment variable PATH
    • On UNIX and Linux: export PATH=/opt/ibm/gsk8/lib
 
  • 'gsk#cmd' execution fails with the following error:

    Failed to parse JAVA_HOME setting

    Resolution: Set the JAVA_HOME to point to JAVA installation location
    • On Windows: set JAVA_HOME=<JAVA install location>\java\jre
    • On UNIX and Linux: export JAVA_HOME=<Java install location>/java/jre
 

[{"Product":{"code":"SS4AKG","label":"Rational Directory Server"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"General Information","Platform":[{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"5.2.1","Edition":"","Line of Business":{"code":"LOB15","label":"Integration"}},{"Product":{"code":"SSKR2T","label":"IBM Engineering Requirements Management DOORS"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"Directory Server","Platform":[{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"","Edition":"","Line of Business":{"code":"LOB59","label":"Sustainability Software"}}]

Document Information

Modified date:
01 May 2020

UID

swg22000773

Page Feedback