JS7 JobScheduler

Space shortcuts

Page tree

Introduction

The JS7 allows to operate JOC Cockpit in one of the security levels low, medium, high, for details see JS7 - Security Architecture.

  • low: workflows are digitally signed from a single private key used by all user accounts in JOC Cockpit. The key is stored in the JS7 database.
  • medium: workflows are digitally signed from private keys per user accounts in JOC Cockpit. The key is stored in the JS7 database.
  • high: workflows have to be digitally signed outside of JOC Cockpit. Users export workflows from the JS7 inventory to a .tar.gz/.zip export archive.

The JS7 offers a Workflow Signing Script that can be used to digitally sign exported workflows for the high security level.

For an overview of the signing process see JS7 - Deployment of Workflows for High Security Level.

Workflow Signing Script

Use Case

The Workflow Signing Script is provided for download and can be used to digitally sign workflows with X.509 certificates

  • The script is available for Linux, MacOS®, AIX® and Solaris® using bash, dash, ksh and zsh POSIX-compatible shells.
  • The script can be used to
    • create signature files for *.workflow.json files exported from the JOC Cockpit inventory.
    • traverse the directory hierarchy for workflow files.
  • The script terminates with exit code 0 to signal success, with exit code 1 for command line argument errors and with other exit codes for non-recoverable errors.
  • The script is intended as a baseline example for customization by JS7 users and by SOS within the scope of professional services.

Signing Procedure

The proceeding for signing workflows is like this:

  • Users export workflows from the JOC Cockpit inventory to a .tar.gz/.zip export archive, see JS7 - Inventory Export and Import.
  • Users can transfer the .tar.gz/.zip export archive to a secure computer that provides access to the user's private key for signing.
  • The Workflow Signing Script can be used like this:
    • Users extract the .tar.gz/.zip export archive to an arbitrary directory on a secure computer.
    • The Workflow Signing Script is executed to traverse the directory hierarchy of the extracted export archive. The script will create a signature for each workflow file (*.workflow.json) that is written to a file with the same name as the workflow and the extension .sig to the workflow's location in the directory hierarchy.
    • With signing being completed users add the updated directory hierarchy to a .tar.gz/.zip import archive file.
    • Users upload, import and deploy the import archive file to JOC Cockpit from a single step. During import the signatures will be verified with the Root CA Certificate that is stored in the user's profile.
    • Users can deploy verified workflows to the related Controller and Agents.

Prerequisites

The Workflow Signing Script requires OpenSSL to be installed. Technically the openssl command line utility is used.

Download

Find the Workflow Signing Script for download from JS7 - Download.

Usage

Invoking the Workflow Signing Script with the -h or --help argument displays the usage clause:


Software Package Management Script
Usage: js7_sign_workflow.sh [Options] [Switches]

  Options:
    --dir=<directory>                                 | optional: path to directory with files that should be signed, default: .
    --file=<file>                                     | optional: path to file that should be signed
    --keystore=<file>                                 | optional: path to keystore file in PKCS12 format
    --key=<private-key-file>                          | optional: path to private key file in .pem format
    --cert=<cert-file>                                | optional: path to certificate file in .pem format
    --password=<password>                             | optional: password for keystore/private key file
    --log-dir=<directory>                             | optional: log directory for log output of this script

  Switches:
    -h | --help                                       | displays usage
    -p | --password                                   | asks for password
    --show-logs                                       | shows log output of the script


