Encryption Command

The Encryption Command is called by the Storage Daemon every time a new volume is initialized or mounted using a device with encryption enabled. We provide a very simple example script that can be used to manage volume encryption keys.

Example Encryption Command setting in the Storage Daemon configuration:

Encryption Command = "/opt/bacula/scripts/key-manager.py getkey"

Important

The command is limited to 127 characters. The same variable substitutions as the Autochanger Command are available to be passed to the script.

The program can be an interface with your existing key management system or perform the key management on its own.

The sample script called key-manager.py may be installed via the bacula-enterprise-storage-key-manager package. The install-key-manager.sh script is designed to help to setup a master key:

# sudo -u bacula /opt/bacula/scripts/install-key-manager.sh check

# sudo -u bacula /opt/bacula/scripts/install-key-manager.sh install

Example interaction using the sample key-manager.py script:

$ OPERATION=LABEL VOLUME_NAME=Volume0001 ./key-manager.py getkey --cipher AES_128_XTS --key-dir /opt/bacula/keys
cipher: AES_128_XTS
cipher_key: G6HksAYDnNGr67AAx2Lb/vecTVjZoYAqSLZ7lGMyDVE=
volume_name: Volume0001

$ OPERATION=READ VOLUME_NAME=Volume0001 ./key-manager.py getkey --cipher AES_128_XTS --key-dir /opt/bacula/keys
cipher: AES_128_XTS
cipher_key: G6HksAYDnNGr67AAx2Lb/vecTVjZoYAqSLZ7lGMyDVE=
volume_name: Volume0001

$ cat /opt/bacula/keys/Volume0001
cipher: AES_128_XTS
cipher_key: G6HksAYDnNGr67AAx2Lb/vecTVjZoYAqSLZ7lGMyDVE=
volume_name: Volume0001

$ OPERATION=READ VOLUME_NAME=DontExist ./key-manager.py getkey --cipher AES_128_XTS --key-dir /opt/bacula/keys 2>/dev/null
error: no key information for volume "DontExist"
$ echo $?
0

$ OPERATION=BAD_CMD VOLUME_NAME=Volume0002 ./key-manager.py getkey --cipher AES_128_XTS --key-dir /opt/bacula/keys 2>/dev/null
error: environment variable OPERATION invalid "BAD_CMD" for volume "Volume0002"
$ echo $?
0

In the command above, notice that the keys are kept in one directory /opt/bacula/keys, and the arguments are passed using the environment variables.

Bacula passes the following variables via the environment:

OPERATION This is LABEL when the volume is labeled. In this case the script should generate a new key or this can be READ when the volume already has a label and the Storage Daemon needs the already existing key to read or append data to the volume

VOLUME_NAME This is the name of the volume.

Some variables already exist to support a Master Key in the future. This feature is not yet supported, but will come later:

ENC_CIPHER_KEY This is a base64 encoded version of the key encrypted by the master key

MASTER_KEYID This is a base64 encoded version of the key ID of the master key that was used to encrypt the ENC_CIPHER_KEY above.

Bacula expects some values in return:

volumename This is a repetition of the name of the volume that is given to the script. This field is optional and ignored by Bacula.

cipher This is the cipher that Bacula must use. Bacula knows the following ciphers: AES_128_XTS and AES_256_XTS. Of course, the key lengths varies depending on the cipher used.

cipher_key This is a symmetric key in base 64 format.

comment This is a single line of text that is optional and ignored by Bacula.

error This is a single line error message. This is optional, but when provided, Bacula considers that the script returned an error and displays this error in the job log.

Bacula expects an exit code of 0. If the script exits with a different error code, any output is ignored and Bacula displays a generic message with the exit code in the job log.

To return an error to Bacula, the script must use the error field and return an error code of 0.