Configuring Luna HSM Software on AIX

We’re using a Luna HSM with Tomcat running on IBM AIX to sign PDFs in a web application. There were a few extra steps required to get the Luna software working with Java that the setup instructions did not mention, so I’m documenting them here.

The LunaSA software installed to /usr/lunasa. The Java Security Provider API for the Luna includes three files, which are found in /usr/lunasa/jsp/lib. They are libLunaAPI.so, the native (C++ I presume) library for accessing the Luna; and LunaJCASP.jar and LunaJCESP.jar, which are the security providers for Java.

First, we verified that we had a randomness generator configured in the right directory, as described by the Luna setup instructions. Then we installed the software. Next we configured a trust relationship between the Luna and our server by exchanging certificates, as per instructions.

The additional steps were setting some environment variables for the user account that Tomcat runs with:

JAVA_OPTS should include -Djava.library.path=/usr/lunasa/jsp/lib/. Putting the Luna library directory on java.library.path makes the native libLunaAPI.so library available to the Java Native Interface. If it is not there, any application trying to use the Luna API will throw an ”UnsatisfiedLinkException”.

LIBPATH should be set and should include /usr/lunasa/jsp/lib/. This is another way of getting the native Luna API library on java.library.path. It may not be necessary if the path is set in JAVA_OPTS.

CLASSPATH should be set and should include /usr/lunasa/jsp/lib/LunaJCASP.jar and /usr/lunasa/jsp/lib/LunaJCESP.jar. Contrary to our expectations, just having the jar files in the /lib folder of our war file didn’t seem to make the jar files available to our web app. Adding them to the Tomcat user’s classpath made everything work.

We are using the 64-bit Luna software with IBM Java 6, 64-bit.

Advertisement