The following describes how to create a Java truststore for the EJBCA Hardware Appliance.

Background

Missing Truststore

If you attempt to establish an outgoing TLS connection from EJBCA running on the EJBCA Hardware Appliance to another system, for example, when using an LDAP Publisher with the StartTLS extension enabled, or when trying to publish to a CT log server, you may get the following error message in the Wildfly log file:

ERROR: Error binding to LDAP server. Connect Error: LDAPException: Could not negotiate a secure connection (91) Connect Error
javax.net.ssl.SSLException: java.lang.RuntimeException: Unexpected error: java.security.InvalidAlgorithmParameterException: the trustAnchors parameter must be non-empty

The reason for this error message is that Hardware Appliance version 3.0 to 3.4.4 shipped without a Java truststore.

Solution

The solution is to create your own Java truststore and add it to the EJBCA Hardware Appliance. You need to access the Hardware appliance over SSH to do this. There is functionality to add and remove trust anchors in WebConf, but they only affect the trust of incoming TLS connections.

Peer connectors are not affected, because a truststore of CAs installed in EJBCA is dynamically created when a pool of TLS connections for a peer connector is created. This means that you will be able to verify server certificates of upstream peers as long as the issuer of the server certificate is present as a CA in EJBCA.

Add Trust for your Internal CA

Even if you already have a Java truststore installed on the Hardware Appliance, you may still want to add additional CA certificates to it, to be able to establish TLS connections to servers secured by your internal PKI.

What is keytool?

Keytool is a utility for managing Java keystores (JKS files). Keytool is part of your Java distribution. If you do not have Java installed on your machine, you can run the keytool commands on the Hardware Appliance instead.

Create Truststore of Publicly Trusted CA Certificates

The following describes how to create a truststore of publicly trusted CA certificates that you can use for a Hardware Appliance that was shipped without a default truststore. This allows you to create outgoing TLS connections to servers on the internet (e.g. to publish to CT logs).

The easiest way to do this is to grab the truststore from an existing installation of Java. The truststore is located in:

 <java-home>/lib/security/cacerts
CODE

For example, on Linux:

/usr/lib/jvm/java-8-openjdk-amd64/jre/lib/security/cacerts
CODE

To inspect the list of CA certificates in this truststore, use the following keytool command:

> keytool -list -keystore <path-to-truststore> -storepass changeit
CODE

Add New CA Certificates

The following describes how to import a new CA certificate (e.g. the CA certificate of your internal root CA) to a truststore. This allows you to create outgoing TLS connections to servers on your intranet.

When adding CA certificates, add only the root CA (self-signed certificate) to the truststore to minimize truststore maintenance.

 To add a new CA certificate to an existing truststore, or create a new truststore from an existing CA certificate, use the following keytool command

> keytool -keystore cacerts -alias <some-alias> -importcert -file <some-certificate.crt> -storepass changeit
[...]
Certificate fingerprints:
	 MD5:  A2:D6:B8:88:46:C7:52:75:26:5F:C4:8F:71:AC:2B:D5
	 SHA1: 10:EE:BA:61:8B:66:49:DC:07:87:AF:7E:F6:B8:87:56:6B:C2:CE:74
	 SHA256: 17:9B:F9:DB:97:7C:67:13:C0:9D:BD:23:E8:83:4F:7E:65:23:84:C2:0C:20:2C:B9:2C:56:EA:C0:F6:69:F4:09
[...]
Trust this certificate? [no]:  yes
Certificate was added to keystore
CODE

The command prints some information about the certificate. Inspect the certificate and enter yes to add it.

Install Truststore on PKI Appliance

This section describes how to transfer a truststore you have created and install it on the EJBCA Hardware Appliance.

The truststore must be installed again after a factory reset of the Hardware Appliance and if you have a cluster of Hardware Appliances you must add the truststore to each node in the cluster (files you add to /etc are not synchronized between the nodes).

  1. Go to the Hardware Appliance WebConf, click Platform > Platform access and select Enable SSH access.
  2. Connect to the Hardware Appliance using, for example, WinSCP (Windows) or SCP (Linux). Connect to the Hardware Appliance using the IP address of the management interface and use the root user to log in. Assuming the IP address of the box is 192.168.31.12, this is what it would look like in WinSCP.
  3. Transfer the cacerts truststore file to the appliance.
  4. Get terminal access to the Hardware Appliance by connecting to it using for example PuTTY (Windows) or SSH (Linux).

  5. Run the following commands to install the cacerts file.

    scp cacerts cos-ejbca:
ssh cos-ejbca
mkdir /etc/ssl/java
mv cacerts /etc/ssl/java/cacerts
reboot
    CODE
  6. Wait for a minute until cos-ejbca has rebooted. This is usually quick (only a part of the Hardware Appliance is rebooting, not the whole machine).