Skip to content

Configure JVM Trust for SSL/TLS Certificates#

Java applications such as TheHive rely on a Java truststore to validate SSL/TLS certificates. By default, the Java virtual machine (JVM) trusts only well-known certificate authorities (CAs).

If you use self-signed certificates or internal CAs, you must configure the JVM to trust them. This configuration is essential for authentication providers and connectors used in TheHive.

Maintenance window required

This procedure involves changing configuration files and restarting services. Schedule a maintenance window to prevent service disruption.

DEB package#

  1. Open the /etc/default/thehive file.

  2. Uncomment the JAVA_OPTS variable.

  3. Enter the path to your truststore file containing the required CA certificates.

    JAVA_OPTS="-Djavax.net.ssl.trustStore=/path/to/<truststore_file> -Djavax.net.ssl.trustStorePassword=<truststore_password>"

  4. Save your modifications.

  5. Restart TheHive service.

    sudo systemctl restart thehive

  1. Ensure the ca-certificates-java package is installed.

    sudo apt-get install -y ca-certificates-java

  2. Copy your CA certificates to the system directory.

    sudo mkdir /usr/share/ca-certificates/extra
sudo cp <custom_certificate>.crt /usr/share/ca-certificates/extra/

  3. Reconfigure and update the Java truststore.

    • When using the Amazon Corretto JVM, the default truststore is a bundled file rather than a symlink to the system truststore. System CA certificates won't be recognized until you manually replace the bundled truststore with a symlink:
    sudo rm $JAVA_HOME/lib/security/cacerts
sudo ln -s /etc/ssl/certs/java/cacerts $JAVA_HOME/lib/security/cacerts

    Amazon Corretto JVM path on DEB

    On Debian/Ubuntu, the Amazon Corretto JVM is usually installed in /usr/lib/jvm/java-11-amazon-corretto.

    • For other JVMs, simply run:
    sudo dpkg-reconfigure ca-certificates

  4. Restart TheHive service.

    sudo systemctl restart thehive

RPM package#

  1. Open the /etc/default/thehive file.

  2. Uncomment the JAVA_OPTS variable.

  3. Enter the path to your truststore file containing the CA certificates.

    JAVA_OPTS="-Djavax.net.ssl.trustStore=/path/to/<truststore_file> -Djavax.net.ssl.trustStorePassword=<truststore_password>"

  4. Save your modifications.

  5. Restart TheHive service.

    sudo systemctl restart thehive

  1. Copy the CA certificate to the system trust anchors.

    sudo cp <custom_certificate>.crt /etc/pki/ca-trust/source/anchors/

  2. Update CA trust.

    • When using the Amazon Corretto JVM, the default truststore is a bundled file rather than a symlink to the system truststore. System CA certificates won't be recognized until you manually replace the bundled truststore with a symlink:
    sudo rm $JAVA_HOME/lib/security/cacerts
sudo ln -s /etc/pki/java/cacerts $JAVA_HOME/lib/security/cacerts

    Amazon Corretto JVM path on RPM

    On RHEL/Fedora, the Amazon Corretto JVM is usually installed in /usr/lib/jvm/java-11-amazon-corretto.

    • For other JVMs, simply run:
    sudo update-ca-trust

  3. Restart TheHive service.

    sudo systemctl restart thehive

Docker environment#

  1. Place your truststore file on the host.

  2. Mount it inside the container and pass JVM options.

    docker run -d \
  --name <thehive_container> \
  -e "JAVA_OPTS=-Djavax.net.ssl.trustStore=/container/path/to/<truststore_file> -Djavax.net.ssl.trustStorePassword=<truststore_password>" \
  -v /host/path/to/<truststore_file>:/container/path/to/<truststore_file> \
  <thehive_image>

  3. Restart TheHive Docker container.

    docker restart <thehive_container>

Starting with TheHive 5.5.4, you no longer need to build or maintain a custom truststore. You can directly mount PEM-format CA certificates, and the entrypoint automatically imports them into the JVM truststore at startup.

Incompatible with --no-config

The TH_CACERT_FOLDER and TH_CACERT_STRING environment variables, as well as their CLI equivalents, have no effect when the entrypoint is started with --no-config.

  1. Store your CA certificates in a host directory.

    Multiple certificates are supported. No password is required.

  2. Mount the directory into the container.

    • Mount a directory containing multiple certificates:
    docker run -d \
  --name <thehive_container> \
  -v /host/path/to/<ca_certificates_directory>:/container/path/to/<ca_certificates_directory> \
  -e TH_CACERT_FOLDER=/container/path/to/<ca_certificates_directory> \
  <thehive_image>
    • Mount a single .pem certificate file:
    docker run -d \
  --name <thehive_container> \
  -v /host/path/to/<ca_certificate_file>:/container/path/to/<ca_certificate_file> \
  -e TH_CACERT_STRING=<ca_certificate_file> \
  <thehive_image>

  3. Restart TheHive Docker container.

    docker restart <thehive_container>

Advanced configuration

Most SSL/TLS requirements are handled through JVM-level configuration. For rare cases requiring TheHive-specific SSL/TLS parameters, see SSL/TLS Client Configuration.

Next steps