Tweak key-manager comments

diff --git a/bacula/scripts/key-manager.py.in b/bacula/scripts/key-manager.py.in
index 1d77f98f16d74ecf6a113cd0ce9c923a4b26b554..4a095495309651bda0d5b3f37989468b4a18b7a2 100644 (file)
--- 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