Changing Master Key
This document describes how to update the Master Key, how to change it for the scenario on the file system, how the migration process works in the background, and what tool is used in this procedure.
Note that this procedure will be applicable only after release 3.0.0.
The PAM Admin/Key Officer updates the Master Key using a java-based tool named dek-rotator.jar.
This tool does two things:
- It takes the old and the new Master Keys as input from PAM Admin/Key Officer and changes the old Masker Key with the new one in the file system.
- Using the new Master Key, the tool re-encrypts the DEK keys, which are encrypted under the old Master Key.
PAM Admin/Key Officer runs dek-rotator.jar with a pamuser, enters the current Master Key, and then the desired value for the new Master Key. After the current Master Key is verified and the new key is entered, they are stored together in the file system encrypted with a hardcoded key and IV until DEK migration is completed.
DEK migration starts. DEK keys located under the t_dek table are migrated from the old Master Key to the new Master Key. The data previously encrypted with the old Master Key is also migrated in the background during the DEK migration. After DEK migration is completed successfully, the dek-rotator.jar tool verifies that the migration went smoothly. The tool deletes the old Master Key from the file system only after the DEK migration is verified to prevent any data loss in case DEK migration fails. The tool also checks the newly encrypted DEK keys’ functionality to identify any possible corruption.
[DEK]Old Master Key → [DEK]New Master Key
Find the Master Key Update process flow in the Workflow section below.
To update the Master Key, the PAM Admin/Key Officer should follow the steps below:
Prerequisite:
- To update the Master Key, PAM Admin/Key Officer must already know the current Master as the process requires entering the current key before typing the new one. If the current Master Key does not match the stored Master Key, the update will not succeed.
- The dek-rotator.jar tool must be run with a pamuser.
- Stop the following services before starting the update process: systemctl stop netright-tomcat systemctl stop mobilet systemctl stop nssoapp systemctl stop guacd systemctl stop http_prox systemctl stop sftp_prox systemctl stop sqlprox systemctl stop superset systemctl stop sc-watchdog systemctl stop sc-diagnostics systemctl stop kron_tacacs systemctl stop auth-service
- Run dek-rotator.jar with a pamuser as follows. You must identify the path of the netright config file when running the tool. java -jar dek-rotator.jar <NETRIGHT_CONFIG_PATH>
- Enter the current Master Key. After the current key is verified, enter the new Master Key.
- DEK migration starts. After the migration is completed successfully, you can start the services that you stopped before. systemctl start netright-tomcat systemctl start mobilet systemctl start start nssoapp systemctl start guacd systemctl start http_prox systemctl start sftp_prox systemctl start sqlprox systemctl start superset systemctl start sc-watchdog systemctl start sc-diagnostics systemctl start kron_tacacs systemctl start auth-service