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:, for details see JS7 - Encryption and Decryption.

• Encryption and decryption can be performed directly by related jobs.Encryption and decryption can be performed jobs or outside of JS7 products.
• This includes that JS7 products have no knowledge of secret keys secrets involved that potentially could be compromised by logging, database persistence etc.

For creation of Encryption Keys see JS7 - How to create X.509 Encryption Keys.

Download

The solution ships with JS7 Agents that can use encyption/decryption from with shell jobs out-of-the-box.

The In addition, the solution is provided for download to perform encryption and decryption outside of JS7 products.

• Download: JS7 - Download (Section: Utililties, Unix: js7.encryption.tar.gz, Windows: js7.encryption.zip),
• The solution is available for Linux, MacOS®, AIX® using bash, zsh, dash shell, see JS7 - How to encrypt and decrypt Variables using Unix Shell 2
• The solution is available for Windows® shell.
• . Encryption and decryption with Unix and Windows can be used interchangeably.
• The solution is available for Windows® Shell.

Managing the Private Key and Certificate

Asymetric encryption makes use of a Private Key and Certificate/Public Key that can be created in a number of ways:

• Users can create a Certificate Signing Request (CSR) and ask their Certificate Authority (CA) to sign the CSR and to receive an X.509 certificate. The Private Key or X.509 Certificate allow to derive the Public Key.
• User can create a CA-signed X.509 Certificate, see JS7 - How to create X.509 SSL TLS Certificates.
• Users can create a Private Key and Certificate as explained in the next chapter.

Note: Private Keys can be protected using a passphrase that acts as a second factor when a human user will access the key: while the Private Key is in the file system, the passphrase is in the user's brains. However, this does not improve security for unattended processing: it's pointless to store a passphrase side-by-side with the Private Key in scripts or configuration files on the same media.

Step 1: Creating the Private Key and Certificate

The following step is performed on the server hosting the Agent that should decrypt secrets. The example makes use of the openssl command line utility that can be installed for Windows. There are alternative ways how to create Private Keys and Certificates. Find more examples and explanations from JS7 - How to create X.509 Encryption Keys.

@rem navigate to the Agent's <agent-data>\config\private directory
cd %Programdata%\sos-berlin.com\js7\agent\config\private

@rem create Private Key
@rem   for use with passphrase add: -passout pass:"secret"
openssl ecparam -name secp384r1 -genkey -noout -out agent.key

@rem create Certificate Signing Request
openssl req -new -sha512 -nodes -key agent.key -out agent.csr -subj "/C=DE/ST=Berlin/L=Berlin/O=SOS/OU=IT/CN=Agent"

@rem create Certificate
set user_crt_tmp_file=user-crt-%RANDOM%.tmp
echo keyUsage=critical,keyAgreement,keyEncipherment > %user_crt_tmp_file%

@rem   for passphrase add: -passin pass:"secret"
openssl x509 -req -sha512 -days 1825 -signkey agent.key -in agent.csr -out agent.crt -extfile %user_crt_tmp_file%
del /q %user_crt_tmp_file%

@rem navigate to the Agent's <agent-data>\config\private directory
cd %Programdata%\sos-berlin.com\js7\agent\config\private

@rem create Private Key and Certificate Signing Request
@rem   for passphrase add: -passout pass:"secret"
openssl req -new -newkey rsa:4096 -sha256 -nodes -keyout agent.key -out agent.csr -subj "/C=DE/ST=Berlin/L=Berlin/O=SOS/OU=IT/CN=Agent"

@rem create Certificate
set user_crt_tmp_file=user-crt-%RANDOM%.tmp
echo keyUsage=critical,keyAgreement,keyEncipherment > %user_crt_tmp_file%

@rem   for passphrase add: -passin pass:"secret"
openssl x509 -req -sha512 -days 1825 -signkey agent.key -in agent.csr -out agent.crt -extfile %user_crt_tmp_file%
del /q %user_crt_tmp_file%

Step 2: Making the Certificate available

