...

• The following explanations assume Private CA-signed Certificates or Public CA-signed Certificates to be used.
  • Private CA-signed Certificates are created by users who operate their own CA, see the JS7 - How to create X.509 SSL TLS Certificates.
  • Public CA-signed Certificates are provided from known and trusted Certificate Authorities (CA) that validate the domain owner.
  • Use of Intermediate CA Certificates is optional.
  • There is no difference in using a Private CA or Public CA concerning functionality of X.509 certificates, usage for Server Authentication / Client Authentication, or security of connections. The only difference is that users trust the Private CA that they set up on their own.
• Certificate stores can be managed from the command line and by use of tools that provide a GUI for this purpose:
  • the Java keytool is available from the Java JRE or JDK,
  • the Keystore Explorer is an open source utility to graphically manage certificate stores.
• Starting from Java 9 the PKCS12 keystore type is default and is not required to be specified with keytool.
• The following sections assume a PKCS12 keystore/truststore format. For Unix OS the .p12 file extension frequently is used, for Windows OS the .pfx extension is preferably used. Both file extensions indicate the same PKCS12 format and can be used interchangeably.

Certificate Management

Private keys Keys and certificates Certificates should be distributed as follows:

...

• Keystore and truststore shown in orange are required for any connections of JOC Cockpit to a Controller.
  • The Controller's private key Private Key and certificate Certificate for Server Authentication are added to the Controller's keystore.
  • The Root CA Certificate is added to the Controller's truststore.
• The keystore and truststore shown in green are required if mutual authentication is in place for certificate based client authentication (default).
• The Controller's truststore shown in green is required should secure connections be used by a Controller to access Agents. It is therefore recommended the Controller's truststore is set up.
• Similar certificate management applies for any additional standby JOC Cockpit instances acting in a cluster.

...

