Configuring CA certificates for SSL

Use this example to help you to deploy your certificate authority (CA) certificates as part of your implementation of SSL.

Assumptions and prerequisites

This example makes the following assumptions and requires the following prerequisites:

You purchased a CA certificate from a third-party vendor. It is intended to help you with your configuration. The exact steps can differ depending on your installation and configuration.
If you deployed a keystore certificate, you need to delete the old keystore file, the <HOME>/IBM®/LogAnalysis/wlp/usr/servers/Unity/resources/security/key.jks file.

Deploying the certificate

To deploy this certificate, you complete the following steps:

1. Generate the key

The first step is not required for all installations. Log Analysis generates a key when it is installed. However, some CAs require a self-signed certificate with a specific name, for example for -dname.

If your CA requires a self-signed certificate with a specific name, then run one of the following commands depending on which signature algorithm you are using:

For users of the SHA1withRSA signature algorithm:

./keytool -genkey -keystore ~/IBM/LogAnalysis/wlp/usr/
servers/Unity/resources/security/key.jks 
-storepass loganalytics -keypass loganalytics -validity 365 
-dname "CN=abc12345678.in.example.com, OU=IT, O=EXAMPLE LTD, 
L=Bangalore,S=Karnataka, C=IN" -alias default -keyalg RSA 
-sigalg SHA1withRSA -ext san=dns:localhost.localdomain,dns:abc12345678,
dns:abc12345678.example.com,dns:localhost,ip:1.234.56.78 -keysize <encryption-key-size>

Where <encryption-key-size> is the size of the encryption key; for example, 2048.

For users of the SHA256withRSA signature algorithm:

./keytool -genkey -keystore ~/IBM/LogAnalysis/wlp/usr/
servers/Unity/resources/security/key.jks 
-storepass loganalytics -keypass loganalytics -validity 365 
-dname "CN=abc12345678.in.example.com, OU=IT, O=EXAMPLE LTD, 
L=Bangalore,S=Karnataka, C=IN" -alias default -keyalg RSA 
-sigalg SHA256withRSA -ext san=dns:localhost.localdomain,dns:abc12345678,
dns:abc12345678.example.com,dns:localhost,ip:1.234.56.78 -keysize <encryption-key-size>

Where <encryption-key-size> is the size of the encryption key, for example, 2048.

The keystore file for Log Analysis is <HOME>/IBM/LogAnalysis/wlp/usr/servers/Unity/resources/security/key.jks.

The value for the -dname parameter is the domain that your server is identified with. The details that are specified here are used to identify the server. For example, this parameter is specified as follows in this example:

-dname "CN=abc12345678.in.example.com, OU=IT, O=EXAMPLE LTD, 
L=Bangalore,S=Karnataka, C=IN"

where CN is the common name. OU is the organizational unit. O is the organization. L is the location. S is the state or province. C is the country.

Note:

If you are using base Log Analysis 1.3.5, Log Analysis 1.3.5 Fix Pack 1, or Log Analysis1.3.5 Fix Pack 2 and your <encryption-key-size> is 4096 or greater, then the policy files in the Java™ SDK might not be able to handle the larger certificate key size. This causes the GUI to have problems loading, and for the following error to be seen in the Liberty logs (ffdc):

..
Stack Dump = java.lang.RuntimeException: Could not generate dummy secret
    at com.ibm.jsse2.C.z(C.java:488)
    at com.ibm.jsse2.ap.b(ap.java:476)
    at com.ibm.jsse2.ap.a(ap.java:44)
..
Caused by: java.security.InvalidKeyException: Illegal key size or default parameters
    at javax.crypto.Cipher.a(Unknown Source)
    at javax.crypto.Cipher.a(Unknown Source)
..

Run the following command to use a policy file that supports a larger key size:

cd <LA_HOME>
cp -p ./ibm-java/demo/jce/policy-files/unrestricted/US_export_policy.jar ./ibm-java/jre/lib/security/
cp -p ./ibm-java/demo/jce/policy-files/unrestricted/local_policy.jar ./ibm-java/jre/lib/security/

2. Export the self-signed certificate to a file

After you generate the keystore in the first step, a default self-signed certificate is generated with an alias called default. You need to export this certificate to a file. After this step is done, you can import the file into the <HOME>/IBM/LogAnalysis/ibm-java folder that is part of the folders that are created by Log Analysis when it is installed. See instructions in Step 3.

Completing this step ensures that all the components of Log Analysis use the same certificate.

This step is required because you are generating a new keystore and this change requires you to refresh the public certificates for the clients.

If you do not delete your old keystore certificate before you generate the new one, and the older certificate used the same alias, that is default, an error can result. To avoid this, you can delete the older certificates or you can change the alias value.

To export the certificate into a file, run the following command:

./keytool -exportcert
-keystore ~/IBM/LogAnalysis/
wlp/usr/servers/Unity/resources/security/key.jks 
-alias default -file client.crt

When prompted, provide the Liberty keystore password; for example: loganalytics.

3. Import the self-signed certificate

To import this certificate into the Java runtime environment keystore, enter the following command:

./keytool
-import -keystore ~/IBM/LogAnalysis/ibm-java/
jre/lib/security/cacerts -alias default -file client.crt

When prompted, provide the Java keystore password; for example: changeit.

If you installed remote instances of Log Analysis components like the EIF Receiver, IBM Tivoli® Monitoring Log File Agent, or Logstash, you must import the certificate in the Java runtime environment on the remote servers.

4. Generate the Certificate Signing request (CSR) and send for signing

To generate the CSR, run the following command:

./keytool -keystore ~/IBM/LogAnalysis/wlp/usr/servers/Unity/
resources/security/key.jks -certreq -alias default 
-keyalg rsa -file csr-req.txt

Send the CSR that you generated to your CA for signing. The CA sends you three files, a root file, an intermediate certificate, and a primary certificate.

5. Import the root certificate

To import the root file, enter the following command:

./keytool -import -trustcacerts -keystore ~/IBM/LogAnalysis/wlp/usr
/servers/Unity/resources/
security/key.jks -alias theCARoot -file root.cer.txt

Enter keystore password:  
Certificate already exists in system-wide CA keystore under alias 
verisignclass3g5ca

Do you still want to add it to your own keystore? [no]:  yes
Certificate was added to keystore

6. Import the intermediate certificate

To import the intermediate certificate, run the following command:

[yogesh@scm91135985 bin]$ ./keytool -import -trustcacerts -keystore 
~/IBM/LogAnalysis/wlp/usr/servers/Unity/resources/security/key.jks 
-alias theIntermediate 
-file intermediate.cer.txt

Enter keystore password:  
Certificate was added to keystore

7. Import the primary certificate

To import the primary certificate, run the following command:

[yogesh@scm91135985 bin]$ ./keytool -import -trustcacerts -keystore 
~/IBM/LogAnalysis/wlp/usr/servers/Unity/resources/security/key.jks 
-alias default
-file scm91135985.in.ibm.com.crt.txt

Enter keystore password:  
Certificate reply was installed in keystore

8. Import the root and the intermediate certificates from your certificate authority to the truststore of IBM Java, with commands similar to the following:

Note: This step is only needed if the root and intermediate certificates are not already available in your Log Analysis Java cacerts file.

./keytool -import -keystore ~/IBM/LogAnalysis/ibm-java/jre/lib/security/cacerts -alias theRoot -file root.cer.txt
keystore password - changeit
./keytool -import -keystore ~/IBM/LogAnalysis/ibm-java/jre/lib/security/cacerts -alias theIntermediate -file intermediate.cer.txt
keystore password - changeit