Directory Server, Version 6.1

---

 

Appendix P. Setting up SSL security – SSL scenarios

The scenarios presented in this appendix are designed to create secure connections between the different components of your IBM® Tivoli® Directory Server system.

The following conditions are assumed:

• IBM Tivoli Directory Server 6.1 is installed on a machine.

• An IBM Tivoli Directory Server instance is created.

• An IBM Tivoli Directory Server database is created.

• There are no key database (.kdb) or key store (.jks) files created.

 

Using HTTPS for the embedded version of WebSphere Application Server Version 5.1.1

The embedded version of WebSphere® Application Server, Version 5.1.1, by default, has HTTPS set up on port 12101. To use HTTPS, change your login Web address to the following:

https://<hostname>:12101/IDSWebApp/IDSjsp/Login.jsp

For non-HTTPS connections, continue to use the following Web address:

http://<hostname>:12100/IDSWebApp/IDSjsp/Login.jsp

Additionally, if you want to change the application server's SSL certificate, we can create new key and trust store database files for the WebSphere Application Server to use. By default, the key and trust store database files are separate and are located in the <WASHOME>/etc directory. These files are named DummyServerKeyFile.jks and DummyServerTrustFile.jks respectively.

After you have created your new jks files, we can change the key and trust store database files that IBM WebSphere Application Server uses by modifying the following items (highlighted in bold) in the <WASHOME>/config/cells/DefaultNode/security.xml file to use your new file names, passwords, and file formats:

<repertoire xmi:id="SSLConfig_1" alias="DefaultNode/DefaultSSLSettings"       <setting xmi:id="SecureSocketLayer_1" 
	keyFileName="${USER_INSTALL_ROOT}/etc/DummyServerKeyFile.jks" 
	keyFilePassword="{xor}CDo9Hgw=" 
	keyFileFormat="JKS" 
	trustFileName="${USER_INSTALL_ROOT}/etc/DummyServerTrustFile.jks" 
	trustFilePassword="{xor}CDo9Hgw=" 
	trustFileFormat="JKS" 
	clientAuthentication="false" securityLevel="HIGH" 
	enableCryptoHardwareSupport="false">
     <cryptoHardware xmi:id="CryptoHardwareToken_1" tokenType="" 
				libraryFile="" password=""/>
     <properties xmi:id="Property_4" name="com.ibm.ssl.protocol" value="SSLv3"/>
     <properties xmi:id="Property_5" name="com.ibm.ssl.contextProvider" 
			value="IBMJSSE"/>
  </setting>
</repertoire>

 

Creating secure connections between IBM WebSphere Application Server, and the IBM Tivoli Directory server and the administration daemon

Create a key pair and certificate request for self-signing key store file (.jks) and a key database file (.kdb).

Notes:

1. See "Appendix O. Setting up GSKit to support CMS key databases" in IBM Tivoli Directory Server Version 6.1 Installation and Configuration Guide .

2. The instructions for creating a key pair and certificate request for self-signing key store file (.jks) and a key database file (.kdb) are given based on the assumption that no key database or key store files have been created. If you already have key database or key store files created that you prefer to use, we can skip to step 5.

The only requirements are that you create the keystore file and the key database file on a machine that has GSkit and Java™ installed:

Note:

There can be only one key store file (.jks) per Web Application 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.

1. Do the following to create a key database (.kdb) file:

   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.
      Note:

      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. Go to Create->New Self-Signed Certificate.

   7. Supply the following:

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

        Remember this label.

      • 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. This is an optional field.

      • The zip code appropriate for the server's location. This is an optional field.

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

      • The Validity Period for the certificate.

   8. Click OK.

2. Do the following to create a self-signing key store file (.jks):

   1. Type gsk7ikm to start the Java utility.

   2. Select Key Database File.

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

      Specify JKS in the Key database type list.

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

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

   6. Go to Create->New Self-Signed Certificate.

   7. Supply the following:

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

        Be sure that you do not use the same label that you used in step 1g.

      • 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. This is an optional field.

      • The zip code appropriate for the server's location. This is an optional field.

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

      • The Validity Period for the certificate.

   8. Click OK.

