Distributing the key database file

After creating the key database file and importing any required certificates, make the key database file and password stash file available to all clients that access the LDAP directory server.

The following variable is used in path names in this topic:
HCL_COMMON
Directory where HCL common files are installed

After you create the key database file and import any self-signed or new signer certificates from other Certificate Authorities into it, you must make the key database file and password stash file available to all clients that access the LDAP directory server. When HCL Compass attempts to authenticate a user against the LDAP directory server using SSL, it retrieves the appropriate signer certificate from the key database file. If HCL Compass cannot find the key database file and password stash file, it cannot authenticate the user.

Choose one of the following methods for making the key database file available for all clients:

  • Place the key database file and password stash file at a location that is accessible to all clients, such as a network share. When you configure the HCL Compass database set for LDAP authentication, you identify the location of the key database file and password stash file by specifying the -K option to the installutil setldapinit subcommand.
  • If you name the key database file and password stash file ldapkey.kdb and ldapkey.sth, respectively, you can distribute copies of both files to all clients and instruct the users to store the files in the default location: drive:\%HCL_COMMON% on Windows™ or $RATIONAL_COMMON on the UNIX™ system and Linux™.
  • Distribute the key database file and password stash file to all clients and instruct the users to store the files in a specific location. The location's path name must be the same on all client computers, including the drive letter. When you configure the HCL Compass database set for LDAP authentication, you identify the location of the key database file and password stash file by specifying the -K option to the installutil setldapinit subcommand.
  • Distribute the key database file and password stash file to all clients and let each user decide where to store the files on their computers. Each user must set the HCL_SSL_KEYRING environment variable to point to the key file name using the full path specification. For example, on Windows, the correct format for the file specification is drive:\%RATIONAL_COMMON%\ldapkey.kdb, and on the UNIX system and Linux, the correct format is $RATIONAL_COMMON/ldapkey.kdb.

It is possible to use a combination of these methods. For example, some clients might use the default location and other clients might use the HCL_SSL_KEYRING environment variable to identify the location of the files. HCL Compass uses the following algorithm to attempt to find the key database file and password stash file:

  1. If the HCL_SSL_KEYRING environment variable is set on the client computer, HCL Compass uses that location.
  2. If the HCL_SSL_KEYRING environment variable is not set, and you identified the location by specifying the -K option to the installutil setldapinit subcommand, HCL Compass uses that location.
  3. If the HCL_SSL_KEYRING environment variable is not set and you did not specify the -K option to the installutil setldapinit subcommand, HCL Compass looks in the default location for ldapkey.kdb and ldapkey.sth.