JS7 JobScheduler

Space shortcuts

Page tree

Introduction

Jobs might require variables for parameterization that hold secrets. We find a number of requirements for management of such variables, see JS7 - How to encrypt and decrypt Variables

The preferred solution with JS7 is to use asymmetric keys:

  • Encryption and decryption is performed directly by the related jobs.
  • No JS7 product is involved in encryption/decryption as otherwise the JS7 product would know the keys involved that potentially could be compromised by logging, database persistence etc.
  • Performing encryption/decryption by jobs limits the attack surface to the OS process executing the job. The job implementation is controlled by the user who can verify secure operation.

Solution Outline

The solution is provided for download and can be used to automate encryption and decryption of variables.

  • The solution is available for Windows, Linux and MacOS® using PowerShell 7.x
  • The solution is intended as a baseline example for customization by JS7 users and by SOS within the scope of professional services.

Solution for PowerShell Jobs on Unix/Windows

Managing the private/public key pair

Step 1: Create a private/public key pair

The following step is performed on the server hosting the Agent that should decrypt variables using the openssl utility from the command line:

Example how to create private/public key pair
# navigate to the Agent's <agent-data>/config/private directory
Set-Location $env:ProgramData/sos-berlin.com/js7/agent/config/private
# cd %ProgramData%/sos-berlin.com/js7/agent/config/private

# create the private key file in pkcs#1 format using "jobscheduler" as a passphrase, keys starts with: -----BEGIN RSA PRIVATE KEY-----
openssl genrsa -aes256 -passout pass:"jobscheduler" -out agent-pkcs1.key 2048

# convert key from pkcs#1 to pkcs#8 format, key starts with: -----BEGIN ENCRYPTED PRIVATE KEY-----
openssl pkcs8 -inform PEM -topk8 -in agent-pkcs1.key -out agent.key

# extract agent.pub public key file from agent.key private key file
openssl rsa -passin pass:"jobscheduler" -in agent.key -pubout > agent.pub

Step 2: Make public key available

Copy the public key file to the server(s) hosting the Agent(s) that should encrypt variables:

Example where to copy the public key
# navigate to the Agent's <agent-data>/config directory
Set-Location $env:ProgramData/sos-berlin.com/js7/agent/config
# cd %ProgramData%/sos-berlin.com/js7/agent/config

# copy the agent.pub public key file from to the current location using a file transfer tool or your clipboard

Setting up the Example

The example introduces a JS7 - Script Include and a workflow holding two jobs to encrypt and to decrypt variables.

First Job: encrypt-variable

The fist job encrypt-variable is implemented like this:

Example how to encrypt variables from a job
@@setlocal enabledelayedexpansion & @@findstr/v "^@@[fs].*&" "%~f0" | pwsh.exe -NonInteractive -Command - & exit !errorlevel!/b&

$ErrorActionPreference = "stop"

# encrypt variable values using the target Agent's public key
##!include CryptoPowerShell

# optionally specify the location of the public key
## include CryptoPowerShell --replace="<public-key>","$env:JS7_AGENT_CONFIG_DIR/agent.pub"

Encrypt-Variable -Name myVar1 -Value "secret1"
Encrypt-Variable -Name myVar2 -Value "secret2"


Explanation:

  • The job makes use of a shebang for Windows to invoke pwsh.exe. For Unix use:
    • #!/usr/bin/env pwsh
  • The job makes use of JS7 - Script Includes: the CryptoPowerShell Script Include holds the PowerShell functions used in the job.
    • The ##!include CryptoPowerShell inserts the PowerShell code available from the indicated CryptoPowerShell Script Include.
    • The Script Include is invoked once per job and optionally can be parameterized to specify the location of the public key.
      • ##!include CryptoPowerShell --replace="<public-key>","/var/sos-berlin.com/js7/agent/config/agent.pub"
      • The first argument of the --replace option is a placeholder available with the CryptoPoserShell Script Include.
      • The second argument represents the value by which the placeholder will be replaced. The above value corresponds to the default value that will be used if the Script Include is invoked without replacement options: the public key is looked up from a file with the name agent.pub in the Agent's <agent-data>/config directory.
  • The Encrypt-Variable PowerShell function expects the name of the variable and the value that should be encrypted:
    • Encrypt-Variable -Name <name> -Value <value> [-KeyName <key-name>] [-PublicKey <public-key>]
      • <name>: The name of the variable is required.
      • <value>: The value of the variable that should be encrypted is required.
      • <key-name>: The name of a second variable holding the encrypted symmetric key. Defaults to <name>_key.
      • <public-key>: The path to the public key file is specified. Defaults to <agent-data>/config/agent.pub.
    • The PowerShell function will encrypt the variable value using the indicated public key.
    • The variable and its encrypted value will be forwarded to subsequent jobs and instructions in the workflow.

