SYNOPSIS
webjob-dsvtool {-s|--sign-payload} {-k|--key-file} key payload [payload
...]
webjob-dsvtool {-V|--verify-signature} {-f|--cert-file} cert payload
signature
webjob-dsvtool {-V|--verify-signature} {-t|--cert-tree} tree payload
signature
webjob-dsvtool {-v|--version}
Note: Command line arguments are position dependent, and argument
snuggling (e.g., '-sk' or '-Vf') is not supported. All arguments and
their values (if any) must be separated by whitespace.
DESCRIPTION
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 WebJob
scripts and binaries (i.e., payloads).
Because Digital Signature Verification (DSV) support is fully
integrated into WebJob client/server components, WebJob deployments
benefit in two important ways: 1) 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 WebJob's GetHook mechanism -- it's not always possible or
practical to have such tools deployed to all systems in the WebJob
framework.
In signature mode (i.e., --sign-payload), WebJob-DsvTool produces a
signature file for each payload specified on the command line.
Multiple payloads may be specified and signed in a single pass. If
your signing key is protected with a passphrase, you will be prompted
to enter it once and only once. This makes signing multiple payloads
in a single pass a snap. Signature files have the same basename as the
original 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., --verify-signature), WebJob-DsvTool
verifies the signature of a payload. There are two sub-modes within
this mode of operation: file-verify and tree-verify. In the file-
verify sub-mode (i.e., --cert-file), a single certificate is used to
verify the payload's signature. In the tree-verify sub-mode (i.e.,
--cert-tree), a directory containing one or more certificates is used
to verify the 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.
MODES OF OPERATION
The modes of operation described in this section are mutually
exclusive. In other words, only one mode may be specified per
invocation.
{-s|--sign-payload} {-k|--key-file} key payload [payload ...]
Use key to digitally sign the specified payload. The key, as
specified by the --key-file argument, must be a PEM-encoded DSA or
RSA key. For each payload signed, a corresponding signature file
will be created. Signature files have the same basename as the
original payload, and they end with a '.sig' suffix. The format
of a signature file is a single line of base64-encoded data.
To allow for automated or batch signing, WebJob-DsvTool will honor
the DSV_PASSPHRASE environment variable so long as it's less than
DSV_MAX_PASSPHRASE_LENGTH bytes long -- this length is defined in
dsv.h. While this mechanism is supported, its use in production
environments is not recommended because it increases the risk of
passphrase exposure.
{-V|--verify-signature} {-f|--cert-file} cert payload signature
Use the specified signature and cert to verify the integrity of
payload. The cert, as specified by the --cert-file argument, must
be a PEM-encoded certificate.
{-V|--verify-signature} {-t|--cert-tree} tree payload signature
Use the specified signature and all certificates stored in the
certificate tree to verify the integrity of payload. The files
stored in the certificate tree must be PEM-encoded certificates --
invalid and non-PEM-encoded files are silently ignored. Each
certificate in the certificate tree is used, in turn, to verify
the payload's integrity. The verification process does not stop
until a match is found or all certificates have been tried. Note
that WebJob-DsvTool will not search for certificates in sub-
directories of the specified tree.
{-v|--version}
Display version information and exit.
RETURN VALUES
Upon successful completion, a value of 0 (XER_OK) is returned.
Otherwise, one of the following error codes is returned:
o 1 = XER_Usage
o 2 = XER_BootStrap
o 3 = XER_ProcessArguments
o 4 = XER_PayloadSigningError
The output produced by WebJob-DsvTool for a valid signature looks like
this:
Signature is valid. CommonName = [<name>]
The output produced by WebJob-DsvTool for an invalid signature looks
like this:
Signature verification failed.
FILES
Certificate File
The certificate file is a PEM-encoded file that binds a public key
to an identity (i.e., a Distinguished Name). The public key is
required to verify payload signatures. Refer to examples 3 and 4
for details on creating self-signed certificate files.
Note: Certificate chains and expiration dates are not checked in
the verification process. It is the responsibility of the WebJob
administrator to periodically manage (i.e., add, remove, update)
any certificates installed on the clients.
Private Key
The private key is a PEM-encoded DSA or RSA key. The private key
is required to sign payloads. Refer to examples 1 and 2 for
details on creating DSA and RSA keys.
EXAMPLES
Example 1. Create a 1024-bit DSA key
This example demonstrates how to create a 1024-bit DSA key called dsa-
key.pem that is protected by a passphrase.
openssl dsaparam -out dsaparam.pem 1024
openssl gendsa -des3 -out dsa-key.pem dsaparam.pem
If you don't want to use a passphrase, drop the '-des3' argument.
Example 2. Create a 1024-bit RSA key
This example demonstrates how to create a 1024-bit RSA key called rsa-
key.pem that is protected by a passphrase.
openssl genrsa -des3 -out rsa-key.pem 1024
If you don't want to use a passphrase, drop the '-des3' argument.
Example 3. Create a self-signed, DSA certificate
Example 5. Sign a single payload
This example demonstrates how to sign a single file called payload
using a key called key.pem.
webjob-dsvtool --sign-payload --key-file key.pem payload
or in shorthand form:
webjob-dsvtool -s -k key.pem payload
Either of the above commands will produce the following file:
payload.sig
Example 6. Sign multiple payloads
This example demonstrates how to sign all files in the commands tree
using a key called key.pem.
webjob-dsvtool --sign-payload --key-file key.pem `find /var/webjob/profiles/common/commands -type f`
or in shorthand form:
webjob-dsvtool -s -k key.pem `find /var/webjob/profiles/common/commands -type f`
Either of the above commands will produce one signature file for each
file returned by find(1).
Example 7. Verify a payload's signature using a single certificate
This example demonstrates how to verify the signature of a file called
payload using a certificate called cert.pem.
webjob-dsvtool --verify-signature --cert-file cert.pem payload payload.sig
or in shorthand form:
webjob-dsvtool -V -f cert.pem payload payload.sig
Note: Certificate chains and expiration dates and are not checked in
this process -- only whether or not the signature is valid. The Common
Name assigned to the certificate will be displayed in the output if the
signature is good.
Example 8. Verify a payload's signature using certificates in a
certificate tree
This example demonstrates how to verify the signature of a file called
openssl(1), webjob(1)
AUTHOR
Klayton Monroe
HISTORY
WebJob-DsvTool first appeared in WebJob 1.6.0.
3rd Berkeley Distribution WebJob-DsvTool 1.0.0 WEBJOB-DSVTOOL(1)
Man(1) output converted with
man2html