3. Extract the certificate from the .kdb file to the .jks file:

   1. Select Key Database File.

   2. Select Open.

   3. Select the key database (.kdb) file name and location.
      Note:

      This is the key database file you created previously.

   4. If asked, provide password.

   5. Click OK.

   6. Go to Personal certificates.

   7. Click Extract Certificate.

   8. Select Data type. For this scenario, select Binary DER data.

   9. Provide a filename and location.
      Note:

      Remember this filename and location.

   10. Select Key Database File.

   11. Select Open.

   12. Select the key store (.jks) file name and location.
       Note:

       This is the key store file you created previously.

   13. If asked, provide password.

   14. Click OK.

   15. Go to Signer certificates.

   16. Click Add.

   17. Select the Binary DER data (.der) file created previously.

   18. Click OK.

   19. Enter a label for this certificate.

   20. Click OK.

4. Extract the certificate from the .jks file to the .kdb file:

   1. Select Key Database File.

   2. Select Open.

   3. Select the key store (.jks) file name and location.
      Note:

      This is the key store file you created previously.

   4. If asked, provide password.

   5. Click OK.

   6. Go to Personal certificates.

   7. Click Extract Certificate.

   8. Select Data type. For this scenario, select Binary DER data.

   9. Provide a filename and location.
      Note:

      Remember this filename and location.

   10. Select Key Database File.

   11. Select Open.

   12. Select the key database (.kdb) file name and location.
       Note:

       This is the key database file you created previously.

   13. If asked, provide password.

   14. Click OK.

   15. Go to Signer certificates.

   16. Click Add.

   17. Select the Binary DER data (.der) file created previously.

   18. Click OK.

   19. Enter a label for this certificate.

   20. Click OK.

5. Start the directory server instance, if not started already. See "Starting the directory server instance" in IBM Tivoli Directory Server Version 6.1 Installation and Configuration Guide .

6. Start the application server. See "Starting the application server to use the Web Administration Tool" in IBM Tivoli Directory Server Version 6.1 Installation and Configuration Guide .

7. Log on to the Web Administration Tool to add a non-SSL-enabled server. Launch the Web Administration Tool:

   1. After you have started the application server, from a Web browser, type the following address: http://localhost:12100/IDSWebApp/IDSjsp/Login.jsp

      The IBM Tivoli Directory Server Web Administration Tool Login page is displayed.

      Note:

      This address works only if you are running the browser on the computer on which the Web Administration Tool is installed. If the Web Administration Tool is installed on a different computer, replace localhost with the hostname or IP address of the computer where the Web Administration Tool is installed.

   2. Log in to the console as the console administrator:

      1. Be sure that Console Admin is displayed in the LDAP Hostname field.

      2. In the Username field, type superadmin.

      3. In the Password field, type secret.
      The IBM Tivoli Directory Server Web Administration Tool console is displayed.

   3. Add a non-SSL-enabled server to the console, using the following instructions:

      1. Expand Console administration in the navigation area.

      2. Click Manage console servers. A table of server host names and port numbers is displayed.

      3. Click Add.

      4. Specify a unique name that identifies a registered IBM Tivoli Directory Server (TDS) instance running on a specified host name or IP address and server port. The server name is displayed in the LDAP Hostname list on the Directory server login panel. If a name is not provided in the Server name field, the hostname:port combination would be displayed for the server instance in the LDAP Hostname list on the Directory server login panel.

      5. Type the hostname or the IP address of the server in the Hostname field; for example, myserver.mycity.mycompany.com

      6. Select the Admin daemon supported check box to enable the Administration port control.

      7. Specify the server port number in the Port field and the Admin daemon port number in the Administration port field. We can accept the defaults.

      8. Ensure the Enable SSL encryption check box is not checked.

      9. Click OK, and then click OK again on the confirmation panel.

   4. Click Logout in the navigation area.

8. Log in as the directory server instance administrator:

   1. On the IBM Tivoli Directory Server Web Administration Login Tool page, select the LDAP host name or IP address for your computer from the drop-down menu for the LDAP Hostname field.

   2. Type the administrator DN and the password for the directory server instance. You specified these fields during instance creation.

   3. Click Login.

