Installing and configuring the Luna HSM client

Install and configure the Luna HSM client on the same machine on which the eperi eperi sEcure Platform is installed. Alternatively, you can also add it to a Docker container as described here: Installing Luna Minimal Client on Linux Using Docker. The eperi sEcure Platform uses the client to access the Luna HSM.

1. Install the Luna HSM client as described in the manual provided by the manufacturer.

   Part of this installation will be the Java JCE provider and it’s JNI part which can be found at:

   • /usr/safenet/lunaclient/jsp/lib/libLunaAPI.so
   • /usr/safenet/lunaclient/jsp/lib/LunaProvider.jar
2. Register the path to the above libraries as follows:
   1. Edit the file /opt/eperi/gateway/tomcat/conf/javaopts.
   2. Add the following path info at the end of the first line:

      -Djava.library.path=$PATH:/usr/safenet/lunaclient/jsp/lib/

      E.g. if the first line contains the following:

      -Xmx1024m -XX:MaxPermSize=128m

      Modify it as follows:

      -Xmx1024m -XX:MaxPermSize=128m -Djava.library.path=$PATH:/usr/safenet/lunaclient/jsp/lib/

   3. Save the javaopts file.
3. Make sure that the following directories and their contents all belong to the group hsmusers:

   /usr/safenet/lunaclient/cert
   /usr/safenet/lunaclient/cert/server
   /usr/safenet/lunaclient/bin
   /usr/safenet/lunaclient/lib
   /usr/safenet/lunaclient/jsp
   /usr/safenet/lunaclient/jsp/lib
   /etc/Chrystoki.conf

4. Add the eperi user to the hsmusers group:

   sudo gpasswd --add eperi hsmusers

   Note: In case of insufficient permissions the eperi sEcure Platform will not be able to connect to the Luna HSM properly which will result in the following error:

   java.io.IOException: function 'CrystokiConnect failed' returns 0x0

5. Copy the Luna Chrystoki library file to the folder JAVA_HOME/jre/lib.
   Note: Please check the manufacturer's manual to find out which library to use for your operating system.
6. Copy the LunaProvider.jar file to the folder /opt/eperi/gateway/tomcat/webapps/ROOT/WEB-INF/lib.
7. Optional: To facilitate troubleshooting, you could switch on logging by adding the following entry to the /etc/Chrystoki.conf (Linux) or C:\Program Files\SafeNet\LunaClient\crystoki.ini (Windows):

   For Linux:

   Chrystoki2 = {
      LibUNIX=/usr/lib/libcklog2.so;
   }
   CkLog2 = {
      LibUNIX=/usr/lib/libCryptoki2.so;
      Enabled=1;
      File=/tmp/cklog.txt;
      Error=/tmp/error.txt;
      NewFormat=1;
      LoggingMask=ALL_FUNC;
   } 

   For Windows:

   [Chrystoki2]
   LibNT=c:\Program Files\SafeNet\LunaClient\cklog201.dll
   [CkLog2]
   LibNT=c:\Program Files\SafeNet\LunaClient\cryptoki.dll
   Enabled=1
   File=c:\Program Files\SafeNet\LunaClient\cklog2.txt
   Error=c:\Program Files\SafeNet\LunaClient\error2.txt
   NewFormat=1
   LoggingMask=ALL_FUNC

   CAUTION: Never insert TAB characters into the crystoki.ini (Windows) or crystoki.conf (Linux) file!
8. Restart the eperi sEcure Platform by executing the following command:

   sudo systemctl restart eperi-gateway

   Important: In a cluster setup, the changes must be made on every eperi sEcure Platform instance and each eperi sEcure Platform instance must be restarted.