IBM PA 2.0.

X
TLS/SSL Implementation

IBM PLANNING ANALYTICS 2.0.X

TLS/SSL IMPLEMENTATION WITH CUSTOM CERTIFICATES

AUTHOR:
Samba Kesinakurthi
Software Architect
IBM Cloud and Cognitive Software

05/02/2020 © IBM India Pvt Ltd 1

 IBM PA 2.0.X
TLS/SSL Implementation

CONTENTS
1. DOCUMENT PURPOSE ........................................................................................................................ 3
2. OVERVIEW ........................................................................................................................................ 3
1.1. DATA TRANSMISSION SECURITY ................................................................................................................. 3
1.2. DEFAULT SECURITY CONFIGURATION ......................................................................................................... 3
1.3. TLS WITH CUSTOM CERTIFICATES ............................................................................................................. 3
1.3.1. DATA TIER........................................................................................................................................... 3
1.3.1.1. KEYSTORE AND CERTIFICATES .............................................................................................................. 3
1.3.1.2. CONFIGURING ADMIN SERVER ............................................................................................................... 4
1.3.1.3. CONFIGURING TM1 SERVER ................................................................................................................. 4
1.3.1.4. TM1 DESKTOP CLIENTS ........................................................................................................................ 5
1.3.2. WEB TIER ........................................................................................................................................... 5
1.3.2.1. KEYSTORE AND CERTIFICATES .............................................................................................................. 5
1.3.2.2. COGNOS CONFIGURATION ..................................................................................................................... 6
1.3.2.3. PMPSVC SERVICES ............................................................................................................................ 6

05/02/2020 © IBM India Pvt Ltd 2

 IBM PA 2.0.X
TLS/SSL Implementation

1. Document Purpose
This document outlines the pre-requisites and the processes/steps relevant to the SSL implementation using
custom certificates for Planning Analytics

2. Overview
1.1. Data Transmission Security
To facilitate privacy and security to the data that is being transmitted between clients and servers, Transport
Layer Security (TLS) protocol can be implemented. TLS is evolved from the previous encryption protocol called
Secure Socket Layer (SSL). The latest versions of IBM Planning Analytics uses TLS to secure the
communication between clients and servers

1.2. Default Security Configuration

IBM Planning Analytics comes with default certificates and provides default configuration with which TLS can
be enabled with minimal manual configuration changes. However, it is recommended to have custom signed
server certificates for TLS configuration to maximize the security, especially in Production environment with
servers/clients installed on distributed systems

When Planning Analytics installed, the default certificates are placed under <PA Instal dir>/bin64/ssl/

1.3. TLS with Custom Certificates

Enabling TLS with custom certificates will involves various activities performed on the servers and they are
explained in the below subsections

1.3.1. Data Tier

This section outlines the steps involved in configuring TLS for Data Tier

** NOTE: Before performing the below activities, bring down the TM1 Admin Server and other
TM1 Servers if they are running

1.3.1.1. Keystore and Certificates

To create a CMS keystore or to perform certificate related activies (create/import/delete),
gsk8capicmd_64 command utility can be used (<PAinstlDir>/bin64/).For convenience and easy
maintenance, one can create a custom folder on the server to hold the custom keystore and
certificates, so that a reference to the keystore path can be used instead of copying the files in
multiple places

For example: D:/PACerts/<keystore and certificates files>

Below are the steps to be followed using GSKit utility for creating keystore and certificates. Assume
that the custom keystore and certificates are placed in a custom directory (D:/PACerts)

i. Open Command Prompt as Administrator and navigate to <PAInslDir>/bin64/

ii. Keystore creation

gsk8capicmd_64 -keydb -create -populate -db D:\PACerts\custom.kdb -type cms -pw

<PASSWORD> -stash

iii. Certificate Request creation

gsk8capicmd_64 -certreq -create -db " D:\PACerts\custom.kdb" -stashed -size 4096 -

sigalg "SHA256WithRSA" -label "tm1server" -dn "CN=hostname.domain.com,O=MyCompany,
C=IN" -san_dnsname "hostname.domain.com,hostname" -san_ipaddr "10.0.123.12" -file
"D:\PACerts\custom_cert_request.arm"

05/02/2020 © IBM India Pvt Ltd 3

 IBM PA 2.0.X
