From: Eric Bollengier Date: Tue, 14 Mar 2023 08:01:26 +0000 (+0100) Subject: Tweak key-manager comments X-Git-Tag: Beta-15.0.0~221 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5df353aeb8c689c78109e6c8605b60adb5bd5a85;p=thirdparty%2Fbacula.git Tweak key-manager comments --- diff --git a/bacula/scripts/key-manager.py.in b/bacula/scripts/key-manager.py.in index 1d77f98f1..4a0954953 100644 --- a/bacula/scripts/key-manager.py.in +++ b/bacula/scripts/key-manager.py.in @@ -5,39 +5,44 @@ # # # This script is a simple key-manager for the Volume Encryption done by the -# Storage Daemon +# Storage Daemon. # # One key is automatically generated at LABEL time for every VOLUME and -# stored into the "KEY_DIR" directory -# The key are random sequence of byt as generated by /dev/urandom. -# Two encryptions are available AES_128_XTS & AES_256_XTS -# A 3th encryption called NULL exist for testing purpose only +# is stored in the "KEY_DIR" directory. +# +# The keys are a random sequence of bytes as generated by /dev/urandom. +# +# Two encryption methods are available: AES_128_XTS & AES_256_XTS +# +# A third encryption method, called "NULL", exists for testing purposes only. # # The main purpose of this script is to provide an example and illustrate the -# protocol between the key-manager and the Storage Daemon. -# It can be used in production environment. -# Uses the --help to get help the command line parameters of this command. -# If you modify this script, rename it to avoid conflict with this file. +# protocol between the key-manager and the Storage Daemon. It may be used in +# a production environment. +# +# Use --help to get help the command line parameters of this script. +# If you modify this script, rename it to avoid the possibility of this script +# being overwritten during an upgrade. # -# The script get its input from the environment variables and return its output -# via STDOUT. +# The script gets its input from environment variables and returns its +# output via STDOUT. # -# The Storage Daemon passes the following variables via the *environment*: +# The Storage Daemon passes the following environment variables: # -# - OPERATION: This is can "LABEL" when the volume is labeled, in this case -# the script should generate a new key or this can be "READ" when -# the volume has already a label and the Storage Daemon need the already -# existing key to read or append data to the volume +# - OPERATION: This is can "LABEL" when the volume is labeled. In this case +# the script should generate a new key for the volume. This variable can +# also be "READ" when the volume has already been labeled 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 +# - VOLUME_NAME: This is the name of the volume. # -# Some variables are already there to support a *Master Key* in the future. +# 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 +# - 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 value above. # # The Storage Daemon expects some values in return via STDOUT: @@ -45,26 +50,28 @@ # - 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 length vary with the cipher. +# - cipher: This is the cipher that the Storage Daemon must use. +# The Storage Daemon knows the following ciphers: AES_128_XTS and AES_256_XTS. +# Of course the key lengths vary with the cipher. # # - cipher_key: This is the symmetric key in base64 format. # -# - comment: This is a single line of comment that is optional and ignored -# by Bacula. +# - comment: This is a single line of text that is optional and ignored +# by the SD. # # - error: This is a single line error message. -# This is optional, but when provided, Bacula consider that the script -# returned an error and display this error in the job log. +# This is optional, but when provided, the SD considers that the script +# returned an error and will display this error in the job log. # -# Bacula expects an exit code of 0, if the script exits with a different -# error code, any output are ignored and Bacula display 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. +# The Storage Daemon expects an exit code of 0. If the script exits with a +# different error code, any output is ignored and the Storage Daemon will +# display a generic message with the exit code in the job log. +# +# To return an error to the Storage Daemon, the script must set the "error" +# variable string and return an error code of 0. +# +# Here are some input/output samples to illustrate the script's funtion: # -# Here are some input/output sample to illustrate the script # $ OPERATION=LABEL VOLUME_NAME=Volume0001 ./key-manager.py getkey --cipher AES_128_XTS --key-dir tmp/keys # cipher: AES_128_XTS # cipher_key: G6HksAYDnNGr67AAx2Lb/vecTVjZoYAqSLZ7lGMyDVE= @@ -80,8 +87,8 @@ # cipher_key: G6HksAYDnNGr67AAx2Lb/vecTVjZoYAqSLZ7lGMyDVE= # volume_name: Volume0001 # -# $ OPERATION=READ VOLUME_NAME=DontExist ./key-manager.py getkey --cipher AES_128_XTS --key-dir tmp/keys 2>/dev/null -# error: no key information for volume "DontExist" +# $ OPERATION=READ VOLUME_NAME=MissingVol ./key-manager.py getkey --cipher AES_128_XTS --key-dir tmp/keys 2>/dev/null +# error: no key information for volume "MissingVol" # $ echo $? # 0 # @@ -90,7 +97,9 @@ # $ echo $? # 0 # - +# ------------ +# BEGIN SCRIPT +# ------------ import sys import logging import argparse