Secure Sockets Layer (SSL) Support
SSL is an important foundation for many TDI security features. We need a working-level knowledge of SSL in order to fully exploit the capabilities in TDI.
The following Connectors support SSL with properly configured IBM TDI Servers:
- Connectors
- JMS Connector
- LDAP Connector
- LDAP Server Connector
- Sun Directory Change Detection Connector
- IBM Directory Server ChangeLog Connector
- Active Directory Change Detection Connector
- Lotus Notes Connector
- Axis Easy Web service Server Connector
- Web service Receiver Server Connector
- DSMLv2 SOAP Server Connector
SSL provides for encryption and authentication of network traffic between two remote communicating parties. Most production deployments of TDI make use of SSL. That is why SSL support is one of the major security features of TDI. More information on SSL as well as information on using SSL in Java programs from a development point of view can be found at http://java.sun.com/j2se/1.5.0/docs/guide/security/jsse/JSSERefGuide.html
TDI can be used as a client, as a server or as both at the same time. Configuring TDI for SSL when used as a client is different from configuring TDI when used as a server. That is why this section has been divided in two sub-sections - Server SSL configuration of TDI components and Client SSL configuration of TDI components.
Server SSL configuration of TDI components
When a TDI component is used as a server (for example a Server mode Connector) SSL mandates that a keystore to be used by IBM TDI must be defined. For information on keystores and truststores, see the guide at http://java.sun.com/j2se/1.5.0/docs/guide/security/jsse/JSSERefGuide.html. The following steps are required to enable SSL support for IBM TDI as a server:
RMI is enabled by default in the TDI server. Properties for server authentication carry the default keystore property values.
- If we don't have a java (jks) keystore file already in IBM TDI create a keystore file using keytool (found in TDI_install_dir/jvm/jre/bin, or TDI_install_dir/jvm/bin depending on your platform). If we don't have a personal key to be used in IBM TDI get one from a Certificate Authority or create a self-signed key.
- If the certificate in the IBM TDI is a self-signed certificate, export the certificate.
- If the IBM TDI certificate is a self-signed certificate, using a key tool, import the exported IBM TDI certificate to the keystore file in the client as a root authority certificate.
- Edit TDI_install_dir/etc/global.properties file
for the keystore file location, keystore file password and keystore
file type. In the current release, we support jks-type only.
## client authentication javax.net.ssl.keyStore=serverapi\testadmin.jks {protect}-javax.net.ssl.keyStorePassword=administrator javax.net.ssl.keyStoreType=jks - Enable SSL for the clients (for example, using https in the Web browser).
- Restart IBM TDI
Notes:
- The TDI server does not manage the keystores/truststores. All that the TDI server provides to the TDI components in terms of keystore support is the global.properties or solution.properties files, in which the standard Java keystore/truststore properties can be specified.
- A TDI component can choose to use the default configured keystore/truststore in global.properties or solution.properties, or it can choose to implement its own handling of SSL sockets (for example implementing a custom SSLServerSocket Java class) so that it can use keystores/truststores different from the default.
- If TDI needs to use both a client and a server certificate only the default certificate configured in global.properties or solution.properties is used, then this must be the same certificate. An alternative would be to write a custom implementation of the SSLSocket or the SSLServerSocket Java class and make it use a certificate different from the default.
- See section Certificates for the TDI Web service Suite for specifics on the certificates for TDI Web service components.
Client SSL configuration of TDI components
When a TDI component is used as a client (for example the LDAP Connector) SSL mandates that a truststore to be used by TDI must be defined. For information on keystores and truststores, see the guide at http://java.sun.com/j2se/1.5.0/docs/guide/security/jsse/JSSERefGuide.html.
The following steps are required to enable SSL support for IBM TDI as a client:
- Configure a server (such as IBM Tivoli Directory Server) to enable SSL.
- If the certificate in the server is a self-signed certificate, export the certificate.
- If we don't have a Java™ (jks) keystore file already, create a keystore file using keytool (found in root_directory/jvm/jre/bin, or root_directory/jvm/bin, depending on your platform) for IBM TDI.
- If the server certificate is a self-signed certificate, import the server certificate to the IBM TDI keystore file as a root authority certificate using keytool.
- Edit root_directory/etc/global.properties file
for the keystore file location, keystore file password and keystore
file type. TDI 7.1 supports
Java keystore (jks) type only.
These four lines (comments starting with #) are no longer needed for client and server authentication to the TDI server. Stores that belong to TDI are set up to be used by default. This is part of enabling Remote Method Invocation (RMI) by default.
# Keystore file information for the server TDI authentication. # It is used to provide the public key of the TDI to the SSL enabled client. # javax.net.ssl.keyStore=D:\test\clientStore.jks # javax.net.ssl.keyStorePassword=secret # javax.net.ssl.keyStoreType=jks
- Enable SSL for the Connectors.
- Restart IBM TDI.
TDI truststore and keystore do not play any part in SSL configuration for the Domino Change Detection connector. See section Lotus Domino SSL specifics for more information.
SSL client authentication
If a TDI component is used as a client and the server with which it communicates requires SSL client authentication, then apart from a truststore, TDI needs a keystore as well. In this case the keystore can be defined just like it is defined when TDI is used a server - see the section Server SSL configuration of TDI components.
Client TDI components which support SSL client authentication do not normally need a "SSL client authentication" check box as do TDI server components. All such a client TDI component needs in order to prove its identity to the server is to have its keystore generated and configured in global.properties or solution.properties. If the server requires an SSL client certificate then the client SSL library automatically sends the client's certificate from the keystore configured in global.properties or solution.properties.
IBM TDI and Microsoft Active Directory SSL configuration
Do the following steps to configure SSL for IBM TDI and Microsoft Active Directory:
- Install Certificate Services on the Windows Server and an Enterprise Certificate Authority in the Active Directory Domain. Details are available at http://windowsitpro.com/article/articleid/14923/how-do-i-install-an-enterprise-certificate-authority.html. Make sure you install an Enterprise Certificate Authority.
- Start the Certificate Server Service. This creates a virtual directory in Internet Information Service (IIS) that enables you to distribute certificates.
- Create a Security (Group) Policy to direct Domain Controllers
to get an SSL certificate from the Certificate Authority (CA).
- Open the Active Directory Users and Computers Administrative tool.
- Right-click, under the domain, Domain Controllers.
- Select Properties.
- Select the Group Policy tab, and click to edit the Default Domain Controllers Policy.
- Go to Computer Configuration->Windows Settings->Security Settings->Public Key Policies.
- Right click Automatic Certificate Request Settings.
- Select New.
- Select Automatic Certificate Request.
- Run the wizard. Select the Certificate Template for a Domain Controller.
- Select your Enterprise Certificate Authority as the CA. Selecting a third-party CA works as well.
- Complete the wizard.
All Domain Controllers automatically request a certificate from the CA, and support LDAP using SSL on port 636.
- Retrieve the Certificate Authority Certificate to the computer
on which you installed IBM TDI.
You must install IIS before installing the certificate server.
- Open a Web browser on the computer on which you installed IBM TDI.
- Go to http://server_name/certsrv/ (where server_name is the name of the Windows 2000 server). You are asked to log in.
- Select the task Retrieve the CA certificate or certificate revocation list.
- Click Next.
The next page automatically highlights the CA certificate.
- Click Download CA certificate
A new download window opens.
- Save the file to the hard drive.
- Create a certificate store using keytool. Use keytool.exe to
create the certificate store and import the CA certificate into this
store.
keytool.exe is found in root_directory/jvm/jre/bin, or root_directory/jvm/bin, depending on your platform.Use the following command:
jvm\jre\bin\keytool -import -file certnew.cer -keystore keystore_name.jks -storepass password-alias keyalias_name
For example, assume the following values:Keystorename = idi.jks Password = secret Keyalias name = AD_CA
The command looks like this script:C:\Program Files\IBM\TDI\V7.1\jvm\jre\bin\keytool -import -file certnew.cer -keystore idi.jks -storepass secret -alias AD_CA
To verify the contents of the keystore, type the following script:C:\Program Files\IBM\TDI\V7.1\jvm\jre\bin\keytool -list -keystore idi.jks -storepass secret
The following lines result:Keystore type: jks Keystore provider: SUN Your keystore contains 1 entry: ad_ca, Mon Nov 04 22:11:46 MST 2002, trustedCertEntry, Certificate fingerprint (MD5): A0:2D:0E:4A:68:34:7F:A0:21:36:78:65:A7:1B:25:55
- Configure IBM TDI to use the keystore created in the previous step.
Edit root_directory/global.properties file
for the keystore file location, keystore file password and keystore
file type. In the current release, only jks-type is supported.
#server authentication #example javax.net.ssl.trustStore=c:\test\idi.jks javax.net.ssl.trustStorePassword=secret javax.net.ssl.trustStoreType=jks #client authentication #example javax.net.ssl.keyStore=c:\test\idi.jks javax.net.ssl.keyStorePassword=secret javax.net.ssl.keyStoreType=jks
- Enable SSL for your LDAP connector.
- Go to the LDAP Connector configuration window.
- Change LDAP URL to port 636.
- Check Use SSL.
- Restart IBM TDI.
The TDI Windows service wrapper permits you to start TDI as multiple service instances.
Summary of properties for enabling SSL and PKCS#11 support
We can configure SSL properties for server authentication, client authentication, and PKCS#11 support. See Using cryptographic keys located on hardware devices on Public Key Cryptography Standards (PKCS).
| Property | Default value | Description |
|---|---|---|
| javax.net.ssl.trustStore | serverapi\testadmin.jks | Location of the truststore files. |
| {protect}-javax.net.ssl.trustStorePassword | administrator(encrypted by default) | truststore password. |
| javax.net.ssl.trustStoreType | jks | Type of the truststore. |
| Property | Default value | Description |
|---|---|---|
| javax.net.ssl.keyStore | serverapi\testadmin.jks | keystore files location. |
| {protect}-javax.net.ssl.keyStorePassword | administrator(encrypted by default) | keystore password. |
| javax.net.ssl.keyStoreType | jks | Keystore type. |
| Property | Default value | Description |
|---|---|---|
| com.ibm.di.pkcs11cfg | etc\pkcs11.cfg | Specify the path of the configuration file required to initialize the IBM PKCS11 implementation provider. Added in TDI 7.0. |
| com.ibm.di.server.pkcs11 | false | Use pkcs11 compliant crypto devices for ssl. Added in TDI 7.0. |
| com.ibm.di.server.pkcs11.library | none | Specify the path to the PKCS11client library. Added in TDI 7.0. |
| com.ibm.di.server.pkcs11.slot | none | Specify the slot number of the device. |
| {protect}-com.ibm.di.server.pkcs11.pass | none | Access the pkcs11 compliant crypto device using this password. Encrypted by default. Added in TDI 7.0. |
SSL example
In order to demonstrate how TDI can be configured for SSL when used as a server and also when used as a client, two examples are provided - one deploying the LDAP Server Connector and one deploying the LDAP Connector.
TDI component as a server
This example uses the LDAP Server Connector. The LDAP Server Connector listens for LDAP requests. When an LDAP request arrives the Connector parses the request and provides the request data to the hosting AssemblyLine. The AssemblyLine then processes the request and provides the data for the response to the LDAP Server Connector, so that it can build the LDAP response and send it back to the LDAP client. What follows is a step by step guide how to configure TDI for SSL when the LDAP Server Connector is used:
- Obtain the server keystore either requesting it from a Certification Authority (CA) or creating a self-signed certificate as explained in the section called "Generate a public/private key pair and a self-signed certificate".
- Set the keystore details in global.properties or solution.properties as described in the "Server SSL configuration of TDI components" section.
- Select Use SSL on the Connector GUI configuration window. You may need to expand the Advanced section to make the parameter visible.
TDI component as a client
This example uses the LDAP Connector. The LDAP Connector connects to an LDAP Server and sends an LDAP request. After the Server returns the LDAP response the LDAP Connector provides that response to the AssemblyLine for further processing. What follows is a step by step guide how to configure TDI for SSL when the LDAP Connector is used:
- Generate the client truststore.
- Import the LDAP server certificate into the client truststore.
- Set the truststore details in global.properties or solution.properties as described in the "Client SSL configuration of TDI components" section.
The following command line imports an existing certificate into a keystore (the keystore is created if not already existing):