Domino, Java Agents, TLS 1.2: a how to

Due to a payment gateway vendor requiring TLS 1.2 on all transactions starting May 1st, we had a client who needed to get their Domino code to achieve it.  This post explains how that was achieved.

From a web server perspective, Domino has been able to do TLS 1.2 for awhile. User connects with a browser, protocol negotiation occurs, conversation can happen at TLS 1.2. No big deal.

However, if there is server to server communication from a Java agent, Domino has not been capable of performing TLS 1.2 until fairly recently.  The reason: TLS 1.2 requires Java 1.8.  Domino did not support Java 1.8 in any fashion prior to Fix Pack 8. Here’s a bullet list of the requirements for getting the right environment for TLS 1.2 capability:

• Upgrade Domino server to 9.01 FP 10 so that it runs Java 1.8 code. But wait, you say, Domino could run 1.8 code starting with FP8.  This is true. In real world for this situation though, it is not sufficient. More on this below.
• Upgrade a Designer client to 9.01 FP 10 so that it’s capable of COMPILING 1.8 code.  So one would think you simply need a Designer client at FP 10 and a server at FP 8 to meet the requirements for 1.8 capability. This did NOT work.  Note the following:

The JVM in Designer is Upgraded to use 1.8 at compile time
With this new upgrade, you can launch Designer client and leverage Java 1.8 compile time features in building applications. For full compatibility, apps compiled in FP10 should be deployed on Notes or Domino FP10 and higher. Java apps may run on Notes/Domino 9.0.1 FP8 and higher as that release upgrade to Java 1.8 runtime. However, Application best practice is to compile with the lowest common denominator to the client/server version deployed.

That’s from the IBM fix list notes: http://www-10.lotus.com/ldd/fixlist.nsf/WhatsNew/86a6c4ba892f0218852581fc0067b4f4?OpenDocument, and as it turns out, WAS necessary to get things working.

• • Upgrading the Designer client to FP10 (as of 4/18/2018 through the writing of this post) is BROKEN. During the installation process, there are expired IBM certificates in the installer.  It will not install.  To overcome this, set the operating system date prior to 4/19, and if you’re doing that in a VM, check your VM settings and turn-off the automatic clock sync to host operating system (or it will just reset during the middle of your installation).  Remember to reset the OS date correctly BEFORE restarting Notes client or you may encounter some bad replication activity as it gets confused by your bad date. See http://www-01.ibm.com/support/docview.wss?uid=swg21657963.

• If Java code in question is using HttpsURLConnection class, add a new text file and .ini variable to the server notes.ini to force TLS 1.2 conversations, otherwise your code won’t work, period. See: https://www-01.ibm.com/support/docview.wss?uid=swg21985289
• Of course, if you’re doing Java agents that have conversations over HTTP(S), you’ve already encountered the requirement to update the java security policy file on the server.  Remember that this file gets blown away when you do Domino server upgrades and you’ll need to reapply the changes you’d made to it.  Also, if you had put .jar files in the jvm/lib/ext directory (a fairly common practice for these kinds of agents), you’ll need to make sure and put those .jar files back in place as it’s likely they’ve been removed as well during server upgrade.

There you go, happy TLS 1.2 server Java agenting 🙂