Directory Server, Version 6.1

 

Securing directory communications

This section describes the steps necessary for keeping the data in your directory secure.

 

Configuring security settings

The IBM® Tivoli® Directory Server has the ability to protect LDAP access by encrypting data with either Secure Sockets Layer (SSL) security or Transaction Layer Security (TLS) or both. When using SSL or TLS to secure LDAP communications with the IBM Directory, both server authentication and client authentication are supported. See Secure Sockets Layer and Transaction Layer Security for more information.

To use SSL or TLS have GSKit installed on your system. Before we can use SSL or TLS first use GSKit to create the key database file and certificates. See Using gsk7ikm.

 

Using Web Administration:

Do the following:

  1. Go to the Web Administration console.

  2. Click Server administration.

  3. Click Manage security properties.

  4. Click Settings.

  5. Enable the type of security connections, select one of the following radio buttons:

    None

    Enables the server to receive only unsecure communications from the client. The default port is 389.

    SSL

    Enables the server to receive either secure (default port 636) or unsecure (default port 389) communications from the client. The default port is 636.

    SSL only

    Enables the server to receive only secure communications from the client. This is the most secure way to configure your server. The default port is 636.

    TLS

    Enables the server to receive secure and unsecure communications from the client over the default port, 389. For secure communications the client must start the TLS extended operation. See Transaction Layer Security for more information.

    SSL and TLS

    Enables the server to receive secure and unsecure communications from the client over the default port, 389. For secure communications on the default port, the client must start the TLS extended operation. The server also receives secure communications over the SSL port, 636. See Transaction Layer Security for more information.
    Notes:

    1. The TLS and the SSL and TLS options are only available if your server supports TLS.

    2. TLS and SSL do not interoperate. Sending a start TLS request over the secure port results in an operations error.

  6. Select the authentication method.

    You must distribute the server certificate to each client. For server and client authentication you also must add the certificate for each client to the server's key database.Select the radio button for either:

    Server authentication

    For server authentication the IBM Tivoli Directory Server supplies the client with the 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 the IBM Tivoli Directory Server and the client application.

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

    Server and client authentication

    This type of 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 the IBM Tivoli Directory Server. See Client authentication.

  7. When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit, or click Cancel to exit this panel without making any changes.

  8. You must stop and restart both the IBM Tivoli Directory Server and the administration daemon for the changes to take effect.

    1. Stop the server. See Starting and stopping the server , if we need information about performing this task.

    2. Stop the administration daemon using one of the following methods.

      • Remotely, issue the command: 
        ibmdirctl -D <adminDN> -w <adminPW> admstop

      • Locally issue the command: 
        idsdiradm <instancename> -k
      See Stopping an instance of the directory administration daemon , if we need information about performing this task.

    3. Start the administration daemon. This must be done locally.

      • Issue the command: 
        idsdiradm <instancename>
      See Starting an instance of the directory administration daemon , if we need information about performing this task.

    4. Start the server. See Starting and stopping the server , if we need information about performing this task.

 

Using the command line:

To use the command line to configure SSL communications, issue the command: 

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

where <filename> contains: 

dn: cn=SSL,cn=Configuration
changetype: modify
replace: ibm-slapdSslAuth
ibm-slapdSslAuth: {serverAuth | serverClientAuth}
-
replace: ibm-slapdSecurity
ibm-slapdSecurity: {none | SSL | SSlOnly | TLS | SSLTLS}

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

 

Transaction Layer Security

Transport Layer Security (TLS) is a protocol that ensures privacy and data integrity in communications between the client and server.

TLS is composed of two layers:

The TLS Record Protocol

Provides connection security with data encryption methods such as the Data Encryption Standard (DES) or RC4 without encryption. The keys for this symmetric encryption are generated uniquely for each connection and are based on a secret negotiated by the TLS Handshake Protocol. The Record Protocol can also be used without encryption.

The TLS Handshake Protocol

Enables the server and client to authenticate each other and to negotiate an encryption algorithm and cryptographic keys before data is exchanged.

