TM1 Server data encryption

You can configure the IBM® TM1® Server to encrypt data when it is written to disk.

Note:

TM1 Server data encryption is only available for Planning Analytics Local users.Planning Analytics on Cloud and distributed TM1 Servers do not support TM1 Server data encryption.

Although TM1 Server data encryption is not supported in Planning Analytics on Cloud, the Planning Analytics on Cloud offering does provide Encryption at Rest.

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 (PK) 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.

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.

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.

Note: Encryption is not supported on a TM1 Server that is using replication and sync.

Key generation and rotation are performed by the TM1 server. Using the TM1 API, a TM1 Admin user can enable and disable server encryption. An API method can also be used to perform an PK rotation.

Users have limited control over the keys that are generated by the TM1 Server. However, the user will still have control over the GSKit store by using the command line utility that is provided by the GSKit. A user must use care when they manage the keys in the GSKit store.

When the TM1 Server generates an PK and a DEK, the keys use the following format for identification and allow the server to associate primary keys to their appropriate DEKs.

ibm_tm1_mk_version_model_name_time_stamp (For example, ibm_tm1_mk_v1_planning_sample_2016031510211514)
ibm_tm1_dek_version_model_name_time_stamp (For example, ibm_tm1_dek_v1_planning_sample_2016031510211514)

The TM1 Server includes a command line utility, which provides a (-K) option to perform a primary key rotation. The order of operation is as follows:

New names (time stamps) are generated for the data encryption and primary keys.
A new primary key is generated in the GSKit store.
The existing DEK is encrypted with the new primary key and saved to disk with the new DEK name.
The existing DEK is moved to the }key_backup folder.
The TM1 Server is shut down.

Note: You cannot perform a key rotation on a model that is not configured for encryption.

If another instance of the TM1 Server is running when a key rotation is performed, an error indicates that the TM1 server log is locked by another server instance.

During startup, the server performs a model conversion based on the existence or absence of a DEK in the model directory. The following table outlines the server actions based on these conditions.

Table 1. TM1 server data encryption behavior
DEK Presence	TM1 Server Behavior
No	TM1 Server operates without data encryption.
Yes	TM1 Server uses the existing DEK to encrypt or decrypt the model files. When the server decrypts a model, the DEK is moved to the backup folder and the server completes the process of loading the model.

TM1 model conversion

The server converts only files that were generated by TM1 processes. The following table lists the files that are converted.

Table 2. TM1 object file extensions
Extension	Description
.dim	Dimension
.hie	Hierarchy
.sub	Subsets can be located in a user's private folder
.cub	Cubes
.tab	Old cube format
.set	Sets can be located in a user's private folder
.vue	Views can be located in a user's private folder
.xbv	Expression-based views can be located in a user's private folder
.pro	Processes
.rux	Rules
.cho	Chores
.namemap	Sandbox
.dr	Data reservation
tm1s*.log	Server transaction logs
tm1s*.rej	Rejected server transaction logs
tm1rawstore.*	Pending audit event entries
tm1auditstore*.log	Process audit event entries
.cube	located under the }Applications folder
.chore	located under the }Applications folder
.dimension	located under the }Applications folder
.process	located under the }Applications folder
.extr	located under the }Applications folder
.view	located under the }Applications folder
.subset	located under the }Applications folder

Note: Binary large objects (BLOBs) used with data import, or Websheets stored as BLOBs under the }Applications folder of any file with a .blb extension, are not encrypted when the TM1 Server is enabled with encryption at rest. These files are out of the control of the TM1 Server, which makes it difficult to track their location and content accurately. For data safety, binary large objects (BLOBs) are not encrypted.

TM1 APIs

You can use TM1 APIs to enable and disable encryption, and rotate the server key. You must be a member of the TM1 Admin group. You can also move data objects manually between two servers.

For example, a user might create a process that they would like to move into their production server. The file can be decrypted by the development server, and encrypted by the production server. The file is then ready to be loaded into the production server.

The following methods perform a server shutdown and then convert the model.

TM1V TM1API TM1EncryptDataModel( TM1P hPool, TM1V hServer, TM1V iMinutesBeforeShutDown );

TM1V TM1API TM1DecryptDataModel( TM1P hPool, TM1V hServer, TM1V iMinutesBeforeShutDown );

The following method performs a key PK rotation.

TM1V TM1API TM1RotateDataModelKey( TM1P hPool, TM1V hServer );

The following methods encrypt and then decrypt a file.

TM1V TM1API TM1EncryptDataFile( TM1P hPool, 
    TM1V hServer, TM1V sFileSrc, TM1V sDestPath, TM1V fileType );

TM1V TM1API TM1DecryptDataFile( TM1P hPool, 
    TM1V hServer, TM1V sFileSrc, TM1V sDestPath, TM1V fileType );

These methods convert a file. Optionally, you can provide a destination path. If omitted, the source file is overwritten. The files must be accessible by the TM1 server and paths must be specified as relative to the TM1 server.

The following file types are valid:

TYPE_OBJECT_FILE (1)
TYPE_TRANSACTION_LOG_FILE (2)
TYPE_AUDIT_LOG_FILE (3)

TM1Crypt utility

The TM1Crypt utility allows users to manage the server for data encryption. The utility can also be used to convert files.

This command demonstrates a key rotation example:

tm1crypt -i tm1crypt.config -action rotate

This command demonstrates a decryption example:

tm1crypt -i tm1crypt.config -action decrypt 
-filesrc C:\DataModel\tm1s20160330182631.log 
-filetype 2 -filedest C:\Temp\LogDir

Details:

tm1crypt -? 
or tm1crypt -help 
or tm1crypt [<cmd_parm>...] 
     where <cmd_parm> is one of:
          -i <filespec>
          -logpath <string>
          -connect <string>
          -action <string>
          -keyfile <string>
          -outfile <string>
          -filesrc <string>
          -filedest <string>
          -filetype <string>
          -minsbeforeshutdown <string>
          -validate
          -<connect_parm>...

     where <connect_parm> is one of:
          -adminhost <string>
          -server <string>
          -user <string>
          -securitymode
          -retryattempts
          -retryinterval
          <password_parm>
          -keystorefile <filespec>
          -keystashfile <filespec>
          -FIPSOperationMode <1|2|3>
          -CAMNamespace <string>

     where <password_parm> is one of:
          -pwd <string>
          -passwordfile <filespec>
          -passwordkeyfile <filespec>

For more information, see Run the TM1Crypt utility.