Apache Tomcat INTEGRATION GUIDE SAFENET LUNA HSM

Document Information

Document Part Number 007-000637-001

Release Date 4 March 2020

Revision History

Revision Date Reason

A 4 March 2020 New

Trademarks, Copyrights, and Third-Party Software © 2020 Gemalto. All rights reserved. Gemalto and the Gemalto logo are trademarks and service marks of Gemalto N.V. and/or its subsidiaries and are registered in certain countries. All other trademarks and service marks, whether registered or not in specific countries, are the property of their respective owners.

Disclaimer All information herein is either public information or is the property of and owned solely by Gemalto NV. and/or its subsidiaries who shall have and keep the sole right to file patent applications or any other kind of intellectual property protection in connection with such information. Nothing herein shall be construed as implying or granting to you any rights, by license, grant or otherwise, under any intellectual and/or industrial property rights of or concerning any of Gemalto’s information. This document can be used for informational, non-commercial, internal and personal use only provided that:  The copyright notice below, the confidentiality and proprietary legend and this full warning notice appear in all copies.  This document shall not be posted on any network computer or broadcast in any media and no modification of any part of this document shall be made. Use for any other purpose is expressly prohibited and may result in severe civil and criminal liabilities. The information contained in this document is provided “AS IS” without any warranty of any kind. Unless otherwise expressly agreed in writing, Gemalto makes no warranty as to the value or accuracy of information contained herein. The document could include technical inaccuracies or typographical errors. Changes are periodically added to the information herein. Furthermore, Gemalto reserves the right to make any change or improvement in the specifications data, information, and the like described herein, at any time. Gemalto hereby disclaims all warranties and conditions with regard to the information contained herein, including all implied warranties of merchantability, fitness for a particular purpose, title and non- infringement. In no event shall Gemalto be liable, whether in contract, tort or otherwise, for any indirect, special or consequential damages or any damages whatsoever including but not limited to damages

resulting from loss of use, data, profits, revenues, or customers, arising out of or in connection with the use or performance of information contained in this document. Gemalto does not and shall not warrant that this product will be resistant to all possible attacks and shall not incur, and disclaims, any liability in this respect. Even if each product is compliant with current security standards in force on the date of their design, security mechanisms' resistance necessarily evolves according to the state of the art in security and notably under the emergence of new attacks. Under no circumstances, shall Gemalto be held liable for any third party actions and in particular in case of any successful attack against systems or equipment incorporating Gemalto products. Gemalto disclaims any liability with respect to security for direct, indirect, incidental or consequential damages that result from any use of its products. It is further stressed that independent testing and verification by the person using the product is particularly encouraged, especially in any application in which defective, incorrect or insecure functioning could result in damage to persons or property, denial of service or loss of privacy.

Contents

CONTENTS

PREFACE...... 5 Audience ...... 5 Document Conventions ...... 5 Notifications ...... 5 Command Syntax and Typeface Conventions ...... 6 Support Contacts ...... 7 Customer Support Portal ...... 7 Telephone Support ...... 7 Email Support ...... 7

CHAPTER 1: Introduction...... 8 About Apache Tomcat...... 8 Third Party Application Details ...... 8 Supported Platforms ...... 8 Prerequisites ...... 9 Configuring the SafeNet Luna HSM ...... 9 Install Java Development Kit ...... 11 Setting up Apache Tomcat ...... 11

CHAPTER 2: Integrating Apache Tomcat with SafeNet Luna HSM ...... 12 Integrating Apache Tomcat by Generating New SSL Certificate and Key on SafeNet Luna HSM ...... 12 Configuring Java for SafeNet Luna HSM ...... 12 Generating Key Materials on SafeNet Luna HSM ...... 13 Configuring SSL for the Apache Tomcat ...... 14 Integrating Apache Tomcat by Migrating Existing SSL Certificate and Key to SafeNet Luna HSM ...... 16 Configuring Java for SafeNet Luna HSM ...... 16 Migrating Key Materials from JKS to Luna Keystore ...... 16 Re-Configuring SSL for the Apache Tomcat ...... 17

Preface

PREFACE

This guide is intended to provide instructions for setting up a small test lab that has Apache Tomcat running with SafeNet Luna HSM to secure the SSL private keys and certificates. The guide explains how to install and configure software required for setting up an Apache Tomcat while storing SSL private keys and certificates on SafeNet Luna HSM.

