Page History
...
- The solution is available for Linux and MacOS® using bash shell.
- The solution is intended as a baseline example for customization by JS7 users and by SOS within the scope of professional services.
Solution for Unix Shell Jobs
Managing the private/public key pair
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
# navigate to the Agent's <agent-data>/config directory cd /var/sos-berlin.com/js7/agent/config # copy the agent.pub public key file from Step 1 to the targetcurrent Agentslocation using scp or a file transfer tool |
...
The example introduces a JS7 - Script Include and a workflow hodling holding two jobs that to encrypt and to decrypt variables.
- Download sample Script Include (upload .json): CryptoShell.includescript.json
- Download sample Workflow (upload .json): pduVariableCryptopduVariableCryptoShell.workflow.json
First Job: encrypt-
...
variable
The fist job encrypt-variables is variable is implemented like this:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
#!/bin/bash set -e # encrypt variable values using the target Agent's public key ##!include CryptoShell EncryptVariable myVar1 "secret1" EncryptVariable myVar2 "secret2" |
...
- The job makes use of JS7 - Script Includes: the Crypto CryptoShell Script Include holds the shell Shell functions used in the job.
- The
##!include Crypto
insertsCryptoShell
inserts the shell Shell code available from the indicated Crypto CryptoShell Script Include. - The Script Include is invoked once per job and optionally can be parameterized to specify the location of the public key.
##!include Crypto CryptoShell --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 Crypto CryptoShell Script Include. - The second argument represents the value by which the placeholder will be replaced. The 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
- The
EncryptVariable
shell Shell function expects the name of the variable and the value that should be encrypted:EncryptVariable
<name> <value> [<key-name> [,<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 shell Shell 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-variablesvariable maps workflow variables to environment variables like this:
...
MY_VAR1
: environment variable that holds the encrypted value of themyVar1
workflow variable created by the encrypt-variables jobvariable job.MY_VAR1_KEY
: environment variable that holds the encrypted value of the symmetric key. The variable is implicitly created by the encrypt-variables jobvariable job.MY_VAR2, MY_VAR2_KEY
: similar to above variables.
The second job decrypt-variables is variable is implemented like this:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
#!/bin/bash set -e # decrypt variable values using the Agent's private key ##!include CryptoCryptoShell secret1=echo "$(DecryptVariable "${MY_VAR1}" "${MY_VAR1_KEY}")" echo "${secret1}" secret2=$(DecryptVariable "${MY_VAR2}" "${MY_VAR2_KEY}") echo "${secret2}" |
Explanation:
- The job makes use of JS7 - Script Includes: the Crypto CryptoShell Script Include holds the shell Shell functions used in the job.
- The
##!include CryptoCryptoShell
inserts the shell Shell code available from the indicated Crypto CryptoShell 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
CryptoShell --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
- CryptoShell 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
CryptoShell --replace="<passphrase>","jobscheduler"
- The Script Include
--replace=<what>,<with>
options- holds the above passphrase as a default value. Users should consider to change or to drop the default passphrase.
- The Script Include optionally can be parameterized to specify the location of the private key.
- The
- The
DecryptVariable
function expects the encrypted value of the variable and the encrypted value of the symmetric key:DecryptVariable
<value> <key-value> <key> [<private-key> [,<passphrase>]]
<value>
: The encrypted value of the variable is required.<key-value>
<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 variable value using the decrypted symmetric key.
- The
DecryptVariable
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.
Anchor | ||
---|---|---|
|
...
|
...
|
...
CryptoShell
The Crypto CryptoShell Script Include is located in the related system inventory folder:
- Download sample Script Include (upload .json): CryptoCryptoShell.includescript.json
The Crypto CryptoShell Script Include is implemented like this:
Explanation:
- The Crypto CryptoShell Script Include implements the
EncryptVariables
andDecryptVariables
shellEncryptVariable
andDecryptVariable
Shell functions. - Both functions create a temporary file for the symmetric key in the Agent's
work
directory. The Script Include implements a trap to reliably remove the symmetric key file on termination of the job. - Encryption and decryption is performed using the
openssl
utility.
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:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
# navigate to the Agent's <agent-data>/config/private directory
cd /var/sos-berlin.com/js7/agent/config/private
# create the private key file using "jobscheduler" as a passphrase, starting with: -----BEGIN RSA PRIVATE KEY-----
openssl genrsa -aes256 -passout pass:"jobscheduler" -out agent-pkcs1.key 2048
# convert key from pkcs#1 to pkcs#8, starting with: -----BEGIN ENCRYPTED PRIVATE KEY-----
openssl pkcs8 -inform PEM -topk8 -in agent-pkcs1.key -out agent.key
# extract the 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
Setting up the Example
The example introduces a JS7 - Script Include and a workflow holding two jobs to encrypt and to decrypt variables.
- Download sample Script Include (upload .json): CryptoPowerShell.includescript.json
- Download sample Workflow (upload .json): pdwVariableCryptoPowerShell.workflow.json
First Job: encrypt-variable
The fist job encrypt-variable is implemented like this:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
@@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 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
- 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 themyVar1
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:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
@@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 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 Script Include optionally can be parameterized to specify the location of the private key.
- The
- 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.
Anchor | ||||
---|---|---|---|---|
|
The CryptoPowerShell Script Include is located in the related inventory folder:
- Download sample Script Include (upload .json): CryptoPowerShell.includescript.json
The CryptoPowershell Script Include is implemented like this:
Explanation:
- The CryptoPowershell Script Include implements the
Encrypt-Variable
andDecrypt-Variable
Powershell functions. - Encryption and decryption is performed without external utilitiesThe operation of encryption and decryption is performed using the
openssl
utility.