IBM Support

How to implement encryption at REST over CAM authenticated Planning Analytics Server.

How To


Summary

This document is a real example that goes through the configuration of Planning Analytics Encryption at REST using a sample server. The intent of this document is to allow you to follow along, implementing the necessary changes for the environment you are configuring.

The official production documentation should still be reviewed and used, and can be found here:
https://www.ibm.com/support/knowledgecenter/SSD29G_2.0.0/com.ibm.swg.ba.cognos.tm1_inst.2.0.0.doc/c_modelencryption.html

Environment

  • Planning Analytics 2.0.4 and later versions.
  • Encryption at REST is available only for Planning Analytics Local.
  • Encryption at REST is not supported for IBM Planning Analytics on cloud.
  • Encryption at REST is not supported on a TM1 Server that is using replication and sync

Steps

The document illustrates steps to perform the following activities over a CAM authenticated TM1 Server.
  • Encrypt a Model
  • Decrypt a Model
  • Migration of an object from a decrypted model to an encrypted model
  • Migration of an object from an encrypted model to another encrypted model
  • Rotation of primary encryption key for added security

Please refer below product documentation for various parameters and values required by tm1crypt.exe:
https://www.ibm.com/support/knowledgecenter/SSD29G_2.0.0/com.ibm.swg.ba.cognos.tm1_inst.2.0.0.doc/r_runthetm1cryptutility_n1208c6.html

Step 1: Creation of Password and Password key files.

  • Execute the listed command to generate crytography keys : tm1crypt.exe -keyfile btkey.dat -outfile btprk.dat -validate

Note: The password and password key file will get generated in the bin64 directory as no specific path has been defined while creating the files. These files can be generated in an alternative directory as well.

image 7228

  • Verify if the encrypted password and key file get created in the bin64 directory.

image 7229

Step 2: Testing Password and Key files

  • Test btkey.dat and btprk.dat by executing a process by using tm1runti.exe

tm1runti.exe -adminhost "9.211.84.159" -server "Planning Sample" -process "z_savedataall" -user "administrator" -CAMNamespace "ApacheDS" -passwordfile "C:\Program Files\ibm\cognos\tm1_64\bin64\btprk.dat" -passwordkeyfile "C:\Program Files\ibm\cognos\tm1_64\bin64\btkey.dat"

image 7230

image 7231

TM1runti can also be executed by using a configuration file instead of executing the code directly on cmd using steps listed below.

  • Create a configuration file containing parameters as per below example screen-print. 

image 7232

  • Navigate to the bin64 directory over cmd and execute the below command
tm1runti.exe -i "C:\Program Files\ibm\cognos\tm1_64\samples\tm1\PlanSamp\config\tm1runti.config" -     process "z_savedataall"
image 7233

Scenario 1: Encrypt model
  • Execute tm1crypt with action 2 in order to encrypt the model.  

tm1crypt.exe -action 2 -server "Planning Sample" -user administrator -CAMNamespace "ApacheDS" -passwordfile "C:\Program Files\ibm\cognos\tm1_64\bin64\btprk.dat" -passwordkeyfile "C:\Program Files\ibm\cognos\tm1_64\bin64\btkey.dat"

Note: Encryption of a model results in TM1 server getting shut down.

image 7234

  • Verify if the Encryption key got generated

image 7235

  • Verify if the model got encrypted by opening any process file from the data directory.

image 7236

  • Start the Planning Analytics Server to confirm if login works as expected.

image 7237

The model encryption can also be performed using a configuration file instead of executing the code directly on cmd using steps listed below.

  • Create a configuration file containing parameters as per below example screen-print.

image 7238

  • Navigate to the bin64 directory over cmd and execute the below command
        tm1crypt.exe -i "C:\Program Files\ibm\cognos\tm1_64\samples\tm1\PlanSamp\config\tm1crypt.config" -    action 2

image 7239

Scenario 2: Decrypt model

  • Execute tm1crypt with action 3 in order to decrypt the model. 

tm1crypt.exe -action 3 -server "Planning Sample" -user administrator -CAMNamespace "ApacheDS" -passwordfile "C:\Program Files\ibm\cognos\tm1_64\bin64\btprk.dat" -passwordkeyfile "C:\Program Files\ibm\cognos\tm1_64\bin64\btkey.dat"

Note: Decryption of a model results in TM1 server getting shut down.

image 7240

  • Verify if the model got decrypted by opening any process file from the data directory.

image 7241

The model decryption can also be performed using the same configuration file used while encrypting the model instead of executing the code directly on cmd by executing the command as per screen-print below.

 tm1crypt.exe -i "C:\Program Files\ibm\cognos\tm1_64\samples\tm1\PlanSamp\config\tm1crypt.config" -action 3

image 7242

Scenario 3: Migration of an unencrypted process to an encrypted Planning Analytics Server.

  • Copy the TI process from a decrypted model to a temporary location. The decrypted TI process showcased in the below screen-print will be migrated to the encrypted Planning Analytics model as part of this activity.

image 7243

  • Encrypt the process to be migrated using keys of the target encrypted server

tm1crypt.exe -action 4 -server "Planning Sample" -user administrator -CAMNamespace "ApacheDS" -passwordfile "C:\Program Files\ibm\cognos\tm1_64\bin64\btprk.dat" -passwordkeyfile "C:\Program Files\ibm\cognos\tm1_64\bin64\btkey.dat" -filesrc “C:\TM1\Migration\z_savedataall_to_be_migrated.pro” -filedest “C:\TM1\Migration\Encrypted”

