Configure the TM1 Server to use custom TLS

Generate the custom SSL keystore and certificate

IBM Planning Analytics includes the gsk8capicmd_64.exe program in the <PA_install_directory>\bin64\ directory. This tool can be used to create and populate a keystore database that is used by the TM1 Admin Server and TM1 Server.

1. Create a keystore database file by using the following command.

   gsk8capicmd_64 -keydb -create -populate 
   -db PA_install_directory\bin64\ssl\custom.kdb 
   -type cms -pw changeit -stash

2. Request a certificate from the keystore database that was created in step 1.

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

   Note: The cn value must match the fully qualified domain name of the system that is running the Planning Analytics Data tier.
3. Provide the certificate request (cert_request.arm file) to the Certificate Authority for signing.

   The certificate authority provides both an issued certificate (tm1server.cer in this example) and a CA certificate (ca.cer in this example). Multiple CA certificates are usually stored in a single file. It is common for a certificate authority to provide both the issued certificate and CA certificates in a single file.

4. Add the CA certificates into the keystore.

   gsk8capicmd_64 -cert -add -db PA_install_directory\bin64\ssl\custom.kdb 
   -stashed -label tm1serverca -file PA_install_directory\bin64\ssl\ca.cer 
   -format ascii -trust enable 

5. Receive the issued certificate into the keystore.

   gsk8capicmd_64 -cert -receive -db PA_install_directory\bin64\ssl\custom.kdb 
   -stashed -file .\ssl\tm1server.cer -default_cert yes 

Complete the following steps for UNIX and Linux environments.

1. Add the <PA_install_directory>\bin64\ directory to the library path environment variable (LD_LIBRARY_PATH) before you run gsk8capicmd_64.

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

   Note: The gsk8capicmd_64 program fails with a missing library error if the library path variable is not set correctly.
2. The gsk8capicmd_64 file in the <PA_install_directory>\bin64\ is missing the execute permission by default. Add the missing execute permissions by running the following command from the bin64 directory.

   chmod +x gsk8capicmd_64 

Configure the TM1 Admin Server to use the custom TLS certificate

1. Point the following TM1 Admin Server settings to the custom.kdb and custom.sth files in Cognos Configuration.
   
2. Restart the TM1 Admin Server service.

The Server certificate parameter in the settings might be incorrectly referenced in the <PA_install_directory>\configuration\cogstartup.xml file. To correct this problem, manually edit the cogstartup.xml file to change this line:

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

To the following line:

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

Configure the TM1 Server to use the custom TLS certificate

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

   keyfile=PA_install_directory\bin64\ssl\custom.kdb 
   keystashfile=PA_install_directory\bin64\ssl\custom.sth 

2. Restart the TM1 Server service.

Configure TM1 Architect and TM1 Perspectives to use the custom TLS certificate

1. Create a file named tm1api.config in the <TM1 Client>\bin\ or <TM1 Client>\bin64\ directory of the TM1 client installation depending on your client installation.
2. Update the contents of the tm1api.config file with the following lines:

   [tm1api] 
   keystorefile=PA_install_directory\bin64\ssl\custom.kdb 
   keystashfile=PA_install_directory\bin64\ssl\custom.sth 

You don't need to make any changes in the options for Cognos TM1 Architect or TM1 Perspectives.

Configure TM1Web to use the Custom TLS certificate

1. The CA certificates must be imported into the <PA_install_directory>\bin64\ssl\ttm1store certificate store file in the TM1Web installation.

   To import the CA certificates, use the Java keytool command found in the <PA_install_directory>\jre\bin\ directory as follows.

   keytool.exe -import -trustcacerts file "PA_install_directory\bin64\ssl\ca.cer" 
   -keystore "PA_install_directory\bin64\ssl\tm1store" -alias tm1cacert 
   -storepass applix 

   Note: This command assumes that all CA certificates are in a file named ca.cer that is already copied into the <PA_install_directory>\bin64\ssl\ directory.
2. Restart the IBM Cognos TM1 service from the Windows services list or Cognos Configuration.

Configure TM1 Applications (pmpsvc) to use the custom TLS certificate

1. Make sure the custom.kdb and custom.sth file are copied into the <PA_install_directory>\bin64\ssl\ directory of the TM1 Server install that includes the pmpsvc web application.
2. Create a file named tm1api.config in the <PA_install_directory>\bin64\ directory of the TM1 Server install containing the pmpsvc web applications.
3. Update the contents of the tm1api.config file:

   [tm1api] 
   keystorefile=PA_install_directory\bin64\ssl\custom.kdb 
   keystashfile=PA_install_directory\bin64\ssl\custom.sth

4. Update the <PA_install_directory>\wlp\usr\servers\tm1\jvm.options file to include the following line:

   -Dcom.ibm.cognos.tm1.certificate.dir=PA_install_directory\bin64 

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

Configuration parameters

The following table describes parameters that are related to secure connections, which can be set in the Tm1s.cfg configuration file. All Tm1s.cfg parameters are described in Planning Analytics database configuration parameters.