TLS is invoked by using the -Y option from the client utilities.

TLS and SSL are not interoperable. Issuing a start TLS request (the -Y option) over an SSL port causes an operations error.

 

Secure Sockets Layer

The 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 the IBM Directory, both server authentication and client authentication are supported.

With server authentication, the IBM Tivoli Directory Server must have a digital certificate (based on the X.509 standard). This digital certificate is used to authenticate the 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 the IBM Tivoli Directory Server supplies the client with the 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 the IBM Tivoli Directory Server and the client application.

For server authentication to work, the 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 the 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 Directory for server authentication. These steps assume you have already installed and configured the IBM Tivoli Directory Server:

  1. Install the IBM Directory GSKit package if it is not installed. See the IBM Tivoli Directory Server Version Installation and Configuration Guide for information on installing the GSKit package.

  2. Generate the IBM Tivoli Directory Server private key and server certificate using the gsk7ikm utility (installed with GSKit). The server's certificate can be signed by a commercial CA, such as VeriSign, or it can be self-signed with the gsk7ikm tool. The CA's public certificate (or the self-signed certificate) must also be distributed to the client application's key database file.

  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, complete the following additional steps:

  1. Configure the replica directory server.

    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, 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.

Only one key database is permitted per ldap server.

Setting Server authentication

For server authentication, we 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 daemon for the changes to take effect.

 

Server certificate from an external Certificate Authority (CA)

In order to provide a secure connection between IBM Directory 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 the IBM Directory are outlined in the following:

  1. Logon as administrator or root.

    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 gsk7ikm 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, we need to provide it when configuring the LDAP server to use SSL. Consider providing a full path name. The gsk7ikm utility is used to generate a private-public key pair and a certificate request. See Using gsk7ikm for additional information.

    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.1 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 gsk7ikm 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 Directory must be the default.

  7. Start the IBM Directory.

If you instruct gsk7ikm 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 the IBM Directory in an intranet environment, use gsk7ikm to create your own server certificates. We can also use gsk7ikm to test IBM Directory 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 gsk7ikm 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 gsk7ikm 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 gsk7ikm 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 Directory

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 gsk7ikm 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 gsk7ikm.

See Using gsk7ikm 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 gsk7ikm.

  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, 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 the 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:

    • The DN that the client is attempting to authenticate as.

    • The method of authentication used.

    • Any credentials, such as a password included in the request.

    • If the method of authentication is SASL, the server also retrieves the name of the SASL mechanism used from the LDAP bind request.

  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, we 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 daemon for the changes to take effect.

 

Using gsk7ikm

The following key-management program, gsk7ikm, is provided with the IBM Global Security Kit (GSKit). It is a user-friendly GUI for managing key files, implemented as a Java™ applet.

If you are prompted to set JAVA_HOME, we can set it to either the system-installed Java or the Java version included with the IBM Tivoli Directory Server. If you use the IBM Tivoli Directory Server version, you also need to set the LIBPATH environment variable as follows: 

export LIBPATH=$JAVA_HOME/bin:$JAVA_HOME/bin/classic:$LIBPATH

Use gsk7ikm to create public-private key pairs and certificate requests, receive certificate requests into a key database file, and manage keys in a key database file.

When setting up Secure Sockets Layer communications, ensure that you use the correct key database file type for your application. For example, Java-based applications such as the Web Administration Console require .jks file types, while C-applications like the IBM Tivoli Directory Server require .cms key database file types.

The tasks we can perform with gsk7ikm include:

 

Creating a key pair and requesting a certificate from a Certificate Authority

If your client application is connecting to an LDAP server that requires client and server authentication, then we need to create a public-private key pair and a certificate.

If your client application is connecting to an LDAP server that requires only server authentication, it is not necessary to create a public-private key pair and a certificate. It is sufficient to have a certificate in your client key database file that is marked as a trusted root. If the Certification Authority (CA) that issued the server's certificate is not already defined in your client key database, we need to request the CA's certificate from the CA, receive it into your key database, and mark it as trusted. See Designating a key as a trusted root.

