IBM Tivoli Directory Server, Version 6.3

Secure Sockets Layer

IBM® Tivoli® Directory Server has the ability to protect LDAP access by encrypting data with Secure Sockets Layer (SSL) security. When using SSL to secure LDAP communications with IBM Tivoli Directory Server, both server authentication and client authentication are supported.

With server authentication, IBM Tivoli Directory Server must have a digital certificate (based on the X.509 standard). This digital certificate is used to authenticate IBM Tivoli Directory Server to the client application (such as the Directory Management Tool or idsldapsearch) or an application built from the application development package, for LDAP access over SSL.

For server authentication, IBM Tivoli Directory Server supplies the client with IBM Tivoli Directory Server's X.509 certificate during the initial SSL handshake. If the client validates the server's certificate, then a secure, encrypted communication channel is established between IBM Tivoli Directory Server and the client application.

For server authentication to work, IBM Tivoli Directory Server must have a private key and associated server certificate in the server's key database file.

Client authentication provides for two-way authentication between the LDAP client and the LDAP server.

With client authentication, the LDAP client must have a digital certificate (based on the X.509 standard). This digital certificate is used to authenticate the LDAP client to IBM Tivoli Directory Server. See Client authentication.

To conduct commercial business on the Internet, you might use a widely known Certification Authority (CA), such as VeriSign, to get a high assurance server certificate.

Securing your server with SSL

The following high-level steps are required to enable SSL support for IBM Tivoli Directory Server for server authentication. These steps assume you have already installed and configured IBM Tivoli Directory Server:

  1. Install the IBM GSKit package if it is not installed. See the IBM Tivoli Directory Server Version 6.3 Installation and Configuration Guide for information on installing the GSKit package.
    Notes:
    1. If the GSKIT_LOCAL_INSTALL_MODE environment variable is set to true, it allows user to use the GSKit version of their choice based on the path they set in LD_LIBRARY_PATH. If the environment variable is set, then the library using the path set in LD_LIBRARY_PATH, LIB, or LIBPATH is loaded. If this environment variable is not set, then the GSKit library installed on system (for example on UNIX based system: /usr/lib or /usr/lib64, etc) is loaded. This environment variable is supported only on the client server. All server side wrapper scripts explicitly unassign this variable.
    2. The GSKIT_CLIENT_VERSION environment variable is set to the major version of GSKit library. Using this environment variable, user can set the major version number of GSKit library that to use with Tivoli Directory Server. The name of the GSKit libraries change with the change in the major version number. For example, if the name of ssl library shipped with the GSKit 7 is gsk7ssl and with GSKit 8 is gsk8ssl. This environment variable is supported only on the client side. All server side wrapper scripts explicitly unassign this variable.
  2. Generate the IBM Tivoli Directory Server private key and server certificate using the ikeyman utility. The server's certificate can be signed by a commercial CA, such as VeriSign, or it can be self-signed with the ikeyman tool. The CA's public certificate (or the self-signed certificate) must also be distributed to the client application's key database file.
    Note:
    With Tivoli Directory Server version 6.3, GSkit version 8 is provided. The gskikm utility is not available with GSkit version 8.
  3. Store the server's key database file and associated password stash file on the server. The default path for the key database,<instance_directory>\etc directory, is a typical location.
  4. Access the Web-based LDAP administrative interface to configure the LDAP server. See Using Web Administration for the procedures.

If you also want to have secure communications between a master IBM Tivoli Directory Server and one or more replica servers, you must complete the following additional steps:

  1. Configure the replica directory server.
    Note:
    Follow the steps shown above for the master, except perform them for each replica. When configuring a replica for SSL, the replica is like the master with respect to its role when using SSL. The master is an LDAP client (using SSL) when communicating with a replica.
  2. Configure the master directory server.
    1. Add the replica's signed server certificate to the master directory server's key database file, as a trusted root. In this situation, the master directory is actually an LDAP client. If using self-signed certificates, you must extract all the self-signed certificates from each replica IBM Tivoli Directory Server, add them to the master's key database, and ensure they are marked as trusted-roots. Essentially, you are configuring the master as an SSL client of the replica server.
    2. Configure the master IBM Tivoli Directory Server to be aware of the replica server. Be sure to set the replicaPort attribute to use the port that the replica IBM Tivoli Directory Server uses for SSL communication.
  3. Restart both the master server and each replica server.
Notes:
  1. Only one key database is permitted per ldap server.
  2. User must provide the required permissions on the key database files for the instance owner for which the files will be used.
  3. For SSL setup in a replication environment, you can have a separate kdb file between supplier and consumer than the one used in the front end of supplier (under cn=SSL, cn=Configuration) to communicate with LDAP client in SSL mode.
  4. In case of Proxy Server, if the proxy server is configured for SSL communication with backend server, it uses the same kdb files specified in the server configuration file (under cn=SSL, cn=Configuration).
