How to generate your own 'tdsserverkey.kdb' keystore and use it in Rational Directory Server (Tivoli) deployment

Technote (FAQ)


Question

How do you generate your own 'tdsserverkey.kdb' keystore and use it in IBM Rational Directory Server (Tivoli) deployment?

Cause

The keystores installed by default for Rational Directory Server and Rational DOORS 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-DOORS setup.
For SSL communications between a server and a client, a keystore with the certificates needed for client-server handshake must be used. These keystores are tdsserverkey.kdb and tdsclientkey.kdb are located in the server and the client location. Both these keystores are provided as a part of Rational Directory Server and DOORS installers and are installed in the Rational Directory Server and DOORS installation location. These keystores are same for any installation anywhere that uses Rational Directory Server and DOORS.

  • RDS Tivoli variant is installed (TDS 4.3 onwards)
  • Tivoli Directory Server is installed (TDS 6.1 onwards)
  • GSKIT 7/8 is installed

Answer

Generating your own keystore for use with a Rational Directory Server installation consists of the following steps:

  1. Generating a new tdsserverkey.kdb file
  2. Importing the server certificate to the tdsclientkey.kdb file
  3. Registering the new password generated for the tdsserverkey.kdb file in the Rational Directory Server database



A. Generating a new tdsserverkey.kdb file

To create the new .kdb keystore, the gsk#capicmd or gsk#cmd script must to be executed.

These two scripts are written in C and in Java.

The examples used in this document refer to the gsk#capicmd script but all these operations can be carried out by the gsk#cmd java script also.

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 contain the server certificates and private and public keys of the server.

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

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

    where:
    PATH: Location where tdskey4server.kdb is created
    Server_password: The password that is set for the new keystore

    On successful completion of the command, the following four files are created:
    • tdsserverkey.kdb -- This file is the key database itself
    • tdsserverkey.rdb -- This file is used to store certificate requests
    • tdsserverkey.crl -- This file is used to hold the certificate revocation list
    • tdsserverkey.sth -- This 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`,O=IBM,C= INDIA" -default_cert yes -expire <Days> -size 2048

    where:
    TDSSRV_CERT: Self-signed certificate with label name. This name must not be changed. -dn "CN=`hostname`,O=IBM,C= INDIA": Must not to be changed.
    Days: Number of days for which the certificate is valid
    size: indicates the size in bits for encryption keys. Minimum recommended is 2048

  3. Verify that the DSSRV_CERT certificate exists in keydb.

    gsk#capicmd -cert -list -db <PATH/tdsserverkey.kdb> -pw <Server_password>

    Sample output:

    Certificates in database: /var/adm/ras/SSLKey_SRV/serverkey.kdb
    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 Certificatdion 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 RSA Secure Server Certification Authority
    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. Importing the server certificate to the tdsclientkey.kdb file

For DOORS to communicate with Rational Directory Server in SSL mode, the tdsclientkey.kdb file is used as the client key to communicate with the server.

For the existing client kdb file (tdsclientkey.kdb) to work, delete the existing (older) TDSSRV_CERT certificate from the tdsclientkey.kdb file and import the TDSSERV_CERTcertificate, generated in section A, to it.

Note: The password for the tdsclientkey.kdb file is fixed and is tdskey4client.
For the DOORS-Rational Directory Server SSL 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 cert TDSSRV_CERT is removed. List 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 where the exported server certificate 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




C. Registering the new password generated for the tdsserverkey.kdb file in the Rational Directory Server database

Procedure:
  1. Make sure that Rational Directory Server is running with the older tdsserverkey.kdb file.

    The default location of the file is as follows:
    • On Windows: TDS install location/LDAP/V6.X/lib/
    • On UNIX and Linux: TDS install location/LDAP/V6.X/lib/

  2. Rename the tdsserverkey.kdb file to tdsserverkey_old.kdb.

  3. Put the newly generated tdsserverkey.kdb file in the lib directory.

  4. Create a test.ldif file with the following contents:

    dn: cn=SSL,cn=Configuration
    changetype: modify
    replace:ibm-slapdsslkeydatabasepw
    ibm-slapdsslkeydatabasepw:
    password

  5. Register the password on Rational Directory Server (ibmslapd.conf file with AES256 encryption) by running the ldapmodify script.

    The default location of the ldapmodify script is as follows:
    On Windows: TDS install location/LDAP/V6.X/bin/
    On UNIX and Linux: TDS install location/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: tdsamdin password
    Ldif_File_location: location of the test.ldif file
    PORT: RDS non-ssl port number
    RDS_Host_Details: IP address of the host machine where 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 Rational Directory Server.

  7. Configure DOORS to communicate with Rational Directory Server in SSL mode and ensure the DOORS-Rational Directory Server communication is successful.

    For more information of setting up SSL communicate between DOORS and Rational Directory Server, see the DOORS documentation.

  8. After the Rational Directory Server-DOORS setup is deployed successfully, store the test.ldif file to another location as a security measure.




Troublshooting
  • 'gsk#capicmd' execution fails with the following error:

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

    Resolution: Update the PATH
    On Windows: Add <GSKIT install location>\gsk7\lib to the environment variable PATH
    On UNIX and Linux: export PATH=/opt/ibm/gsk7/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

Cross reference information
Segment Product Component Platform Version Edition
Software Development Rational DOORS Directory Server Linux, Solaris, Windows

Rate this page:

(0 users)Average rating

Add comments

Document information


More support for:

Rational Directory Server
General Information

Software version:

4.3, 5.0, 5.1, 5.1.0.1, 5.1.0.2, 5.2, 5.2.0.1, 5.2.0.2, 5.2.1

Operating system(s):

Linux, Solaris, Windows

Reference #:

1509313

Modified date:

2014-05-14

Translate my page

Machine Translation

Content navigation