PingDirectory

Encrypting backups

Even if the data stored in a backend’s database is encrypted, there is additional benefit in encrypting backups of that database.

The encryption covers additional database metadata that is not encrypted, and it also serves as a kind of integrity check to ensure that the backup hasn’t been altered or corrupted since it was created.

If you enable data encryption when running setup, then the server is automatically configured to encrypt backups by default. If encryption is enabled after setup, you can use the encrypt-backups-by-default global configuration property to configure this. In either case, the default behavior is to use the preferred encryption settings definition to obtain the encryption key, but you can explicitly specify an alternative definition for backups using the backup-encryption-settings-definition-id property.

The backup tool offers the following arguments related to encryption.

Argument Description

--encrypt

Indicates that the backup should be encrypted. This can be used to explicitly enable encryption if the encrypt-backups-by-default global configuration property is set to false. This argument is also required if you use one of the --promptForEncryptionPassphrase, --encryptionPassphraseFile, or --encryptionSettingsDefinitionID arguments. If encryption is not enabled by default in the global configuration and this argument is provided without one of the --promptForEncryptionPassphrase, --encryptionPassphraseFile, or --encryptionSettingsDefinitionID arguments, then the server’s preferred encryption settings definition is used.

--promptForEncryptionPassphrase

Indicates that the backup tool should interactively prompt for the passphrase used to generate the encryption key. If this is provided, then the backup is encrypted with that key rather than one obtained from an encryption settings definition.

--encryptionPassphraseFile

Specifies the path to a file that contains the passphrase that should be used to generate the encryption key. If this is provided, then the backup is encrypted with that key rather than one obtained from an encryption settings definition.

--encryptionSettingsDefinitionID

Specifies the identifier for the encryption settings definition that should be used to encrypt the data. This can override the logic that the server would otherwise use to select the encryption settings definition.

--doNotEncrypt

Indicates that the backup should not be encrypted. This can be used to explicitly obtain an unencrypted backup if encrypt-backups-by-default is set to true in the global configuration.

Each backup directory includes a descriptor file with information about all of the backups contained in that directory. This descriptor indicates whether the backup is encrypted, and if it was encrypted with a definition from the encryption settings database, then it includes its ID. In such cases, the restore tool automatically obtains the necessary key from the encryption settings database.

However, if the backup was encrypted with a passphrase rather than an encryption settings definition or if the definition is not included in the encryption settings database but you know the passphrase used to create that definition, then you can use one of the following arguments to provide the necessary passphrase.

Argument Description

--promptForEncryptionPassphrase

Indicates that the restore tool should interactively prompt for the passphrase used to generate the encryption key.

--encryptionPassphraseFile

Indicates that the restore tool should interactively prompt for the passphrase used to generate the encryption key.