Backup and Restore
Individual backup files are encrypted with the cluster data encryption key (CDKEK). Backups are forest driven, so data from an encrypted forest will also be encrypted in backups. Configuration files included in a backup will be encrypted if the cluster is enabled for configuration file encryption. This encryption works with full backups, incremental backups, and journal archiving.
Note
If any forest in the backup has encryption enabled, then the entire backup will be encrypted.
The encryption keys residing in the PKCS #11 secured wallet (the embedded KMS) will be exported as part of a full backup by default. This is true whether encryption is configured to use the internal KMS or an external KMS. Full backups will include this exported copy of the keystore, encrypted using the embedded KMS passphrase, unless you specify otherwise. See Excluding the Embedded KMS from a Backup.
Warning
If you cannot access your PKCS #11 secured wallet (or external KMS if you are using one), or lose your encryption keys, you will not be able to decrypt any of your encrypted data (including backups). There is no workaround to recover the encrypted data. We recommend that you backup your encryption keys in a secure location.
The built-in function admin:cluster-set-keystore-passphrase() can be used to change the KMS passphrase. When you first set up encryption, we strongly recommend that you change the KMS passphrase to something other than the admin passphrase. This is to ensure that you utilize the Separation of Duties security principle as much as possible.
Note
By default, the keystore passphrase is automatically set to the admin password. We strongly recommend that you set a new, different passphrase before turning on encryption.
During an internal keystore backup/restore, data is added to the embedded PKCS #11 secured wallet; no keys are deleted. The encrypted file containing the keys is named kms.exp. The exported keystore is not imported during a restore from a backup. If you need to restore the keys, use the xdmp:keystore-import() function. The keystore passphrase will be required to decrypt the exported keystore file when restoring backups on another MarkLogic Server instance.
Note
To change the keystore passphrase, the current password or passphrase is required.
To restore an encrypted backup to the same cluster:
Restore the backup as usual. See Backing Up and Restoring a Database in Administrating MarkLogic Server for details.
To restore an encrypted backup to a different cluster:
Use the
xdmp:keystore-import()function to import the keystore. This function requires the keystore passphrase of the cluster where the backup was created, to decrypt the keystore:xdmp:keystore-import("keystore passphrase", "/backup-directory/kms.exp")The import process will reject duplicate keys and log a warning that includes the ID of the rejected keys. Imported keys can only be used for decryption.
Restore the backup as usual. See Backing Up and Restoring a Database in Administrating MarkLogic Server for details.
Note
As long as the current database being restored is encrypted, the restored database will also be encrypted.
Using this process, you can move your encrypted backups from one system to another and restore them, as long as you have the passphrase and import the keystore into the new system before restoring the backup. See Backup and Restore Overview in Administrating MarkLogic Server for more information about backup and restore procedures.
Warning
If you lose the cluster configuration information, you must first manually restore the keystore before an encrypted backup can be restored.
To export your keystore, use the xdmp:keystore-export() function: xdmp:keystore-export("strong passphrase", "/backups/MarkLogic.wallet.bak")
This function exports all of the encryption keys stored in the MarkLogic Server-embedded KMS (the PKCS #11 secured wallet) and stores them at the location provided to the function.