Table of Contents

Introduction

The JS7 - Certificate Authority included with the JOC Cockpit benefits users by allowing them to create and rollout private keys and certificates.
- This includes simplified rollout to the Controller and Agent instances for establishing JS7 - Secure Connections.
- The built-in Certificate Authority is applicable when operating JOC Cockpit in a 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 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 and therefore it is preferable to use a Server Authentication Certificate which has been signed by a known Certificate 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 Authority.

JS7 provides a 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 Authority. Rollout of private keys and certificates created The certificate rollout with the command line client supports only the usage of the JS7 JOC Certificate Authority. Rollout of certificates generated with an external Certificate Authority are not supported.

Prerequisites

A number of conditions have to be met before the command line client can be used to rollout the generated certificates.

A JOC CA has to be present in JS7 JOC.
A valid token has to be generated in JS7 JOC for the desired JS7 controller/ JS7 agent.

Command Line Client

Parameters:

...

in scope of the Certificate Rollout Client. The Certificate Rollout Client provides the following functions:

use of a security token to authenticate with the JOC Cockpit, see JS7 - Certificate Authority - Manage Certificates with JOC Cockpit for more information.
requesting a private key and certificate to be created by the JOC Cockpit on-the-fly,
updating a Controller or Agent instance's configuration for use of the private key and certificate with HTTPS mutual authentication.

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

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 the JOC Cockpit.	`--token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b`
`--dn-only`	No	Flag to receive relevant Distinguished Names (DN) to update the `private.conf` file, without generating certificates.	`--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 in the target keystore.

--

...

key-

...

Path of the Keystore holding the keys to connect to JS7 JOC over HTTPS.

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

...

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

...

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 made to the 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 adds related DNs 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 if the JOC Cockpit has been 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.	`--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 verification of the JOC Cockpit Server Authentication Certificate.
The --source-

...

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

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 if the JOC Cockpit is set up 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"

--

...

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/

...

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.

using KeyStore/Truststore
- The following parameters have to be set
  - --source-keystore
    - required
  - -source-keystore-type
    - optional
    - has to be set if JKS is used
  - --source-keystore-pass
    - optional
    - has to be set if the keystore is secured with a password
  - --source-keystore-entry-pass
    - optional
    - has to be set if the private key entry is secured with a password
  - --source-truststore
    - required
  - --source-truststore-type
    - optional
    - has to be set if JKS is used
  - --source-truststore-pass
    - optional
    - has to be set if the truststore is secured with a password
using key and certificate files instead of stores
- The following parameters have to be set
  - --source-private-key
    - required
  - --source-certificate
    - required
  - --source-ca-cert
    - required

Examples

