You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 25
Next »
Introduction
- Users benefit from the certificate authority included with JOC Cockpit to create and to roll-out private keys and certificates.
- This includes simplified roll-out to Controller and Agent instances to establish secure HTTPS connections.
- The build-in certificate authority is applicable when operating JOC Cockpit in a low or medium security level, see JS7 - Security Architecture.
- The built-in certificate authority
- 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 for access to JOC Cockpit. Access is performed by user browsers, therefore it is preferable to use a server authentication certificate that is signed by a known certificate authority for which user browsers include the root certificate.
- Users benefit from simplified rollout of private keys and certificates when using the built-in certificate authority.
JS7 provides a Command Line Client available with Controller and Agents instances to create and to roll-out private keys and certificates using the built-in certificate authority. Rollout of private keys and certificates created with an external certificate authority are not in scope of the Command Line Client. The functionality includes
- to authenticate with JOC Cockpit by use of a security token, see JS7 - Certificate Authority - Manage Certificates with JOC Cockpit,
- to request a private key and certificate to be created by JOC Cockpit on-the-fly,
- to update 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.
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:
List of Standard Arguments
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 |
--dn-only | No | Flag to receive relevant DNs to update the private.conf file, without certficate generation. | --dn-only |
--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 used. Supported values include: PKCS12 (default),
JKS (deprecated). | --target-keystore-type=PKCS12 |
--target-keystore-pass | No | Password for access to the keystore. | --target-keystore-pass="YourKeystorePassword" |
--target-keystore-entry-pass | No | Password for the requested private key that should be added to the keystore. | --target-keystore-entry-pass="YourKeystoreEntryPassword" |
|
|
|
|
--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: PKCS12 (default),
JKS (deprecated). | --target-truststore-type=PKCS12 |
--target-truststore-pass | No | Password for access to the truststore. | --target-truststore-pass=" YourTruststorePassword"
|
--help | No | Displays usage information, this option has to be specified as the only command line option and has no value. |
|
Explanation:
- Arguments qualified as required have to be used with any request to JOC Cockpit to create a private key and certificate.
- The
--joc-uri
argument specifies the URL for JOC Cockpit. When used with the HTTPS protocol then check the next section for additional arguments. - The
--target-keystore
is located in the Controller or Agent instance's ./config/private
directory. The --dn-only
argument: If present, only related DNs are added to the private.conf file in
the Controller or Agent instances ./config/private
directory. No certificates/keys are generated.
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:
List of Arguments for use with JOC Cockpit HTTPS Connections
Argument | Required | Description | Example |
---|
--source-truststore | No | Path to the truststore holding the trusted certificate(s) to connect to JOC Cockpit by HTTPS. | --source-truststore=/home/sos/public/js7-truststore.p12 |
--source-truststore-type | No | Type of the truststore used. Supported values include: PKCS12 (default),
JKS (deprecated). | --source-truststore-type=PKCS12 |
--source-truststore-pass | No | Password for access to the truststore. | --source-truststore-pass="YourTruststorePassword" |
--source-certificate | No | Path to a certificate file holding the JOC Cockpit server authentication certificate. | --source-certificate=/home/sos/public/js7-joc-cockpit.crt |
--source-ca-cert | No | 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. | --source-ca-cert="/home/sos/public/intermediate_ca.crt, /home/sos/public/root_ca.crt" |
Explanation:
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.
List of Arguments for use with JOC Cockpit HTTPS Connections using Mutual Authentication
Argument | Required | Description | Example |
---|
--source-keystore | No | Path of the keystore holding the client's private key and certificate for client authentication. | --source-keystore=/home/sos/private/js7-keystore.p12 |
--source-keystore-type | No | Type of keystore used. Supported values include: PKCS12 (default),
JKS (deprecated). | --source-keystore-type=PKCS12 |
--source-keystore-pass | No | Password for access to the keystore holding the private key for client authentication. | --source-keystore-pass="YourKeystorePassword" |
--source-keystore-entry-pass | No | Password for the private key entry in the keystore. | --source-keystore-entry-pass="YourKeystoreEntryPassword" |
--source-private-key | No | Path to the private key file holding the client authentication private key. | --source-private-key=/home/sos/private/client.key |
Explanation:
Examples
Example for use with an HTTP Connection to JOC Cockpit
java -jar sos-commons-cli.jar com.sos.cli.ExecuteRollOut \
--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, ST=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 Truststore
java -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, ST=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
java -jar sos-commons-cli.jar com.sos.cli.ExecuteRollOut \
--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, ST=Berlin" \
--key-alias=myhost \
--ca-alias="Root CA" \
--source-private-key=/home/sos/private/myhost.key \
--source-certificate=/home/sos/public/myhost.pem \
--source-ca-cert="/home/sos/public/intermediate_ca.pem, /home/sos/public/root_ca.pem" \
--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 the Controller-/Agent-Instance Startscript and default values
./bin/controller_instance.sh cert --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446
OR
./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 startscript to build the classpath and start the java executable - The
--token
argument specifies the one-time token to connect to JOC Cockpit once. - The
--joc-uri
argument specifies the URL for JOC Cockpit. - If other arguments are not set the java executable tries to determine default values for the Key-/Trustsstore from the instances
./config/private/private.conf
configuration, defaults for the DN and the SAN of the certificate.
Example for use with the Controller-/Agent-Instance Startscript to update relevant DN entries
./bin/controller_instance.sh cert --dn-only --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446
OR
./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 set no certificates are generated. Only relevant distinguished names (DNs) will be updated in the ./config/private/private.conf
configuration.