JS7 JobScheduler

Space shortcuts

Page tree

Introduction

For JS7 - Secure Operation the connections between JS7 JOC Cockpit, Controller and Agents are secured by SSL/TLS certificates.

  • Users create a keystore that holds the private key and SSL/TLS certificate for the respective server. Users create a truststore that holds the Root CA Certificate and optionally Intermediate CA Certificate(s).
  • The process of creating and updating keystores and truststores can be automated in a number of ways:
    • Users can use their preferred tools such as Ansible®, Puppet®, Chef®.
    • Users can apply the Certificate Management Script that is described in this article either standalone or in combination with such tools.

Certificate Management Script

The Certificate Management Script is provided for download and can be used to automate the creation of keystores and truststores.

  • The script is available for Linux, MacOS® and AIX® using bash, dash, ksh, and zsh shells.
  • The script makes use of OpenSSL and the Java Keytool available from a JRE/JDK.
  • The script terminates with exit code 0 to signal success, with exit code 1 for command line argument errors and with other exit codes for non-recoverable errors.
  • The script is intended as a baseline example for customization by JS7 users and by SOS within the scope of professional services.

Download

Find the Certificate Management Script for download from JS7 - Download.

Usage

Invoking the Certificate Management Script without arguments displays the usage clause:


Certificate Management Script: js7_create_certificate_store.sh
Usage: js7_create_certificate_store.sh [Options] [Switches]

  Options:
    --keystore=<file>                     | required: path to keystore file in PKCS12 format
    --truststore=<file>                   | optional: path to truststore file in PKCS12 format
    --key=<private-key-file>              | required: path to private key file in .pem format
    --cert=<cert-file>                    | required: path to certificate file in .pem format
    --alias=<alias-name>                  | required: alias name for keystore entry
    --password=<password>                 | required: password for certificate store, optionally for private key
    --ca-cert=<ca-cert-bundle-file>       | optional: path to CA Certificate Bundle file in .pem format
    --ca-root=<ca-root-file>              | optional: path to Root CA Certificate file in .pem format
    --ca-intermediate=<ca-file[,ca-file]> | optional: paths to Intermediate CA Certificate files in .pem format
    --backup-dir=<directory>              | optional: backup directory for existing certificate stores
    --log-dir=<directory>                 | optional: log directory for log output of this script
  Switches:
    -h | --help                           | displays usage
    --chain                               | add certificate chain to keystore
    --show-logs                           | shows log output of the script
    --make-dirs                           | creates the specified directories if they do not exist


Explanation:

  • Options
    • --keystore
      • Specifies the path to a PKCS12 keystore file that should be created. The keystore holds the private key and server certificate for HTTPS connections to JS7 products.
      • Users are free to specify any file name, typically the name https-keystore.p12 is used.
      • Further settings in JS7 configuration files such as the keystore location and password have to be considered.
    • --truststore
      • Specifies the path to a PKCS12 truststore file that should be created. The truststore holds the certificate(s) for HTTPS connections from JS7 products.
      • Users are free to specify any file name, typically the name https-truststore.p12 is used.
      • Further settings in JS7 configuration files such as the truststore location and password have to be considered.
    • --key
      • Specifies the path to the file that holds the private key that should be added to the keystore.
      • This argument is required should a keystore be created, see --keystore.
    • --cert
      • Specifies the path to the file that holds the server/client authentication certificate that should be added to the keystore.
      • This argument is required should a keystore be created, see --keystore.
    • --alias
      • Specifies the alias name of the entry in the keystore that holds the private key and certificate.
      • This argument is required should a keystore be created, see --keystore.
    • --password
      • Specifies the password that protects the keystore and truststore. If the private key is encrypted then the password is used to read the key. Private key passphrase and keystore password must match.
      • Passwords for certificate stores are not intended to improve security but to prevent users from shooting themselves in their foot. For a keystore the password protects read and write access, for a truststore the password protects write access.
      • This argument is required should a keystore or truststore be created, see --keystore, --truststore.
    • --ca-cert
      • Specifies the path to a CA Certificate Bundle file that holds the Intermediate CA Certificate(s) and Root CA Certificate in the indicated sequence.
      • This argument is required should a keystore be created and the --chain switch be used. In addition this argument is required should a truststore be created and no Root CA Certificate be specified, see --ca-root.
    • --ca-root
      • Specifies the path to a Root CA Certificate file.
      • This argument is required if no CA Certificate Bundle file is specified, see --ca-cert, and should a keystore be created with the --chain argument. In addition this argument is required should a truststore be created using the --truststore option and no CA Certificate Bundle file is specified, see --ca-cert option.
    • --ca-intermediate
      • Specifies the path to one or more Intermediate CA Certificate files.
      • If more than one file is specified then file names have to be separated by comma, for example --ca-intermediate="./certs/intermediate-ca-1.crt,./certs/intermediate-ca-2.crt".
      • This argument is required if no CA Certificate Bundle file is specified, see --ca-cert, and should a keystore be created using the --chain switch.
    • --backup-dir
      • If a backup directory is specified then an existing keystore and truststore will be added to a .tar.gz file in this directory.
      • File names are created according to the pattern: backup_js7_<keystore|truststore>.<hostname>.<yyyy>-<MM>-<dd>T<hh>-<mm>-<ss>.tar.gz
      • For example: backup_js7_keystore.centostest_primary.2022-03-19T20-50-45.tar.gz
    • --log-dir
      • If a log directory is specified then the installer script logs information about processing steps to a log file in this directory.
      • File names are created like this: certificate_store_js7.<hostname>.<yyyy>-<MM>-<dd>T<hh>-<mm>-<ss>.log
      • For example: certificate_store_js7.centostest_primary.2022-03-19T20-50-45.log
  • Switches
    • -h | --help
      • Displays usage.
    • --chain
      • Adds the certificate chain to the keystore if the --keystore option is used. In most situations this is not required as the certificate chain is made available with the truststore. The certificate chain will be created from the CA Certificate Bundle file, see --ca-cert, or from individual CA Certificates, see --ca-root, --ca-intermediate.
    • --show-logs
      • Displays the log output created by the script.
    • --make-dirs
      • If directories are missing that are indicated with the --keystore, --truststore, --backup-dir or --log-dir options then they will be created.
  • Exit Codes
    • 1: argument errors, OpenSSL errors
    • 2: this exit code is returned in case of keystore/truststore verification errors.