Options

  • --dir
    • Specifies the directory in which JS7 workflow files with the extension *.workflow.json are looked up. Sub-directories are looked up recursively.
    • All files found will be signed by creating a signature file with the extension *.workflow.json.sig that holds the signature.
  • --file
    • Specifies an individual *.workflow.json file that should be signed. The signature will be stored to a *.workflow.json.sig file.
  • --keystore
    • Specifies the path to a keystore file in PKCS12 format. The keystore is expected to hold the private key and certificate.
    • Only one of the options --keystore and --key can be specified.
  • --key
    • Specifies the path to a key file that holds the private key used for signing in .pem format.
    • Only one of the options --keystore and --key can be specified.
  • --cert
    • Specifies the path to a certificate file that matches the private key used for signing. The certificate is expected in .pem format.
    • The argument is required if the --key option is used.
    • The argument is optional If the --keystore option is used. The --cert option has precedence if used with the --keystore option.
  • --password
    • Specifies the password for access to the keystore or key file.
    • Password input from the command line is considered insecure. Consider use of the -p switch or more elaborate mechanisms, for example by temporarily populating the system keystore form a security key such as a YubiKey® or similar.
  • --log-dir
    • If a log directory is specified then the Workflow Signing Script will write information about processing steps to a log file in this directory.
    • Log file names are created according to the pattern: js7_sign_workflow.<hostname>.<yyyy>-<MM>-<dd>T<hh>-<mm>-<ss>.log
    • For example: js7_sign_workflow.centostest_primary.2023-05-19T20-50-45.log

Switches

  • -h | --help
    • Displays usage.
  • -p | --password
    • Specifies that the user will be prompted for password input.
  • --show-logs
    • Displays the log output created by the script if the --log-dir option is used.

Environment Variables

The following environment variables can be used to provide default values for options of the Workflow Signing Script:

  • JS7_SIGN_KEYSTORE
    • The environment variable can be used to populate the --keystore option from a default value.
  • JS7_SIGN_KEY
    • The environment variable can be used to populate the --key option from a default value.
  • JS7_SIGN_CERT
    • The environment variable can be used to populate the --cert option from a default value.

Exit Codes

  • 0: success
  • 1: argument errors
  • 2: non-recoverable errors

Examples

The following examples illustrate typical use cases.

Signing all Workflows in the current Directory recursively using a Keystore and prompting for a Password

Example for use of Workflow Signing Script
./js7_sign_workflow.sh \
    --keystore=/home/sos/signing-keystore.p12 \
    -p

# makes use of the default value to recursively sign all workflows starting from the current directory 
# specifies the location of the keystore with the private key and certificate for digital signing
# specifies that the user will be prompted for a password to access the keystore

Signing all Workflows in the current Directory recursively using a Key File and Certificate File

Example for use of Workflow Signing Script
./js7_sign_workflow.sh \
    --key=/home/sos/signing.key \
    --cert=/home/sos/signing.crt

# makes use of the default value to recursively sign all workflows starting from the current directory
# specifies the location of the private key file and certificate file
# no password is used for access to the private key file

Signing all Workflows in a specific Directory recursively using a Key File and Certificate File

Example for use of Workflow Signing Script
./js7_sign_workflow.sh \
    --dir=/home/sos/workflows \
    --key=/home/sos/signing.key \
    --cert=/home/sos/signing.crt

# specifies the directory in which workflows will be signed recursively
# specifies the location of the private key file and certificate file
# no password is used for access to the private key file

Signing a specific Workflow  using a Key File and Certificate File

Example for use of Workflow Signing Script
./js7_sign_workflow.sh \
    --file=/home/sos/workflows/eod_processing.workflow.json \
    --key=/home/sos/signing.key \
    --cert=/home/sos/signing.crt

# specifies the workflow file to be signed
# specifies the location of the private key file and certificate file
# no password is used for access to the private key file

Signing all Workflows in the current Directory recursively using a Key File and Certificate File from Environment Variables

Example for use of Workflow Signing Script
export JS7_SIGN_KEY=/home/sos/signing.key
export JS7_SIGN_CERT=/home/sos/signing.crt

./js7_sign_workflow.sh

# exports environment variables, for example from a shell user profile to locate the private key and certificate files
# makes use of the default value to recursively sign all workflows starting from the current directory
# no password is used for access to the private key file

Extracting an Export Archive, Signing all Workflows recursively using a Key File and Certificate File, Creating an Import Archive

Example for use of Workflow Signing Script
# navigate to the directory where to extract the export archive file
cd /home/sos/signing

# extract export archive file
tar -xzf /tmp/export_workflows.tar.gz

# sign workflow files recursively
./js7_sign_workflow.sh --key=/home/sos/signing.key --cert=/home/sos/signing.crt

# compress workflow files and signature files to an import archive file for upload to JOC Cockpit
tar -czf /tmp/import_workflows.tar.gz *



  • No labels