TLS/SSL Implementation

iv. Provide the Certificate Request file (custom_cert_request.arm in this case) to the team
who will sign the same and issue Signed Certificate and Chain certificate(s) (Intermediate
and Root certificate).

Let’s say, Signed Certifcate is signedCert.cer and Chain certificate as chainCA.cert

v. Copy the signedCert.cer and chainCA.cert into D:/PACerts/ directory. Now import the
chain certificate using the below command

gsk8capicmd_64 -cert -add -db "D:\PACerts\custom.kdb" -stashed -label certCA -file

"D:\PACerts\chainCA.cert" -format ascii -trust enable

vi. Import the Signed certificate into the keystore using the below command

gsk8capicmd_64 -cert -receive -db "D:\PACerts\custom.kdb" -stashed -file

"D:\PACerts\signedCert.cer" -default_cert yes

vii. Make sure the signed certificate is made as Default for the keystore. The above command
should set it as a default, in case if you are unable to do it, you can use the below
command to make a certificate default

gsk8capicmd_64 -cert -setdefault -db "D:\PACerts\custom.kdb" -stashed -label

tm1server

viii. To list the certificates available in a keystore run the below command

gsk8capicmd_64 -cert -list -db "D:\PACerts\custom.kdb" -stashed

ix. To validate the certificates if they are imported successfully and they are valid, run the
below for each certificate using its label

gsk8capicmd_64 -cert -validate -db "D:\PACerts\custom.kdb" -stashed -label

<labelName>

1.3.1.2. Configuring Admin Server

i. Open Cognos Configuration
ii. Under Environment, select TM1 Admin Server
iii. Update the properties as shown below
a. Key database location = D:\PACerts\custom.kdb
b. Key database password location = D:\PACerts\custom.sth
c. Server Certificate = tm1server (use the label of the default certificate in the
keystore)
iv. Save the configurations and start the TM1 Admin Server

1.3.1.3. Configuring TM1 Server

i. Bring down the TM1 Server that you intend to configure TLS
ii. Open the tm1s.cfg
iii. Add the below lines and update the UseSSL parameter as below
a. keyfile=D:\PACerts\custom.kdb
b. keystashfile=D:\PACerts\custom.sth
c. UseSSL=T
iv. Save the tm1s.cfg and start the TM1 Server
v. To check if the TLS configuration is working and if HttpPortNumber is maintained in
tm1s.cfg, you can run https://hostname.domain.com:<HttpPortNumber>/api/v1/$metadata
in a browser

05/02/2020 © IBM India Pvt Ltd 4

 IBM PA 2.0.X
TLS/SSL Implementation

1.3.1.4. TM1 desktop clients

i. Create a file tm1api.config with the below lines added to it

[tm1api]
keystorefile=D:\PACerts\custom.kdb
keystashfile=D:\PACerts \custom.sth

ii. Place this file in the below directories

a. <PAInstlDir>\bin64\
b. <PAInstlDir>\perfmodeler\
c. <PAInstlDir>\perfmodeler\bins\bin_xxxx\bin
d. <PAInstlDir>\perfmodeler\bins\bin_xxxx\tm1api101
e. <PAInstlDir>\perfmodeler\bins\bin_xxxx\tm1api102
f. <PAInstlDir>\perfmodeler\plugins\com.cognos.pmta.tm1.distributed.bin.win32.x86
_64_xxxx\extract_bin\tm1\bin
g. <PAInstlDir>\perfmodeler\plugins\com.cognos.pmta.tm1.distributed.bin.win32.x86
_64_xxxx\extract_bin\tm1\bin\tm1api101
h. <PAInstlDir>\perfmodeler\plugins\com.cognos.pmta.tm1.distributed.bin.win32.x86
_64_xxxx\extract_bin\tm1\bin\tm1api102

iii. Launch Architect/ Perspectives/ Performance Modeler as Administrator if you face

certificate validation issue when you launch the clients as a normal user

1.3.2. Web Tier

This section outlines the steps involved in configuring TLS for Web Tier

** NOTE: Before performing the below activities, bring down the TM1 Servicesr if it is already
running

1.3.2.1. Keystore and Certificates