Examples

The following examples represent typical use cases. Users should consider to specify current releases, see JS7 - Download.

Creating a Keystore and Truststore (recommended)

Example for use of Certificate Management Script
./js7_create_certificate_store.sh \
    --keystore=https-keystore.p12 \
    --truststore=https-truststore.p12 \
    --key=./private/centostest-primary.key \
    --cert=./certs/centostest-primary.crt \
    --alias=centostest-primary \
    --password=jobscheduler \
    --ca-root=./certs/root-ca.crt

# creates a keystore from the private key and certificate
# creates a truststore from the Root CA Certificate
# the keystore and truststore will be protected with the given password

Creating a Keystore

Example for use of Certificate Management Script
./js7_create_certificate_store.sh \
    --keystore=https-keystore.p12 \
    --key=./private/centostest-primary.key \
    --cert=./certs/centostest-primary.crt \
    --alias=centostest-primary \
    --password=jobscheduler

# creates a keystore from the private key and certificate
# the keystore will be protected with the given password

Creating a Keystore with a Certificate Chain

Example for use of Certificate Management Script
./js7_create_certificate_store.sh \
    --keystore=https-keystore.p12 \
    --key=./private/centostest-primary.key \
    --cert=./certs/centostest-primary.crt \
    --alias=centostest-primary \
    --password=jobscheduler \
    --ca-cert=./certs/ca-bundle.crt \
    --chain

# creates a keystore from the private key and certificate
# adds the certificate chain from the CA Certificate Bundle to the keystore
# the keystore will be protected with the given password

Creating a Truststore from a CA Certificate Bundle

Example for use of Certificate Management Script
./js7_create_certificate_store.sh \
    --truststore=https-truststore.p12 \
    --password=jobscheduler \
    --ca-cert=./certs/ca-bundle.crt
 
# creates a truststore from the CA Certificate Bundle
# the truststore will be protected with the given password

Creating a Truststore from a number of CA Certificates

Example for use of Certificate Management Script
./js7_create_certificate_store.sh \
    --truststore=https-truststore.p12 \
    --password=jobscheduler \
    --ca-root=./certs/root-ca.crt \
    --ca-intermediate=./certs/sos.intermediate-ca-1.crt,./certs/sos.intermediate-ca-2.crt

# creates a truststore from the Intermediate CA Certificates and the Root CA Certficate
# the truststore will be protected with the given password

Creating a Keystore using Log Files and Backups

Example for use of Certificate Management Script
./js7_create_certificate_store.sh \
    --keystore=https-keystore.p12 \
    --key=./private/centostest-primary.key \
    --cert=./certs/centostest-primary.crt \
    --alias=centostest-primary \
    --password=jobscheduler \
    --log-dir=./logs \
    --backup-dir=./backup

# creates a keystore from the private key and certificate
# creates a log file in the indicated directory
# creates a backup file of the keystore in the indicated directory

Automation

The Certificate Management Script can be executed from a job for automated creation of keystores and truststores.

Further Resources