Note: The filesrc refers to the “Process” file path that needs to be converted and filedest refers to the temporary location where the encrypted process file will get created.

image 7244

  • Verify if the TI to be migrated got encrypted by opening it in notepad or notepad++

image 7245

image 7246

  • Copy the process file to the Planning Sample data directory and restart the TM1 server.

image 7247

  • Login to the TM1 server to confirm if the TI got migrated successfully.

image 7248

The process can also be encrypted using keys of the target server using a configuration file used to encrypt the target model instead of executing the code directly on cmd by executing the command as per screen-print below.

tm1crypt.exe -i "C:\Program Files\ibm\cognos\tm1_64\samples\tm1\PlanSamp\config\tm1crypt.config" -action 4 -filesrc “C:\TM1\Migration\z_savedataall_to_be_migrated.pro” -filedest “C:\TM1\Migration\Encrypted”

image 7249

Scenario 4: Migration of an object from an encrypted Server to another encrypted server.

As part of this activity a TI process “zzz_test” will be migrated from an encrypted server SData to another encrypted server Planning Sample.

  • Copy the encrypted TI from source server SData to a temporary location

image 7250

  • Decrypt the process to be migrated using keys of the source encrypted server

tm1crypt.exe -action 5 -server "SData" -user administrator -CAMNamespace "ApacheDS" -passwordfile "C:\Program Files\ibm\cognos\tm1_64\bin64\btprk.dat" -passwordkeyfile "C:\Program Files\ibm\cognos\tm1_64\bin64\btkey.dat" -filesrc “C:\TM1\Migration\zzz_test.pro” -filedest “C:\TM1\Migration\Decrypted”

image 7251

  • Verify if the process “zzz_test” got decrypted and got copied to the destination path specified in the decryption command.

image 7252

The process can also be decrypted using keys of the source server using a configuration file used while encrypting the source model instead of executing the code directly on cmd by executing the command as per screen-print below.

tm1crypt.exe -i "C:\Program Files\ibm\cognos\tm1_64\samples\tm1\SData\config\tm1crypt.config" -action 5  -filesrc "C:\TM1\Migration\zzz_test.pro" -filedest "C:\TM1\Migration\Decrypted"

image 7253

  • Encrypt the process to be migrated using keys of the target encrypted server

tm1crypt.exe -action 4 -server "Planning Sample" -user administrator -CAMNamespace "ApacheDS" -passwordfile "C:\Program Files\ibm\cognos\tm1_64\bin64\btprk.dat" -passwordkeyfile "C:\Program Files\ibm\cognos\tm1_64\bin64\btkey.dat" -filesrc “C:\TM1\Migration\Decrypted\zzz_test.pro” -filedest “C:\TM1\Migration\Encrypted”

image 7254

The process can also be encrypted using keys of the target server using a configuration file used while encrypting the target model instead of executing the code directly on cmd by executing the command as per screen-print below.

tm1crypt.exe -i "C:\Program Files\ibm\cognos\tm1_64\samples\tm1\PlanSamp\config\tm1crypt.config" -action 4  -filesrc "C:\TM1\Migration\Decrypted\zzz_test.pro" -filedest "C:\TM1\Migration\encrypted"

image 7255

  • Verify if the process “zzz_test” got encrypted and copied to the destination path specified in the encryption command. 

image 7256

  • Copy the encrypted process “zzz_test” to the data directory of the target server and restart
  • Verify if the process got migrated successfully.

image 7257

Scenario 5: Rotation of primary encryption key for added security

TM1 Server uses a two-tier key management system to encrypt/decrypt server data. The first tier includes a data encryption key (DEK) to encrypt data. The DEK is stored on-disk in a directory (within the model) called }key. The second tier uses a primary key (MK) to encrypt the DEK. The primary key is stored in an IBM Global Security Kit (GSKit) store and can be rotated regularly for added security.

When a primary key is rotated, the DEK is decrypted by using the previous primary key and then encrypted with the new primary key. During a rotation, the DEK is backed up in a  }key_backup subdirectory; located in the }key directory. Older primary keys are persisted in the KeyStore in case a model restoration is required later.

  • Primary key can be rotated by executing the below command

tm1crypt.exe -action 6 -server "Planning Sample" -user administrator -CAMNamespace "ApacheDS" -passwordfile "C:\Program Files\ibm\cognos\tm1_64\bin64\btprk.dat" -passwordkeyfile "C:\Program Files\ibm\cognos\tm1_64\bin64\btkey.dat"

image 7258

The primary key can also be rotated by using the same configuration file used while encrypting the model instead of executing the code directly on cmd by executing the command as per screen-print below.

tm1crypt.exe -i "C:\Program Files\ibm\cognos\tm1_64\samples\tm1\SData\config\tm1crypt.config" -action 6

image 7259

  • Verify if the DEK got backed up within the }Key_backup directory

image 7260

Caution: You must back up your primary key as part of your regular TM1 backup and restore procedure. If you lose your primary key, you cannot restore the primary key. You will be unable to access data on your TM1 server.

Document Location

Worldwide

[{"Line of Business":{"code":"LOB10","label":"Data and AI"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSCTEW","label":"IBM Planning Analytics Local"},"ARM Category":[{"code":"a8m0z000000blxdAAA","label":"How To"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"2.0.4;and future releases"}]

Document Information

Modified date:
13 September 2022

UID

ibm16371880