How to Configure Custom SSL Certificates for Planning Analytics 2.0 and 2.0.1

Answer

Generate the Custom SSL Keystore and Certificate

Planning Analytics 2.0 and 2.0.1 includes the gsk8capicmd_64.exe program in the .\tm1_64\bin64\ directory that can be used to create and populate a keystore database that will be used by the TM1 Admin Server and TM1 Server.

The following commands and run from the D:\Program Files\ibm\cognos\tm1_64\bin64\ directory. In this example assume Planning Analytics 2.0 is installed to D:\Program Files\ibm\cognos\tm1_64\

1 - Create a new keystore database file

gsk8capicmd_64 -keydb -create -populate -db D:\Program Files\ibm\cognos\tm1_64\bin64\\ssl\custom.kdb -type cms -pw changeit -stash

2 - Request a certificate from the keystore database created in step 1

gsk8capicmd_64 -certreq -create -db D:\Program Files\ibm\cognos\tm1_64\bin64\ssl\custom.kdb -stashed -label tm1server -dn "CN=tm1server.canlab.ibm.com,O=IBM" -file D:\Program Files\ibm\cognos\tm1_64\bin64\ssl\cert_request.arm –size 2048

The CN value should match the fully qualified domain name of the system where the TM1 Server is installed.

3 - Provide the certificate request (cert_request.arm file) to the Certificate Authority for signing. The Certificate Authority will provide both an issued cert (tm1server.cer in this example) and a CA certificate (ca.cer in this example). Multiple CA certs will typically be stored in a single file. It is common for a Certificate Authority to provide both the issued cert and CA certs in a single file.

4 - Add the CA certs into the keystore

gsk8capicmd_64 -cert -add -db D:\Program Files\ibm\cognos\tm1_64\bin64\ssl\custom.kdb -stashed -label tm1serverca -file D:\Program Files\ibm\cognos\tm1_64\bin64\ssl\ca.cer -format ascii -trust enable

5 - Receive the issued cert into the keystore

gsk8capicmd_64 -cert -receive -db D:\Program Files\ibm\cognos\tm1_64\bin64\ssl\custom.kdb -stashed -file .\ssl\tm1server.cer -default_cert yes

Additional steps for UNIX and Linux environments:

1 - Add the Planning Analytics bin64 directory to the library path environment variable (LD_LIBRARY_PATH on Linux and LIBPATH on AIX) before running gsk8capicmd_64. For example:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ibm/cognos/tm1_64/bin64

The gsk8capicmd_64 program will fail to run with a missing lib error if the library path variable is not set correctly.

2 - The gsk8capicmd_64 file in the bin64 is missing the execute permission by default. To add the missing execute permissions run the following command from the bin64 directory.

chmod +x gsk8capicmd_64

Configure the TM1 Admin Server to use the Custom SSL Certificate

Point the following TM1 Admin Server settings to the custom.kdb and custom.sth in Cognos Configuration.

Restart the TM1 Admin Server service.

* There is a known defect in the PA 2.0 release where the Server certificate parameter in the above settings is incorrectly referenced in the .\tm1_64\configuration\cogstartup.xml file. To correct this problem the cogstartup.xml file must be manually updated to change this line:

<crn:parameter name="tm1AdminKeyLabel">
<crn:value xsi:type="xsd:filePath">tm1server</crn:value>
</crn:parameter>

to this:

<crn:parameter name="tm1AdminKeyLabel">
<crn:value xsi:type="xsd:string">tm1server</crn:value>
</crn:parameter>

Note that saving from Cognos Configuration will reset the above line to the incorrect value. For this reason it's recommended to make sure the certificate being used is the default certificate in the key database, and leave the Server certificate parameter empty in Cognos Configuration.

Configure the TM1 Server to use the Custom SSL Certificate

Edit the tm1s.cfg file to include the following lines.

keyfile=D:\Program Files\ibm\cognos\tm1_64\bin64\ssl\custom.kdb
keystashfile=D:\Program Files\ibm\cognos\tm1_64\bin64\ssl\custom.sth

Restart the TM1 Server service.


Configure TM1 Architect and TM1 Perspectives to use the Custom SSL Certificate

Create a file named tm1api.config in the <TM1 Client>\bin\ or <TM1 Client>\bin64\ directory of the TM1 client install depending on the bit variant of the TM1 Client install.

Update the contents of the tm1api.config file with the following line:

[tm1api]
keystorefile=D:\Program Files\ibm\cognos\tm1_64\bin64\ssl\custom.kdb
keystashfile=D:\Program Files\ibm\cognos\tm1_64\bin64\ssl\custom.sth

No changes in the options for Cognos TM1 Architect or Perspectives are required.


Configure TM1Web to use the Custom SSL Certificate

The CA certs must be imported into the .\tm1_64\bin64\ssl\ttm1store certificate store file in the TM1Web installation. To import the CA certs the Java keytool command found in the D:\Program Files\ibm\cognos\tm1_64\bin64\jre\7.0\bin\ directory can be used as follows.

keytool.exe -import -trustcacerts file "D:\Program Files\ibm\cognos\tm1_64\bin64\ssl\ca.cer" -keystore "D:\Program Files\ibm\cognos\tm1_64\bin64\ssl\tm1store" -alias tm1cacert -storepass applix

The above command assumes all CA certs are contained in a file named ca.cer that is already copied into the D:\Program Files\ibm\cognos\tm1_64\bin64\ssl\ directory.

Restart the IBM Cognos TM1 service from the Windows services list or Cognos Configuration after making the above changes.


Configure TM1 Applications (pmpsvc) to use the Custom SSL Certificate

Make sure the custom.kdb and custom.sth file are copied into the D:\Program Files\ibm\cognos\tm1_64\bin64\ssl\ directory of the TM1 Server install that includes the pmpsvc web application.

Create a file named tm1api.config in the D:\Program Files\ibm\cognos\tm1_64\bin64\ directory of the TM1 Server install containing the pmpsvc web applications.

Update the contents of the tm1api.config file similar to this:

[tm1api]
keystorefile=D:\Program Files\ibm\cognos\tm1_64\bin64\ssl\custom.kdb
keystashfile=D:\Program Files\ibm\cognos\tm1_64\bin64\ssl\custom.sth

Update the D:\Program Files\ibm\cognos\tm1_64\wlp\usr\servers\tm1\jvm.options file to include the following line:

-Dcom.ibm.cognos.tm1.certificate.dir=D:\Program Files\ibm\cognos\tm1_64\bin64

Restart the IBM Cognos TM1 service (WebSphere Liberty Profile).