9. Configure the security settings for the Web Administration console:

   1. Go to the Web Administration console.

   2. Click Server administration.

   3. Click Manage security properties.

   4. Click Settings.

   5. To enable an SSL connection, select the SSL radio button.
      Note:

      The security settings you set for the IBM Tivoli Directory Server here apply to the directory administration daemon as well.

   6. Select the Server and client authentication radio button.
      Note:

      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.

   7. Select the Key database tab:

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

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

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

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

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

      • Click Apply to save your changes without exiting.

      • Click OK to apply your changes and exit.

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

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

10. Configure the console properties settings for the Web Administration console:

    1. After you have restarted the application server, log in to the console as the console administrator:

       1. Be sure that Console Admin is displayed in the LDAP Hostname field.

       2. In the Username field, type superadmin.

       3. In the Password field, type secret.

    2. Expand Console administration in the navigation area.

    3. Click Manage console properties.

    4. Click Component management to specify the components that are enabled for all servers in the console. By default all the components are enabled.
       Note:

       You might not see a management component or some of its tasks, even if it is enabled, if you do not have the correct authority on the server or the server does not have the needed capabilities, or both.

    5. Click Session properties to set the time out limit for the console session. The default setting is 60 minutes.
       Note:

       A session might be valid for three to five minutes more than what you have set. This is because the invalidations are performed by a background thread in the application server that acts on a timer interval. This timer interval extends the session time out duration.

    6. Click SSL key database to set up the console so that it can communicate with other LDAP servers using the Secure Sockets Layer (SSL), if necessary. Set the key database path and file name, the key password, the trusted database path and file name, the trusted password in the appropriate fields.
       Note:

       The supported file type is jks. Use the .jks file you created previously. See Using gsk7ikm and Secure Sockets Layer for information about key databases and SSL.

       Note:

       The LDAP server and the administration daemon can have separate credentials (key database files).

    7. Click OK.

11. Add an SSL-enabled server to the console:

    1. Expand Console administration in the navigation area.

    2. Click Manage console servers.

    3. Click Add.

    4. Specify a unique name that identifies a registered IBM Tivoli Directory Server (TDS) instance running on a specified host name or IP address and server port. The server name is displayed in the LDAP Hostname list on the Directory server login panel. If a name is not provided in the Server name field, the hostname:port combination would be displayed for the server instance in the LDAP Hostname list on the Directory server login panel.

    5. Type the hostname or the IP address of the server in the Hostname field; for example, myserver.mycity.mycompany.com

    6. Select the Admin daemon supported check box to enable the Administration port control.

    7. Specify the server secure port number in the Port field and the Admin daemon secure port number in the Administration port field.
       Note:

       The Port number and Administration port numbers are different for an SSL-enabled server. Click Help for more information.

    8. Select the Enable SSL encryption check box.

    9. Click OK, and then click OK again on the confirmation panel.

    10. Click Logout in the navigation area.
        Note:

        You might need to restart the IBM WebSphere Application Server.

12. Log in as the directory server instance administrator to verify that the SSL-enabled server was added correctly:

    1. On the IBM Tivoli Directory Server Web Administration Login Tool page, select the LDAP host name or IP address for your computer from the drop-down menu for the LDAP Hostname field.

    2. Type the administrator DN and the password for the directory server instance. You specified these fields during instance creation.

    3. Click Login.

13. Configure the SSL-enabled localhost as SSL only-enabled:

    1. Go to the Web Administration console.

    2. Click Server administration.

    3. Click Manage security properties.

    4. Click Settings.

    5. To enable an SSL connection, select the SSL only radio button.

    6. Select the Server and client authentication radio button.
       Note:

       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.

    7. When you are finished, click Apply to save your changes without exiting. Click OK to apply your changes and exit. 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.

14. Issue the following command to verify that the server is functioning as an SSL server:

    idsldapsearch -D <admin_dn> -w <admin_pw> -Z  -K <server_kdb_file> 
    	-P <keyfile_password> -b "cn=localhost"  
    	-p <server_secure_port> objectclass=* 
    

 

Setting up an SSL connection between a client and server