Your client uses its private key to sign messages sent to servers. The server sends its public key to clients so that they can encrypt messages to the server, which the server decrypts with its private key.

To send its public key to a server, the client needs a certificate. The certificate contains the client's public key, the Distinguished Name associated with the client's certificate, the serial number of the certificate, and the expiration date of the certificate. A certificate is issued by a CA, which verifies the identity of the client.

The basic steps to create a certificate that is signed by a CA are:

  1. Create a certificate request using gsk7ikm.

  2. Submit the certificate request to the CA. This can be done using e-mail or an online submission from the CA's Web page.

  3. Receive the response from the CA to an accessible location on the file system of your server.

  4. Receive the certificate into your key database file.

If you are obtaining a signed client certificate from a CA that is not in the default list of trusted CAs, we need to obtain the CA's certificate, receive it into your key database and mark it as trusted. This must be done before receiving your signed client certificate into the key database file.

To create a public-private key pair and request a certificate:

  1. Start the gsk7ikm Java utility by typing: 
    gsk7ikm

  2. Select Key database file.

  3. Select New (or Open if the key database already exists).

  4. Specify key database file name and location. Click OK.

    A key database is a file that the client or server uses to store one or more key pairs and certificates.

  5. When prompted, supply a password for the key database file. Click OK.

  6. Select Create.

  7. Select New certificate request.

  8. Supply user-assigned label for key pair. The label identifies the key pair and certificate in the key database file.

  9. If you are requesting a low-assurance client certificate, enter the common name. This must be unique and the full name of the user.

  10. If you are requesting a high-assurance secure server certificate, then:

    • Enter the X.500 common name of the server. Usually this is the TCP/IP fully qualified host name, for example, www.ibm.com. For a VeriSign server certificate, it must be the fully qualified host name.

    • Enter the organization name. This is the name of your organization. For a VeriSign secure server certificate, if you already have an account with VeriSign, the name in this field must match the name on that account.

    • Enter the organizational unit name. This is an optional field.

    • Enter the locality/city where the server is located. This is an optional field.

    • Enter a three-character abbreviation of the state/province where the server is located.

    • Enter the postal code appropriate for the server's location.

    • Enter the two-character country code where the server is located.

  11. Click OK.

  12. A message identifying the name and location of the certificate request file is displayed. Click OK.

  13. Send the certificate request to the CA.

    If this is a request for a VeriSign low assurance certificate or secure server certificate, e-mail the certificate request to VeriSign.

    We can mail the low assurance certificate request to VeriSign immediately. A secure server certificate request requires more documentation. To find out what VeriSign requires for a secure server certificate request, go to the following URL: http://www.verisign.com/server/index.html.

  14. When you receive the certificate from the CA, use gsk7ikm to receive it into the key database where you stored the key pair. See Receiving a certificate into a key database.

Change the key database password frequently. If you specify an expiration date, we need to keep track of when we need to change the password. If the password expires before you change it, the key database is not usable until the password is changed.

 

Receiving a certificate into a key database

After receiving a response from your CA, we need to receive the certificate into a key database.

To receive a certificate into a key database:

  1. Type gsk7ikm to start the Java utility.

  2. Select Key database file.

  3. Select Open.

  4. Specify the key database file name and location. Click OK.

  5. When prompted, supply a password for the key database file. Click OK.

  6. Select Create.

  7. Select Personal certificates in the middle window.

  8. Click Receive.

  9. Enter the name and location of the certificate file that contains the signed certificate, as received from the CA. Click OK.

 

Changing a key database password

To change a key database password:

  1. Type gsk7ikm to start the Java utility.

  2. Select Key database file.

  3. Select Open.

  4. Specify the key database file name and location. Click OK.

  5. When prompted, supply the password for the key database file. Click OK.

  6. Select Key database file.

  7. Select Change password.

  8. Enter <New password>.

  9. Confirm <New password>.

  10. Select and set an optional password expiration time.

  11. Select Stash the password to a file? if you want the password to be encrypted and stored on disk.

  12. Click OK.

  13. A message is displayed with the file name and location of the stash password file. Click OK.

