NAME

WebJob-DsvTool - Digitally sign and verify WebJob payload files

SYNOPSIS

webjob-dsvtool {-s|--sign-payload} {-k|--key-file} key {payload|-} [payload ...]

webjob-dsvtool {-c|--check-signature} {-f|--cert-file} cert signature [signature ...]

webjob-dsvtool {-c|--check-signature} {-t|--cert-tree} tree signature [signature ...]

webjob-dsvtool {-g|--generate-key} {-b|--bits} bits {-t|--type} type

webjob-dsvtool {-p|--generate-password} [{-C|--character-class} class] [{-c|--character-set} set] [{-l|--length} length]

webjob-dsvtool {-v|--version}

Note: Command line arguments are position dependent, and argument snuggling (e.g., '-sk' or '-cf') 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., --check-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 specified signatures. In the tree-verify sub-mode (i.e., --cert-tree), a directory containing one or more certificates is used to verify the specified signatures. 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.

{-c|--check-signature} {-f|--cert-file} cert signature [signature ...]

Use the specified cert to verify each signature. The cert, as specified by the --cert-file argument, must be a PEM-encoded certificate. Note that signature files are expected to have the same basename as the corresponding payload file, and they must end with a '.sig' suffix.

{-c|--check-signature} {-t|--cert-tree} tree signature [signature ...]

Use all certificates stored in the certificate tree to verify each signature. 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 specified signature. 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. Note that signature files are expected to have the same basename as the corresponding payload file, and they must end with a '.sig' suffix.

{-g|--generate-key} {-b|--bits} bits {-t|--type} type

Generate a PEM-encoded private key having the specified number of bits. The bits must be a multiple of 256 and in the range [1024-4096]. The type argument must be 'DSA' or 'RSA'. The new key will be written to stdout. If the key needs to be protected with a passphrase, one can be added with openssl(1).

{-p|--generate-password} [{-C|--character-class} class] [{-c|--character-set} set] [{-l|--length} length]

Generate a pseudo random password using the default character set (alnum) or one specified on the command line. The password length, if specified, must be in the range [1-1048576] bytes. Otherwise, the default length is 8 bytes. The character set, if specified, becomes the literal set of characters from which passwords may be generated. The character class, if specified, allows the user to select one of the following character sets:

    char95  - [0-9A-Za-z] + specials
    char92  - [0-9A-Za-z] + specials - (space and double/single/back quotes)
    alnum   - [0-9A-Za-z]
    alpha   - [A-Za-z]
    lower   - [a-z]
    upper   - [A-Z]
    base16  - [0-9a-f] (a.k.a. hex)
    base10  - [0-9] (a.k.a. digit)
    base8   - [0-7] (a.k.a. octal)
    base2   - [0-1] (a.k.a. binary)

{-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

• 9 = XER_KeyGenerationError

• 10 = XER_PasswordGenerationError

• 11 = XER_SignatureVerificationMixed

For signature verification operations, a value of XER_OK means that all specified signatures have been positively verified, a value of XER_SignatureVerificationFailed means that no matching certificate was found or the signature is invalid for one or more of the specified signatures, value of XER_SignatureVerificationError means that a fatal processing or certificate error was encountered for one or more of the specified signatures, and a value of XER_SignatureVerificationMixed means that there were both invalid signatures and fatal errors.

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.

You can also create a DSA key using webjob-dsvtool:

    webjob-dsvtool --generate-key --bits 1024 --type dsa | openssl dsa -des3 > dsa-key.pem

If you don't want to use a passphrase, run it like this:

    webjob-dsvtool --generate-key --bits 1024 --type dsa > dsa-key.pem

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.

You can also create a RSA key using webjob-dsvtool:

    webjob-dsvtool --generate-key --bits 1024 --type rsa | openssl rsa -des3 > rsa-key.pem

If you don't want to use a passphrase, run it like this:

    webjob-dsvtool --generate-key --bits 1024 --type rsa > rsa-key.pem

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 --check-signature --cert-file cert.pem payload.sig

or in shorthand form:

    webjob-dsvtool -c -f cert.pem 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 --check-signature --cert-tree certs payload.sig

or in shorthand form:

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