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 or outside of JS7 products.
- This includes that JS7 products have no knowledge of 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.
Display feature availability |
---|
|
Display feature availability |
---|
|
Display feature availability |
---|
|
Download
The solution ships with JS7 Agents that can use encyption/decryption from 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 The solution is available for Linux, MacOS®, AIX® using bash, zsh, dash shell, see JS7 - How to encrypt and decrypt Variables using Unix 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 Assymetric encryption makes use of a private/public key pair Private Key and Certificate/Public Key that can be created in a number of ways:
- If SSL certificates are in use to secure HTTPS connections to an Agent, see JS7 - Agent HTTPS Connections, then the related private key and certificate can be used for encryption/decryption too.
- Users can create a Certificate Signing Request 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 allows 509 Certificate allow to derive the public keyPublic Key.
- User can create a selfCA-signed X.509 certificateCertificate, see JS7 - How to create self-signed X.509 SSL TLS Certificates.
- Users can create a private/public key pair Private Key and Certificate as explained in subsequent chaptersthe next chapter.
Step 1: Create a private/public key pair
...
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.
Code Block |
---|
language | bash |
---|
title | Example how to create Private Key and Certificate using ECDSA encryption |
---|
linenumbers | true |
---|
collapse | true |
---|
|
@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"
|
Code Block |
---|
language | bash |
---|
title | Example how to create ECDSA private/public key pair |
---|
linenumbers | true |
---|
|
# navigate to the Agent's <agent-data>/config/private directory
cd /var/sos-berlin.com/js7/agent/config/private
# create the private key in pkcs#1 format
# without passphrase
# openssl ecparam -name secp256k1secp384r1 -genkey -noout -out agent.key
#@rem create Certificate withSigning passphraseRequest
openssl ecparamreq -genkeynew -namesha512 secp256k1-nodes | openssl ec -aes256 -passout pass:"jobscheduler" -out agent.key
# create certificate
openssl req -new -x509 -key agent.key-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:"jobschedulersecret"
openssl x509 -out agent.crtreq -sha512 -days 1825
# extract public key from private key
openssl ec -signkey agent.key -in agent.keycsr -passin pass:"jobscheduler" -pubout > agent.pubout agent.crt -extfile %user_crt_tmp_file%
del /q %user_crt_tmp_file% |
Code Blockcode |
---|
language | bash |
---|
title | Example how to create RSA private/public key pairPrivate Key and Certificate using RSA encryption |
---|
linenumbers | true |
---|
collapse | true |
---|
|
@rem# navigate to the Agent's <agent-data>/\config/\private directory
cd /var/%Programdata%\sos-berlin.com/\js7/\agent/\config/\private
#@rem create thePrivate privateKey keyand inCertificate pkcs#1Signing formatRequest
#@rem without passphrase
# for passphrase add: -passout pass:"secret"
openssl req -x509 -sha256new -newkey rsa:20484096 -sha256 -nodes -keyout agent.key -out agent.crt
# with passphrase
openssl reqcsr -x509 -sha256 -newkey rsa:2048 -passout pass:"jobscheduler" -keyout agent.key -out agent.crt
# extract public key from certificatesubj "/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 -pubkeyreq -nooutsha512 -days 1825 -signkey agent.key -in agent.crtcsr >-out agent.pubcrt -extfile %user_crt_tmp_file%
del /q %user_crt_tmp_file% |
Step 2:
...
Making the Certificate available
Copy the public key 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:
Code Block |
---|
Code Block |
---|
language | bash |
---|
title | Example where to copy the public key |
---|
linenumbers | true |
---|
Usage |
|
Usage: js7_encrypt.cmd [Options] [Switches]
Options:
--cert=<path-to-certificate> | path to X.509 certificate or # 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 fromused to encrypt the currentsecret.
location using a file--in=<secret> transfer tool or your clipboard |
Encryption
Usage
Invoking the script without arguments displays the usage clause:
Code Block |
---|
|
Usage: js7_encrypt.cmd [Options] [Switches]
Options: | secret that should be encrypted.
--certinfile=<path-to-certificate>file> | path to X.509 certificate| orpath publicto keyinput file.
used to encrypt the secret.
--in=<secret>outfile=<path-to-file> | path to output | secret file that should be encrypted.
Switches:
--infile=<path-to-file>h | --help | path to input file.
--outfile=<path-to-file> | | path to output file that should be encrypted.
Switches:
-h | --help | displays usage |
Options
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
--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 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 used required if the
--infile
option is specified.
Switches
Exit Codes
1
: argument errors2
: 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
Code Block |
---|
title | Example for Encryption using Windows Shell |
---|
linenumbers | true |
---|
|
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 stringsecret separated by space |
Encrypting
...
and forwarding Secret using Windows Shell in Jobs
Code Block |
---|
title | Example for Encryption using Windows Shell |
---|
linenumbers | true |
---|
|
echo secret file > %TEMP%\secret.txt
call .\call .\bin\js7_encrypt.cmd "--cert=agent.crt" "--infilein=%TEMP%\secret.txt" "--outfile=%TEMP%\secret.txt.encrypted"
@echo result=%JS7_ENCRYPT_VALUE% >> %JS7_RETURN_VALUES
@rem encrypts the given filesecret using an Agent's X.509 certificate
@rem consider that for Windows Shell all arguments have to be quoted
@rem output is availablestored fromto the JS7_ENCRYPT_VALUE environment"result" variable
@rem output includes the symmetric key, initialization vector and encrypted file separated by space |
Decryption
Usage
...
(key/value pair) that is made available for later jobs in the workflow |
Encrypting File using Windows Shell
Code Block |
---|
title | Usage | Example for Encryption using Windows Shell |
---|
linenumbers | true |
---|
|
echo secret file > %TEMP%\secret.txt
call .\bin\js7_encrypt.cmd "--cert=agent.crt" "--infile=%TEMP%\secret.txt" "--outfile=%TEMP%\secret.txt.encrypted"
@echo %JS7_ENCRYPT_VALUE%
@rem encrypts the given file using an Agent's X.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 spaces |
Decryption
Usage
Invoking the script without arguments displays the usage clause:
Code Block |
---|
|
Usage: js7_decrypt.cmd [Options] [Switches]
Options:Usage: js7_decrypt.cmd [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><path> | base64path encodedto encryptedprivate symmetric key (returnedfile byfor encryption)decryption.
--key-in=<encrypted-secret>password=<password> | password for |the encryptedprivate secretkey.
to decrypt ( --in=<encrypted-result> | encrypted symmetric key, initialization vector and path to encrypted file as 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 a the private key Private Key file that matches the X.509 certificate Certificate or public key Public Key used for previous encryption.
- The argument is required.
--key-password
- Specifies the password passphrase if the private key Private Key file indicated with the
--key
option is protected by a passwordpassphrase.
--ivin
- 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 encryptionencryption result that should be decrypted. The result includes the encrypted symmetric key, initialization vector and path to encrypted file separated by spaces as returned from the encryption step.
- The argument is required.
--in
- Specifies the encrypted value that should be decrypted.
- One of the options
--in
or --infile
has to be specifiedIf 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 that should be decrypted.
- One of the options
--in
or --infile
has to be specified. - 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
option.
--outfile
- Specifies the path to the output file that will be created holding the decrypted content of the input file.
- The option is used required if the
--infile
option is specified.
Switches
Exit Codes
1
: argument errors2
: 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
Code Block |
---|
title | Example for Decryption using Windows Shell |
---|
linenumbers | true |
---|
|
@rem call .\bin\js7_encrypt.cmd "--cert=agent.crt" "--in=secret"
for /f "tokens=1-3" %%i in ("%JS7_ENCRYPT_VALUE%") do (
set encrypted_symmetric_key=%%i
set encrypted_base64_iv=%%j
set encrypted_string=%%k
)
call .\bin\js7_decrypt.cmd ^
"--key=agent.key" ^
"--key-password=jobscheduler" ^
"--encrypted-key=%encrypted_symmetric_key%" ^
"--iv=%encrypted_base64_iv%" ^
"--in=%encrypted_string%"
@echo %JS7_DECRYPT_VALUE%
@rem decrypts the encrypted secret using an Agent's private key and passphrase
@rem consider that for Windows Shell all arguments have to be quoted
@rem the JS7_DECRYPT_VALUE environment variable is automatically created and holds the decrypted secret |
...
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
Code Block |
---|
title | Example for Decryption using Windows Shell |
---|
linenumbers | true | true |
---|
|
@rem call .\bin\js7_encrypt.cmd "--cert=agent.crt" "--in=secret"
@rem call .\bin\js7_encryptdecrypt.cmd ^
"--certkey=agent.crt"key" ^
"--in=%JS7_ENCRYPT_VALUE%"
@echo %JS7_DECRYPT_VALUE%
@rem decrypts the encrypted result 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 and holds the decrypted secret |
Decrypting File using Windows Shell
Code Block |
---|
title | Example for Decryption using Windows Shell |
---|
linenumbers | true |
---|
|
@rem call .\bin\js7_encrypt.cmd "--cert=agent.crt" "--infile=%TEMP%\secret.txt" "--outfile=%TEMP%\secret.txt.encrypted"infile=%TEMP%\secret.txt" "--outfile=%TEMP%\secret.txt.encrypted"
for /f "tokens=1-3" %%i in ("%JS7_ENCRYPT_VALUE%") do (
set encrypted_symmetric_key=%%i
set encrypted_base64_iv=%%j
set encrypted_file=%%k
)
call .\bin\js7_decrypt.cmd ^
"--key=agent.key" ^
"--key-password=jobscheduler" ^
"--encrypted-key=%encrypted_symmetric_key%in=%JS7_ENCRYPT_VALUE%" ^
"--iv=%encrypted_base64_iv%" ^
"--infile=%encrypted_file%infile=%TEMP%\secret.txt.encrypted" ^
"--outfile=%TEMP%\secret.txt.decrypted"
type %TEMP%\secret.txt.decrypted
@rem decrypts the given encrypted file using an Agent's private key and passphrasetype %TEMP%\secret.txt.decrypted
@rem decrypts the given encrypted file using an Agent's 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