Copy the Certificate file to the server(s) hosting the Agent(s) or 3rd-party components that should encrypt variables:

Encryption

Usage

Invoking the script without arguments displays the usage clause:

...

Usage: js7_encrypt.cmd [Options] [Switches]

  Options:
     --cert=<path-to-certificate>  | path to X509X.509 certificate or public key file used to encrypt the secret.
     --in=<secret>                 | secret that should be encrypted.
     --infile=<path-to-file>       | path to ainput file.
     --outfile=<path-to-file>      | path to output file that should be encrypted. 

  Switches:
     -h | --help                   | displays usage

Options

• --cert
  • Specifies the path to a file that holds the CA signed or self-signed x509 certificateX.509 Certificate. Alternatively the path to a file holding the public key Public Key can be specified.
• --in
  • Specifies the input value that should be encrypted, typically a secret.
  • One of the options --in or --infile has to be specified.
• --infile
  • Specifies the path to a the input file that should be encrypted.
  • One of the options --in or --infile has to be specified.
  • This option requires use of the --outfile option.
• --outfile
  • Specifies the path to the output file that will be created holding the encrypted content of the input file.
  • The option is required if the --infile option is specified.

Switches

• -h | --help
  • Displays usage.

Exit Codes

• 1: argument errors
• 2: processing errors

Return Values

The script writes output to the JS7_ENCRYPT_VALUE environment variable. Output includes the following items separated by spaces:

• encrypted symmetric key,
• base64 encoded initialization vector,
• encrypted secret.

Examples

The following examples illustrate typical use cases.

Encrypting

...

Secret using Windows Shell

call .\bin\js7_encrypt.cmd "--cert=agent.crt" "--in=secret"
@echo %JS7_ENCRYPT_VALUE%
 
@rem encrypts the given secret using an Agent's X.509 certificate
@rem consider that for Windows Shell all arguments have to be quoted
@rem output is provided from an environment variable that includes the encrypted symmetric key, initialization vector and encrypted secret separated by space

Encrypting and forwarding Secret using Windows Shell in Jobs

call .\bin\js7_encrypt.cmd "--cert=agent.crt" "--in=secret"
@echo result=%JS7_ENCRYPT_VALUE% >> %JS7_RETURN_VALUES
 /f "tokens=1-3" %%i in ("%JS7_ENCRYPT_VALUE%") do (
  set encrypt_symmetric_key=%%i
  set encrypt_base64_iv=%%j
  set encrypt_string=%%k
)

@rem encrypts the given secret using an Agent's X509X.509 certificate
@rem consider that for Windows Shell all arguments have to be quoted
@rem output includesis thestored symmetricto key, initialization vector and encrypted string separated by space that are passed to environment variables

...

the "result" variable (key/value pair) that is made available for later jobs in the workflow

Encrypting File using Windows Shell

echo secret file > %TEMP%\secret.txt
call .\bin\js7_encrypt.cmd "--cert=agent.crt" "--infile=%TEMP%\secret.txt"

for /f "tokens=1-3" %%i in (""--outfile=%TEMP%\secret.txt.encrypted"
@echo %JS7_ENCRYPT_VALUE%") do (
  set encrypt_symmetric_key=%%i
  set encrypt_base64_iv=%%j
  set encrypt_string=%%k
)

@rem encrypts the given file using an Agent's X509X.509 certificate
@rem consider that for Windows Shell all arguments have to be quoted
@rem output is available from the JS7_ENCRYPT_VALUE environment variable
@rem output includes the encrypted symmetric key, initialization vector and path to encrypted file separated by space that are passed to environment variablesspaces

Decryption

Usage

Invoking the script without arguments displays the usage clause:

...