The password is important because it protects the private key. The private key is the only key that can sign documents or decrypt messages encrypted with the public key.

 

Showing information about a key

To show information about a key, such as its name, size or whether it is a trusted root:

  1. Type gsk7ikm to start the Java utility.

  2. Select Key database file.

  3. Select Open.

  4. Specify a key database file name and location. Click OK.

  5. When prompted, supply the password for the key database file. Click OK.

  6. To see information about keys designated as Personal certificates:

    • Select Personal certificates at the top of the Key database content window.

    • Select a certificate.

    • Click View/Edit to display information about the selected key.

    • Click OK to return to the list of Personal Certificates.

  7. To see information about keys that are designated as Signer Certificates:

    • Select Signer certificates at the top of the Key database content window.

    • Select a certificate .

    • Click View/Edit to display information about the selected key.

    • Click OK to return to the list of Signer Certificates.

 

Deleting a Key

To delete a key:

  1. Type gsk7ikm to start the Java utility.

  2. Select Key database file.

  3. Select Open.

  4. Specify key a database file name and location. Click OK.

  5. When prompted, supply the password for the key database file. Click OK.

  6. Select the type of key you want to delete at the top of the Key database content window (Personal certificates, Signer certificates, or Personal certificate requests).

  7. Select a certificate.

  8. Click Delete.

  9. Click Yes to confirm.

 

Making a key the default key in the key ring

The default key must be the private key that the server uses for its secure communications.

To make a key the default key in the key ring:

  1. Type gsk7ikm to start the Java utility.

  2. Select Key database file.

  3. Select Open.

  4. Specify a key database file name and location. Click OK.

  5. When prompted, supply the password for the key database file. Click OK.

  6. Select Personal certificates at the top of the Key database content window.

  7. Select the desired certificate.

  8. Click View/Edit.

  9. Select the Set the certificates as the default box. Click OK.

 

Creating a key pair and certificate request for self-signing

By definition, a secure server must have a public-private key pair and a certificate.

The server uses its private key to sign messages to clients. The server sends its public key to clients so they can encrypt messages to the server, which the server decrypts with its private key.

The server needs a certificate to send its public key to clients. The certificate contains the server's public key, the distinguished name associated with the server's certificate, the serial number of the certificate, and the expiration date of the certificate. A certificate is issued by a CA, who verifies the identity of the server.

We can request one of the following certificates:

  • A low assurance certificate from VeriSign, best for non-commercial purposes, such as a beta test of your secure environment

  • A server certificate to do commercial business on the Internet from VeriSign or some other CA

  • A self-signed server certificate if you plan to act as your own CA for a private Web network

For information about using a CA such as VeriSign to sign the server certificate, see Creating a key pair and requesting a certificate from a Certificate Authority.

The basic steps to creating a self-signed certificate are:

  1. Type gsk7ikm to start the Java utility.

  2. Select Key database file.

  3. Select New, or Open if the key database already exists.

  4. Specify a key database file name and location. Click OK.

    A key database is a file that the client or server uses to store one or more key pairs and certificates.

  5. When prompted, supply the password for the key database file. Click OK.

  6. Click New self-signed.

  7. Supply the following:

    • User-assigned label for the key pair. The label identifies the key pair and certificate in the key database file.

    • The desired certificate Version.

    • The desired Key Size.

    • The X.500 common name of the server. Usually this is the TCP/IP fully qualified host name, for example, www.ibm.com.

    • The organization name. This is the name of your organization.

    • The organizational unit name. This is an optional field.

    • The locality/city where the server is located. This is an optional field.

    • A three-character abbreviation of the state/province where the server is located.

    • The zip code appropriate for the server's location.

    • The two-character country code where the server is located.

    • The Validity Period for the certificate.

  8. Click OK.

 

Exporting a key

If we need to transfer a key pair or certificate to another computer, we can export the key pair from its key database to a file. On the other computer, we can import the key pair into a key ring.