Like explained in the section 1.3.1.1 GSKit utility can be used to create a keystore and do the
certificate management in the Web tier too. However, unlike in data tier there is a slight difference in
creating a keystore. Planning Analytics for web tier will only look for a keystore named as
CAMKeystore exists in the directory <PAInstlDir>/configurations/certs. Below are the steps can be
followed to create one and then do certificate management

i. Back up the existing CAMKeystore and CAMKeystore.lock files or remove from the
<PAInstlDir>/configuration/certs directory
ii. Launch Command prompt as an Administrator, then navigate to <PAInstlDir>/bin64 from
where you can run the GSKit utility
iii. Creating the CAMKeystore keystore

gsk8capicmd_64 -keydb -create -db "..\configuration\certs\CAMKeystore" -pw

"NoPassWordSet" -type pkcs12

iv. The CAMKeystore that Planning Analytics looks for, has no file extension but the GSKit
will create a keystore with an extension which can be removed using the rename
command as shown below

rename "..\configuration\certs\CAMKeystore.p12" "CAMKeystore"

v. Creating a Certificate Request for the Web Tier server

gsk8capicmd_64 -certreq -create -db "..\configuration\certs\CAMKeystore" -pw

"NoPassWordSet" -size 2048 -sigalg "SHA256WithRSA" -label "encryption" -dn
"CN=webhostname.domain.com,O=MyCompany,C=IN" -san_dnsname

05/02/2020 © IBM India Pvt Ltd 5

 IBM PA 2.0.X
TLS/SSL Implementation

"webhostname.domain.com,webhostname" -san_ipaddr "10.0.234.65" -file

"..\configuration\certs\certReq.arm"

vi. Provide the certificate request file to the Certificate Authority to get it signed and also to
receive the intermediate and root certificate(s) or Chain certificate
vii. Import the chain certificate into the keystore

gsk8capicmd_64 -cert -add -db "..\configuration\certs\CAMKeystore" -pw

"NoPassWordSet" -label caChain -file "..\configuration\certs\ca-chain.cert.pem" -
format ascii -trust enable

viii. Import the signed certificate into the keystore

gsk8capicmd_64 -cert -receive -db "..\configuration\certs\CAMKeystore" -pw

"NoPassWordSet" -file "..\configuration\certs\signedCertReq.arm" -default_cert yes

ix. As the Data tier and Web tier servers will be using the custom certificates, both need to
have the others server certificates exchanged or imported into their keystores to enable
the handshake. So here, the data tier certificate will be imported into the CAMKeystore

gsk8capicmd_64 -cert -add -db "..\configuration\certs\CAMKeystore" -pw

"NoPassWordSet" -label tm1 -file "<DataTierCertificateFilepath>\certSigned.cer" -
format ascii -trust enable

1.3.2.2. Cognos Configuration

As the default configurations will refer to the default certificates, some changes need to be done on
the Cognos Configuration as explained below

i. Launch the Cognos Configuration as an Administrator

ii. Select the Local Configuration, then add the below property

StandaloneCertificateAuthority = True

iii. Under Environment, select TM1 Applications and then change the URLs on the detailed
pane, change http to https and change localhost to FQDN of the server
iv. Under Cryptography, select Cognos and make the below change

Use third party CA = True

v. Save the configuration and start the TM1 Services

1.3.2.3. PMPSVC services

To enable the PMPSVC applications/services (Performance Modeler, TM1 Applications) to work
with the custom certificates, follow the below steps

i. Rather than creating an extra keystore, you can take a copy of the custom.kdb that
was created and configured in Data tier server and place the same into a directory
within the Data tier server
ii. Create a tm1api.config in <PAInstlDir>/bin64 directory. For the below, we assume that
the custom.kdb is placed in D:\PACerts directory

[tm1api]
keystorefile=D:\PACerts\custom.kdb
keystashfile=D:\PACerts \custom.sth

iii. Navigate to <PAInstlDir>/wlp/usr/servers/tm1/ and edit the jvm.options file to add the
below line

-Dcom.ibm.cognos.tm1.certificate.dir=<instldir>\bin64

05/02/2020 © IBM India Pvt Ltd 6

 IBM PA 2.0.X
TLS/SSL Implementation

iv. To see if the TM1 applications working fine, run the below URL and login

https://webhostname.domain.com:9510/pmpsvc

05/02/2020 © IBM India Pvt Ltd 7