1. Do the following to create a key database (.kdb) file and self-signed certificate on the server:

   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, for example, <server_file>.kdb. Click OK.

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

   6. Make sure the Stash a password to a file? box is checked.

   7. Click OK.

   8. Go to Create->New Self-Signed Certificate.

   9. Supply the following:

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

        Remember this label.

      • 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. This is an optional field.

      • The zip code appropriate for the server's location. This is an optional field.

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

      • The Validity Period for the certificate.

2. Do the following to create a new .kdb file on the client machine:

   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, for example, <client_file>.kdb. Click OK.

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

   6. Make sure the Stash a password to a file? box is checked.

   7. Click OK.

3. Do the following on the server machine (in the GSkit utility):

   1. Open the <server_file>.kdb file.

   2. Go to Personal certificates.

   3. Click Extract Certificate.

   4. Provide a filename and location.
      Note:

      Remember this filename and location.

4. Go to a command prompt on the server machine:

   1. Go to the directory to which you extracted the server self-signed certificate in the previous step.

   2. FTP the server self-signed certificate to the client machine.

5. Do the following on the client machine (in the GSkit utility):

   1. Open the <client_file>.kdb file.

   2. Go to Signer certificates.

   3. Click Add.

   4. Click Browse to find the server self-signed certificate you added to the client machine in the previous step.

   5. Open the file.

   6. Click OK.

   7. Enter the label for this certificate.
      Note:

      This label must match the label you defined in step ***.

   8. Click View/Edit. Make sure the Set the certificate as a trusted root box is checked.

   9. Go to Create->New Self-Signed Certificate.

   10. Supply the following:

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

         Remember this label.

       • 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. This is an optional field.

       • The zip code appropriate for the server's location. This is an optional field.

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

       • The Validity Period for the certificate.

   11. Click OK.

   12. Click Extract Certificate.

   13. Provide a filename and location.
       Note:

       Remember this filename and location.

   14. Click OK.

6. Go to a command prompt on the client machine:

   1. Go to the directory to which you extracted the client self-signed certificate in the previous step.

   2. FTP the server self-signed certificate to the server machine.

7. Do the following on the server machine (in the GSkit utility):

   1. Open the <server_file>.kdb file.

   2. Go to Signer certificates.

   3. Click Add.

   4. Click Browse to find the client self-signed certificate you added to the server machine in the previous step.

   5. Open the file.

   6. Click OK.

   7. Enter the label for this certificate.
      Note:

      This label must match the label you defined in step ***.

   8. Click View/Edit. Make sure the Set the certificate as a trusted root box is checked.

8. Issue the following command, from either the client or the server, to modify the cn=SSL,cn=Configuration entry in the ibmslapd.conf file:

   idsldapmodify -D <admin_dn> -w <admin_pw>  -i <filename>
   

   where <filename> contains:

   dn: cn=SSL,cn=Configuration
   changetype: modify
   replace: ibm-slapdSslAuth
   ibm-slapdSslAuth: serverClientAuth
   -
   replace: ibm-slapdSecurity
   ibm-slapdSecurity: SSLonly
   -
   replace: ibm-slapdSSLKeyDatabase
   ibm-slapdSSLKeyDatabase: <server_keyfile>
   -
   replace: ibm-slapdSSLKeyDatabasePW
   ibm-slapdSSLKeyDatabasePW: <server_keyfile_password>
   -
   replace: ibm-slapdSslKeyRingFilePW
   ibm-slapdSslKeyRingFilePW: <server_keyfile_password>
   

9. Restart the server and the administration daemon for the changes to take effect.

10. Issue the following command, from either the client or the server, to verify that the server is functioning as an SSL server:

    idsldapsearch -D <admin_dn> -w <admin_pw>  -K <keyfile> 
    	-b "cn=localhost" -p <server_secure_port>	objectclass=* 
    

    Notes:

    1. You do not need to specify the -P option here because the keyfile password was attached to a stash file.

    2. If issuing this command from a client, use the -h option, for example:

       idsldapsearch -D <admin_dn> -w <admin_pw> -h <hostname> -K <keyfile> 
       	-b "cn=localhost" -p <server_secure_port>	objectclass=* 
       

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