Starting in Version 2.0.4, TM1 Server / Planning Analytics Local has had an ‘Encryption at Rest’ feature.  In this Cubewise blog post, we explain what EaR means, why you would want to enable it, and how you can set it up using the “tm1crypt” utility.

A TM1 Server data directory contains a number of files that store the various objects that make up a TM1 model.

The major file types that make up a model are the “.cub” cube file, the “.rux” rule file, the “.dim” dimension file, and the “.pro” (TI) process file.

In a standard, non-encrypted TM1 environment, you can open and inspect these files using a professional text editor, such as Notepad++. Opening a .dim file for a ‘month’ dimension and an ‘expenses’ cube may look something like this:

As you can probably see, the cell-level data stored in a .cub file is largely inscrutable with a text editor, but it is possible to make out the dimension’s elements from the .dim files themselves

Even more human-readable are  the .rux rules and .pro process files, which are essentially plain ASCII files with a tiny bit of machine-generated control data:

Although cell-level cube data is the most important information asset in a TM1 application, a great deal of sensitive business information can be gleaned from inspecting .dim, .rux and .pro files.

Malicious hackers would be able to see account , subscriber and product identifiers, get a very good understand how a company’s KPIs are calculated, and ascertain all the different upstream data sources and transformations used in the TM1 application. This information in turn can be applied to additional hacking, cracking and phishing attacks, leaving the company’s mission-critical finance exposed to threats.

Encrypting these file-based objects “at rest” i.e. at the file level, eliminates this risk. TM1’s EaR feature allows the entire TM1 data directory to be encrypted so that they can only be interpreted by a TM1 instance operating with the correct encryption key. This secures a TM1 instance so that copying or viewing files does not divulge any data or business logic.

Following these step-by-step instructions will encrypt a TM1 instance using the “tm1crypt” utility that is included in a standard TM1 installation (version 2.0.4 or higher). The TM1 instance in question is operating under Security Mode 1.

Use the following command line to create two files in the location C:TM1ModelsSecurity:

• tm1key.dat – a file that contains your encrypted password (in this case ‘apple’)
• tm1cipherdat – a file that contains the key to decrypt your password

“C:Program Filesibmcognostm1_64bintm1crypt.exe” -pwd apple -keyfile “C:TM1ModelsSecuritytm1key.dat” -outfile “C:TM1ModelsSecuritytm1cipher.dat” –validate

Create a TM1RunTI.config file with the following parameters;

[TM1RunTI]

Adminhost=localhost

Server=Test2

User=admin

passwordkeyfile=”C:TM1ModelsTest1tm1key.dat”

passwordfile=”C:TM1ModelsTest1tm1password.dat”

Use the following command line to create execute a test process (zzCount) using the tm1runti config file:

“C:Program Filesibmcognostm1_64bin64tm1runti.exe” -i “C:TM1ModelsSecuritytm1runti.config” -process “zzCount”

Now we know the encrypted password and key file are working, and we can use them to encrypt the TM1 instance.

As we have seen in Step 1, typing “tm1crypt” at the command line generates an encrypted password file and a key. Typing “tm1crypt” without any parameters invokes the default action, but there are more options, as follows:

1 [default] – Generate encrypted password and key file

2 – Encrypt server model

3 – Decrypt server model

4 – Encrypt file using server key

5 – Decrypt file using server key

6 – Rotate server key

Exploring these a little bit – and using the username and password approach we can do the following at the command line (note that an encryption or decryption will shut-down a server, so ensure you have performed a “SaveDataAll” operation first!);

To encrypt the database:

“C:Program Filesibmcognostm1_64bintm1crypt.exe” -action 2 -server Test2 -user admin

To decrypt the database:

“C:Program Filesibmcognostm1_64bintm1crypt.exe” -action 3 -server Test2 -user admin   

To change the key that encrypts the database:

“C:Program Filesibmcognostm1_64bintm1crypt.exe” -action 6 -server Test2 -user admin

Once we have verified that the username and password approach works, we can utilise the password and key that we created and tested with TM1RunTi

Create a TM1Crypt.config file with the following parameters;

[tm1crypt]

Adminhost=localhost

Server=Test2

User=admin

passwordkeyfile=”C:TM1ModelsTest1tm1key.dat”

passwordfile=”C:TM1ModelsTest1tm1password.dat”

To encrypt the database (no need to manually enter password)

“C:Program Filesibmcognostm1_64bintm1crypt.exe” -i “C:TM1ModelsSecuritytm1crypt.config” -action 2

Now we know how to encrypt a TM1 database we can deal with migrating an object between two TM1 instances with different encrypted data directories (for example development to production).

Step 1 – decrypt the file and save it to a different folder (i.e. save a copy of the unencrypted file to C:TM1ModelsSecurityData)

“C:Program Filesibmcognostm1_64bintm1crypt.exe” -i “C:TM1ModelsSecuritytm1crypt.config” -action 5 -filesrc “C:TM1ModelsTest2DatazzCount.pro” -filedest “C:TM1ModelsSecurityData”

Step 2 – encrypt the file and save it to a different folder (i.e. save a copy of the encrypted file to C:TM1ModelsSecurityData1 but use a different tm1crypt.config file)

“C:Program Filesibmcognostm1_64bintm1crypt.exe” -i “C:TM1ModelsSecuritytm1crypttest1.config” -action 4 -filesrc “C:TM1ModelsSecurityDatazzCount.pro” -filedest “C:TM1ModelsSecurityData1”

Now we are ready to copy the newly converted .pro file to the target data directory and re-start that server as we would do in a traditional migration.

A quick look at the encrypted and un-encrypted files in the example above shows us a bit of what is happening.

A portion of the original .pro file

Side by side comparison of the .pro file encrypted using different encryption keys from tm1crypt.config and tm1crypttest1.config

You must decrypt using the source key and then encrypt using the target key when migrating files. If you do not then the file will be unreadable for the target TM1 instance.

After a data directory has been encrypted, you will notice a new folder called }key that includes a .dat file. This is the encryption key for the TM1 instance that gets created when you encrypt a data directory.

As we have seen above this key can be changed (and should be on a rolling basis). Historical key .dat files are placed in the }key_backup folder.

“C:Program Filesibmcognostm1_64bintm1crypt.exe” -action 6 -server Test2 -user admin

If you copy an entire data directory for an encrypted TM1 instance (and include the }key folder) you can create a copy of the instance and start it up as you would normally. Including the }key is the key if you pardon the pun.

If we can do that then where is the security benefit?

In a normal, un-encrypted, TM1 instance we can copy a data directory and start up the server with the }Clients removed. During start-up a new }Clients dimension will be created with only the Admin user present and a blank password.

In an encrypted instance removing the }Clients dimension and starting the instance results in the following error and the server will not start;