To export a key from a key database:

  1. Type gsk7ikm to start the Java utility.

  2. Select Key database file.

  3. Select Open.

  4. Specify a key database file name and location. Click OK.

  5. When prompted, supply the password for the key database file. Click OK.

  6. Select Personal certificates at the top of the Key database content window.

  7. Select the desired certificate.

  8. Click Export/Import.

  9. For Action type, select Export key.

  10. Select the Key file type:

    The IBM Tivoli Directory Server requires .cms key database file types.

    • PKCS12 file

    • CMS Key database file

    • Keyring file (as used by mkkf)

    • SSLight key database class

  11. Specify a file name.

  12. Specify the location.

  13. Click OK.

  14. Enter the required password for the file. Click OK.

 

Importing a key

To import a key into a key ring:

  1. Type gsk7ikm to start the Java utility.

  2. Select Key database file.

  3. Select Open.

  4. Specify the key database file name and location. Click OK.

  5. When prompted, supply the password for the key database file. Click OK.

  6. Select Personal certificates at the top of the Key database content window.

  7. Select the desired certificate.

  8. Click Export/Import.

  9. For Action type, select Import key.

  10. Select the desired Key file type.

    When setting up Secure Sockets Layer communications, ensure that you use the correct key database file type for your application. For example, Java-based applications such as the Web Administration Console require .jks file types, while C-applications like the IBM Tivoli Directory Server require .cms key database file types.

  11. Enter the file name and location.

  12. Click OK.

  13. Enter the required password for the source file. Click OK.

 

Designating a key as a trusted root

A trusted root key is the public key and associated distinguished name of a CA. The following trusted roots are automatically defined in each new key database:

  • Integrion Certification Authority Root

  • IBM World Registry™ Certification Authority

  • Thawte Personal Premium CA

  • Thawte Personal Freeemail CA

  • Thawte Personal Basic CA

  • Thawte Premium Server CA

  • VeriSign Test CA Root Certificate

  • RSA Secure Server Certification Authority

  • VeriSign Class 1 Public Primary Certification Authority

  • VeriSign Class 2 Public Primary Certification Authority

  • VeriSign Class 3 Public Primary Certification Authority

  • VeriSign Class 4 Public Primary Certification Authority

Each of these trusted roots are initially set to be trusted roots by default.

To designate a key as a trusted root:

  1. Type gsk7ikm to start the Java utility.

  2. Select Key database file.

  3. Select Open.

  4. Specify a key database file name and location. Click OK.

  5. When prompted, supply the password for the key database file. Click OK.

  6. Select Signer certificates at the top of the Key database content window.

  7. Select the desired certificate.

  8. Click View/Edit.

  9. Check the Set the certificate as a trusted root box, and click OK.

  10. Select Key database file and then select Close.

 

Removing a key as a trusted root

A trusted root key is the public key and associated distinguished name of a CA. The following trusted roots are automatically defined in each new key database:

  • Integrion Certification Authority Root

  • IBM World Registry Certification Authority

  • Thawte Personal Premium CA

  • Thawte Personal Freeemail CA

  • Thawte Personal Basic CA

  • Thawte Premium Server CA

  • VeriSign Test CA Root Certificate

  • RSA Secure Server Certification Authority

  • VeriSign Class 1 Public Primary Certification Authority

  • VeriSign Class 2 Public Primary Certification Authority

  • VeriSign Class 3 Public Primary Certification Authority

  • VeriSign Class 4 Public Primary Certification Authority

Each of these trusted roots are initially set to be trusted roots by default.

To remove the trusted root status of a key:

  1. Type gsk7ikm to start the Java utility.

  2. Select Key database file.

  3. Select Open.

  4. Specify the key database file name and location. Click OK.

  5. When prompted, supply the password for the key database file. Click OK.

  6. Select Signer certificates at the top of the Key database content window.

  7. Select the desired certificate.

  8. Click View/Edit.

  9. Clear the Set the certificate as a trusted root box. Click OK.

  10. Select Key database file and then select Close.

 

Requesting a certificate for an existing key

