Secure Sockets Layer (SSL) is an industry-standard protocol that provides secure communication on the Internet using symmetric-key and public-key cryptography mechanisms. The SSL protocol runs above TCP/IP and below application protocols, such as Lightweight Directory Access Protocol (LDAP) and Hypertext Transfer Protocol (HTTP), and provides trust and privacy for the transport data. During the configuration of security settings for centralized databases, administrators may want to implement additional security measures for accessing the directory database. AIX supports SSL security over IBM Tivoli Directory Server (ITDS). After you install and configure the certificate, clients can communicate over both secure (636) and unsecured ports (389).
- The ITDS 6.0 fileset package should be installed and updated to the most current level.
- Install Global Security GSKit filesets.
- ITDS should be running with the default ldapdb2 instance, as shown below:
# ps -e | grep -E "[i]bmslapd|[i]bmdiradm" 503982 - 0:00 ibmdiradm 540812 pts/0 1:35 ibmslapd
In a normal LDAP connection, the client connects to port 389 and information exchange is in plain text. There is no way to guarantee that an LDAP client is connected to the right LDAP server. Hackers can infect your DNS or they could have installed their own server on the correct machine.
Using SSL with ITDS can potentially solve these vulnerabilities.
First of all, SSL can solve the problem of verifying that you are connected to the correct server. When the client and server connect, they perform a special SSL "handshake," part of which involves the server and client exchanging cryptographic keys, which are described using X.509 certificates. If the client wishes to confirm that it is connected to the correct server, he needs to verify the server's certificate, which is sent in the handshake. This can be done by checking that the certificate is signed (trusted) by someone that you trust, and that the certificate has not been revoked. For instance, the server's certificate may have been signed by Verisign (www.verisign.com), and you decide that you want to trust Verisign to sign legitimate certificates.
When SSL is enabled, data exchanged between the client and the LDAP registry is encrypted. Both server and client authentication are supported.
Configuring SSL for server authentication
For server authentication, the ITDS supplies the client with the ITDS X.509 certificate during the initial SSL handshake. If the client validates the server's certificate, as shown in Figure 1, then a secure, encrypted communication channel is established between the ITDS and the client application.
Figure 1. Configuring server authentication
Let's divide the server authentication shown in Figure 1 into two parts:
- Configuring IBM Tivoli Directory Server for SSL access
- Configuring IBM Tivoli Directory Server client for SSL access
Configuring IBM Tivoli Directory Server for SSL access
The following steps are required to enable SSL support for ITDS for server authentication:
- Create a key database (CMS) to contain the server certificates as well as the server's
private and public keys.
# gsk7cmd -keydb -create -db $SRVKEY_PATH/serverkey -pw $SRVKEY_PASSWD -type cms -stash
On successful completion of the above command, four files were created:
- serverkey.kdb -- This file is the key database itself.
- serverkey.rdb -- This file is used to store certificate requests.
- serverkey.crl -- This file is used to hold the certificate revocation list.
- serverkey.sth -- This file stores encrypted version of the password.
- Create a self-signed certificate and extract the certificate and make it available on
all client systems that securely communicate with the server.
# gsk7cmd -cert -create -db $SRVKEY_PATH/serverkey.kdb -pw $SRVKEY_PASSWD -label \ $SRV_LABEL -dn "CN=`hostname`,O=IBM,C= INDIA" -default_cert yes -expire 999
A self-signed certificate can be created and used only in test or in intranet environments. In production or Internet environments, obtain a commercial certificate from a recognized Certificate Authority (CA), such as Verisign.
Check the availability of SRV_CERT certificate inside keydb. See the code listing below.
# gsk7cmd -cert -list -db $SRVKEY_PATH/serverkey.kdb -pw $SRVKEY_PASSWD 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 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 RSA Secure Server Certification Authority -->SRV_CERT
- After you have created a self-signed certificate, you must extract the certificate for
use by client systems that securely communicate with the server:
# gsk7cmd -cert -extract -db $SRVKEY_PATH/serverkey.kdb -pw $SRVKEY_PASSWD –label \ $SRV_LABEL -target $EXTRACT_PATH/ serverkey.arm –format binary
- Once the key database is ready with the self-signed certificate, configure the directory server to use this certificate.
Create an LDIF, file.ldif, in the following format using a text editor.
dn: cn=SSL,cn=Configuration changetype: modify replace: ibm-slapdSslAuth ibm-slapdSslAuth: serverAuth - replace: ibm-slapdSecurity ibm-slapdSecurity: SSL dn: cn=SSL,cn=Configuration changetype: modify replace: ibm-slapdSSLKeyDatabase ibm-slapdSSLKeyDatabase: /var/adm/ras/SSLKey_SRV/serverkey.kdb - replace:ibm-slapdSslCertificate ibm-slapdSslCertificate: SRV_CERT - replace: ibm-slapdSSLKeyDatabasePW ibm-slapdSSLKeyDatabasePW: key4server
Present this LDIF file to the directory server now.
# idsldapmodify -D cn=admin -w admin -i file.ldif -p 389 modifying entry cn=SSL,cn=Configuration modifying entry cn=SSL,cn=Configuration
Look in the /home/ldapdb2/idsslapd-ldapdb2/etc/ibmslapd.conf file and notice the change in the entries denoted with arrows shown below.
dn: cn=SSL, cn=Configuration cn: SSL ibm-slapdSecurePort: 636 #ibm-slapdSecurity must be one of none/SSL/SSLOnly/TLS/SSLTLS -->ibm-slapdSecurity: SSL #ibm-slapdSslAuth must be one of serverAuth/serverClientAuth -->ibm-slapdSslAuth: serverAuth -->ibm-slapdSslCertificate: SRV_CERT ibm-slapdSslCipherSpec: AES ibm-slapdSslCipherSpec: AES-128 ibm-slapdSslCipherSpec: RC4-128-MD5 ibm-slapdSslCipherSpec: RC4-128-SHA ibm-slapdSslCipherSpec: TripleDES-168 ibm-slapdSslCipherSpec: DES-56 ibm-slapdSslCipherSpec: RC4-40-MD5 ibm-slapdSslCipherSpec: RC2-40-MD5 ibm-slapdSslFIPSProcessingMode: false -->ibm-slapdSslKeyDatabase: /var/adm/ras/SSLKey_SRV/serverkey.kdb ibm-slapdSSLKeyDatabasePW: {AES256}5+6hlNHZ8DFvhRRjmRP9GA== objectclass: top objectclass: ibm-slapdConfigEntry objectclass: ibm-slapdSSL
- You must stop and restart both the Tivoli Directory Server and the administration daemon for the
changes to take effect.
a. Stopping directory server. # ibmslapd -k -I "instance name" b. Stopping administrator daemon # ibmdirctl -h host_name -D ldap_admin -w ldap_pw admstop c. Starting administrator daemon # ibmdiradm "instance name" d. Starting directory server # ibmslapd -n -I "instance name"
Configuring the ITDS client for SSL access
After enabling SSL access on the LDAP server, you can set up SSL access on the client systems. Similar to creating a key database file for the server, you must create a key database file on the client system. Note that for the client to authenticate the LDAP server, the client must recognize the Certificate Authority (CA) that created the certificate for the LDAP server. If the LDAP server is using a self-signed certificate, the client must be enabled to recognize the system that generated the LDAP server's certificate as a trusted root (certificate authority).
To configure the LDAP client for SSL access to the LDAP server, complete the instructions below on the client machine:
-
Create a key database (CMS) file using GSKit key management utility.
# gsk7cmd -keydb -create -db $CLIKEY_PATH/clientkey -pw $CLIKEY_PASSWD \ -type cms -stash
-
Copy the extracted certificate file from the LDAP server to the client machine.
# rcp -r $LDAP_SERVER:$SRVKEY_PATH/EXTRACT/ $CLIKEY_PATH/
-
Import the server certificate (either from the CA or the self-signed one) as a trusted
signer into the client's key database.
Enter a label for the signer certificate that you are adding. If the certificate was created
by a certificate authority, you can use the name of the Certificate Authority as the label.
For a self-signed certificate, use the name of the LDAP server for the label.
# gsk7cmd -cert -add -db $CLIKEY_PATH/clientkey.kdb -pw $CLIKEY_PASSWD -label \ $LDAP_SERVER -file $CLIKEY_PATH/serverkey.arm
List the added certificate and verify.
# gsk7cmd -cert -list -db $CLIKEY_PATH/clientkey.kdb -pw $CLIKEY_PASSWD Certificates in database: /var/adm/ras/SSLKey_CLI/clientkey.kdb -->fluffy01 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 RSA Secure Server Certification Authority CLI_CERT
-
To test that SSL access has been enabled, enter the following command on the LDAP client system:
# idsldapsearch -h $LDAP_SERVER -Z -K $CLIKEY_PATH/clientkey.kdb -P $CLIKEY_PASSWD \ -b "" -s base objectclass=*
Since ITDS allows for multiple instances you will need to specify the port number if you are not using the default 636 secure port. Secure port 636 is listening for SSL requests on the LDAP server. Since the server has been enabled for both SSL and non-SSL requests, notice the value of 389, as well, in the above command output.
-
To set up the client to talk to the LDAP server using SSL, enter:
# mksecldap -c -h $LDAP_SERVER -a cn=admin -p admin -d o=ibm -k $CLIKEY_PATH/ \ clientkey.kdb -w $CLIKEY_PASSWD
In the final steps of the client setup, the mksecldap command starts the client-side daemon and adds an entry in the /etc/inittab file so the daemon starts at every reboot. You can check whether the setup is successful by checking the secldapclntd daemon process through the ls-secldapclntd command.
# ls-secldapclntd ldapservers=fluffy01 ldapport=636 ldapversion=3 userbasedn=ou=People,o=ibm groupbasedn=ou=Groups,o=ibm idbasedn=ou=system,o=ibm usercachesize=1000 usercacheused=0 groupcachesize=100 groupcacheused=0 usercachetimeout=300 groupcachetimeout=300 heartbeatT=300 numberofthread=10 connectionsperserver=10 alwaysmaster=no authtype=UNIX_AUTH searchmode=ALL defaultentrylocation=LDAP ldaptimeout=60 userobjectclass=posixaccount,account,shadowaccount,aixauxaccount, ibm-securityIdentities groupobjectclass=posixgroup,aixauxgroup
This step completes SSL for Server Authentication.
Configuring SSL for server and client authentication
This type of authentication provides a two-way handshake between the LDAP client and the LDAP server. A certificate must be established on the client system, so that after the client authenticates the server, the server requests the client's certificate and uses it to authenticate the client's identity.
Figure 2. Configuring server and client authentication
To establish a certificate for the client system, do the following:
-
Create the key database (CMS) file on the client.
# gsk7cmd -keydb -create -db $CLIKEY_PATH/clientkey -pw $CLIKEY_PASSWD -type cms -stash
-
Create a personal certificate and its associated private key on the key database. This personal certificate represents the
identity of the Tivoli Directory Server client system during SSL communications.
# gsk7cmd -cert -create -db $CLIKEY_PATH/clientkey.kdb -pw $CLIKEY_PASSWD -label \ $CLI_LABEL -dn "CN=`hostname`,O=IBM,C=INDIA"
List the certificates from keydb.# gsk7cmd -cert -list -db $CLIKEY_PATH/clientkey.kdb -pw $CLIKEY_PASSWD Certificates in database: /var/adm/ras/SSLKey_CLI/clientkey.kdb fluffy01 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 RSA Secure Server Certification Authority -->CLI_CERT
-
After you have created a self-signed certificate, you must extract the certificate for use on the LDAP server
system that will securely communicate with the client.
# gsk7cmd -cert -extract -db $SRVKEY_PATH/serverkey.kdb -pw $SRVKEY_PASSWD –label $SRV_LABEL -target $EXTRACT_PATH/ serverkey.arm –format binary
Once the client certificate has been extracted to a file, that file must be made available on the Tivoli Directory Server.
-
Now add the extracted client certificate inside the key database on the server system as a trusted signer.
FTP the client certificate to the server machine.
# gsk7cmd -cert -add -db $SRVKEY_PATH/serverkey.kdb -pw $SRVKEY_PASSWD \ -label $CLI_NAME -file $PATH/clientkey.arm
Enter a label for the certificate you are creating. If you are using self-signed certificate, use the client name for uniquenessList the certificates inside server keydb and verify the client certificate.
# gsk7cmd -cert -list -db $SRVKEY_PATH/serverkey.kdb -pw $SRVKEY_PASSWD Certificates in database: /var/adm/ras/SSLKey_SRV/serverkey.kdb -->charleston01 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 RSA Secure Server Certification Authority -->SRV_CERT
-
After the LDAP server recognizes the certificate authority that created the client's personal certificate,
test SSL access using the following command on the LDAP client.
# idsldapsearch -h server_name -Z -K $CLIKEY_PATH/clientkey.kdb -P \ $CLIKEY_PASSWD -N $CLI_LABEL -b "" -s base objectclass=*
SSL setup is now complete.
Certificate and key database maintenance
When you create a new key database, you specify a key database password. This password protects the private key and is the only key that can sign documents or decrypt messages encrypted with the public key. It is good practice to change the key database password frequently.
How to update an expired key database password
To change the database password, type:
# gsk7cmd -keydb -changepw -db $SRVKEY_PATH/serverkey.kdb -pw $SRVKEY_PASSWD \
-new_pw newpassw0rd -stash
|
You must also update the password inside the ibmslapd.conf file.
Search for the following keyword inside /home/ldapdb2/idsslapd-ldapdb2/etc/ibmslapd.conf and replace it with
the
new password in text format.
ibm-slapdSSLKeyDatabasePW: newpassw0rd |
You must restart the ibmslapd process to make the new password effective.
# ibmslapd -k; ibmslapd -n |
This code below shows how to display a list of certificates in a key database and their expiration dates:
# gsk7cmd -cert -list -expiry -db $CLIKEY_PATH/clientkey.kdb -pw \
$CLIKEY_PASSWD -type cms
Certificates in database: /var/adm/ras/SSLKey_CLI/clientkey.kdb
COFFEE
Validity
Not Before: Wed Nov 28 02:43:42 CST 2007
Not After: Fri Nov 30 02:43:42 CST 2007
VeriSign Class 2 OnSite Individual CA
Validity
Not Before: Mon May 18 19:00:00 CDT 1998
Not After: Mon Oct 12 18:59:59 CDT 2009
VeriSign International Server CA - Class 3
Validity
Not Before: Wed Apr 16 19:00:00 CDT 1997
Not After: Mon Oct 24 18:59:59 CDT 2011
Verisign Class 3 Public Primary Certification Authority - G2
Validity
Not Before: Sun May 17 19:00:00 CDT 1998
Not After: Tue Aug 01 18:59:59 CDT 2028
Verisign Class 2 Public Primary Certification Authority - G2
Validity
Not Before: Sun May 17 19:00:00 CDT 1998
Not After: Tue Aug 01 18:59:59 CDT 2028
|
Specifying the number of days is optional with -expiry, though when used it displays all certificates that expire within that amount of days. To list certificates that have already expired, enter the value 0.
Showing the entire certificate
To display the entire key entry, type the following:
# gsk7cmd -cert -details -showOID -db $CLIKEY_PATH/clientkey.kdb \
-pw $CLIKEY_PASSWD -label COFFEE
|
Resolving an expired certificate
Take the following steps if the certificate has expired:
- Create a new certificate on the LDAP server.
- Remove the expired certificate from your key store.
- Configure the LDAP server to use the new certificate.
- Restart ibmdiradm and ibmslapd.
- Extract the certificate and provide the new certificate to all client key stores.
IBM Tivoli Directory Server contains several tools in addition to the operating system tools to help you determine the source of problems you encounter.
Error logs record error messages that occur during directory server processing. IBM Tivoli Directory Server detects and saves these errors in a text file.
By default all logs are located under:
"instance home"/idsslapd-"instance name"/logs |
For the ldapdb2 instance, the configuration file and logs are located here:
# /home/ldapdb2/idsslapd-ldapdb2/etc/ibmslapd.conf
# /home/ldapdb2/idsslapd-ldapdb2/logs/
adminaudit.log bulkload.log db2clicmds.log ibmslapd.log
lostandfound.log audit.log db2cli.log ibmdiradm.log
idstools.log traceibmslapd.log
|
This is an example of what the log looks like:
11/16/07 06:50:30 GLPCTL115I Maximum data segment limit for the process (in bytes):
'1073741312'(Soft limit) and '-1'(Hard limit).
11/16/07 06:50:30 GLPCTL116I Maximum physical memory limit for the process
(in bytes): '1073741312'(Soft limit) and '-1'(Hard limit).
11/16/07 06:50:30 GLPSRV009I IBM Tivoli Directory (SSL), 6.0 Server started.
11/16/07 06:50:30 GLPSRV048I Started 15 worker threads to handle client requests.
|
Verify the key store repositories and certificates
Some of the common certificate issues are discussed below.
- Issue 1:
GLPCOM003I Non-SSL port initialized to 389. GLPCOM004I SSL port initialized to 636. GLPSSL002E File I/O error on opening SSL key database file $SRVKEY_PATH/serverkey.kdb. GLPSRV004I Terminating server.
If the SSL key database used by the LDAP directory and administration servers cannot be read or are not available, the above error bumps up. Verify the name and path to your key database file and update the ibmslapd.conf file to reflect the correct fully qualified path to the key database file. Restart the server.
- Issue 2:
# idsldapsearch -h `hostname` -Z -K SRVKEY_PATH/serverkey.kdb -P badpassw0rd \ -b "" -s base objectclass=* ldap_ssl_client_init failed! rc == 113, failureReasonCode == 408 Bad keyfile password
Check your key database password in this case.
- Issue 3:
# idsldapsearch -h `hostname` -Z -K $CLIKEY_PATH/badkey.kdb -P $CLIKEY_PASSWD \ -b "" -s base objectclass=* ldap_ssl_client_init failed! rc == 113, failureReasonCode == 202 Keyring file open error
Verify the client key database name. Or the specified client key database does not exist.
- Issue 4:
# idsldapsearch -h `hostname` -Z -K $CLIKEY_PATH/clientkey.kdb -P \ $CLIKEY_PASSWD -b "" -s base objectclass=* ldap_ssl_client_init failed! rc == 113, failureReasonCode == 102 Keyfile I/O error
The wrong client key database is specified. The client certificate cannot find the inside key database.
- Issue 5:
# mksecldap -c -h coffee -a cn=admin -p admin -d o=ibm -k $CLIKEY_PATH/clientkey.kdb \ -w $CLIKEY_PASSWD Cannot contact LDAP server coffee. client presetup check failed.
The ibmslapd process is not running on the server side. Start it using ibmslapd -n and retry.
During the configuration of security settings for the LDAP directory in AIX, administrators may want to implement additional security measures for accessing the ITDS. AIX provides SSL security, a certificate-based authentication mechanism over LDAP. This article gives you an overview of the SSL configuration for ITDS 6.0 on the AIX 5L operating system. A step-by-step command-line configuration procedure is explained for SSL key database creation, certificate creation, certificate extraction, understanding of SSL authentication mechanisms, troubleshooting for SSL issues, and methods for use against LDAP client-server communication.
Learn
- See the IBM
Tivoli Directory Server Messages Guide for a list of all informational, warning, and error messages associated with IBM Tivoli Directory Server 6.1.
-
IBM
Tivoli Directory Server product support provides technical self-help information to help troubleshoot technical problems with Tivoli
- See the LDAP client plug-in programming
reference guide for Possible
extended error codes returned by LDAP SSL function codes.
- The IBM Global Security Kit Secure Sockets
Layer Introduction and iKeyman User's Guide provides information for network or system security administrators who install,
administer, and use SSL-based systems.
- Read the developerWorks article LDAP configuration management and troubleshooting on AIX.
-
AIX Wiki: Discover a collaborative environment for technical information related to AIX.
Discuss
-
Participate in the AIX and UNIX forums:
- AIX 5L -- technical forum
- AIX for Developers Forum
- Cluster Systems Management
- IBM Support Assistant
- Performance Tools -- technical
- Virtualization -- technical
- More AIX and UNIX forums

Chethan Jain is a Staff Software Engineer in the IBM Bangalore office on the AIX UPT Release team. Chethan has been involved in AIX testing for over two years. He specializes in installation and configuration of Secure Sockets Layer (SSL), IBM Tivoli Directory Server (ITDS), and Tivoli Access Manager for Operating Systems (TAMOS) components on AIX. You can reach him at chetjain@in.ibm.com.



