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, and Windows using PowerShell 5.1, 7.x.
• 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 an import the import archive file to JOC Cockpit. 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

For usage of the Workflow Signing Script see JS7 - PowerShell Examples - Sign-JS7Workflows.ps1

Environment Variables

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

• JS7_SIGN_KEYSTORE
  • The environment variable can be used to populate the -Keystore argument from a default value.
• JS7_SIGN_KEY
  • The environment variable can be used to populate the -Key argument from a default value.
• JS7_SIGN_CERT
  • The environment variable can be used to populate the -Cert argument from a default value.

Exit Codes

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

Examples

The following examples illustrate typical use cases.

Examples for all Platforms

Sign from Keystore

./Sign-JS7Workflow.ps1 `
    -Keystore ./signing.p12 `
    -AskForCredentials

# signs all *.workflow.json files in the current directory
# makes use of the indicated keystore that holds the private key and certificate for code signing
# asks for secure input of the keystore password

Sign from Key File and Certificate File

./Sign-JS7Workflow.ps1 `
    -Key ./signing.key `
    -Cert ./signing.crt

# signs all *.workflow.json files in the current directory
# makes use of the indicated key file that holds the private key and certificate file for code signing

Sign single Workflow File

./Sign-JS7Workflow.ps1 `
    -File ./end-of-day.workflow.json `
    -Keystore ./signing.p12 `
    -AskForCredentials
 
# signs the indicated *.workflow.json file
# makes use of the indicated keystore that holds the private key and certificate for code signing

Sign all Workflow Files from a Directory

./Sign-JS7Workflow.ps1 `
    -Dir ./some/folder `
    -Recurse `
    -Keystore ./signing.p12 `
    -AskForCredentials
 
# signs all *.workflow.json files in the indicated directory and sub-directories recursively
# makes use of the indicated keystore that holds the private key and certificate for code signing

Sign from Key File and Certificate File specified by Environment Variables

$env:JS7_SIGN_KEY=/home/sos/signing.key
$env:JS7_SIGN_CERT=/home/sos/signing.crt

./Sign-JS7Workflow.ps1 `
    -Dir ./some/folder `
    -Recurse `
    -Hash sha256

# makes use of environment variables to populate the -Key and -Cert arguments
# signs all *.workflow.json files in the indicated directory and sub-directories recursively
# makes use of the indicated key file that holds the private key and certificate file for code signing
# applies the indicated hash algorithm to signatures

Example for Unix

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

# navigate to the directory where to extract the export archive file
Set-Location /home/sos/signing

# extract export archive file
tar -xzf /tmp/export_workflows.tar.gz
# alternatively extract .zip archive file
# Expand-Archive -Path /tmp/export_workflows.zip -DestinationPath .

# sign workflow files recursively
./Sign-JS7Workflow.ps1 -Key /home/sos/signing.key -Cert /home/sos/signing.crt -Dir . -Recurse

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

Example for Windows

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

# navigate to the directory where to extract the export archive file
Set-Location C:\js7\signing

# extract export archive file
tar.exe -xzf C:\tmp\export_workflows.tar.gz
# alternatively extract .zip archive file
# Expand-Archive -Path C:\tmp\export_workflows.zip -DestinationPath .

# sign workflow files recursively
C:\js7\Sign-JS7Workflow.ps1 -Key C:\js7\signing.key -Cert C:\js7\signing.crt -Dir . -Recurse

# compress workflow files and signature files to an import archive file for upload to JOC Cockpit
tar.exe -czf C:\tmp\import_workflow.tar.gz *.*