To create a certificate request for an existing key:

  1. Type gsk7ikm to start the Java utility.

  2. Select Key database file.

  3. Select Open.

  4. Specify the key database file name and location. Click OK.

  5. When prompted, supply the password for the key database file. Click OK.

  6. Select Personal Certificates at the top of the Key database content window.

  7. Select the desired certificate.

  8. Click Export/Import.

  9. For Action type, select Export key.

  10. Select the desired Data type:

    • Base 64-encoded ASCII data

    • Binary DER data

    • SSLight Key Database Class

  11. Enter the certificate file name and location.

  12. Click OK.

  13. Select Key database file and then select Close.

Send the certificate request to the CA.

If this is a request for a VeriSign low assurance certificate or secure server certificate, e-mail the certificate request to VeriSign.

We can mail the low assurance certificate request to VeriSign immediately. A secure server certificate request requires more documentation. To find out what VeriSign requires for a secure server certificate request, go to the following URL: http://www.verisign.com/server/index.html.

 

Migrating a key ring file to the key database format

The gsk7ikm program can be used to migrate an existing key ring file, as created with mkkf, to the format used by gsk7ikm.

To migrate a key ring file:

  1. Type gsk7ikm to start the Java utility.

  2. Select Key database file.

  3. Select Open.

  4. Specify the key database file name and location. Click OK.

  5. When prompted, supply the password for the key ring file. Click OK.

  6. Select Key database file.

  7. Select Save as....

  8. Select CMS key database file as the Key database type.

  9. Specify a file name.

  10. Specify location.

  11. Click OK.

 

Setting the key database

To set the key database, use one of the following procedures.

 

Using Web Administration:

If you have not done so already, click Server administration in the Web Administration navigation area and then click Manage security properties in the expanded list. Next, click the Key database tab.

  1. Specify the Key label. This administrator-defined key label indicates what part of the key database to use.

  2. Specify the Key database path and file name. This is the fully qualified file specification of the key database file. If a password stash file is defined, it is assumed to have the same file specification, with an extension of .sth.

  3. Specify the Key password. If a password stash file is not being used, the password for the key database file must be specified here. Then specify the password again in the Confirm password field.

  4. When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit, or click Cancel to exit this panel without making any changes.

In order for the server to use this file, it must be readable by the user ID ldap. See the IBM Tivoli Directory Server version 6.1 Problem Determination Guide for information about file permissions.

 

Using the command line:

To use the command line to set the key database for SSL and TLS, issue the command: 

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

where <filename> contains: 

dn: cn=SSL,cn=Configuration
changetype: modify
replace: ibm-slapdSSLKeyDatabase
ibm-slapdSSLKeyDatabase: <databasename>
-
replace: ibm-slapdSSLKeyDatabasePW
ibm-slapdSSLKeyDatabasePW: <password>
-
replace: ibm-slapdSslKeyRingFilePW
ibm-slapdSslKeyRingFilePW: <password>

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

 

PKCS#11

PKCS#11 is an interface that enables an LDAP user to use crypto hardware. Using PKCS#11, an LDAP user can use the crypto hardware to securely store the key database file and accelerate cryptographic operations as well. The PKCS#11 interface can be used to configure the following types of crypto devices:

  • Accelerators: These devices are usually connected to the host by a permanent connection such as a card slot or a LAN connection. The primary purpose of an accelerator is to increase the number of cryptographic operations per second for a server. Private key storage is maintained in an SSL KDB (Key Database) file, which is loaded into the accelerator as needed. This type of device should be considered for use when the objective is to increase the number of cryptographic operations only and stronger hardware protection of the server's private key is not a concern.

  • Key storage with accelerators: These devices are primarily for server applications where cryptographic performance is an issue and stringent security of the server's private key is also essential. The private key and certificate are stored on the device. If a cryptographic operation requires use of the private key, the hardware device uses the key locally on the adapter. The application can never access the key in an un-encrypted format. These devices usually employ tamper-resistant procedures to protect external access to the key.

 

How to configure the server to use PKCS#11 interface

