Encryption key management

Netwrix Privilege Secure for Access Management (Privilege Secure) encrypts the secrets that it stores, such as account passwords. The encryption key is a file on the application server. By default, the Windows Data Protection API (DPAPI) protects the key with the machine key of that server. You can protect it with an Amazon Web Services (AWS) Key Management Service (AWS KMS) key instead. See Protect the encryption key with AWS KMS.

The key files are in C:\ProgramData\Stealthbits\PAM\Protect. Include this folder in your backups, and keep each copy with the database backup that it matches. Without the key, the secrets in a database backup can't be decrypted. See Back up and recover.

warning

Windows machine protection ties the key files to the server. Don't copy the folder to another server. To move the key, export it and import it as described in Export and import the key.

The SbPAM.RotateKey.exe tool

SbPAM.RotateKey.exe manages the encryption key. It is in the KeyTools folder of the installation directory, which is C:\Program Files\Stealthbits\PAM\KeyTools by default. Run it from a Command Prompt that you opened as an administrator. The tool stops with the message "You must run as Administrator." otherwise.

Command	What it does
rotate	Generates a new encryption key, makes it the current key, and re-encrypts the stored secrets with it.
update-secrets	Re-encrypts the stored secrets with the current key.
export	Writes the key files to a password-protected file for import on another server.
import	Reads the key files from a file that export created.
create	Generates an encryption key without making it the current key.
refreshaws	Updates the AWS KMS connection settings that a key stores.

Options

Command	Option	Description
rotate	-f, --force	Rotates without asking for confirmation.
rotate	-k, --keymodule	The key module type. The default is LocalMachine. For AWS KMS protection, use AwsKms or its number, 6. The name is case-sensitive.
rotate	-a, --awsfilename	A file that holds the AWS KMS settings. Required with -k AwsKms.
rotate	-i, --initialize	Rotates only if no current key exists.
create	-k, --keymodule	The key module type. Required.
create	-a, --awsfilename	A file that holds the AWS KMS settings. Required with -k AwsKms.
refreshaws	-a, --awsfilename	A file that holds the AWS KMS settings. Required.
refreshaws	-k, --keyid	The ID of the key file to update. The default is the current key.
export	-n, --filename	The file to create. Required.
export	-p, --password	The password that protects the file. It must have at least 12 characters.
export	-f, --force	Overwrites an existing file.
import	-n, --filename	The file that export created. Required.
import	-p, --password	The password that protects the file.
import	-f, --force	Imports without asking for confirmation.

The -k option sets the key module for rotate and create, and the key ID for refreshaws. Without -f, rotate and import ask for a Y or N answer. The default is no.

The AWS KMS settings file is a JSON file with the properties AwsAccessKey, AwsSecretKey, AwsRegionName, and KmsKeyId. The SbPAM.RotateAwsKey tool creates the file for you, passes it to SbPAM.RotateKey.exe, and deletes it afterward. See Rotate the AWS KMS key. Use the tool instead of writing the file by hand, because the file holds the AWS secret key in plain text.

Export and import the key

Export and import the key to install an additional server that shares the database, such as a high availability secondary or a server that runs a remote Action Service, Host Scan Service, or Scheduler Service. Every server that decrypts secrets needs the same key files.

1. On the server that has the key, open a Command Prompt as an administrator.

2. Run the export command. Replace keys.exp with a file name.

   cd "C:\Program Files\Stealthbits\PAM\KeyTools"
   .\SbPAM.RotateKey.exe export -n keys.exp

3. Copy the password that the tool prints. If you don't supply -p, the tool generates a 32-character password and prints it as Password for file: <password>.

4. Copy keys.exp to the KeyTools folder on the other server.

5. On the other server, back up the C:\ProgramData\Stealthbits\PAM\Protect folder. The import overwrites key files that have the same names.

6. Run the import command, enter Y to confirm, and enter the password when prompted. To skip the confirmation, add -f. To supply the password, add -p <password>.

   cd "C:\Program Files\Stealthbits\PAM\KeyTools"
   .\SbPAM.RotateKey.exe import -n keys.exp

7. Delete keys.exp and any saved copies of the password from both servers.

The import protects the key files on the other server with that server's Windows machine key.

If AWS KMS protects the key, the export reads the key through AWS KMS, so the exporting server needs working AWS access. The other server doesn't need AWS access. The import protects the key there with the Windows machine key, so the key on that server isn't protected by AWS KMS.

For the full high availability procedure, see How to Configure Encryption Keys in Multiple NPS Server Environments.

Rotate the key

Rotate the key to replace it with a new one. The tool re-encrypts the stored secrets, so the run can take several minutes on a large system.

1. Back up the database and the Protect folder.

2. Open a Command Prompt as an administrator.

3. Run the rotate command.

   cd "C:\Program Files\Stealthbits\PAM\KeyTools"
   .\SbPAM.RotateKey.exe rotate

4. Enter Y to confirm.

If the key is protected with AWS KMS, don't run rotate without the AWS options. Without -k, the tool creates a key protected by the Windows machine key. To rotate an AWS KMS-protected key, see Rotate the AWS KMS key.

The output includes "Key rotation complete." when the key rotation succeeds. The tool sets exit code 2 when it doesn't generate a key and exit code 3 after an unexpected error. It can exit with code 0 after it reports an error for a missing option, so check the output.

After you rotate the key on one server, export it again and import it on every other server that shares the database. A server that has only the old key can't decrypt secrets that the new key protects.

Privilege Secure encrypts each secret with the key that was current at that time and records the key ID with the secret. A server can decrypt a secret only when it has the key file with that ID.

The tool doesn't restart any services, and you don't need to restart them. Running services read the current key from disk for each operation. Export the new key and import it on the other servers.

The installer runs rotate -f -i when it installs the key tool. The -i option rotates only when no current key exists, so an installation or upgrade on a server that already has a key keeps that key.

Related topics

• Protect the encryption key with AWS KMS
• Rotate the AWS KMS key
• Install services on additional servers
• Security hardening checklist