Second Job: decrypt-variable

The second job decrypt-variable maps workflow variables to environment variables like this:


Explanation:

  • MY_VAR1: environment variable that holds the encrypted value of the myVar1 workflow variable created by the encrypt-variable job.
  • MY_VAR1_KEY: environment variable that holds the encrypted value of the symmetric key. The variable is implicitly created by the encrypt-variable job.
  • MY_VAR2, MY_VAR2_KEY: similar to above variables.


The second job decrypt-variable is implemented like this:

Example how to decrypt variables in a job
@@setlocal enabledelayedexpansion & @@findstr/v "^@@[fs].*&" "%~f0" | pwsh.exe -NonInteractive -Command - & exit !errorlevel!/b&

$ErrorActionPreference = "stop"

# decrypt variable values using the Agent's private key
##!include CryptoPowerShell

Write-Output (Decrypt-Variable -Value $env:MY_VAR1 -Key $env:MY_VAR1_KEY)
Write-Output (Decrypt-Variable -Value $env:MY_VAR2 -Key $env:MY_VAR2_KEY)


Explanation:

  • The job makes use of a shebang for Windows to invoke pwsh.exe. For Unix use:
    • #!/usr/bin/env pwsh
  • The job makes use of JS7 - Script Includes: the CryptoPowerShell Script Include holds the PowerShell functions used in the job.
    • The ##!include CryptoPowerShell inserts the PowerShell code available from the indicated CryptoPowerShell Script Include.
    • The Script Include can be invoked with repeated --replace=<what>,<with> options.
      • The Script Include optionally can be parameterized to specify the location of the private key.
        • ##!include CryptoPowerShell --replace="<private-key>","/var/sos-berlin.com/js7/agent/config/private/agent.key"
        • The first argument of the --replace option is a placeholder available with the CryptoPowerShell Script Include.
        • The second argument represents the value by which the placeholder will be replaced. The above value represents the default value that will be used of the Script Include is invoked without replacement options.
      • The Script Include can be parameterized to specify a passphrase required by the private key.
        • ##!include CryptoPowerShell --replace="<passphrase>","jobscheduler"
        • The Script Include holds the above passphrase as a default value. Users should consider to change or to drop the default passphrase.
  • The Decrypt-Variable function expects the encrypted value of the variable and the encrypted value of the symmetric key:
    • Decrypt-Variable -Value  <value> -Key <key> [-PrivateKey <private-key> [-Passphrase <passphrase>]]
      • <value>: The encrypted value of the variable is required.
      • <key>: The value of the variable holding the encrypted symmetric key is required.
      • <private-key>: The path to the private key file is specified. Defaults to <agent-data>/config/private/agent.key.
      • <passphrase>: The passphrase of the private key is specified.
    • The function will decrypt the encrypted symmetric key and will decrypt the encrypted value using the decrypted symmetric key.
  • The Decrypt-Variable function returns the secret that can be assigned an environment variable or other function.
  • It is recommended not to write the secret to a file or to perform any operation that will expose the secret to logging of output in the stdout and stderr channels.

Script Include: CryptoPowerShell

The CryptoPowerShell Script Include is located in the related inventory folder:

The CryptoPowerShell Script Include is implemented like this:


Explanation:

  • The CryptoPowerShell Script Include implements the Encrypt-Variable and Decrypt-Variable PowerShell functions.
  • Encryption and decryption is performed without use of external utilities.

Interoperability

Variables can be encrypted/decrypted by Agents using the PowerShell solution on any supported platform:

  • Encryption by Agents operated for Windows and Decryption by Agents operated for Windows and Unix.
  • Encryption by Agents operated for Unix and Decryption by Agents operated for Windows and Unix.

There is limited interoperability when sing the PowerShell solution and the solution available from JS7 - How to encrypt and decrypt Variables using OpenSSL and Unix Shell interchangeably for encryption/decryption. The PowerShell solution makes use of a salt limit of 16 bytes, earlier versions of openssl use 8 bytes.

Further Resources



  • No labels