IBM Spectrum Protect (TSM) Master Encryption Key Management: Best Practices for TSM Database Recovery

Method 1: Manually Copy the Key Database Files (Not Recommended)

One approach is to manually back up the key database files located in the TSM server’s home instance directory:

• dsmkeydb.kdb – The key database where the master encryption key is stored
• dsmkeydb.sth – The stash file that allows access to the key database

To use this method, you must configure the TSM server to skip encryption key protection by running the following command:

set dbrecovery TSMDEVCLASS protectkeys=no 

With this configuration, TSM database recovery (dsmserv restore db) can be performed without requiring a password. Essentially, this method instructs the TSM server not to include the master encryption key in the database backup. As a result, during database recovery, these key files must be manually restored to the home instance directory; otherwise, TSM client access will be denied, meaning TSM client restore operations will not be possible.

Method 2: Automatically Include the Master Encryption Key in TSM Database Backup (Recommended)

The preferred method is to include the master encryption key as part of the TSM database backup by using the following command:

set dbrecovery TSMDEVCLASS protectkeys=yes password=xxxxx  

As you can see, a password must be generated when running this command, and it will be required during TSM database recovery (dsmserv restore db). This ensures that the master encryption key is backed up along with the TSM database. However, it is crucial for the administrator to remember the configured password, as forgetting it will result in database recovery failure.

Failure Scenarios and Error Messages

It is important to understand what could happen if the master key encryption is missing when TSM database recovery executed. I tested both scenarios and observed the following failures. Please review each case below to see the the errors you might encounter. Consider this carefully!!! If you haven’t prepared for it, you could find yourself in a disasterous situation. This is not the scenario you want to face due to oversight or neglect.

1. Failure Due to Missing Key Files (Manual Method)

If the master encryption key files (dsmkeydb.kdb and dsmkeydb.sth) are missing after a TSM database restore, the server start, but client access will be denied with errors such as:

ANR8599W The connection with MYTSMSVR01.mydomain.com:60584 failed due to an untrusted server certificate. An attempt to reconnect and establish certificate trust might follow.
ANR0150E Failed to open Node MYTSMSVR01. There was an error decrypting the Node password. 👈     
ANR0422W Session 2 for node MYTSMSVR01 (MYTSMSVR01.mydomain.com(60586)) refused - node name not registered.
ANR0150E Failed to open Node MYTSMSVR01. There was an error decrypting the Node password.
ANR0422W Session 3 for node MYTSMSVR01 (MYTSMSVR01.mydomain.com(60588)) refused - node name not registered.
ANR0423W Session 4 for administrator MYTSMSVR01 (MYTSMSVR01.mydomain.com(60590)) refused - administrator name not registered.
ANR0150E Failed to open Node MYTSMSVR01. There was an error decrypting the Node password.
ANR0422W Session 5 for node MYTSMSVR01 (MYTSMSVR01.mydomain.com(60592)) refused - node name not registered.

These errors indicate that the encryption key was not successfully restored, preventing client connections. it means even if TSM server database successfully restored. you won’t be able to execute any TSM client restore.

2. Failure Due to Forgotten Password (Automated Method)

If the password used to protect the master encryption key is forgotten, TSM database recovery will fail with the following error when executing dsmserv restore db. Below is the sample output right after dsmserv restore db started.

ANR7801I Subsystem process ID is 11900.
ANR0900I Processing options file /opt/tivoli/mytsmsvr01/dsmserv.opt.
ANR0010W Unable to open message catalog for language en_US.UTF-8. The default language message catalog will be used.
ANR7814I Using instance directory /opt/tivoli/mytsmsvr01.
ANR3339I Default Label in key data base is TSM Server SelfSigned SHA Key.
ANR4726I The ICC support module has been loaded.
ANR1636W The server machine GUID changed: old value (), new value (18.7d.8a.1e.76.b7.e7.11.b6.75.14.02.ec.70.9c.10).
ANR8598I Outbound SSL Services were loaded.
ANR8200I TCP/IP Version 4 driver ready for connection with clients on port 1500.
ANR0152I Database manager successfully started.
ANR4634I Starting point-in-time database restore to date 11/16/2017 10:25:28 AM.
ANR4591I Selected backup series 45 from 11/16/2017 and 10:12:49 AM as best candidate available for restore database processing.
ANR4592I Restore database backup series 45 includes eligible operation 0 with volume /tsmstg01/tsmfile/tsmdbbackup/10855969.DBV having sequence 100001 and using device
class TSMDBBACKUP.
ANR4598I Validating database backup information for selected backup series 45 and operation 0 using volume /tsmstg01/tsmfile/tsmdbbackup/10855969.DBV.
ANR8340I FILE volume /tsmstg01/tsmfile/tsmdbbackup/10855969.DBV mounted.
ANR1363I Input volume /tsmstg01/tsmfile/tsmdbbackup/10855969.DBV opened (sequence number 1).
ANR1364I Input volume /tsmstg01/tsmfile/tsmdbbackup/10855969.DBV closed.
ANR1739E The database backup contains a copy of the server master encryption key but no password was provided.  👈

dsmserv restore db failed due to no or incorrect password. It means you can’t even start TSM server database restoration.

Conclusion: Choosing the Right Approach

When managing the TSM Master Encryption Key, you have two choices:

• Manual Key Backup: If you do not want to store a password, you must manually back up the encryption key files (dsmkeydb.kdb and dsmkeydb.sth). Failure to do so will result in denied access for all TSM clients. No TSM client restore operation is possible.
• Automated Key Backup (Recommended): If you choose to include the master encryption key in the TSM database backup, you must securely store the password. Forgetting the password will make TSM database recovery impossible.