The directory server can be configured to use the PKCS#11 interface under the entry "dn: cn=SSL, cn=Configuration".

 

Using Web Administration:

Expand the Server administration category in the navigation area of the Web Administration Tool and click Manage security properties tab. Next, click the PKCS#11 settings tab. The PKCS#11 settings panel is displayed. This panel is displayed only if the root DSE search on ibm-supportedCapabilities returns the PKCS#11 interface support OID 1.3.18.0.2.32.67.

For the settings specified in this panel to take effect, you must select the Enable PKCS#11 interface support check box in the Settings panel under Manage security properties category.

To set PKCS#11 interface supported hardware:

  1. Select the Enable crypto hardware key storage check box to specify the key storage location as the crypto hardware.

  2. Select the required acceleration facility of the crypto hardware by selecting the Symmetric cipher, Digest, or Random data generator check box.

    We can select one or more check boxes under the Accelerator mode options section.

  3. In the Crypto hardware library path and file name text box, specify the library path of the crypto hardware driver to be accessed using the PKCS#11 interface.

  4. In the Token password text box, specify the password to be used for accessing the crypto hardware slot.

  5. In the Confirm password text box, reenter the password.

  6. In the Token label text box, specify the token label of the crypto hardware's slot to be accessed.

  7. When you are finished, do one of the following:

    1. Click OK to apply your changes and exit this panel.

    2. Click Apply to apply your changes and stay on this panel.

    3. Click Cancel to exit this panel without making any changes.

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

 

Using the command line:

To configure the server to use PKCS#11 interface using the command line, issue the following command: 

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

where <filename> contains:

dn: cn=ssl,cn=configuration
changetype: modify
replace: ibm-slapdSecurity
ibm-slapdSecurity: SSLOnly
-
replace: ibm-slapdSslAuth
ibm-slapdSslAuth: serverauth
-
replace: ibm-slapdSslCertificate
ibm-slapdSslCertificate: tlabel1
-
replace: ibm-slapdSslPKCS11Enabled
ibm-slapdSslPKCS11Enabled: True
-
replace: ibm-slapdSslPKCS11Lib
ibm-slapdSslPKCS11Lib: /opt/nfast/toolkits/pkcs11/libcknfast.so
-
replace: ibm-slapdSslPKCS11Keystorage
ibm-slapdSslPKCS11Keystorage: true
-
replace:  ibm-slapdSslPKCS11TokenLabel
ibm-slapdSslPKCS11TokenLabel: OpCard
-
replace: ibm-slapdSslPKCS11TokenPW
ibm-slapdSslPKCS11TokenPW: PASSWORD

 

Setting the level of encryption for SSL and TLS communications

By default the SSL and TLS versions of IBM Tivoli Directory Server uses the following list of ciphers when performing cipher negotiation with the client (during the SSL or TLS handshake).

Although the password policy feature is not available in configuration only mode, we can change your level of password encryption in configuration only mode.

 

Using Web Administration:

