Prepare files for enabling secure communication

Edit online

Before you begin:

  • Make sure that aJava™ Runtime Environment is installed on your machine and that the JAVA_HOME variable is defined in the Environment variables. For more information, see the Java requirements section.
  • Make sure that you obtain a signed certificate from a certificate authority (CA) and that you have its root certificate.
    Note: In case you don't want to use a CA signed certificate, you can use a self-signed certificate instead. For more information, see (Optional) Generate a self-signed key certificate.

Keystore requirements

Each server must have a keystore that contains the following entries:
  • A PrivateKeyEntry of the CA signed certificate.
  • A TrustedCertEntry of the root CA certificate.
Note: Certificates can be imported into a keystore or a truststore with the following command:
keytool -keystore "<server_keystore.p12>" -import -file "<path_to_certificate>" -alias "<alias_name>"
Note: The keystore can be in JKS (.jks) or PKCS12 (.p12) format. However, it is recommended to use PKCS12, which is an industry standard format. JKS keystores can be migrated to PKCS12 with the following command:
keytool -importkeystore -srckeystore <server_keystore.jks> -destkeystore "<server_keystore.p12>" -deststoretype pkcs12

(Optional) Generate a self-signed key certificate

Important: This step is needed only in case a CA signed certificate is not available.
  1. At your convenience, use any tool to generate the certificates in a dedicated location. For example, C:\certificates.
  2. Use the Java keytool utility with the following input to generate private and public key (key pair): 
    keytool -genkeypair -alias "<hostname>" -keyalg RSA -keysize 2048 -dname "cn=<hostname>" -ext BasicConstraints:critical=ca:true -keypass "<password>" -keystore "<server_keystore.p12>" -storepass "<password>" -storetype PKCS12
    Notes:
    • The distinguished name (-dname) and Subject Alternative Name (SAN) must match the hostname of the machine that it is associated. Otherwise, the hostname verification fails.
    • The value of the Common Name (CN) is recommended to be a Fully Qualified Domain Name (FQDN). For example, addi-server.my-company.com, which is the industry standard.
    • The value of the Subject Alternative Name (SAN) must be set and equal to the value of CN. You need to add SAN requirements by using the commands -ext "san=dns:<DNS_VALUE>" and -ext "san=ip:<IP_ADDRESS>"
    • The certificate Enhanced Key Usage needs to be set to both server and client authentication.
    The generated key is in the specified keystore.
  3. Export the certificate.
    keytool -exportcert -alias "<hostname>" -keystore "<server_keystore.p12>" -file "server_certificate.crt" -storepass "<password>"
  4. Check the folder where the certificates were created. Both keystore and certificate files need to be there.

Export the certificate and private key

Currently, the IBM ADDI Build Client, IBM AD File Service, and Authentication Server (DEX) require the certificate and private key to be in external files. Complete the following steps to prepare those files:

Warning: Do not use PowerShell to run the following commands, which run with UTF-16 encoding by default and might cause errors.
  1. Use the OpenSSL tool from Cygwin to export the certificates in a dedicated location. For example, C:\certificates.
  2. To generate the server.key file, run the following command. 
    openssl pkcs12 -in "<server_keystore.p12>" -nocerts -nodes -out server.key
  3. To generate the server_certificate.crt file, run the following command. 
    keytool -list -keystore "<server_keystore.p12>" -alias "<hostname>" -rfc > "<server_certificate.crt>"
  4. Check the folder where the certificates were created. Both server.key and server_certificate.crt files need to be there.

Import the certificate to the Trusted Root Certificate Authorities

The root CA certificate or the self-signed certificate must be installed into the local machine's trusted root certificate authorities.
  • On WindowsWindows:
    1. Right-click the certificate and then click Install Certificate.
    2. Select Local Machine and click Next.
    3. Select Place all certificates in the following store.
    4. Click Browse... Import the certificate to Root Certificate Authorities.
    5. Click OK and then Next.
    6. Click Finish to complete the certificate import wizard.

Import the certificate to the Java runtime keystore

The root CA certificate or the self signed certificate must be installed into the local machine's Java cacerts keystore. A certificates file named cacerts resides in the security properties directory, java.home\jre\lib\security, where java.home is the Java runtime environment directory (the jre directory in the SDK or the top-level directory of the Java 2 Runtime Environment).

The cacerts file represents a system-wide keystore with CA certificates. System administrators can configure and manage that file by using keytool, specifying jks as the keystore type. The cacerts keystore file ships with several root CA certificates. The initial password of the cacerts keystore file is changeit. System administrators need to change that password and the default access permission of that file when they install the SDK.

To import the certificate to the Java runtime keystore, complete the following steps:
  1. Open a Command Prompt (on Windows) or a Terminal (on Linux®) and go to the folder that contains the newly prepared server_keystore.p12.
  2. Execute the following command to import all certificates from server_keystore.p12 to the Java's cacerts keystore. 
    keytool -importkeystore -srckeystore "<server_keystore.p12>" -srcstorepass "<server_keystore_password>" -destkeystore "%JAVA_HOME%\jre\lib\security\cacerts" -deststorepass "<cacerts_password>"
    Note: The default cacerts password is changeit.