WEBJOB-DSVTOOL(1)

NAME
WebJob-DsvTool - Digitally sign and verify WebJob payload files

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.

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 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 payload signatures.

To achieve the highest degree of security that WebJob has to offer, one should not store signing keys or use WebJob-DsvTool on the WebJob server as this could potentially defeat the purpose of signing the 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.

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:

•   1 = XER_Usage

•   2 = XER_BootStrap

•   3 = XER_ProcessArguments

•   4 = XER_PayloadSigningError

•   5 = XER_SignatureVerificationFailed

•   6 = XER_SignatureVerificationError

•   7 = XER_RunMode

•   8 = XER_Shutdown

For signature verification operations, a value of XER_OK means that the payload's signature has been positively verified, a value of XER_SignatureVerificationFailed means that no matching certificate was found or the signature is invalid, and a value of XER_SignatureVerificationError means that a fatal processing or certificate error was encountered.

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
This example demonstrates how to create a self-signed, 5-year DSA certificate called dsa-crt.pem that is bound to a key called dsa-key.pem.

    openssl req -new -x509 -dss1 -days 1825 -key dsa-key.pem -out dsa-crt.pem

  Example 4. Create a self-signed, RSA certificate
This example demonstrates how to create a self-signed, 5-year RSA certificate called rsa-crt.pem that is bound to a key called rsa-key.pem.

    openssl req -new -x509 -sha1 -days 1825 -key rsa-key.pem -out rsa-crt.pem

  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 payload using certificates located in a certificate tree called certs.

    webjob-dsvtool --verify-signature --cert-tree certs payload payload.sig
or in shorthand form:

    webjob-dsvtool -V -t certs 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.

SEE ALSO
openssl(1), webjob(1)

AUTHOR
Klayton Monroe

HISTORY
WebJob-DsvTool first appeared in WebJob 1.6.0.