Table of Contents

Introduction

Users benefit from simplified rollout of the certificate authority included with JOC Cockpit to create and to roll-out private keys and certificates.
- This includes simplified roll-out to Controller
instances and Agents when using the built-in JS7 - Certificate Authority.
Users have a choice to use an external certificate authority or to use the built-in certificate authority that ships with JOC Cockpit.
- 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 JOC Cockpit server authentication certificates. As JOC Cockpit is accessed by user browsers it is preferable to use a server/client 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 JS7 provides a command line client available with Controller instances and Agents to create and to roll-out private keys and certificates of using the built-in certificate authority. Rollout of private keys and certificates created with an external certificate authority are not in scope of the JS7 command line clientCommand 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 or Agents configuration for use of the private key and certificate for with HTTPS mutual authentication.

Prerequisites

The following conditions have to be met before the command line client Command Line Client can be used to rollout roll-out private keys and certificates.

The JOC Cockpit certificate authority has to be available and the root private key and certificate have been created.
A valid token has to be generated in Valid security tokens have been generated with JOC Cockpit for the desired JS7 Controller and Agent instances and Agents..
For details see JS7 - Certificate Authority - Manage Certificates with JOC Cockpit

Command Line Client

...

Parameters:

...

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:

Expand

title	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`
`--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`

...

Path of the Keystore holding the keys to connect to JS7 JOC over 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

...

Path to the private Key file used to connect to JS7 JOC over HTTPS.

...

Path to the certificate file used to connect to JS7 JOC over HTTPS.

...

Path to the CA certificate file(s) used to connect to JS7 JOC over HTTPS. (Comma separated)

...

Path to the Keystore where the generated SSL certificates and keys should be stored.

...

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 agument 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.

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:

Expand

title	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.

--

...

Path to the Truststore where the trusted ca certificate should be stored.

...

Type of the truststore to store to. (PKCS12[default] and JKS are supported only)

...

Password for the truststore to store to.

...

--target-truststore-pass="YourTruststorePassword"

...

Alias used to store the certificate and its private key in the target keystore.

...

Alias used to store the ca certificate in both, the target keystore and truststore.

...

Connection to JS7 JOC over HTTP

No parameter starting with --source has to be set.

Connection to JS7 JOC over HTTPS

There are two ways supported to connect over HTTPS. Depending on the method which is chosen some optional parameters are required.

...

`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:

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.

Argument 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.

Expand

title	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"`

...

required

...

optional
has to be set if JKS is used

...

--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-

...

optional
has to be set if the truststore is secured with a password

...

The following parameters have to be set
- --source-private-key
  - required
- --source-certificate
  - required
- --source-ca-cert
  - required

private-key=/home/sos/private/client.key

Explanation:

An HTTPS connection with mutual authentication to JOC Cockpit requires
- to verify the JOC Cockpit server authentication certificate and
- to verify the client authentication certificate of the requesting client.
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.

Examples

Example for use of an HTTP Connection to JOC Cockpit

Examples

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)

For testing purpose the jar files are internally available in archiva http://archiva.sos:8080/archiva/repository/sos/com/sos-berlin/sos-commons-cli/2.0.0-SNAPSHOT/ . The files in archiva have an additional timestamp and a build number in their filenames.

Code Block

language	bash
title	HTTP Connection to JOC Cockpit
collapse	true

java -jar sos-commons-cli.jar com.sos.cli.ExecuteRollOut \
    --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b \
    --joc-uri=http://spsomehost.example.sos:3333com:4446 \
    --san="spmyhost.example.soscom, spmyhost" \
    --subject-dn="CN=spmyhost, OU=developmentIT Operations, O=SOS, C=DE, L=Berlin, S=Berlin" \
    --key-alias=myhost \
    --ca-alias="Root CA" \
    --target-keystore=C:/sp/develvar/sos-berlin.com/js7/testingcontroller/CLIvar/controllerconfig/withHTTPprivate/https-keystore.p12 --target-keystore-type=PKCS12 \
    --target-keystore-pass=jobscheduler \
    --target-keystore-entry-pass=jobscheduler \
    --target-truststore=C:/sp/develvar/sos-berlin.com/js7/testingcontroller/CLIvar/controllerconfig/withHTTPprivate/https-truststore.p12 --target-truststore-type=PKCS12\
    --target-truststore-pass=jobscheduler --key-alias=sp --ca-alias="sp root ca"

Explanation:

tbd

Example for use of an HTTPS Connection to JOC Cockpit with Mutual Authentication from a Client Truststore

Code Block

language	bash
title	HTTPS with Key-/Connection to JOC Cockpit with Mutual Authentication from a Client Truststore
collapse	true