• On the Controller instance's server create the keystore using openssl and the keytool from your Java JRE or JDK or a third 3rd-party utility.
  • For use with a third 3rd-party utility create a keystore, e.g. https-keystore.p12, in PKCS12 format and import:
    • Controller Private Key and Certificate for Server Authentication
  • For use with openssl and keytool create the keystore with the Private Key and Certificate for Server Authentication from the command line. The examples below show a possible approach for certificate management - however, there are other ways of achieving similar results.

    • Example for importing a Private Key and CA-signed certificate Certificate to a PKCS12 keystore:

      Code Block
      language bash title Example how to import a Private Key and CA-signed Certificate to a PKCS12 keystore
      # Assume the fully qualified domain name (FQDN) of the Controller server to be "controller.example.com" # If the Controller's CA-signed Certificate is provided from a pkcs12 keystore (certificate.p12), extract the Certificate to a .crt file in PEM format (controller.example.com.crt) # openssl pkcs12 -in certificate.p12 -nokeys -out controller.example.com.crt # Import the Controller's Private Key (controller.example.com.key) and Certificate (controller.example.com.crt) from PEM format to a new keystore (https-keystore.p12) openssl pkcs12 -export -in controller.example.com.crt -inkey controller.example.com.key -name controller.example.com -out "JS7_CONTROLLER_CONFIG_DIR/private/https-keystore.p12"

    • Example for creating a Private Key and CA-signed Certificate and import to a keystore

      • Refer to examples available from JS7 - How to create X.509 SSL TLS Certificates, chapter Creating SSL/TLS Server Certificates.

        Code Block
        language bash title Example how to create a Private Key and CA-signed Certificate
        # Creating the Private Key and selfCA-signed Certificate for the given validity period ./create_server_certificate.sh --dns=controller.example.com --days=365

      • Refer to examples available from JS7 - How to add SSL TLS Certificates to Keystore and Truststore.

        Code Block
        title Example how to add a Private Key and CA-signed Certificate to a PKCS12 keystore
        # Adding the Private Key and Certificate to a keystore ./js7_create_certificate_store.sh \ --keystore=JS7_CONTROLLER_CONFIG_DIR/private/https-keystore.p12 \ --key=controller.example.com.key \ --cert=controller.example.com.crt \ --alias=controller.example.com \ --password="jobscheduler"

        
        When using additional arguments for creation of a truststore then users have the truststore available for the later step 4:

        Code Block
        title Example how to add a private key Private Key and selfCA-signed certificate Certificate to a PKCS12 keystore and the Root CA Certificate to a truststore
        # Adding the Private Key and Certificate to a keystore and Root CA Certificate to a truststore ./js7_create_certificate_store.sh \ --keystore=JS7_CONTROLLER_CONFIG_DIR/private/https-keystore.p12 \   --truststore=JS7_CONTROLLER_CONFIG_DIR/private/https-truststore.p12 \    --key=controller.example.com.key \ --cert=controller.example.com.crt \ --alias=controller.example.com \ --password="jobscheduler" \ --ca-root=root-ca.crt

  • With the keystore being set up, specify the relevant properties with the JS7_CONTROLLER_CONFIG_DIR/private/private.conf configuration file:

    • Example

      Code Block
      language text title Example for private.conf file specifying the Controller keystore
      js7 { web { # keystore location for https connections https { keystore { # Default: ${js7.config-directory}"/private/https-keystore.p12" file=${js7.config-directory}"/private/https-keystore.p12" key-password="jobscheduler" store-password="jobscheduler" } } } }

      
      

      Explanation:
      • js7.web.https.keystore.file is used for the path to the keystore.
      • js7.web.https.keystore.key-password is used for access to the private keyPrivate Key.
      • js7.web.https.keystore.store-password is used for access to the keystore. Passwords for private key Private Key and keystore have to match when using PKCS12 keystores.
        
        
• On the Controller instance's server create the truststore using the keytool from your Java JRE or JDK or a third 3rd-party utility.
  • For use with a third 3rd-party utility create a truststore, e.g. https-truststore.p12, in PKCS12 format and import:
    • Root CA Certificate
  • The examples below show a possible approach for certificate management - however, there are other ways of achieving similar results.

    • Example for importing a Root CA Certificate to a PKCS12 truststore:

      Code Block
      language bash title Example how to import a Root CA Certificate to a PKCS12 truststore
      # Import Root CA Certificate in PEM format to a PKCS12 truststore (https-truststore.p12) keytool -importcert -alias "root-ca" -file "root-ca.crt" -keystore "JS7_CONTROLLER_CONFIG_DIR/private/https-truststore.p12" -storetype PKCS12

...

• On the JOC Cockpit server create the truststore using the keytool from your Java JRE or JDK or a third 3rd-party utility.
  • For use with a 3rd-party utility create a truststore, e.g. https-truststore.p12, in PKCS12 format and import:
    • Root CA Certificate
  • For use with keytool create the truststore in PKCS12 or JKS format with the Root CA Certificate. The examples below show a possible approach for certificate management - however, there are other ways how to achieve similar results.
    

    • Example showing how to import a Root CA Certificate to a PKCS12 truststore:

      Code Block
      language bash title Example how to import a Root CA Certificate into a PKCS12 truststore
      # import Root CA Certificate in PEM format to a PKCS12 truststore (https-truststore.p12) keytool -importcert -alias "root-ca" -file "root-ca.crt" -keystore "JETTY_BASE/resources/joc/https-truststore.p12" -storetype PKCS12

• The location of the truststore is added to the JETTY_BASE/resources/joc/joc.properties configuration file like this:

  • Example for a PKCS12 truststore

    Code Block
    language text title Example how to specify a PKCS12 truststore location with the joc.properties file
    ### Location of the truststore that contains the certificates of all ### Controllers used with HTTPS connections. The path can be absolute or ### relative to joc.properties truststore_path = https-truststore.p12 truststore_type = PKCS12 truststore_password = jobscheduler

  • Example for a JKS truststore

    Code Block
    language text title Example how to specify a JKS truststore location with the joc.properties file collapse true
    ### Location of the truststore that contains the certificates of all ### Controllers used with HTTPS connections. The path can be absolute or ### relative to joc.properties truststore_path = https-truststore.jks truststore_type = JKS truststore_password = jobscheduler

• Hostname verification by default is in place with the JETTY_BASE/resources/joc/joc.properties configuration file.

  Code Block
  title Example how to specify hostname verification with the joc.properties file
  ################################################################################ ### Specifies if hostname verification should be carried out for HTTPS connections. ### Default true https_with_hostname_verification = true

...

• On the JOC Cockpit server create the client keystore using the keytool from your Java JRE or JDK or a third 3rd-party utility.
  • For use with a 3rd-party utility create a client keystore, e.g. https-client-keystore.p12, in PKCS12 format and import:
    • the JOC Cockpit Private Key and Certificate for Client Authentication
  • For use with keytool create the client keystore in PKCS12 or JKS format according to the steps indicated with JS7 - JOC Cockpit HTTPS Connections: Step 2: Create JOC Cockpit Keystore chapter.
    • Apply the steps indicated to the client keystore and use the Private Key/Certificate pair for Client Authentication.

• The location of the client keystore is added to the JETTY_BASE/resources/joc/joc.properties configuration file like this:

  • Example for a PKCS12 client keystore:

    Code Block
    language text title Example how to specify the PKCS12 client keystore location with joc.properties file
    ### Location of the client keystore that contains the private key and ### certificate for JOC Cockpit client authentication relative to ### joc.properties keystore_path = https-client-keystore.p12 keystore_type = PKCS12 keystore_password = jobscheduler

  • Example for a JKS client keystore:

    Code Block
    language text title Example how to specify the JKS client keystore location with joc.properties file collapse true
    ### Location of the client keystore that contains the private key and ### certificate for JOC Cockpit client authentication relative to ### joc.properties keystore_path = https-client-keystore.jks keystore_type = JKS keystore_password = jobscheduler

...

• A restart of the relevant product is required to apply changes to either the the Controller JS7_CONFIG_DIR/private/private.conf file or to JOC Cockpit configuration files.

...

Resources

• JS7 - JOC Cockpit HTTPS Connections
• JS7 - Agent HTTPS Connections
• JS7 - Configuration Templates
  • JS7 - Configuration for mutual HTTPS Server Authentication and Client Authentication
  • JS7 - Configuration for HTTP Basic Authentication with Passwords
  • JS7 - Configuration for HTTPS Server Authentication with Passwords
• JS7 - How to create X.509 SSL TLS Certificates
• JS7 - How to add SSL TLS Certificates to Keystore and Truststore

...