Usage: js7_decrypt.cmd [Options] [Switches]

  Options:
     --key=<path>                  | path to private key file for decryption.
     --key-iv=<initialization-vector>password=<password>   | base64 encoded| initializationpassword vectorfor (returnedthe byprivate encryption)key.
     --encrypted-key=<key>in=<encrypted-result>       | encrypted  | base64 encodedsymmetric key, initialization vector and path to encrypted symmetricfile keyas (returned by encryption).
     --ininfile=<encrypted<path-to-secret>file>       | encrypted secretpath to decryptencrypted (returned by encryption)input file.
     --infileoutfile=<path-to-file>       | path to decrypted encryptedoutput file. to decrypt.

  Switches Switches:
     -h | --help                   | displays usage

Options

• --key
  • Specifies the path to a the private key Private Key file that matches the X509 certificate or public key X.509 Certificate or Public Key used for previous encryption.
  • The argument is required.
• --key-ivpassword
  • Specifies the base64 encoded initialization vector as retured during encryptionthe passphrase if the Private Key file indicated with the --key option is protected by a passphrase.
• --encrypted-keyin
  • Specifies the base64 encoded, the encryption result that should be decrypted. The result includes the encrypted symmetric key as retured during encryption., initialization vector and path to encrypted file separated by spaces as returned from the encryption step.
  • The argument is required. If the option --infile is specified, then its value takes precedence to the path specified with the --in option.
• --infile
  • Specifies the path to an encrypted file
  --in
  • Specifies the encrypted value that should be decrypted.
  • If this option is specified then its value takes precedence to the path specified with the --in option.
  • This option requires use of the --outfile optionOne of the options --in or --infile has to be specified.
• --infileoutfile
  • Specifies the path to an encrypted the output file that should will be created holding the decrypted content of the input file.
  • One of the options --in or The option is required if the --infile has to be option is specified.

Switches

• -h | --help
  • Displays usage.

Exit Codes

• 1: argument errors
• 2: processing errors

Return Values

The script creates the following environment variables:

• JS7_DECRYPT_VALUE holds the decrypted secret if the --in option is used,
• JS7_DECRYPT_FILE holds the path to the decrypted output file if the --infile and --outfile options are used.

Examples

The following examples illustrate typical use cases.

Decrypting

...

Secret using Windows Shell

@call@rem call .\bin\js7_decryptencrypt.cmd "--keycert=agent.keycrt" "--iv=%encrypt_base64_iv%" "--encrypted-key=%encrypt_symmetric_key%" in=secret"

call .\bin\js7_decrypt.cmd ^
    "--key=agent.key" ^
    "--in=%encrypt%JS7_ENCRYPT_string%VALUE%"
@echo %JS7_DECRYPT_VALUE%

@rem decrypts the encrypted secretresult using an Agent's private key
@rem consider that for Windows Shell all arguments have to be quoted
@rem the JS7_DECRYPT_VALUE environment variable is automatically created thatand holds the decrypted secret

Decrypting

...

File using Windows Shell

@call@rem call .\bin\js7_encrypt.cmd "--cert=agent.crt" "--infile=%TEMP%\secret.txt" "--outfile=%TEMP%\secret.txt.encrypted"

call .\bin\js7_decrypt.cmd ^
    "--key=agent.key" ^
    "--ivin=%encrypt%JS7_base64ENCRYPT_iv%"VALUE%" ^
    "--encrypted-key=%encrypt_symmetric_key%" infile=%TEMP%\secret.txt.encrypted" ^
    "--in=%encrypt_string%outfile=%TEMP%\secret.txt.decrypted"
@echo %JS7_DECRYPT_VALUE%type %TEMP%\secret.txt.decrypted

@rem decrypts the given encrypted file using an Agent's X509 private key private key
@rem the JS7_ENCRYPT_VALUE environment variable is returned in the encryption step and holds the encrypted symmetric key, initialization vector and path to the encrypted file
@rem consider that for Windows Shell all arguments have to be quoted
@rem output includes the path to the decrypted file that is provided from the JS7_DECRYPT_FILE environment variable

Further Resources

• JS7 - How to encrypt and decrypt Variables
  • JS7 - How to encrypt and decrypt Variables using Unix Shell 2
  • JS7 - How to encrypt and decrypt using PowerShell