java -jar sos-commons-cli.jar com.sos.cli.ExecuteRollOut \
     --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b \
     --joc-uri=httphttps://spsomehost.example.sos:3333com:4446 \
     --san="spmyhost.example.soscom, sp"myhost" \
     --subject-dn="CN=spmyhost, OU=developmentIT Operations, O=SOS, C=DE, L=Berlin, S=Berlin" \
     --key-alias=myhost \
     --ca-alias="Root CA" \
     --source-keystore=C:/home/spsos/develprivate/js7/keys/sp-keystore.p12 -source-keystore-type=PKCS12 \
     --source-keystore-pass="" \
     --source-keystore-entry-pass="" \
     --source-truststore=C:/home/spsos/develprivate/js7/keys/sp-truststore.p12 --source-truststore-type=PKCS12 \
     --source-truststore-pass="" \
     --target-keystore=C:/sp/develvar/sos-berlin.com/js7/testingcontroller/CLIvar/controllerconfig/withHTTPprivate/https-keystore.p12 --target-keystore-type=PKCS12 \
     --target-keystore-pass=jobscheduler \
     --target-keystore-entry-pass=jobscheduler \
     --target-truststore=C:/sp/develvar/sos-berlin.com/js7/testingcontroller/CLIvar/controllerconfig/withHTTPprivate/https-truststore.p12 --target-truststore-type=PKCS12 \
     --target-truststore-pass=jobscheduler --key-alias=sp --ca-alias="sp root ca"

Explanation:

tbd

Example for use of an HTTPS Connection to JOC Cockpit with Mutual Authentication from a Client Key File

Code Block

language	bash
title	HTTPS with credential filesConnection to JOC Cockpit with Mutual Authentication from a Client Key File
collapse	true

java -jar sos-commons-cli.jar com.sos.cli.ExecuteRollOut \
     --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b \
     --joc-uri=httphttps://spmyyhost.example.sos:3333com:4446 \
     --san="spmyhost.example.soscom, sp"myhost" \
     --subject-dn="CN=spmyhost, OU=developmentIT Operations, O=SOS, C=DE, L=Berlin, S=Berlin" \
     --key-alias=myhost \
     --ca-alias="Root CA" \
     --source-private-key=C:/sphome/develsos/js7/keys/sp/spprivate/myhost.key \
     --source-certificate=C:/sphome/develsos/js7/keys/sp/sp.cerpublic/myhost.pem \
     --source-ca-cert="C:/sphome/devel/js7/keys/sp/sos_sos/public/intermediate_ca.cerpem, C:/sphome/devel/js7/keys/sp/sos_sos/public/root_ca.cer"pem" \
     --target-keystore=C:/sp/develvar/sos-berlin.com/js7/testingcontroller/CLIvar/controllerconfig/withHTTPprivate/https-keystore.p12 --target-keystore-type=PKCS12 \
     --target-keystore-pass=jobscheduler \
     --target-keystore-entry-pass=jobscheduler \
     --target-truststore=C:/sp/develvar/sos-berlin.com/js7/testingcontroller/CLIvar/controllerconfig/withHTTPprivate/https-truststore.p12 \
     --target-truststore-type=PKCS12 --target-truststore-pass=jobscheduler --key-alias=sp --ca-alias="sp root ca"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)

For testing purpose the jar files are internally available in archiva http://archiva.sos:8080/archiva/repository/sos/com/sos-berlin/sos-commons-cli/2.0.0-SNAPSHOT/ . The files in archiva have an additional timestamp and a build number in their filenames.

Space shortcuts

Page tree

Versions Compared

Old Version 15

New Version 16

Key

Introduction

Prerequisites

Command Line Client

Parameters:

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

Arguments for use with JOC Cockpit HTTPS Connections

Connection to JS7 JOC over HTTP

Connection to JS7 JOC over HTTPS

Argument for use with JOC Cockpit HTTPS Connections using Mutual Authentication

Examples

Example for use of an HTTP Connection to JOC Cockpit

Examples

Example for use of an HTTPS Connection to JOC Cockpit with Mutual Authentication from a Client Truststore

Example for use of an HTTPS Connection to JOC Cockpit with Mutual Authentication from a Client Key File

Developer Notes

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 15

New Version 16

Key

Introduction

Prerequisites

Command Line Client

Parameters:

The command line client is available for Unix and Windowsfor a Controller instance: ./bin/controller.sh|cmdfor an Agent instance: ./bin/agent.sh|cmd

Standard Arguments

Arguments for use with JOC Cockpit HTTPS Connections

Connection to JS7 JOC over HTTP

Connection to JS7 JOC over HTTPS

Argument for use with JOC Cockpit HTTPS Connections using Mutual Authentication

Examples

Example for use of an HTTP Connection to JOC Cockpit

Examples

Example for use of an HTTPS Connection to JOC Cockpit with Mutual Authentication from a Client Truststore

Example for use of an HTTPS Connection to JOC Cockpit with Mutual Authentication from a Client Key File

Developer Notes

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`