The jar file to use is present in two forms (http://archiva.sos:8080/archiva/repository/sos/com/sos-berlin/sos-commons-cli/2.0.0-SNAPSHOT/)

sos-commons-cli-2-0-0-SNAPSHOT.jar
- 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
- this is a fat/uber jar file
- using this jar needs no classpath at all

...

private/client.key

Explanation:

An HTTPS connection to JOC Cockpit with mutual authentication requires:
- verification of the JOC Cockpit Server Authentication Certificate by the requesting client and
- verification of the Client Authentication Certificate of the requesting client by the 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 if the private key is available from an individual file instead of a keystore.

Examples

Standard Examples

Example for use with the Controller/Agent Instance Start Script and default values

Code Block

language	bash
title	with instance startscript and default values

# 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

language	bash
title	with instance startscript and default values

# 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

language	bash
title	HTTP Connection to JOC Cockpit
collapse	true

java -jar sos-commons-cli.jar com.sos.cli.ExecuteRollOut./bin/controller_instance.sh cert \
    --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"ST=Berlin" \
    --key-alias=myhost \
    --ca-alias="Root CA" \
    --target-keystore=C:/sp/develvar/sos-berlin.com/js7/testingcontroller/CLIconfig/controller/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/CLIconfig/controller/withHTTPprivate/https-truststore.p12 --target-truststore-type=PKCS12\
    --target-truststore-pass=jobscheduler --key-alias=sp --ca-alias=sp root ca

Example for use with an HTTPS Connection to JOC Cockpit and Mutual Authentication from a Client Keystore

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./bin/controller_instance.sh cert \
     --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b \
     --joc-uri=httphttps://spsomehost.example.sos:3333com:4446 \
     --san="spmyhost.example.soscom, spmyhost" \
     --subject-dn="CN=spmyhost, OU=developmentIT Operations, O=SOS, C=DE, L=Berlin, SST=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:/sp/devel/js7/keys/sp/home/sos/private/js7-truststore.p12 --source-truststore-type=PKCS12 \
     --source-truststore-pass="" \
     --target-keystore=C:/sp/develvar/sos-berlin.com/js7/testingcontroller/CLIconfig/controllerprivate/withHTTP/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/CLIconfig/controller/withHTTPprivate/https-truststore.p12 --target-truststore-type=PKCS12 \
     --target-truststore-pass=jobscheduler --key-alias=sp --ca-alias=sp root ca

Example for use with an HTTPS Connection to JOC Cockpit and 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./bin/controller_instance.sh cert \
     --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b \
     --joc-uri=httphttps://spmyhost.example.sos:3333com:4446 \
     --san="spmyhost.example.soscom, spmyhost" \
     --subject-dn="CN=spmyhost, OU=developmentIT Operations, O=SOS, C=DE, L=Berlin, SST=Berlin" \
     --key-alias=myhost \
     --ca-alias="Root CA" \
     --source-private-key=C:/sphome/develsos/js7/keys/sp/sp.keyprivate/myhost.key \
     --source-certificate=C:/sphome/develsos/js7/keys/sp/sp.cerpublic/myhost.pem \
     --source-ca-cert="C:/sphome/develsos/js7/keys/sp/sos_public/intermediate_ca.cerpem, C:/sphome/devel/js7/keys/sp/sos_sos/public/root_ca.cerpem" \
     --target-keystore=C:/sp/develvar/sos-berlin.com/js7/testingcontroller/CLIconfig/controllerprivate/withHTTP/https-keystore.p12 --target-keystore-type=PKCS12 \
     --target-keystore-pass=jobscheduler \
     --target-keystore-entry-pass=jobscheduler \
     --target-truststore=C:/sp/devel/js7/testing/CLI/controller/withHTTPvar/sos-berlin.com/js7/controller/config/private/https-truststore.p12 --target-truststore-type=PKCS12 \
     --target-truststore-pass=jobscheduler --key-alias=sp --ca-alias=sp root ca

Space shortcuts

Page tree

Versions Compared

Old Version 7

New Version Current

Key

Introduction

Prerequisites

Command Line Client

Parameters:

Certificate Rollout

Certificate Rollout Client

Standard Arguments

Arguments for use with JOC Cockpit HTTPS Connections

Arguments for use with JOC Cockpit HTTPS Connections using Mutual Authentication

Connection to JS7 JOC over HTTP

Connection to JS7 JOC over HTTPS

Examples

Examples

Standard Examples

Example for use with the Controller/Agent Instance Start Script and default values

Example for use with the Controller/Agent Instance Start Script to update relevant DN entries

Advanced Examples

Example for use with an HTTP Connection to JOC Cockpit

Example for use with an HTTPS Connection to JOC Cockpit and Mutual Authentication from a Client Keystore

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

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 7

New Version Current

Key

Introduction

Prerequisites

Command Line Client

Parameters:

Certificate Rollout

Certificate Rollout Client

Standard Arguments

Arguments for use with JOC Cockpit HTTPS Connections

Arguments for use with JOC Cockpit HTTPS Connections using Mutual Authentication

Connection to JS7 JOC over HTTP

Connection to JS7 JOC over HTTPS

Examples

Examples

Standard Examples

Example for use with the Controller/Agent Instance Start Script and default values

Example for use with the Controller/Agent Instance Start Script to update relevant DN entries

Advanced Examples

Example for use with an HTTP Connection to JOC Cockpit

Example for use with an HTTPS Connection to JOC Cockpit and Mutual Authentication from a Client Keystore

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