Audience This document is intended to guide administrators through the steps of supporting Apache Tomcat with SafeNet HSMs, including installation, configuration, and integration. All products manufactured and distributed by Gemalto, Inc. are designed to be installed, operated, and maintained by personnel who have the knowledge, training, and qualifications required to safely perform the tasks assigned to them. The information, processes, and procedures contained in this document are intended for use by trained and qualified personnel only.

Document Conventions This section provides information on the conventions used in this document.

Notifications This template uses notes, cautions, and warnings to alert you to important information that may help you to complete your task, or prevent personal injury, damage to the equipment, or data loss.

Notes Notes are used to alert you to important or helpful information.

NOTE: Take note. Notes contain important or helpful information.

Cautions Cautions are used to alert you to important information that may help prevent unexpected results or data loss.

CAUTION! Exercise caution. Caution alerts contain important information that may help prevent unexpected results or data loss.

Warnings Warnings are used to alert you to the potential for catastrophic data loss or personal injury.

Preface

**WARNING** Be extremely careful and obey all safety and security measures. In this situation you might do something that could result in catastrophic data loss or personal injury

Command Syntax and Typeface Conventions

Convention Description

Bold The bold attribute is used to indicate the following:  Command-line commands and options (Type dir /p.)  Button names (Click Save As.)  Check box and radio button names (Select the Print Duplex check box.)  Window titles (On the Protect Document window, click Yes.)  Field names (User Name: Enter the name of the user.)  Menu names (On the File menu, click Save.) (Click Menu > Go To > Folders.)  User input (In the Date box, type April 1.)

Italic The italic attribute is used for emphasis or to indicate a related document. (See the Installation Guide for more information.)

Double quote marks Double quote marks enclose references to other sections within the document.

In command descriptions, angle brackets represent variables. You must substitute a value for command line arguments that are enclosed in angle brackets.

[ optional ] Square brackets enclose optional keywords or in a command line [ ] description. Optionally enter the keyword or that is enclosed in square brackets, if it is necessary or desirable to complete the task.

Square brackets enclose optional alternate keywords or variables in a command [ a | b | c ] line description. Choose one command line argument enclosed within the braces, [ | | ] if desired. Choices are separated by vertical (OR) bars.

{ a | b | c } Braces enclose required alternate keywords or in a command line { | | } description. You must choose one command line argument enclosed within the braces. Choices are separated by vertical (OR) bars.

Preface

Support Contacts If you encounter a problem while installing, registering, or operating this product, refer to the documentation. If you cannot resolve the issue, contact your supplier or Gemalto Customer Support. Gemalto Customer Support operates 24 hours a day, 7 days a week. Your level of access to this service is governed by the support plan arrangements made between Gemalto and your organization. Please consult this support plan for further information about your entitlements, including the hours when telephone support is available to you.

Customer Support Portal The Customer Support Portal, at https://supportportal.thalesgroup.com, is a repository where you can find solutions for most common problems. The Customer Support Portal is a comprehensive, fully searchable database of support resources, including software and firmware downloads, release notes listing known problems and workarounds, a knowledge base, FAQs, product documentation, technical notes, and more. You can also use the portal to create and manage support cases.

NOTE: You require an account to access the Customer Support Portal. To create a new account, go to the portal and click on the REGISTER link.

Telephone Support If you have an urgent problem, or cannot access the Customer Support Portal, you can contact Gemalto Customer Support by telephone at +1 410-931-7520. Additional local telephone support numbers are listed on the support portal.

Email Support You can also contact technical support by email at [email protected].

CHAPTER 1: Introduction

This document provides the necessary information to install, configure, and integrate Apache Tomcat with SafeNet HSMs. The integration between SafeNet HSMs and Apache Tomcat uses the Java JCE/JCA interface to generate the SSL keys on SafeNet HSMs. SafeNet HSMs integrate with Apache Tomcat to generate 2048 bit RSA key pairs for SSL and provide security by protecting the private keys and certificate within a FIPS 140-2 certified hardware security module. The benefits of using SafeNet HSMs to generate the SSL keys for Apache Tomcat include the following:  Secure generation, storage, and protection of the SSL keys on FIPS 140-2 level 3 validated hardware.  Full life cycle management of the keys.  HSM audit trail.  Significant performance improvements by off-loading cryptographic operations from servers. About Apache Tomcat The Apache Tomcat software is an open source implementation of the Java Servlet, JavaServer Pages, Java Expression Language and Java WebSocket technologies. The Java Servlet, JavaServer Pages, Java Expression Language and Java WebSocket specifications are developed under the Java Community Process. The Apache Tomcat software is developed in an open and participatory environment and released under the Apache License version 2. The Apache Tomcat project is intended to be a collaboration of the best-of-breed developers from around the world. Apache Tomcat software powers numerous large-scale, mission-critical web applications across a diverse range of industries and organizations. Apache Tomcat provides a "pure Java" HTTP web server environment in which Java code can run. The SafeNet HSM solution for Apache Tomcat provides secure key management as well as SSL acceleration and provides extra security by protecting and managing the server’s SSL private key within a FIPS 140-2 certified hardware security module.

