=head1 DESCRIPTION

B<WebJob-DsvTool> is a utility for digitally signing and verifying
arbitrary files using certificate-based public/private keys.
Initially, it was created as a helper utility to sign and verify
B<WebJob> scripts and binaries (i.e., B<payloads>).

Because Digital Signature Verification (DSV) support is fully
integrated into B<WebJob> client/server components, B<WebJob>
deployments benefit in two important ways: 1) B<WebJob> clients have
an additional mechanism to protect against the case where their server
can no longer be trusted (e.g., because it has been compromised) and
2) it reduces the installation footprint by eliminating dependencies
on external tools (e.g., GnuPG or OpenSSL) that provide equivalent
functionality through B<WebJob's> B<GetHook> mechanism -- it's not
always possible or practical to have such tools deployed to all
systems in the B<WebJob> framework.

In signature mode (i.e., B<--sign-payload>), B<WebJob-DsvTool>
produces a signature file for each B<payload> specified on the command
line.  Multiple B<payloads> may be specified and signed in a single
pass.  If your signing B<key> is protected with a passphrase, you will
be prompted to enter it once and only once.  This makes signing
multiple B<payloads> in a single pass a snap.  Signature files have
the same basename as the original B<payload>, and they end with a
'.sig' suffix.  The format of a signature file is a single line of
base64-encoded data.

In verification mode (i.e., B<--verify-signature>), B<WebJob-DsvTool>
verifies the signature of a B<payload>.  There are two sub-modes
within this mode of operation: file-verify and tree-verify.  In the
file-verify sub-mode (i.e., B<--cert-file>), a single certificate is
used to verify the B<payload's> signature.  In the tree-verify
sub-mode (i.e., B<--cert-tree>), a directory containing one or more
certificates is used to verify the B<payload's> signature.  If you are
attempting to track down or debug a potential signature verification
issue with a particular certificate, it's best to use the file-verify
sub-mode of operation as it does a better job of reporting errors.

Each person that is granted the ability to schedule jobs should create
his/her own signing key/certificate.  Each signing key must be
fiercely protected.  Remember, if the B<WebJob> server is compromised,
one of these keys would, in theory, be required by the attacker to
schedule new jobs or modify existing jobs -- this assumes that all
clients are configured to verify B<payload> signatures.

To achieve the highest degree of security that B<WebJob> has to offer,
one should not store signing keys or use B<WebJob-DsvTool> on the
B<WebJob> server as this could potentially defeat the purpose of
signing the B<payloads>.  In other words, if the server is
compromised, you must assume that everything on it, including the
signing keys (and their passphrases), can be compromised as well.