______________________________________________________________________

Steps to import MCS SSL certificates on a Sametime Server

Securing LDAP connections to and from Sametime server using SSL

Author: Madhu S Dutta / Manoj Palaniswamy, IT Specialist

1|Page

______________________________________________________________________
Configuring security for the Lotus Sametime Community Server

Introduction:
IBM Global Security Kit (GSKit) provides Secure Sockets Layer (SSL) data encryption between Sametime
servers and the LDAP servers. The GSKit package also installs the iKeyman key management utility
(gsk7ikm), which you can use to create key databases, public-private key pairs, and certificate requests.
The IBM Lotus Sametime server uses the Internet and intranet security features of the Domino server on
which it is installed to authenticate Web browser users who access Domino databases on the server.
You can encrypt communications for Lotus Sametime Services and the communication between Lotus
Sametime and Web browsers. You can also encrypt communications between an LDAP server and the
Lotus Sametime server with the LDAPS protocol. You can set up either, or both, of these protocols
independently:
GSKit is required to provide SSL encryption between the Lotus Sametime server and LDAP server. This
document assumes that you already have secured the communication between your sametime server
and the LDAP server using SSL security. If you do not have GSKit installed, please follow the link to
install one - https://www-304.ibm.com/support/docview.wss?rs=203&uid=swg21099766
Please note that there is no configuration required from the Sametime server side either in the
sametime.ini or Sametime config files. By enabling LDAP (S) through the Sametime configuration
or DA, sametime server starts looking for the GSKit program and the *.kdb file which contains the
root certificates. There are no changes to be done on the domino side as well.

Procedure for enabling LDAP over SSL:

This procedure enables the Sametime server to trust the SSL server certificate of the LDAP server. To
ensure the Sametime server trusts the certificate of the LDAP server, the administrator must perform the
following procedures:

Install the Key Management Utility (IKeyMan) program on the Sametime server.

Create a key database on the Sametime server named "key.kdb" and store this database in the
root Sametime directory.

Ensure that the key.kdb database on the Sametime server contains the SSL trusted root certificate
that enables the Sametime server to trust the SSL server certificate of the LDAP server.
Note: Ensure you keep the name of the keystore database as key.kdb as we had experienced
issues when the name was changed.

How LDAP(S) works?

If the LDAP server is set up to listen for SSL connections, the LDAP server will include an SSL key
database that contains (at minimum) one certificate.
This certificate is:

A trusted root (or "signer") certificate signed by a specific Certificate Authority (CA), such as
VeriSign.

The LDAP server presents its SSL server certificate to the Sametime server during the SSL connection
handshake. The key database on the Sametime server ("key.kdb" created above) must contain a trusted
root (or "signer") certificate that matches the trusted root certificate for the CA that signed the LDAP
server certificate.

2|Page

______________________________________________________________________
For example, if the key database on the LDAP server contains a "VeriSign Class 4 Public Primary
Certification Authority" trusted root certificate and the LDAP SSL server certificate is signed by VeriSign,
the key database on the Sametime server must also contain a "VeriSign Class 4 Public Primary
Certification Authority" trusted root certificate.
In summary, the SSL connection from the Sametime server to the LDAP server should succeed if both of
the following are true:

The key database on the LDAP server and the key.kdb database on the Sametime server have a
trusted root (or "signer") certificate in common.

The trusted root certificate above is issued by the same CA that signed the LDAP SSL server
certificate.

When the key.kdb database is created, the database contains several trusted root (or "signer") certificates
by default. If the appropriate trusted root certificate exists in the key.kdb database by default, no other
procedures are required to ensure that the Sametime server trusts the LDAP server certificate. The
procedure required to ensure the Sametime server trusts the SSL certificate of the LDAP server is
complete. If there is any change in the trusted root certificate on the LDAP server, the same certificate
has to be imported into the key.kdb database in order for the SSL encryption to work. The below
procedure describes the steps required to import the trusted root certificate of the LDAP server into the
key.kdb keystore.
If the root certificates have expired or if there is some problem with the keystore database, you may
receive the error stating that the specified database has been corrupted.

If you experience this problem, you will have to create a new keystore database using the following steps:

Creating new key.kdb database:

To create the key.kdb database, follow the instructions below:
1. Start the IBM IKeyMan utility. To start the utility, run the gsk7ikm.exe file located in the
C:\Lotus\Domino\IBM\gsk7\bin directory on the Sametime server.

2. From

3|Page

the

IBM

IKeyMan

menu

bar,

select

Key

Database

File

->

New.

______________________________________________________________________

3. In the New window, do the following:

a. For Key database type, select "CMS key database file."
b. For File Name, enter "key.kdb."
c. For Location, enter "C:\Lotus\Domino" (or other directory in which Sametime is installed.)
d. Click OK.

4. In the Password prompt window, do the following:

a. Type a password and confirm the password used to access the key database. The password is
at your discretion.
b. Select the "Stash the password to a file?" check box.
c. Click OK.

5. In information window appears indicating the password is encrypted and saved in the location
C:\Lotus\Domino\key.sth (or <Sametime install directory>\key.sth).
6. Ensure you delete the old *.kdb, *.rdb, *.sth, *.jks, *.crl from the data folder.
After creating the key.kdb database, ensure the key.kdb database contains the appropriate trusted root
certificate. If the date and time is not set to the correct settings, certain certificates may not be inserted
correctly since the certificate may not be valid yet.

4|Page

______________________________________________________________________
Installing the trusted root into the KDB file

Sametime accepts certificates in Base-64 format and Binary formats only.

Ensure you receive the root certificates in the above format before installing them into the key
database

A pre-built .cer and .pem file should have been emailed to you when your certificate was issued.

Normally jre based applications (like Sametime application) does not have ability to import MCS
certificate automatically. You have to import certificate one by one by IKEYMAN utility if you have
multiple domains on your Sametime environment. So you should have IKEYMAN software
installed on your Sametime server.

1. Open Ikeyman .exe from domino directory to the path ibm\gsk7\bin

2. Double click gsk7ikm.exe

3. The IBM Key Management window will open as below

4. Click on open folder icon
5. It will open another window which will prompt for key file name and location of the file.

6. You should use the key.kdb which is located in Sametime domino directory. Then you navigate
the key.kdb file location as below.

5|Page

______________________________________________________________________
7. Click ok and it will prompt for password. Use the password for key.kdb file when you first time
created.

8. Once you click ok it will populate key database contents and you can identify what are the
certificates imported earlier or currently exists.

9. You can see the existing certificate status by clicking view edit button as below

6|Page

______________________________________________________________________

10. Then click Add button to import new certificate

7|Page

______________________________________________________________________
11. You will get CA certificate window from there you can browse .cer file by browse button

12. Browse the .cer file which you have received from LDAP Team

13. Its not mandatory to import .cer files from domino directory. You can copy the .cer and .pem files
anywhere in your system from there you can import.
14. Click OK and it will prompt for label for the certificate. You can type any name as per your
convenience.

15. Then click ok. It will propagate the new certificate in key Management console under signer
certificate as displayed in below screen shot.

8|Page

______________________________________________________________________

16. The following files are generated and please verify their existence on the data directory - key.kdb,
key.sth, key.crl, key.rdb and key.jks as below.

9|Page