Third Party Application Details This integration uses the following third party applications:  Apache Tomcat

Supported Platforms List of the platforms which are tested with the following HSMs: SafeNet Luna HSM: SafeNet Luna HSM appliances are purposefully designed to provide a balance of security, high performance, and usability that makes them an ideal choice for enterprise, financial, and government organizations. SafeNet Luna HSMs physically and logically secure cryptographic keys and accelerate cryptographic processing.

CHAPTER 1: Introduction

The SafeNet Luna HSM on premise offerings include the SafeNet Luna Network HSM, SafeNet PCIe HSM, and SafeNet Luna USB HSMs. SafeNet Luna HSMs are also available for access as an offering from cloud service providers such as IBM cloud HSM and AWS cloud HSM classic. The following platforms are supported for Apache Tomcat:

Apache Tomcat Java Platforms

Apache Tomcat/9.0.31 Open JDK 8 Red Hat Enterprise Linux 7

Apache Tomcat/8.5.51 Oracle JDK 8 Windows Server 2016 Datacenter

Apache Tomcat/8.5.40 Open JDK 8 Red Hat Enterprise Linux 7

Apache Tomcat/8.5.40 Oracle JDK 8 Windows Server 2016 Datacenter

Prerequisites Before you proceed with the integration, complete the following processes:

Configuring the SafeNet Luna HSM SafeNet Luna HSMs provide strong physical protection of secure assets, including keys, and should be considered a best practice when building systems based on Apache Tomcat.

To configure the SafeNet Luna HSM Ensure that the HSM is set up, initialized, provisioned and ready for deployment. Refer to the HSM product documentation for help. Create a partition that will be later used by Apache Tomcat. Create and exchange certificate between the SafeNet Network HSM and Client system. Register client and assign partition to create an NTLS connection. Initialize Crypto Officer and Crypto User roles for the registered partition. Ensure that the partition is successfully registered and configured. The command to see the registered partitions is: C:\Program Files\SafeNet\LunaClient>lunacm.exe lunacm.exe (64-bit) v10.1.0-32. Copyright (c) 2019 SafeNet. All rights reserved.

Available HSMs: Slot Id -> 0 Label -> apache_par1 Serial Number -> 1238696045103

CHAPTER 1: Introduction

Model -> LunaSA 7.4.0 Firmware Version -> 7.4.1 Configuration -> Luna User Partition With SO (PW) Key Export with Cloning Mode Slot Description -> Net Token Slot FM HW Status -> FM Ready Current Slot Id: 0 For PED-authenticated HSM, enable partition policies 22 and 23 to allow activation and auto-activation.

NOTE: Follow the SafeNet Network Luna HSM documentation for detailed steps for creating NTLS connection, initializing the partitions, and various user roles.

Controlling User Access to the HSM By default, only the root user has access to the HSM. You can specify a set of non-root users that are permitted to access the HSM, by adding them to the hsmusers group. The client software installation automatically creates the hsmusers group. The hsmusers group is retained when you uninstall the client software, allowing you to upgrade the software while retaining your hsmusers group configuration.

Adding a user to hsmusers group To allow non-root users or applications access to the HSM, assign the user to the hsmusers group. The users you assign to the hsmusers group must exist on the client workstation. Ensure that you have sudo privileges on the client workstation. Add a user to the hsmusers group. sudo gpasswd --add hsmusers Where is the name of the user you want to add to the hsmusers group.

Removing a user from hsmusers group Ensure that you have sudo privileges on the client workstation. Remove a user from the hsmusers group. sudo gpasswd -d hsmusers Where is the name of the user you want to remove from the hsmusers group. You must log in again to see the change.

NOTE: The user you delete will continue to have access to the HSM until you reboot the client workstation.

Configuring SafeNet Luna HSM HA (High-Availability) Please refer to the SafeNet Luna HSM documentation for HA steps and details regarding configuring and setting up two or more HSM appliances on Windows and UNIX systems. You must enable the HAOnly setting in HA for failover to work so that if primary stop functioning for some reason, all calls automatically routed to secondary till primary starts functioning again.

CHAPTER 1: Introduction

