Basic information

By default the installation of the custo diagnostic server in Windows already creates a key pair with a self-signed certificate. This already permits an encrypted HTTPs connection with the IP port defined in the installation program. You may test it with your browser:

However neither the common name stored in the certificate probably matches with the client name nor the trust to this certificate is given. The custo diagnostic client expects both. Beyond that the certificate validity must be within the time range specified in the certificate and this is by default only a one year period.

On the other hand: There is already a key pair installed - so no new one needs to be created, which is good from the IT security point of view as you should avoid creating a key pair on another system: Even a certification authority (CA should never get in touch with the private key. The only task of the CA should be the proper signature of the public key of your system. Therefor ethe CA should be trusted by all customer clients and the certificate should have a reasonable validity monitored administratively. 

Signature

The procedure consists of the creation of a certificate signing request (CSR), the signature of it by the CA and the import of the signed public key - the certificate. The CSR creation as well as the import of the certificate can be done either by command line program keytool (part of the the Java Runtime Engine installed with the custo diagnostic server) or via a graphic tool like the Keystore Explorer  (see https://keystore-explorer.org/index.html).

With both tools you access the diagserver keystore stored in the diagserverdata directory: 

To modify it the custo diagnostic service (Apache Tomcat service) must be stopped. The keystore is installed in parallel to the Windows certificate store and the diagserver uses only that one for the web server SSL service.

To work with the keytool program start CMD in administative context (run as admin): 

Create a key for the signing request:

The program then asks for a password. The password is: custo1234

In this example a request for the server is test.customed.de created. For your server replace it by the full name of the server running custo diagnostic.

The result in this example is the file test.customed.de.csr. This is the file you need to transfer to the CA to get a signed certificate created.

The answer from a CA is normally a pkcs file or several PEM files.

With the keystore explorer:

Open the keystore in the diagserverdata directory called keystore.jks:

The keystore password is here as well "custo1234".

There should be only one entry called "main":

Right click on "main" and create a CSR request;

After entering the key store password that menu opens:

Modify there the domain name details - replace "test.customed,de" with the full name of your custo diagnostic server - as specified in the custocfg.ini:

By then clicking twice "OK" you get the CSR at the location you have specified above. Send that to the CA for the signature.

Import a PKCS file

With the keytool program:

In our example use:

The password of the keystore should still be custo1234.

With the keystore explorer:

Open the pkcs answer file via the "import CA response" menu and install it:

Import PEM files

You need to install all certificate files one by one. Here an example:

Finally:

Restart the custo diagnostic service and check with a web browser (use the URL in the custocfg.ini and use https instead of http) if everything works as expected.

Appendix: Import a PFX file:

With the keytool program:

In some cases you will get a whole key pair from the CA. Though this approach is not recommended it is described here:

Now delete the old main key:

Rename the new key pair to the old main key pair:

With this command you can check the keystore content and verify the correct thumprint:

Finally restart the custo diagnostic service and check with a web browser (use the URL in the custocfg.ini and use https instead of http) if everything works as expected.

With the keystore explorer:

Delete the main key pair in the context menu of it (right click). Then the keystore should be empty. Now import the new key. To do so go to →Import Keypair

Choose the type of key pair. In case of .pem files it is OpenSSL which in this example has been selected as well.

On the following page select the key file for the installation. Encrypted private key can be turned off.

After clicking import you get prompted for the alias. Important: Specify here "main"!

Then you will get prompted for the password. Enter twice "custo1234":

Now the new key pair is in the key store. Save it (CTRL + S), restart the custo diagnostic service and check with a web browser (use the URL in the custocfg.ini and use https instead of http) if everything works as expected.

Danach ist das neue Keypair im Keystore eingelagert und der diag server kann damit gestartet werden.

Appendix: Satellite system sync with HTTPs

If you set up a satellite system the Apache Tomcat server will not act as a server, but as a client.

In this case Apache Tomcat will not use the server key store (keystore,jks) in the diagserverdata directory, but its client keystore cacerts (by default stored in (C:\Program Files\custo diagnostic server\jre\lib\security). You can use the same tools as above to open that certificate store - the password is by default empty. Import the root certificate of the SSL certificate installed on the master server.

Now you need to configure Apache Tomcat to use its own keystore and not the one of the Windows operating system. For this open the "Configure custo diagnostic server" app on the SAT server and go to the Java tab. Remove the line "-Djavax.net.ssl.trustStoreType=WINDOWS-ROOT" and restart the custo diagnostic SAT server.

Further information:

See also Tomcat HTTP / SSL Howto: https://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html man den CSR erstellen, aber auch die CA-Antwort importieren.