Page History
Table of Contents |
---|
Introduction
- Users benefit from the certificate authority The JS7 - Certificate Authority included with the JOC Cockpit benefits users by allowing them to create and to roll-out rollout private keys and certificates.
- This includes simplified roll-out rollout to the Controller and Agent instances to establish secure HTTPS connectionsfor establishing JS7 - Secure Connections.
- The buildbuilt-in certificate authority Certificate Authority is applicable when operating JOC Cockpit in a low or medium security level, see Security Level Low or Medium, see the JS7 - Security Architecture. and JS7 - Secure Operation articles for more information.
- The built-in Certificate Authority:
- creates X.509
- creates certificates for HTTPS Mutual Authentication
- between JOC Cockpit and Controller instances,
- between Primary and Secondary Controller instances,
- between Controller instances and Agents.
- is not used to create server authentication certificates Server Authentication Certificates for access to JOC Cockpit. Access is performed by user browsers , and therefore it is preferable to use a server authentication certificate that is Server Authentication Certificate which has been signed by a known certificate authority for which user browsers include the root certificateCertificate Authority and whose Root CA certificate is recognized by user's browsers.
- Users benefit from the simplified rollout of private keys and certificates when using the built-in certificate authorityin Certificate Authority.
JS7 provides a Command Line Client available with Controller and Agents instances to create and to roll-Certificate Rollout Client as part of the Controller and Agent instance's Start Scripts. This client creates and rolls out private keys and certificates using the built-in certificate authorityCertificate Authority. Rollout of private keys and certificates created with an external certificate authority Certificate Authority are not in scope of the Command Line Certificate Rollout Client. The functionality includesCertificate Rollout Client provides the following functions:
- use of a security token to authenticate with the JOC Cockpit by use of a security token, see JS7 - Certificate Authority - Manage Certificates with JOC Cockpit, for more information.
- requesting to request a private key and certificate to be created by the JOC Cockpit on-the-fly,
- to update updating a Controller or Agent instance's configuration for use of the private key and certificate with HTTPS mutual authentication.
Prerequisites
The following conditions have to be met before the Command Line Client can be used to roll-out private keys and certificates.
Certificate Rollout
Rollout of certificates includes performing the following steps:
- JOC Cockpit
- The JOC Cockpit Certificate Authority is set up and the Root CA private key and certificate are made available
- .
- Valid security tokens
- are generated with the JOC Cockpit for the
- Controller and Agent instances that require a certificate.
- For details see JS7 - Certificate Authority - Manage Certificates with JOC Cockpit
Command Line Client
The command line client is available for Unix and Windows
- for a Controller instance:
./bin/controller.sh|cmd
- for an Agent instance:
./bin/agent.sh|cmd
Standard Arguments
The following arguments are used independently from an HTTP or HTTPS connection to JOC Cockpit:
- Controller/Agent Instance
- Both components include the Certificate Rollout Client which is available from the Controller/Agent Instance Start Script.
- The Certificate Rollout Client connects to the JOC Cockpit. Authentication is performed using the one-time security token generated in the previous step.
- The JOC Cockpit Certificate Authority is requested to create a private key and Server/Client Authentication Certificate for the specified host. The private key and certificate are created on-the-fly and are returned to the Certificate Rollout Client. In addition, the JOC Cockpit stores the certificate in the JS7 - Database.
The Certificate Rollout Client:- stores the private key in a keystore file,
- stores the Server/Client Authentication Certificate in a truststore file,
- updates the configuration in the
./config/private/private.conf
file.
Certificate Rollout Client
The Controller/Agent Instance Start Script includes the Certificate Rollout Client and is available from the following locations:
- for a Controller instance:
./bin/controller_instance.sh|cmd
- For details see the JS7 - Controller - Command Line Operation article.
- for an Agent instance:
./bin/agent_<port>.sh|cmd
- For details see the JS7 - Agent Command Line Operation article.
Standard Arguments
The following arguments are used independently of whether the connection to the JOC Cockpit is made with HTTP or HTTPS:
Expand | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Explanation:
|
Arguments for use with JOC Cockpit HTTPS Connections
The following arguments are used in addition to standard arguments if the JOC Cockpit has been set up for HTTPS connections:
Expand | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Expand | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Argument | Required | Description | Example | --joc-uri Yes | URI of the JOC Cockpit instance from which to receive the private key and certificate. --joc-uri=http://myhost.example.com:4446 --token Yes | UUID of the security token for one-time authentication with JOC Cockpit. --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --subject-dn Yes | The subject of the requested certificate includes the Distinguished Name (DN) consisting of CN, OU, O, L, S, C attributes. The hostname of the requesting client is specified as CN. --subject-dn="CN=myhost, OU=IT Operations, O=SOS, L=Berlin, S=Berlin, C=DE" --san Yes | The Subject Alternative Name (SAN) specifies the hostname of the requesting client and optionally variations of the hostname, e.g. the domain part (FQDN). Alternative hostnames are separated by comma. --san="myhost, myhost.example.com" --key-alias Yes | Alias name used when storing the requested private key and certificate to the target keystore. --key-alias="MyKeyAlias" --ca-alias Yes | Alias name used when storing the requested CA certificate in both, the target keystore and truststore. --ca-alias="MyTrustedCertificateAlias" --target-keystore Yes | Path to the keystore to which the requested private key and certificate should be stored. --target-keystore=/var/sos-berlin.com/js7/controller/var/config/private/https-keystore.p12 --target-keystore-type No | Type of the keystore
No |
--target-truststore Yes | Path to the truststore to which the trusted CA certificate should be stored. --target-truststore=/var/sos-berlin.com/js7/controller/var/config/private/https-truststore.p12 --target-truststore-type No | Type of the truststore used. Supported values include: --target-truststore-type=PKCS12 --target-truststore-pass No | Password for access to the truststore.
--help No | Displays usage information, this option has to be specified as the only command line option and has no value. | Explanation:
|
Arguments for use with JOC Cockpit HTTPS Connections
The following arguments are used in addition to standard arguments in case that JOC Cockpit is set up for HTTPS connections:
...
title | List of Arguments for use with JOC Cockpit HTTPS Connections |
---|
...
Path to the truststore holding the trusted certificate(s) to connect to JOC Cockpit by HTTPS.
...
Type of the truststore used. Supported values include: PKCS12
(default),JKS
(deprecated).
...
Password for access to the truststore.
...
Path to a certificate file holding the JOC Cockpit server authentication certificate.
...
Path to the CA certificate file(s) that are used to verify the JOC Cockpit server authentication certificate. A number of paths can be specified, separated by comma.
...
Explanation:
- An HTTPS connection to JOC Cockpit requires to verify the JOC Cockpit server authentication certificate.
- The
--source-truststore-*
arguments are used to specify a truststore that holds the root CA certificate and optionally any intermediate CA certificates involved in signing the JOC Cockpit server authentication certificate. The
--source-certificate
and--source-ca-cert
arguments are used as an alternative to--source-truststore-*
arguments in case that JOC Cockpit server authentication certificates are available from individual files instead of being available from a common truststore. Supported certificate formats include PEM.
Arguments for use with JOC Cockpit HTTPS Connections using Mutual Authentication
The following arguments are used in addition to HTTPS connection arguments in case that JOC Cockpit is setup for JOC Cockpit - HTTPS Mutual Authentication.
...
title | List of Arguments for use with JOC Cockpit HTTPS Connections using Mutual Authentication |
---|
...
Path of the keystore holding the client's private key and certificate for client authentication.
...
Type of keystore used. Supported values include: PKCS12
(default),JKS
(deprecated).
...
Password for access to the keystore holding the private key for client authentication.
...
Password for the private key entry in the keystore.
...
Path to the private key file holding the client authentication private key.
...
Explanation:
- An HTTPS connection to JOC Cockpit with mutual authentication requires
- to verify the JOC Cockpit server authentication certificate by the requesting client and
- to verify the client authentication certificate of the requesting client by JOC Cockpit.
- The
--source-keystore-*
arguments are used to specify a keystore that holds the client's private key and certificate for client authentication. The
--source-private-key
argument is used as an alternative to--source-keystore-*
arguments in case that the private key is available from an individual file instead of a keystore.
Explanation:
|
Arguments for use with JOC Cockpit HTTPS Connections using Mutual Authentication
The following arguments are used in addition to HTTPS connection arguments if the JOC Cockpit is set up for JOC Cockpit - HTTPS Mutual Authentication.
Expand | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||
Explanation:
|
Examples
Standard Examples
Example for use with the Controller/Agent Instance Start Script and default values
Code Block | ||||
---|---|---|---|---|
| ||||
# use with a Controller instance
./bin/controller_instance.sh cert --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446
# use with an Agent instance
./bin/agent_<port>.sh cert --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446 |
Explanation:
- the
cert
argument for the Instance Start Script is used to build the Java classpath and start the Java executable. - The
--token
argument specifies the one-time token to connect to JOC Cockpit. - The
--joc-uri
argument specifies the URL for JOC Cockpit. - If no additional arguments are used then the Command Line Client determines default values for the Keystore and Truststore from the instances'
./config/private/private.conf
configuration file, including defaults for the DN and for the SAN of the certificate.
Example for use with the Controller/Agent Instance Start Script to update relevant DN entries
Code Block | ||||
---|---|---|---|---|
| ||||
# use with a Controller instance
./bin/controller_instance.sh cert --dn-only --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446
# use with an Agent instance
./bin/agent_<port>.sh cert --dn-only --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446 |
Explanation:
- With the
--dn-only
argument only relevant Distinguished Names (DNs) will be updated to the./config/private/private.conf
configuration file.
Advanced Examples
Example for use with an HTTP Connection to JOC Cockpit
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
java -jar sos-commons-cli.jar com.sos.cli.ExecuteRollOut./bin/controller_instance.sh cert \ --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b \ --joc-uri=http://somehost.example.com:4446 \ --san="myhost.example.com, myhost" \ --subject-dn="CN=myhost, OU=IT Operations, O=SOS, C=DE, L=Berlin, SST=Berlin" \ --key-alias=myhost \ --ca-alias="Root CA" \ --target-keystore=/var/sos-berlin.com/js7/controller/var/config/private/https-keystore.p12 \ --target-keystore-pass=jobscheduler \ --target-keystore-entry-pass=jobscheduler \ --target-truststore=/var/sos-berlin.com/js7/controller/var/config/private/https-truststore.p12 \ --target-truststore-pass=jobscheduler |
Explanation:
...
Example for use with an HTTPS Connection to JOC Cockpit and Mutual Authentication from a Client
...
Keystore
Code Block | |||||||||
---|---|---|---|---|---|---|---|---|---|
| |||||||||
./bin/controller_instance.sh certjava -jar sos-commons-cli.jar com.sos.cli.ExecuteRollOut \ --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b \ --joc-uri=https://somehost.example.com:4446 \ --san="myhost.example.com, myhost" \ --subject-dn="CN=myhost, OU=IT Operations, O=SOS, C=DE, L=Berlin, SST=Berlin" \ --key-alias=myhost \ --ca-alias="Root CA" \ --source-keystore=/home/sos/private/js7-keystore.p12 \ --source-keystore-pass="" \ --source-keystore-entry-pass="" \ --source-truststore=/home/sos/private/js7-truststore.p12 \ --source-truststore-pass="" \ --target-keystore=/var/sos-berlin.com/js7/controller/var/config/private/https-keystore.p12 \ --target-keystore-pass=jobscheduler \ --target-keystore-entry-pass=jobscheduler \ --target-truststore=/var/sos-berlin.com/js7/controller/var/config/private/https-truststore.p12 \ --target-truststore-pass=jobscheduler |
Explanation:
...
Example for use with an HTTPS Connection to JOC Cockpit and Mutual Authentication from a Client Key File
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
java -jar sos-commons-cli.jar com.sos.cli.ExecuteRollOut./bin/controller_instance.sh cert \ --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b \ --joc-uri=https://myhost.example.com:4446 \ --san="myhost.example.com, myhost" \ --subject-dn="CN=myhost, OU=IT Operations, O=SOS, C=DE, L=Berlin, S=Berlin" \ --key-alias=myhost" \ --casubject-aliasdn="Root CA" \ --source-private-key=/home/sos/private/myhost.keyCN=myhost, OU=IT Operations, O=SOS, C=DE, L=Berlin, ST=Berlin" \ --sourcekey-certificate=/home/sos/public/myhost.pemalias=myhost \ --source-ca-certalias="/home/sos/public/intermediate_ca.pem, /home/sos/public/root_ca.pemRoot CA" \ --targetsource-private-keystorekey=var/sos-berlin.com/js7/controller/var/config/home/sos/private/https-keystoremyhost.p12key \ --targetsource-keystore-pass=jobschedulercertificate=/home/sos/public/myhost.pem \ --targetsource-keystore-entry-pass=jobschedulerca-cert="/home/sos/public/intermediate_ca.pem, /home/sos/public/root_ca.pem" \ --target-truststorekeystore=var/sos-berlin.com/js7/controller/var/config/private/https-truststore.p12 \ --target-truststore-pass=jobscheduler |
Explanation:
- tbd
Developer Notes
The jar file to use is present in two forms
- sos-commons-cli-2-0-0-SNAPSHOT.jar (ca. 9 KB)
- this is a standard jar file
- using this jar needs to get the complete classpath set from the outside
- sos-commons-cli-2-0-0-SNAPSHOT-jar-with-dependencies.jar (ca. 22 MB)
- this is a fat/uber jar file
- using this jar needs no classpath at all
The filename of the jar file should be changed through the setup, so that customers will later only have to call sos-commons-cli.jar or a different desired name in either way (external classpath in agent, without classpath in the controller)
...
https-keystore.p12 \
--target-keystore-pass=jobscheduler \
--target-keystore-entry-pass=jobscheduler \
--target-truststore=var/sos-berlin.com/js7/controller/config/private/https-truststore.p12 \
--target-truststore-pass=jobscheduler |