A Legacy Notes Developer's journey into madness.

Importing an SSL Certificate Authority into the JVM

Devin Olson  May 7 2018 09:45:16 AM

This issue is documented in IBM Technote Importing an SSL Certificate Authority into the JVM



Issue


Java code running on a Domino server (or from within a Notes client) can reach out and pull in information (such as with a REST API, or an HTTP GET) from an outside source.  
Due to the Notes/Domino security model, all of these communications must occur over an encrypted (HTTPS / SSL) channel. Normally this is not a problem, however there are occasions when the Domino JVM does not recognize the Certificate Authority in use at the outside source.  When this happens, the connection handshake fails, and returns an exception similar to:

HTTP JVM: javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.g: No trusted certificate found.

The way to correct this is to import the appropriate Certificate Authority into the cacerts database.

This is NOT to be confused with the "Certificates" view in the Domino Directory -they are entirely different things.  

There are a few things that need to be pointed out about this Technote (reproduced below).  The Notes Client and the Domino Server have different instances of the cacerts database.  Certificate Authority files need to be imported into the appropriate instance, based on from where the code will run (Notes Client vs. Domino Server).  

When importing the certificates, simply importing the top-level certificate may not be enough.  I recommend that you import the intermediate certificates as well, simply to alleviate any headaches.

ALWAYS make a backup of the cacerts database before you start this process.  If you somehow corrupt the file and you have no backup, ALL JVM connections from your Domino server to external sources will fail.  This is a catastrophic event in a production environment.

The filepaths specified in the Technote (and below) are not necessarily correct, and will vary by installation.  Normal (default) installation locations are listed below.  Be advised that the Technote explains to use the Windows version of IKEYMAN.  I have found this in testing to be correct.

Windows
NOTES: C:\Program Files (x86)\IBM\Notes\jvm\bin\IKEYMAN.exe
NOTES: C:\Program Files (x86)\IBM\Notes\jvm\lib\security\cacerts
DOMINO: C:\Program Files (x86)\IBM\Notes\jvm\bin\IKEYMAN.exe
DOMINO: C:\Program Files (x86)\IBM\Notes\jvm\lib\security\cacerts

Linux
NOTES /opt/ibm/notes/90010/linux/jvm/bin/ikeyman  
NOTES /opt/ibm/notes/90010/linux/jvm/lib/security/cacerts  
DOMINO /opt/ibm/domino/notes/90010/linux/jvm/bin/ikeyman  
DOMINO /opt/ibm/domino/notes/90010/linux/jvm/lib/security/cacerts


Technote



Problem


A Java application running on a Domino server connecting over SSL to another server may require having the SSL certificate authority of the other server imported into its JVM.  

Symptom


When a Java application running on a Domino server connects over SSL to another server, but does not have that server's trusted root certificates, an error may occur. One example of such an error is:

HTTP JVM: javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.g: No trusted certificate found

Cause


The trusted root certificates that signed the remote server's SSL certificate must be also be trusted by the Domino server's JVM if a Java application is making an SSL connection.  

Resolving the problem


To add the trusted root certificates to a Domino server JVM follow these steps:

A. Obtain the Certificate to be Imported
Each browser displays certificates in different ways, but they are usually quite similar. On the browser's URL bar, there is usually a zone that you can click on to display SSL certificate information. For example, you may see a padlock in the status bar, and clicking on the padlock opens the certificate information. Once the certificate information is open, click on the "Certification Path" information. There normally will be a way to export each of the signing certificates (trusted roots). Export the certifiers in the "Base-64 encoded X.509 (.CER)" format. The exported file in this format will be an ASCII text file that has "BEGIN CERTIFICATE" and "END CERTIFICATE" lines at the top and bottom. Once you have exported the certificates that signed the remote server's SSL certificate you can then import them into the JVM.
     
B. Import the SSL certifier into the JVM.
If Domino is on a UNIX server, perform these steps on a Windows workstation, and then move the cacerts to the server after the import is completed.

Import the SSL Certificate into the JVM using these steps:
1. Open a command prompt as Administrator and change directory to C:\Lotus\Domino\jvm\bin.  
2. Run the batch file "IKEYMAN.exe" (a Java application will load).
3. Click "Key Database File" then "Open".
4. Browse to C:\Lotus\Domino\jvm\lib\security\cacerts. Note, you will have to view "All Files" to locate cacerts.  
5. Supply the default password of "changeit". Note, consult your administrator if you receive an error pertaining to the password.  
6. Select "Signer Certificates" in the drop-down menu.  
7. Click "Add"  
8. Select "Browse" and locate the .CER file you copied.  
9. Click "OK" and enter a descriptive label.  
10. On the Domino console issue the command "restart task http".