Configure trusted root certificates on ActiveGate

ActiveGate connects to third-party systems like VMware, Cloud Foundry, and cloud infrastructures using SSL-secured channels. The root CA certificate store shipped with Java is sometimes insufficient to cover all required use cases. The solution is to provide a customized list of trusted root certificates.

You can choose from one of two options:

You can use a set of Java system properties to indicate a single place for your trusted store that won't be overwritten with the next ActiveGate update.
You can provide your own certificates, and ActiveGate will combine them with the defaults.

Java trusted store configuration

By default, Java looks for trusted certificates in three locations:

The location defined by the javax.net.ssl.trustStore system property.
Two files in the java-home/lib/security/ directory:
- The jssecacerts file (initially, this file is absent).
- The cacerts file (by default, shipped with Java).

The ActiveGate installer replaces the Java directory with every update. As a result, any modifications to the jssecacerts or cacerts files will be overwritten. To preserve a customized list of trusted root certificates in Java, use the javax.net.ssl.trustStore system property in the launcheruserconfig.conf file. The launcheruserconfig.conf file is preserved during ActiveGate updates.

To modify the root CA certificate store in Java so that it's preserved during ActiveGate updates

Copy the cacerts file to a location outside the /opt/desk directory.

Edit the launcheruserconfig.conf file located in:

Linux: /var/lib/desk/gateway/config/
Windows: C:\ProgramData\desk\gateway\config

Define javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword to specify the root certificate file location and its password using a set of Java system properties with the -D option after -vmargs.

For example:

-vmargs
-Djavax.net.ssl.trustStore=/etc/MyJavaStore/cacerts
-Djavax.net.ssl.trustStorePassword=changeit

Create PKCS12 or JKS trusted file from CA certificate

Java can use PKCS12 certificate files created using the Java keytool utility but not certificate files created with OpenSSL. You can create a PKCS12 or JKS trusted file from CA certificate. Execute the following command on either Linux or Windows (depending on your installation).

To create a PKCS12 trusted file from CA certificate:

keytool -import -noprompt -alias myCertAuthority -keystore mytrust.p12 -storetype pkcs12 -file CA.crt

To create a JKS trusted file from CA certificate:

keytool -import -noprompt -alias myCertAuthority -keystore mytrust.jks -storetype jks -file CA.crt

ActiveGate custom trusted store configuration

This feature is only available with ActiveGate version 1.169+.

The custom Java configuration requires the system administrator to keep all root CAs up to date. An alternative solution is to merge root CA certificates provided with the Java installation with a list of root CA certificates managed by your organization. This can be configured in ActiveGate by configuring a custom trust store file.

Configuring custom trust store file

To configure ActiveGate to use a custom trust store file

Copy the trusted.jks file to the SSL directory.

Add the following entries to the config/custom.properties file:

[collector]
trustedstore = trusted.jks
# the following entries are optional
trustedstore-password = changeit
trustedstore-type = JKS

Troubleshooting

ActiveGate always logs its actions related to the above configuration. The configured trust store won't be used (and the trust store configuration will be left unchanged) if any of the following is true:

The javax.net.ssl.trustStore system property is specified.
If this property is specified, it takes precedence over the ActiveGate configuration.
The configured trust store can't be read using the configured path, password, and type.
The java-home/lib/security/cacerts file can't be read using the default password changeit.
The merged configuration can't be written to the ssl/runtime.cacerts file.