Security: Web Server SSL configuration

Omniscope web server includes HTTPS support, shipping out of the box a self-signed certificate located into the omniscope-server install folder (named keystore.jks.default), untrusted, suitable for testing and development.

To obtain and use your own fully validated (trusted) SSL certificate, you need to create a keystore (jks) file containing the certificate, and configure the keystore path and password in Omniscope.

Generating the keystore (jks) file

Follow these 6 steps to create your Java keystore with a trusted certificate and the full chain of certificates required. You will need the "keytool" / "keytool.exe" command-line tool, included in the Java JDK; we suggest using JDK 11 (download it from https://adoptium.net/). 

NOTE: It is important you choose JDK 11 and not a different version when you download JDK.

1. Generate your RSA Private key. The alias here is a unique arbitrary value that must be the same alias in steps 1, 2 and 5 here.
   keytool -genkey -J-Dkeystore.pkcs12.legacy -alias myalias -keyalg EC -keysize 256 -sigalg SHA256withECDSA -keystore mykeystore.jks
It will ask for a keystore password. Enter a secure password that you'll need again in subsequent steps and will later specify in Omniscope's configuration.
It will ask for your "first and last name". This is actually asking for the "CN" (common name) and should be the domain of the certificate, which must match the domain your server will be accessed at, with "*." prefix for wildcard domains. For example: "mysite.com" if accessing the site at "https://mysite.com", or "www.mysite.com" for "https://www.mysite.com", or "*.mysite.com" for a wildcard certificate supporting "https://<anything>.mysite.com".
It will ask for other organizational unit, organization, city or locality, state or province, and 2-letter country code; provide everything accurately.
When asked, you can choose whether to provide a different password for the key within the keystore, from the keystore password itself. This is up to you; you can press Enter for the latter.
   
   
2. Generate a CSR (certificate signing request) file
   keytool -certreq -keyalg EC -alias myalias -file certreq.txt -keystore mykeystore.jks
   
   
3. Use your CSR when purchasing and generating a new certificate from your chosen Certificate Authority (e.g. http://www.ksoftware.net/ssl_certs.html or https://gogetssl.com).
   You may need to validate your domain by (for example) temporarily creating a DNS entry for your domain, typically with your domain name provider/registrar, which can take a few hours to propagate.
   Typically you'll receive a zip containing 2 or more .crt files, being a root certificate, perhaps some intermediate certificate(s), and your domain certificate.
   To inspect the certificate you've bought, use
   keytool -printcert -file MySiteCert.crt
Look for "Owner: CN=mysite.com", or, if you have bought a multi-domain certificate:
   SubjectAlternativeName [
   DNSName: www.mysite.com

     DNSName: mysite.com

   ]

   
   
4. Install the Trusted Root and all intermediate certificates; give each one a unique alias
   keytool -import -alias MyTrustedCert1 -keystore mykeystore.jks -trustcacerts -file MyTrustedCert1.crt
   It may say that the root is already in the system wide store; import it anyway.
   You should see "Certificate was added to keystore".
   
   
5. Install the SSL Certificate under the same alias that the CSR was created from (e.g. myalias):
   keytool -J-Dkeystore.pkcs12.legacy -import -alias myalias -keystore mykeystore.jks -trustcacerts -file MySiteCert.crt
   You should receive a message: "Certificate reply was installed in keystore" if successful.
   You can check the keystore contents using:
   keytool -list -keystore mykeystore.jks
You will typically see a "Private key entry" and one or more "trustedCertEntry", each with their alias used earlier.

Configuring Omniscope

Go to the Admin -> Network setting section, once you enable "HTTPS" the "SSL Configuration" section will appear for you to configure the necessary keystore path and password(s).

Additional guides

To generate keys and certificates, you can follow one of these two guides: 

Generate a Self Signed Certificate using Java Keytool

Generate a Trusted Certificate