Changing the master passphrase for container deployment

The master passphrase is used to generate a password-based encryption (PBE) key that encrypts the value of sensitive properties that are stored in a Global MailboxGlobal Mailbox database. If your security policy requires you to change the master passphrase, you can do so with the command line utility.

Before you begin

Restriction: For Java™ regular expressions, you must escape the following list of special characters:
  • Backslash (\)
  • Exclamation point (!)
  • Less than symbol (<)
  • Dollar sign ($)
You must use the appropriate escape characters, depending on your operating system:
Windows
  • A caret (^) must precede each special character.
  • A caret (^) followed by an exclamation point (!) must precede each exclamation point special character.
Linux®
A backslash (\) must precede each special character.

About this task

The master passphrase must be set with the masterPassphrase set utility. It is not sufficient to change the master passphrase by manually editing the global.properties file. The masterPassphrase set utility decrypts all existing passwords with the previous master passphrase and then re-encrypts them with the new master passphrase. The utility must be used so that any existing passwords that are initially XOR-encoded are encrypted with the master passphrase.

Important: To avoid data corruption, you must ensure that the masterPassphrase set utility is not used concurrently from other nodes, or from command line sessions within the same node.
The master passphrase can be either a user-specified value, or it can be a randomly generated value set by the masterPassphrase set utility.
  • For a user-specified master passphrase, include the passphrase parameter with the masterPassphrase set utility. The master passphrase must contain at least 8 characters, but has no complexity requirements for case sensitivity, numerical values, or special characters.
  • For a randomly generated master passphrase, include the random parameter with the masterPassphrase set utility. The master passphrase is a 32 character alphanumeric string.

To change the master passphrase:

Procedure

  1. 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. Optional:
    Tip:

    You need to do this step only once on any DC and it should not be repeated on other DCs.

    To update the master passphrase, type masterPassphrase set and specify values for the adminUser , adminPassword, and passphrase parameters:
    adminUser
    Global MailboxGlobal Mailbox administrator user.
    adminPassword
    Global MailboxGlobal Mailbox administrator password.
    passphrase
    User-specified master passphrase value. Must be at least 8 characters.
    skipWriteToProperties
    This parameter is mandatory for container deployment.
    For example:
    masterPassphrase set --adminUser="admin" --adminPassword="password" --passphrase="passphrase" –-skipWriteToProperties

What to do next

When the master passphrase change is complete, make sure you update the Kubernetes secret with the new password on all data centers and run the helm upgrade to apply the changes.