Expand the Server administration category in the navigation area in the Web Administration Tool.

  1. Click Manage security properties.

  2. Click Encryption.

  3. Select the method of encryption that you want to use based on the clients accessing the server. AES-128 is the default level of encryption. If you select multiple encryption methods, the highest level of encryption is used by default, however clients using the selected lower encryption levels still have access to the server.

    The IBM Tivoli Directory Server Version supports the Advanced Encryption Standard (AES) level of encryption. For information on AES, see the NIST Web page at http://csrc.nist.gov/encryption/aes/.

    Table 14. Supported levels of encryption
    Encryption level Attribute
    Triple DES encryption with a 168-bit key and a SHA-1 MAC ibm-slapdSslCipherSpec: TripleDES-168
    DES encryption with a 56-bit key and a SHA-1 MAC ibm-slapdSslCipherSpec: DES-56
    RC4 encryption with a 128-bit key and a SHA-1 MAC ibm-slapdSslCipherSpec: RC4-128-SHA
    RC4 encryption with a 128-bit key and a MD5 MAC ibm-slapdSslCipherSpec: RC4-128-MD5
    RC2 encryption with a 40-bit key and a MD5 MAC ibm-slapdSslCipherSpec: RC2-40-MD5
    RC4 encryption with a 40-bit key and a MD5 MAC ibm-slapdSslCipherSpec: RC4-40-MD5
    AES 128-bit encryption ibm-slapdSslCipherSpec: AES-128
    AES 256-bit encryption ibm-slapdSslCipherSpec: AES

    SSL and TLS do not support AES 192 encryption.The selected ciphers are stored in the configuration file using the ibm-slapdsslCipherSpec keyword and the attribute defined from the preceding table. For example, to use only Triple DES, select Triple DES encryption with a 168-bit key and an SHA-1 MAC. The attribute ibm-slapdSslCipherSpec: TripleDES-168 is added to the ibmslapd.conf file. In this case, only clients that also support Triple DES are able to establish an SSL connection with the server. We can select multiple ciphers.

  4. If your server supports the Federal Information Processing Standards (FIPS) mode enablement feature, under the heading "Implementation" a preselected Use FIPS certified implementation check box is displayed. This enables the server to use the encryption algorithms from the ICC FIPS-certified library. If you deselect this check box the encryption algorithms from a non-FIPS certified library are used.

    The server can be configured to turn FIPS Processing Mode on. It requires the FIPS-enabled libraries to also be on.

  5. When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit, or click Cancel to exit this panel without making any changes.

 

Using the command line:

To use the command line to set the SSL level of encryption (in this example to Triple DES encryption with a 168-bit key and an SHA-1 MAC) issue the command: 

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

where <filename> contains: 

dn: cn=SSL,cn=Configuration
changetype: modify
replace: ibm-slapdSslCipherSpec
ibm-slapdSslCipherSpec: TripleDES-168

See Table 14 for other encryption values.

To add more than one level of encryption, your <filename> might contain: 

dn: cn=SSL,cn=Configuration
changetype: modify
replace: ibm-slapdSslCipherSpec
ibm-slapdSslCipherSpec: RC2-40-MD5
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

To use the command line to turn off FIPS mode, issue the command: 

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

where <filename> contains: 

dn: cn=SSL,cn=Configuration
changetype: modify
replace: ibm-slapdSslFIPSModeEnabled
ibm-slapdSslFIPSModeEnabled: false

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

 

Certificate revocation verification

If you have selected to use server and client authentication in your SSL settings, you might want to configure your server to check for revoked or expired certificates.

When a client sends an authenticated request to a server, the server reads the certificate and sends a query to an LDAP server with a list that contains revoked certificates. If the client certificate is not found in the list, communications between the client and server are allowed over SSL. If the certificate is found, communications are not allowed.

To configure SSL certificate revocation verification use one of the following methods:

 

Using Web Administration:

Under Server administration, expand the Manage security properties category in the navigation area of the Web Administration Tool, select the Certificate revocation tab.

  1. Select an LDAP server and port that contains the certificate revocation list from the Server hostname:port drop-down list or enter a host name and port number of a server in the field in the hostname:port format.

  2. In the Bind DN field, specify the bind DN used for connection to the server. If a bind DN is not specified, an anonymous bind is used.

  3. In the Bind password field, specify the bind password. Then specify the password again in the Confirm password field.

  4. When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit, or click Cancel to exit this panel without making any changes.

Expired certificates are not included in the list because the expiration date is contained in the certificate itself.

 

Using the command line:

To use the command line to configure for SSL certificate revocation verification, issue the command: 

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

where <filename> contains: 

dn: cn=CRL,cn=SSL,cn=Configuration
changetype: modify
replace: ibm-slapdCrlHost
ibm-slapdCrlHost: <newhostname>
-
replace: ibm-slapdCrlPassword
ibm-slapdCrlPassword: <password>
-
replace: ibm-slapdCrlPort
ibm-slapdCrlPort: <portnumber>
-
replace: ibm-slapdCrlUser
ibm-slapdCrlUser: <username>

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



[ Top of Page | Previous Page | Next Page | Contents | Index ]