Deleted master passphrase

Edit online
If the master passphrase is deleted from the global.properties file, or the value is corrupted, all data that was encrypted by the deleted master passphrase is unrecoverable. To create a new master passphrase, you can disable encryption, reconfigure the applications in the Global Mailbox system and then re-enable encryption.

Symptoms

You are unable to view information about the application users by selecting an application on the User Explorer page of the Global Mailbox management tool.

Deletion of the master passphrase from the global.properties file, or corruption of the value results in a failure of the User Lookup service and the Event Data Lookup service.

Causes

If the global.properties file is manually edited, the line that contains the master passphrase can be unintentionally deleted or modified.

Environment

Linux® and Windows.

Diagnosing the problem

If you notice that actions performed in the User Explorer page result in error messages, you can troubleshoot the situation by checking the configuration of the master passphrase:

  1. From the command line, locate the /<install_dir>/MailboxUtilities/admin/bin (UNIX/Linux) or \<install_dir>\MailboxUtilities\admin\bin (Windows) directory.
    Tip: Replace <install_dir> with the directory where your instance is installed.
  2. Type ./masterPassphrase.sh set (Linux or UNIX) or masterPassphrase.bat set (Windows).
    The following message indicates that the master passphrase is deleted from the global.properties file:
    The master passphrase has already been configured, but the value  specified 
on the global.properties file is not valid. In order to change  the master passphrase, the
correct current value needs to be available  on the global.properties file.

Resolving the problem

To recover data that is encrypted by the deleted master passphrase, you must take the following steps:
  1. From the command line, locate the /<install_dir>/MailboxUtilities/admin/bin (UNIX/Linux) or \<install_dir>\MailboxUtilities\admin\bin (Windows) directory.
    Tip: Replace <install_dir> with the directory where your instance is installed.
  2. Stop the Liberty server. Type ./server stop (Linux or UNIX) or server stop (Windows).
  3. Open the global.properties file.
  4. Delete the com.ibm.mailbox.master.passphrase property.
  5. From the command line, type cqlsh to access the password vault with the cqlsh utility.
    Important: Make sure that you run the cqlsh utility on a server that is running Apache Cassandra.
  6. Type the following command:
    use gatekeeper;
select * from password_vault;
  7. Delete all of the records that are listed from the password vault:
    cqlsh:gatekeeper> delete from password_vault where id='EXAMPLE_ID'
  8. For each processing application in the Global Mailbox system, complete the following steps to disable encryption and then reconfigure each application:
    1. From the command line, locate the /<install_dir>/MailboxUtilities/admin/bin (UNIX/Linux) or \<install_dir>\MailboxUtilities\admin\bin (Windows) directory.
      Tip: Replace <install_dir> with the directory where your instance is installed.
    2. Disable encryption on your Global Mailbox system. Type ./appConfigUtility.sh updateAppConfig (Linux or UNIX) or appConfigUtility.bat updateAppConfig (Windows), and enter the following list of parameters, specifying a value for each parameter. Specify false for the encryption parameter:
      appName
      The application name.
      adminUser
      The Global Mailbox administrator user.
      adminPassword
      The Global Mailbox administrator password.
      encryption
      Specifies encryption for sensitive properties for the application. If the value is specified as false, sensitive properties for the application are not encrypted in storage on the database.
    3. Reconfigure the user lookup service. Type ./appConfigUtility.sh setUserLookup (Linux or UNIX) or appConfigUtility.bat setUserLookup, and enter the following list of parameters, specifying a value for each parameter:
      appName
      The application name.
      adminUser
      The Global Mailbox administrator user.
      adminPassword
      The Global Mailbox administrator password.
      authPassword
      Sterling B2B Integratoradministrator password.
    4. Reconfigure the event data lookup service. Type ./appConfigUtility.sh setEventDataLookup (Linux or UNIX) or appConfigUtility.bat setEventDataLookup (Windows), and enter the following list of parameters, specifying a value for each parameter:
      appName
      The application name.
      adminUser
      The Global Mailbox administrator user.
      adminPassword
      The Global Mailbox administrator password.
      authPassword
      Sterling B2B Integratoradministrator password.
    5. Respecify the WebSphere® MQ password. Type ./appConfigUtility.sh setEventNotification (Linux or UNIX) or appConfigUtility.bat setEventNotification (Windows), and enter the following list of parameters, specifying a value for each parameter:
      appName
      The application name.
      adminUser
      The Global Mailbox administrator user.
      adminPassword
      The Global Mailbox administrator password.
      mqPassword
      The WebSphere MQ server password.
    6. Reconfigure SSL for all registered applications. To reconfigure SSL, see Securing with SSL.
  9. Reenter the keystore password for the storage buckets in your Global Mailbox system. Type ./storagePassphrase.sh check (Linux or UNIX) or storagePassphrase.bat check (Windows), and enter the following list of parameters, specifying a value for each parameter:
    adminUser
    The Global Mailbox administrator user.
    adminPassword
    The Global Mailbox administrator password.
  10. Set a new master passphrase for your Global Mailbox system. Type ./masterPassphrase.sh set (Linux or UNIX) or masterPassphrase.bat set (Windows), and enter the following list of parameters, specifying a value for each parameter:
    adminUser
    The Global Mailbox administrator user.
    adminPassword
    The Global Mailbox administrator password.
    random
    Randomly generated master passphrase value. The utility creates a 32-character alphanumeric string.
    Important: Do not specify a value for random parameter.
  11. Enable encryption for an application. Type ./appConfigUtility.sh updateAppConfig (Linux or UNIX) or appConfigUtility.bat updateAppConfig (Windows), and enter the following list of parameter, specifying a value for each parameter. Specify true for the encryption parameter:
    appName
    The application name.
    adminUser
    The Global Mailbox administrator user.
    adminPassword
    The Global Mailbox administrator password.
    encryption
    Specifies encryption for sensitive properties for the application. If the value is specified as false, sensitive properties for the application are not encrypted in storage on the database.
  12. Set the database storage passphrase. Type ./storagePassphrase.sh set (Linux or UNIX) or storagePassphrase.bat set (Windows) and enter the following list of parameters, specifying a value for each parameter:
    adminPassword
    The Global Mailbox administrator password.
    adminUser
    The Global Mailbox administrator user.
    passphrase
    The storage passphrase (also known as key encryption passphrase) is used to generate the key encryption key (KEK) for a storage bucket.
  13. Copy the global.properties file to the <config_root>/ directory in each data center of your Global Mailbox system.
  14. Locate the /<install_dir>/MailboxUtilities/admin/bin (UNIX/Linux) or \<install_dir>\MailboxUtilities\admin\bin (Windows) directory.
    Tip: Replace <install_dir> with the directory where your instance is installed.
  15. Type ./server start (Linux or UNIX) or server start (Windows) to start the Liberty server.