How to…..Encryption at Rest

Jun 27. 20197 min read
Ian Boltz

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.

What do we mean by Encryption at Rest?

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:

What’s the problem, exactly?

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.

How to enable EaR using the “tm1crypt” utility.

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.

1.      Set-up an encrypted password file and a key

Use the following command line to create two files in the location C:\TM1Models\Security:

  • 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 Files\ibm\cognos\tm1_64\bin\tm1crypt.exe” -pwd apple -keyfile “C:\TM1Models\Security\tm1key.dat” -outfile “C:\TM1Models\Security\tm1cipher.dat” –validate

2.      Test this with TM1RunTI

Create a TM1RunTI.config file with the following parameters;







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

“C:\Program Files\ibm\cognos\tm1_64\bin64\tm1runti.exe” -i “C:\TM1Models\Security\tm1runti.config” -process “zzCount”

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

3.      Encrypt the data directory

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 Files\ibm\cognos\tm1_64\bin\tm1crypt.exe” -action 2 -server Test2 -user admin

To decrypt the database:

“C:\Program Files\ibm\cognos\tm1_64\bin\tm1crypt.exe” -action 3 -server Test2 -user admin   

To change the key that encrypts the database:

“C:\Program Files\ibm\cognos\tm1_64\bin\tm1crypt.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;







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

“C:\Program Files\ibm\cognos\tm1_64\bin\tm1crypt.exe” -i “C:\TM1Models\Security\tm1crypt.config” -action 2

Migrating between two TM1 instances with different encryption keys:

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:\TM1Models\Security\Data)

“C:\Program Files\ibm\cognos\tm1_64\bin\tm1crypt.exe” -i “C:\TM1Models\Security\tm1crypt.config” -action 5 -filesrc “C:\TM1Models\Test2\Data\” -filedest “C:\TM1Models\Security\Data”

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

“C:\Program Files\ibm\cognos\tm1_64\bin\tm1crypt.exe” -i “C:\TM1Models\Security\tm1crypttest1.config” -action 4 -filesrc “C:\TM1Models\Security\Data\” -filedest “C:\TM1Models\Security\Data1”

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.

Encrypted Files

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

Migration Summary

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.

Copying the Entire Data Directory

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 Files\ibm\cognos\tm1_64\bin\tm1crypt.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;

Tagged , ,