Setting Server authentication

For server authentication, you can modify the ibmslapd.conf file under the cn=SSL, cn=Configuration entry. To use the Web Administration Tool, see Using Web Administration.

To use the command line:

idsldapmodify -D <adminDN> -w <adminPW> -i <filename>

where <filename> contains:

dn: cn=SSL,cn=Configuration
changetype: modify
replace: ibm-slapdSSLAuth
ibm-slapdSSLAuth: serverAuth

You must restart the server and the administration server for the changes to take effect.

Server certificate from an external Certificate Authority (CA)

In order to provide a secure connection between IBM Tivoli Directory Server and its clients, the server must have an X.509 certificate and a private key.

The steps required to generate a private key, obtain the required server certificate from an external CA, and prepare them for use by IBM Tivoli Directory Server are outlined in the following:

  1. Logon as administrator or root.
    Note:
    If the administrator DN which was created during the server configuration process was cn=root, then enter the full administrator DN. Do not just use root.
  2. Change to the directory where you want to create the key database file and where your private key and certificate will be stored.
  3. Run ikeyman to create a new key database file. You can use any valid value for the key database file name that you want. Whatever file name you use, you need to provide it when configuring the LDAP server to use SSL. Consider providing a full path name. The ikeyman utility is used to generate a private-public key pair and a certificate request. See Using ikeyman for additional information.
    Note:
    By default, the new KDB created by GSKit is not readable by the server. You must change the owner to idsldap. 
    chown idsldap:idsldap <mykeyring>.*
    See the IBM Tivoli Directory Server Version 6.3 Problem Determination Guide for a more detailed explanation about the Kerberos service name change.
  4. If VeriSign is your external CA, obtain a certificate from VeriSign, as follows:
    1. Access the following VeriSign Web site: http://www.verisign.com/server/index.html.
    2. Click on IBM internet connection servers.
    3. After reviewing the information at this site, click on Begin.
    4. Provide the required information and follow the steps required to request your server certificate. VeriSign is the primary Certification Authority supported for obtaining externally generated, high-assurance server certificates.
  5. If you have another CA that you want to use, follow the directions for that CA to submit the contents of the certificate request file to them.

When you receive the resulting certificate from the CA:

  1. Logon using your server identity.
  2. Change to the directory where you created the key database file.
  3. Place the signed certificate from the CA into a file in this directory. The file is used in the next step.
  4. From the same directory, run ikeyman to receive the certificate into your key database file.
  5. Access the LDAP server's Web administrative interface, and configure the various SSL parameters, including the file specification for the key database file. See Using Web Administration.
  6. If you have more than one certificate in the key database file, the certificate you want to use for IBM Tivoli Directory Server must be the default.
  7. Start IBM Tivoli Directory Server.
Note:
If you instruct ikeyman to save the password in a password stash file, it is not necessary to change or set the password in the ibmslapd.conf file.

Using a self-signed server certificate

If you are using IBM Tivoli Directory Server in an intranet environment, use ikeyman to create your own server certificates. You can also use ikeyman to test IBM Tivoli Directory Server with SSL without purchasing a VeriSign high-assurance server certificate. These types of certificates are known as self-signed certificates.

Follow these steps to create a key database file using self-signed certificates.

  1. On each server:
    1. Change to the directory where you want to create the key database file and where your private key and certificate is to be stored.
    2. Create a new key database file and the self-sign certificate request that is to be used as your CA certificate.
      • Use the largest key size available.
      • Use a secure server certificate, not a low-assurance certificate.
    3. Obtain the certificate request file. The certificate is put into the key database file automatically by the ikeyman tool.
  2. If you are using an application created for the client, do the following on each client machine:
    1. Place the CA certificate request file in an accessible location on the client machine.
    2. Receive the CA certificate request file into the client's key database.
    3. Mark the received certificate as a trusted root.

See Using ikeyman for additional information.

Notes:
  1. You must always receive the CA certificate into the server's key database file and mark it as a trusted root before receiving the server certificate into the server's key database file.
  2. Whenever you use ikeyman to manage the IBM Tivoli Directory Server's key database file, remember to change to the directory in which the key database file exists.
  3. Each IBM Tivoli Directory Server must have its own private key and certificate. Sharing the private key and certificate across multiple IBM Tivoli Directory Servers increases security risks. By using different certificates and private keys for each server, security exposure is minimized if a key database file for one of the servers is compromised.

Setting up your LDAP client to access IBM Tivoli Directory Server

