How do I manage certificates in the Java keystore? (Plus using certtool)

Introduction

Use of certificates with Entuity

To get certificates into Entuity

To implement LDAPS on Entuity

When patching and upgrading

Actions allowed with certtool

Introduction:

The certtool utility in Entuity stops the default Java keystore and the certificates within it (entuity_home/install/JRE/lib/security/cacerts) from being lost when the JRE is upgraded in a patch or upgrade. The certtool utility creates a second store that is not deleted by JRE upgrades. Running configure after a patch or upgrade will automatically merge back in the certificates into the new version of Entuity.

certtool must be used alongside keytool when patching and upgrading:

1. use keytool to export existing certificates before patching Entuity.
2. use certtool to reimport the certificates into the new version of Entuity.

Entuity recommends that you always use certtool when required to import certificates for LDAP integrations (and RESTful API integrations that are called via Groovy scripts). certtool is only used to import certificates for LDAP authentication and when an SSL connection is required for TSOM integration. It is not required for SSL client connections to the Entuity web server.

Use of certificates with Entuity:

Certificates are widely used to pass trust between various applications. In Java, the JRE manages a set of certificates - in Entuity, these are installed in entuity_home/install/JRE/lib/cacerts.

For Entuity users, the core use cases are:

• LDAP over SSL (LDAPs)
• Server-based monitoring (CE)
• Virtualization
• Web application use 
• SSO (for example, Okta)
• RESTful API integrations over HTTPS that are called with Groovy scripts
  • Note, might require importing certificates, if using internal CA certificates. 

With LDAP over SSL (LDAPs), Entuity is expected to 'share trust' with an external application without requiring that the user enters a password. The certificate is necessary to ensure the Entuity server can verify that a given token supplied by the user's browser is generated by a system that can be trusted.

The certificates need to be exported by the LDAP/SSO administrator and copied onto the Entuity server. This is a manual process.

To get certificates into Entuity:

Use certtool to import your certificates into Entuity because it will ensure that certificates are imported into both the Entuity trust store and the default JRE trust store.

To implement LDAPS on Entuity:

1. Export your certificate file from the LDAP server.
2. Copy the certificate file onto the Entuity server.
3. Run certtool.
4. Verify that certtool has added the cert to both keystores.
5. In the Entuity web UI, log in as an admin user, and go to Main Menu, Administration, and then click Account Management.
6. In the LDAP section, add a new LDAP server. 
   You will need to map at least one LDAP user (or group) to be in the Administrators' group. 
7. Once you have specified the parameters, click Apply LDAP Settings.
   The system will run a test connection to the LDAP server, and, if successful, will restart the Entuity server.
8. Refresh the page.
9. Log in using a valid LDAP username/password.

Note: when configured for external authentication with LDAPs, ENA v18.0 upwards enforces hostname verification between certificates and the LDAP server. If your LDAP TLS certificates are non-compliant with hostname verification, then the LDAPs integrations will stop working after installing ENA v18.0.

Entuity recommends that users plan for new certificates before upgrading to ENA v18.0. If you are unable to rebuild certificates, Entuity recommends that you contact Entuity Support for details on how to handle non-compliant certifications.

When patching and upgrading:

When running ENA v17.0 and above:

1. Upon patching, configure will merge your existing keys from the /etc/entuity_cacerts keystore into the new Java keystore without any user intervention.

When upgrading from an earlier version of Entuity to ENA v17.0:

1. Export your keys using keytool.
2. Upgrade and configure.
3. Re-import your keys, using certtool instead of keytool.
4. Restart Tomcat.

Actions allowed with certtool:

Usage: certtool <actions>, where allowed actions are:

-import -file <certificate file> -alias <certificate alias> [-entuityStorePass <password>] [-defaultStorePass <password>]

1. Import the certificate file to both the Entuity trust store and the default JRE trust store. The Entuity trust store is located at entuity_home/etc/entuity_cacerts. The default JRE trust store is located at entuity_home/install/JRE/lib/security/cacerts.
2. Specify an alias that is unique in both trust stores. The prefix entuity_ will be added to the alias. Passwords are optional - if missing, then the default password changeit will be used for both stores.

-delete -alias <certificate alias> [-entuityStorePass <password>] [-defaultStorePass <password>]

1. Delete a certificate by its alias from both the Entuity trust store and the default JRE trust store. The specified alias must not contain the prefix entuity_. Passwords are optional - if missing, then the default password changeit will be used for both stores.

-merge

1. Merge the default JRE trust store with the Entuity trust store (which will run every time that configure runs).
   • If the Entuity trust store does not exist, then exit immediately.
   • If all certificates in the Entuity trust store already exist in the default JRE trust store, then do nothing.
2. Otherwise, the Entuity trust store will be merged into the default JRE trust store, and the default JRE trust strore's password will be reset.