NOTE: This integration is tested in both HA and FIPS mode.

Install Java Development Kit Ensure that the Java Development Kit (JDK) is installed on your system. You can run the commands in this instruction wherever you have the keytool command available.

Setting up Apache Tomcat You need to install Apache Tomcat on the target machines. For a detailed installation procedure, refer to http://tomcat.apache.org/

NOTE: Compatible JDK version must be installed on the system before installing Apache Tomcat. For details, please refer the Apache Tomcat documentation.

After installation ensure that Apache Tomcat is running successfully by accessing the URL: https://:8080/

CHAPTER 2: Integrating Apache Tomcat with SafeNet Luna HSM

Integration of Apache Tomcat with SafeNet Luna HSM involves the following use cases:  Integrating Apache Tomcat by Generating New SSL Certificate and Key on SafeNet Luna HSM  Integrating Apache Tomcat by Migrating Existing SSL Certificate and Key to SafeNet Luna HSM Integrating Apache Tomcat by Generating New SSL Certificate and Key on SafeNet Luna HSM Integrating Apache Tomcat with SafeNet Luna HSM by generating new SSL certificate and key involves following steps:  Configuring Java for SafeNet Luna HSM  Generating Key Materials on SafeNet Luna HSM  Configuring SSL for Apache Tomcat

Configuring Java for SafeNet Luna HSM Apache Tomcat uses Java JSSE for SSL/TLS support. Configure Java to add support for Luna Provider that will be consumed by Apache Tomcat for securing the SSL keys and certificates on SafeNet Luna HSM.

To configure Luna Provider in Java Log on to Apache Tomcat server as root or as another user having administrative privileges. Ensure that JAVA_HOME and PATH variables are set. If not, set JAVA_HOME and PATH variables. # export JAVA_HOME= # export PATH=$JAVA_HOME/bin:$PATH

NOTE: For Windows, set the JAVA_HOME and PATH System variables under System> Advanced system settings> Environment Variables…

Edit the Java Security Configuration file java.security located in the directory /jre/lib/security and add the Luna Provider to the java.security file as below: Example: security.provider.1=sun.security.provider.Sun security.provider.2=sun.security.rsa.SunRsaSign security.provider.3=sun.security.ec.SunEC security.provider.4=com.sun.net.ssl.internal.ssl.Provider security.provider.5=com.sun.crypto.provider.SunJCE

CHAPTER 2: Integrating Apache Tomcat with SafeNet Luna HSM

security.provider.6=com.safenetinc.luna.provider.LunaProvider security.provider.7=sun.security.jgss.SunProvider security.provider.8=com.sun.security.sasl.Provider security.provider.9=org.jcp.xml.dsig.internal.dom.XMLDSigRI security.provider.10=sun.security.smartcardio.SunPCSC security.provider.11=sun.security.mscapi.SunMSCAPI Copy the LunaAPI.dll (Windows) or libLunaAPI.so (UNIX) and LunaProvider.jar file from the /jsp/lib folder to the /jre/lib/ext directory.

Generating Key Materials on SafeNet Luna HSM When Java is configured to use Luna Provider, we can create the keys and certificate in the keystore pointing to SafeNet Luna HSM partition.

To Create Keys and Certificate in Luna HSM Create a keystore config file named lunastore and add the following entry where would be your Luna HSM partition label: tokenlabel: Save the file, preferably in the /conf directory. Generate a key pair in the keystore using the Java keytool utility. The key pair will be generated on the registered partition of SafeNet Luna HSM. keytool -genkeypair -alias -keyalg -keysize -sigalg -keypass -keystore -storepass -storetype For Example: keytool -genkeypair -alias lunakey -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -keypass userpin1 -keystore lunastore -storepass userpin1 - storetype luna Enter the details to generate key and certificate in the SafeNet Luna HSM and keystore in the current directory.

CHAPTER 2: Integrating Apache Tomcat with SafeNet Luna HSM

To display the generated key materials, use the following command: keytool -list -v -storetype luna -keystore lunastore

Generate a certificate request from a key in the keystore. The system will prompt you for the keystore password. # keytool -certreq -alias lunakey -sigalg SHA256withRSA -file certreq_file - storetype luna -keystore lunastore Enter the keystore password, when prompted. File certreq_file will be generated in the current directory. Submit the CSR file to your Certification Authority (CA). The CA will authenticate the request and return a signed certificate or a certificate chain. Save the reply and the root certificate of the CA in the current working directory. Import the CA’s Root certificate and signed certificate or certificate chain in to the keystore. To import the CA root certificate, execute the following: # keytool -trustcacerts -importcert -alias rootca -file root.cer -keystore lunastore -storetype luna

