key-manager Script Implementation

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 a single directory, specifically /opt/bacula/keys, while the arguments are conveyed through the use of environment variables.

Bacula passes the following variables via the environment:

OPERATION This is set to LABEL when the Volume is being labeled. In this case the script is expected to generate a new key. Alternatively, it may be set to READ when the Volume already has a label, necessitating the Storage Daemon to use the 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. Although this feature is not currently available, it is anticipated to be introduced 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 anticipates the following values in response:

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. The key lengths will vary based on the cipher selected.

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. Should the script terminate with any other error code, all output will be disregarded, and Bacula will log a generic message along with the exit code.

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