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 outside of JS7 products.
- This includes that JS7 products have no knowledge of secret keys involved that potentially could be compromised by logging, database persistence etc.
FEATURE AVAILABILITY STARTING FROM RELEASE 2.5.9
FEATURE AVAILABILITY STARTING FROM RELEASE 2.6.6
Download
The solution ships with JS7 Agents that can use encyption/decryption with shell jobs out-of-the-box.
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 as explained with this article,
- for Windows® Shell, see JS7 - How to encrypt and decrypt using Windows Shell,
- for Linux, MacOS®, Windows® from JS7 - How to encrypt and decrypt using PowerShell.
- Encryption and decryption with Unix and Windows can be used interchangeably.
Managing the Private Key and Certificate
Assymetric 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 X.509 Private Key or Certificate allow to derive the Public Key.
- User can create a self-signed X.509 Certificate, see JS7 - How to create self-signed Certificates.
- Users can create a Private Key and Certificate as explained in the next chapter.
Step 1: Creating the Private Key and Certificate
The following step is performed on the server hosting the Agent that should decrypt secrets using the openssl
utility from the command line:
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 secrets:
Encryption
Usage
Invoking the script without arguments displays the usage clause:
Usage: js7_encrypt.sh [Options] [Switches] Options: --cert=<path-to-certificate> | path to X.509 certificate or public key file used to encrypt the secret. --in=<secret> | secret that should be encrypted. --infile=<path-to-file> | path to input 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 X.509 certificate. Alternatively the path to a file holding the 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 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 used if the
--infile
option is specified.
Switches
-h | --help
- Displays usage.
Exit Codes
1
: argument errors2
: processing errors
Return Values
The script writes output to the stdout channel that includes the following items separated by spaces:
- encrypted symmetric key,
- base64 encoded initialization vector,
- encrypted secret or path to encrypted output file.
Examples
The following examples illustrate typical use cases.
Encrypting Secret using Unix Shell
result=$(./bin/js7_encrypt.sh --cert=agent.crt --in="secret") echo "$result" # encrypts the given secret using an Agent's X.509 certificate # output includes the symmetric key, initialization vector and encrypted string separated by space
Encrypting and forwarding Secret using Unix Shell in Jobs
result=$(./bin/js7_encrypt.sh --cert=agent.crt --in="secret") echo "new_var=$result" >> $JS7_RETURN_VALUES # encrypts the given secret using an Agent's X.509 certificate # output includes the symmetric key, initialization vector and encrypted string separated by spaces # output is stored to the "new_var" variable (key/value pair) that is made available for later jobs in the workflow
Encrypting File using Unix Shell
echo "secret file" > /tmp/secret.txt result=$(./bin/js7_encrypt.sh --cert=agent.crt --infile=/tmp/secret.txt --outfile=/tmp/secret.txt.encrypted) echo "$result" # encrypts the given file using an Agent's X.509 certificate and creates an encrypted output file # output includes the symmetric key, initialization vector and path to encrypted file separated by spaces
Decryption
Usage
Invoking the script without arguments displays the usage clause:
Usage: js7_decrypt.sh [Options] [Switches] Options: --key=<path> | path to private key file for decryption. --key-password=<password> | password for the private key. --iv=<initialization-vector> | base64 encoded initialization vector (returned by encryption). --encrypted-key=<key> | base64 encoded encrypted symmetric key (returned by encryption). --in=<encrypted-secret> | encrypted secret to decrypt (returned by encryption). --infile=<path-to-file> | path to encrypted input file. --outfile=<path-to-file> | path to decrypted output file. Switches: -h | --help | displays usage
Options
--key
- Specifies the path to the Private Key file that matches the X.509 Certificate or Public Key used for previous encryption.
- The argument is required.
--key-password
- Specifies the password if the Private Key file indicated with the
--key
option is protected by a password.
- Specifies the password if the Private Key file indicated with the
--iv
- Specifies the base64 encoded initialization vector as returned during encryption.
- The argument is required.
--encrypted-key
- Specifies the base64 encoded, encrypted symmetric key as returned during encryption.
- The argument is required.
--in
- Specifies the encrypted secret that should be decrypted.
- One of the options
--in
or--infile
has to be specified.
--infile
- Specifies the path to an encrypted file that should be decrypted.
- 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 decrypted content of the input file.
- The option is required if the
--infile
option is specified.
Switches
-h | --help
- Displays usage.
Exit Codes
1
: argument errors2
: processing errors
Return Values
The script writes output to the stdout channel that includes the following items:
- decrypted secret or path to decrypted output file if the
--infile
and--outfile
options are used.
Examples
The following examples illustrate typical use cases.
Decrypting Secret using Unix Shell
# assumes that previous encryption created the "result" variable # result=$(./bin/js7_encrypt.sh --cert=agent.crt --in="secret") secret=$(./bin/js7_decrypt.sh \ --key=agent.key \ --key-password="jobscheduler" \ --encrypted-key="$(echo "$result" | cut -d' ' -f 1)" \ --iv="$(echo "$result" | cut -d' ' -f 2)" \ --in="$(echo "$result" | cut -d' ' -f 3)") echo "${secret}" # decrypts the given encrypted secret using an Agent's private key and passphrace # initialization vector, encrypted symmetric key and encrypted secret are returned during encryption # output includes the decrypted secret
Decrypting File using Unix Shell
# assumes that previous encryption created the "result" variable # result=$(./bin/js7_encrypt.sh --cert=agent.crt --infile=/tmp/secret.txt --outfile=/tmp/secret.txt.encrypted) ./bin/js7_decrypt.sh \ --key=agent.key \ --key-password="jobscheduler" \ --encrypted-key="$(echo "${result}" | cut -d' ' -f 1)" \ --iv="$(echo "${result}" | cut -d' ' -f 2)" \ --infile=$(echo "${result}" | cut -d' ' -f 3) \ --outfile=/tmp/secret.txt.decrypted cat /tmp/secret.txt.decrypted # decrypts the given encrypted file using an Agent's private key and passphrase # creates the decrypted output file