To import the signed certificate reply or certificate chain, execute the following: # keytool -trustcacerts -importcert -alias lunakey -file certchain.p7b - keystore lunastore -storetype luna

Here, root.cer and certchain.p7b are the CA Root Certificate and Signed Certificate Chain, respectively.

Configuring SSL for the Apache Tomcat Apache Tomcat server uses the SSL key and certificate stored in the keystore for SSL communication. Apache Tomcat uses server.xml file available in /conf to define connector setting for SSL.

To configure SSL for Apache Tomcat Stop the server, if running. Run the shutdown.bat or shutdown.sh script provided under bin folder of .

CHAPTER 2: Integrating Apache Tomcat with SafeNet Luna HSM

Edit the server.xml file of Tomcat server and add the following. You can uncomment the existing Connector and update it as explained below, or you can add the below snippet in entirety without uncommenting the existing one. Save and close the server.xml file. Ensure that the keystore settings values are correct as per your environment. Now start the Tomcat server using the batch file startup.bat or startup.sh under bin directory of . If the Tomcat starts successfully, you should be able to see the default page of Tomcat on the browser using https and port 8443. The SSL certificate will be the same that you generated and stored in Luna Keystore. https://:8443/

This completes the Apache Tomcat integration with SafeNet Luna HSM and SSL certificate private key is secured on HSM partition. The SSL page will be accessible only if HSM partition is accessible and available to Apache Tomcat Server.

CHAPTER 2: Integrating Apache Tomcat with SafeNet Luna HSM

Integrating Apache Tomcat by Migrating Existing SSL Certificate and Key to SafeNet Luna HSM Integrating Apache Tomcat by migrating an existing SSL certificate and key on SafeNet Luna HSM includes the following:  Configuring Java for SafeNet Luna HSM  Migrating Key Materials from JKS to Luna Keystore  Re-Configuring SSL for the Apache Tomcat Before proceeding, it is assumed that you have installed Apache Tomcat and have configured the SSL using the key and certificate available on Java Keystore.

Configuring Java for SafeNet Luna HSM To configure Java for Apache Tomcat for securing the SSL keys and certificates on SafeNet Luna HSM, refer the “Configuring Java for SafeNet Luna HSM”.

Migrating Key Materials from JKS to Luna Keystore When Java is configured to use Luna Provider, we can migrate the keys and certificate from JKS to Luna Keystore and key materials will be migrated and secured to SafeNet Luna HSM partition.

To Migrate Java Keystore to Luna Keystore Create a keystore config file named lunastore and add the following entry where would be your Luna HSM partition label: tokenlabel: Save the file, preferably in the /conf directory. Migrate the Java keystore to Luna keystore including SSL certificate/key using the keytool utility. The certificate/key will be migrated on the registered partition of SafeNet Luna HSM. keytool -importkeystore -srckeystore -srcstorepass -srcalias -destalias –destkeystore -deststorepass -deststoretype For Example: keytool -importkeystore -srckeystore mykeystore.jks -srcstorepass changeit - srcalias tomcat_key -destalias tomcat_migrated_key –destkeystore lunastore – deststorepass userpin1 -deststoretype luna

Provide partition password, when prompted.

CHAPTER 2: Integrating Apache Tomcat with SafeNet Luna HSM

To display the generated key materials, use the following command: keytool -list -v –alias tomcat_migrated_key -storetype luna -keystore lunastore Provide partition password, when prompted.

NOTE: It is recommended that you should destroy the Java keystore after migrating the key materials to Luna keystore. Keeping the SSL key in software keystore may result in security breach.

Re-Configuring SSL for the Apache Tomcat After successfully migrating the JKS keystore to lunastore, SSL settings in server.xml need to be reconfigured to pick the SSL certificate/key from lunastore. Apache Tomcat configuration files are available under /conf folder. Edit server.xml file to update connector settings for SSL.

To configure SSL for Apache Tomcat Stop the server, if running. Run the shutdown.bat or shutdown.sh script provided under bin folder of . Edit the server.xml file of Tomcat server and update the following. Ensure that the keystore values are correct as per your environment. Now start the Tomcat server using the batch file startup.bat or startup.sh under bin directory of .

CHAPTER 2: Integrating Apache Tomcat with SafeNet Luna HSM

If Tomcat starts successfully, you should be able to see the default page of Tomcat on the browser using https and port 8443. The SSL certificate will be the same that you migrated and stored in Luna Keystore. https://:8443/