How to install HTTPS certificates in DataMinder

HTTPS certificates in DataMinder

DataMinder creates a new unique self-signed certificate during installation

When you install DataMinder for the first time, a self-signed certificate is created. It is unique for your installation. DataMinder creates this certificate to allow you to start working in a secure way by using HTTPS. Both in the admin interface and the service interface.

But since this is self-signed certificate nobody trusts it. You may trust it since it is your certificate, and you created it. But nobody else will. That's why browsers show a warning when you access the admin interface.

You may use this certificate if you like. But if you want a certificate from a proper authority, you need to update the Keystore with a new one.

How DataMinder uses HTTPS certificates

DataMinder stores its certificates in the standard Java Keystore or JKS. You will use the standard Java keytool to managed the JKS. The keytool is provided with the Java SDK.

The Keystore file, which is just a plain Java Keystore file, and is named DMKeyStore. You'll find it in: 

{DM_ROOT}/Server/Config/Certificates/DMKeyStore

DataMinder needs 3 parameters to access the certificate in your key store

The reason Keystore password and key password should be identical comes from the keytool documentation for -importkeystore option (for JDK 8).

... For example, most third-party tools require storepass and keypass in a PKCS #12 Keystore to be the same. In order to create a PKCS #12 Keystore for these tools, always specify a -destkeypass to be the same as -deststorepass.

And you set them in the standard property file DataMinder properties file DataMinder.properties

{DM_ROOT}/Server/Config/DataMinder.properties

You will find them as:

dataminder.environment.web.https.keyStorePassword=FoEgHtwaN6D5s8LdpQCq
dataminder.environment.web.https.keyAlias=acme.com
dataminder.environment.web.https.keyPassword=FoEgHtwaN6D5s8LdpQCq

To avoid problems using your JKS file, it is best to keep keyStorePassword and keyPassword identical. And let keyAlias match your domain as in the example above (domain is acme.com).

How to install a new HTTPS certificate in DataMinder

DataMinder currently uses the Java Keystore JKS file format to store certificates. Unfortunately, it is not the most accessible format to work with.

To keep things as easy and standard as possible, we recommend first installing the certificate on a standard Apache Tomcat installation. The goal is to create a Java Keystore file with:

Most likely, your certificate provider will have documentation (and may provide support) about how to install certificates on a Apache Tomcat server. When you get it to work on your Tomcat server you know that the JKS file should work in DataMinder.

You just need to install the Tomcat server and start it to verify your JKS file works properly.

We would recommend the following flow.

  1. Download and install a standard Apache Tomcat (version 8 or 9) from http://tomcat.apache.org
  2. Install your certificate as described by the certificate provider.
  3. Make sure the conf/server.xml file contains the configuration bellow.
  4. Start the tomcat (with the {TOMCAT_ROOT}/bin/startup.sh or {TOMCAT_ROOT}/bin/startup.bat command) and verify you can access the default http and https page at: http://127.0.0.1:8080 and https://yourdomain.com:8443. The .sh file for Linux and .bat for Windows.
  5. Shut down the Tomcat server (with the {TOMCAT_ROOT}/bin/shutdown.sh or {TOMCAT_ROOT}/bin/shutdown.bat command). You now have a proper JKS file.
    Note: The name and location of your file must be {DM_ROOT}/Server/Config/Certificates/DMKeyStore for DataMinder to work. If you created the JKS file in some other location, you must copy your working JKS file to {DM_ROOT}/Server/Config/Certificates/DMKeyStore

The configuration in the Tomcat server conf/server.xml file that will work with DataMinder must be as:

  <Connector port="8080" protocol="HTTP/1.1"
             connectionTimeout="20000"
             redirectPort="8443" />

  <Connector
    protocol="org.apache.coyote.http11.Http11NioProtocol"
    port="8443"
    maxThreads="200"
    scheme="https"
    secure="true"
    SSLEnabled="true"
    keystoreFile="{DM_ROOT}/Server/Config/Certificates/DMKeyStore"
    keystorePass="MyStorePassword"
    keyAlias="yourdomain.com"
    keyPass="MyStorePassword"
    clientAuth="false"
    sslProtocol="TLS"/>

The important parameters to make it work with DataMinder are: 

    keystoreFile="{DM_ROOT}/Server/Config/Certificates/DMKeyStore"
    keystorePass="MyStorePassword"
    keyAlias="yourdomain.com"
    keyPass="MyStorePassword"

Tomcat can work with JKS and PEM files. But currently, DataMinder only works with JKS file format. Therefore, you must make sure your Tomcat works with the JKS file as in the configuration above.

The default Tomcat start page

If you can access the default Tomcat start page at http (http://127.0.0.1:8080) and https (https://yourdomain.com:8443). Then the JKS file should work with DataMinder. If it doesn't work with Tomcat, please check with your certificate provider.

Here are instructions for how to install a new certificate on Tomcat server: https://www.digicert.com/csr-ssl-installation/tomcat-keytool.htm

If Tomcat worked fine shut down the Tomcat server (with the {TOMCAT_ROOT}/bin/shutdown.sh or {TOMCAT_ROOT}/bin/shutdown.bat command). And start DataMinder provided the new JKS file DMKeyStore is in the DataMinder installation as {DM_ROOT}/Server/Config/Certificates/DMKeyStore

Bonus tip

Import PEM files (from e.g. Let's Encrypt)

Let's Encrypt https://letsencrypt.org/ is a free, automated, and open Certificate Authority. You can get free certificates from them.

They provide the certificates as several PEM files.

To move them to a Java Keystore file JKS you need to run these 2 commands (on Linux).

Step 1: Run openssl to create a P12 file. We assume your domain is yourdomain.com and your store passwords is MyStorePassword.

openssl pkcs12 -export -inkey privkey.pem -in fullchain.pem -CAfile chain.pem -caname root -name yourdomain.com -passout pass:MyStorePassword -out PKC12_file_for_dataminder.p12

Step 2: Next, you need to create the Java Keystore JKS file from the just created P12 file. You do it with the keytool provided with the Java SDK

keytool -importkeystore -srckeystore PKC12_file_for_dataminder.p12 -srcstorepass MyStorePassword -srcstoretype pkcs12 -deststorepass MyStorePassword -destkeypass MyStorePassword -destkeystore DMKeyStore -v

Now you have the JKS file containing your new certificate. Copy it to your DataMinder installation as: {DM_ROOT}/Server/Config/Certificates/DMKeyStore

When we run this, we found we needed to have the same password for both -deststorepass and -destkeypass.

Also, we needed to have the -name parameter in openssl to match the domain the certificate was issued to.

You can verify the contents of JKS file by: 

keytool -list -Keystore DMKeyStore  -storepass MyStorePassword -v
Back to top
Email:   Address: LucidArt AB Visby Sweden