The following steps are required to create a key database file for an LDAP client that contains one or more self-signed server certificates that are marked as trusted by the client. The process can also be used to import CA certificates from other sources, such as VeriSign, into the client's key database file for use as trusted roots. A trusted root is simply an X.509 certificate signed by a trusted entity (for example VeriSign, or the creator of a self-signed server certificate), imported into the client's key database file, and marked as trusted.

  1. Copy the server's certificate file (cert.arm) to your client workstation.
  2. Run ikeyman to create a new client key database file or to access an existing one. For a new client key database, choose a file name associated with the client for ease of management. For example, if the LDAP client runs on Fred's machine, you might choose to name the file FRED.KDB.
  3. If adding a server's certificate to the existing client key database:
    1. Click Key database file and select Open.
    2. Enter the path and name of the existing key database file then click OK.
    3. Enter the password.
    4. Ensure signer certificates is chosen. Click Add.
    5. Enter the name and location of the server's certificate file.
    6. Enter a label for the server certificate entry in the client's key database file, for example, Corporate Directory Server, and then click OK.
  4. If creating the new Client key database:
    1. Click Key database file and select New.
    2. Enter the name and location for the new Client Key DataBase file, and then click OK.
    3. Enter the password.
    4. After the new client key database is created, repeat the previous steps for adding the server's certificate to the existing key database file.
  5. Exit ikeyman.

See Using ikeyman for additional information.

When the LDAP client creates a secure SSL connection with the server, it uses the server's self-signed certificate to verify that it is connecting to the proper server.

Repeat the preceding steps for each IBM Tivoli Directory Server that the LDAP client needs to connect to in a secure fashion.

Migrate the key ring file to key database file

To migrate the old key ring file that was created from MKKF utility:

  1. Start ikeyman.
  2. Click Key database file and select Open.
  3. Enter the path and filename of your key ring file and then click OK.
  4. Enter the password of your key ring file. If the key ring file is created without a password, you must use the old MKKF to assign a password for it.
  5. After the old key ring file is opened, click Key database file and select Save as.
  6. Ensure the key database type is set to CMS key database file. Fill out the name and location of the key database file, and then click OK.

Client authentication

Client authentication provides for two-way authentication between the LDAP client and the LDAP server.

With client authentication, the LDAP client must have a digital certificate (based on the X.509 standard). This digital certificate is used to authenticate the LDAP client to IBM Tivoli Directory Server.

The Simple Authentication and Security Layer (SASL) can be used to add authentication support to connection protocols. A protocol includes a command for identifying and authenticating a user to a server. It can optionally negotiate a security layer for subsequent protocol interactions.

After a server receives the authentication command or any client response, it may issue a challenge or indicate failure or completion. If a client receives a challenge it may issue a response or end the exchange, depending on the profile of the protocol.

During the authentication protocol exchange, the SASL mechanism performs authentication, transmits an authorization identity (known as userid) from the client to the server, and negotiates the use of a mechanism-specific security layer.

When the LDAP server receives an LDAP bind request from a client, it processes the request in the following order:

  1. The server parses the LDAP bind request and retrieves the following information:
  2. The server normalizes the DN retrieved from the request.
  3. The server retrieves any LDAP control included with the LDAP bind request.
  4. If the method of authentication is SASL, the server determines whether or not the SASL mechanism (specified in the request) is supported. If the SASL mechanism is not supported by the server, the server sends an error return code to the client and ends the bind process.
  5. If the SASL mechanism is supported (=EXTERNAL) and the SSL authentication type is server and client authentication, the server verifies that the client's certificate is valid, issued by a known CA, and that none of the certificates on the client's certificate chain are invalid or revoked. If the client DN and password, as specified in the ldap_sasl_bind, are NULL, then the DN contained within the client's x.509v3 certificate is used as the authenticated identity on subsequent LDAP operations. Otherwise, the client is authenticated anonymously (if DN and password are NULL), or the client is authenticated based on the bind information provided by the client.
  6. If the method of authentication is Simple, the server checks to see if the DN is an empty string or if there are no credentials.
  7. If the DN is an empty string, or if the DN or no credentials are specified, the server assumes that the client is binding anonymously and returns a good result to the client. The DN and authentication method for the connection are left as NULL and LDAP_AUTH_NONE respectively.
  8. If the client has not bound beforehand, and does not present a certificate during the bind operation, the connection is refused.
Setting client authentication

For client authentication, you can modify the ibmslapd.conf file under the cn=SSL, cn=Configuration entry. To use the Web Administration Tool, see Using Web Administration.

To use the command line:

idsldapmodify -D <adminDN> -w <adminPW> -i <filename>

where <filename> contains:

dn: cn=SSL,cn=Configuration
cn: SSL
changetype: modify
replace: ibm-slapdSSLAuth
ibm-slapdSSLAuth: serverClientAuth

You must restart the server and the administration server for the changes to take effect.

[ Top of Page | Previous Page | Next Page ]