In this chapter you will learn everything about backy2’s encryption, migration to the next encryption version and changing your keys (aka re-keying)
$ backy2 migrate-encryption --help usage: backy2 migrate-encryption [-h] version_uid positional arguments: version_uid The version uid to migrate optional arguments: -h, --help show this help message and exit
$ backy2 rekey --help usage: backy2 rekey [-h] oldkey positional arguments: oldkey The old key as it was found in the config optional arguments: -h, --help show this help message and exit
You must set a encryption key (64 hex characters, resulting in a 32-byte AES key)
[DEFAULTS] section of backy.cfg. You will only be able to read or scrub
data when the key is correct (or the blocks don’t have encryption):
encryption_key: decafbaddecafbaddecafbzddecafbaddecafbaddecafbaddecafbaddecafba encryption_version: 1
The above key is intentionally invalid so that nobody copy&pastes this.
Please create your own key, e.g. via:
$ openssl rand -hex 32
If you lose your key¶
If you lose your key you will not be able to restore or scrub your data and you will have to backup all data again. Please note that if you lose your key, you will have to start with a new backy2 database.
The reason is, that backy2 will not check if existing blocks (which may be used when using a hints-file during backup or when deduplication is enabled) have a valid encryption key during backups for performance reasons.
Re-keying is good habit. You may change your backup key every now and then, for example when persons leave your company and they might have the old key.
Re-keying does not access your data backend (i.e. the stored blocks). This means, it’s a relatively fast, local process on your backup-server.
This is possible because backy2 sets an individual encryption key for each
block and wraps this key with the key in your
backy2.cfg. When re-keying,
the encryption-key will not be changed. Instead, it will be unwrapped with your
old key and wrapped with your new key. As the wrapped keys are stored in your
meta backend (i.e. your database), this action can be performed locally.
These are the recommended steps for re-keying:
check that you have
backy2 exportfor every of your versions, because the export contains the keys wrapped by your old key
comment out your old key configured in
create a new key by calling
openssl rand -hex 32
set the new key into
backy2 rekey <oldkey>
The rekeying is done in one database transaction and it will lock backy2 completely (i.e. you can not run any backups, scrubs, restores while it is running).
Just in case your DBMS has a bug or something crashes really badly there’s a
small chance that this process only changes some blocks. If this happens,
remove all existing version (
backy2 rm -f <version>) and re-import
them from the exports you created in step 1 above. Then repeat the process.
After the process has finished, create new exports for all versions because they now contain the new wrapped keys.
backy2 defines integer versions for encryption. Usually 1 should be better than 0, 2 better than 1.
As of this writing, version 1 is the current version whereas previous backy2 versions created backups with no encryption, which has been redefined as encryption version 0.
Version 1 uses AES GCM with 256bit keys + a nonce per block. Before it encrypts a block, data is compressed with zstandard compression level 1.
If we learn that there’s a problem with this encryption, we will be able to implement a next version with corrected encryption or compression.
Migrating to the next encryption version¶
When migrating to a new encryption version, you will have to call
backy2 migrate-encryption <version> for each version.
backy2 will then create a new version for the encrypted blocks. Doing this means, backy2 will read each block from the data backend, decrypt it, encrypt it and store it to the data backend again, just like a regular backup.
migrate-encryption is faster than restoring and backing up
again because it benefits from existing blocks which already are
encrypted - just like deduplication works.
These are the steps to perform in order to migrate to the next encryption version (if available).
set the new
for each existing version (
backy2 ls -f uid) call
backy2 migrate-encryption <version uid>
This process may run in parallel to running backups/restores.