Apache Tomcat...Gemalto and the Gemalto logo are trademarks and service marks of Gemalto N.V. and/or...

Apache Tomcat INTEGRATION GUIDE

SAFENET LUNA HSM

Apache Tomcat: Integration Guide 007-000637-001, Rev. A, January 2020, Copyright © 2020 Gemalto

2

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


3

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


4

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


5

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


6

**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 ]

[ ]

[ a | b | c ]

[ | | ]

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 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


7

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].

https://supportportal.thalesgroup.com/mailto:[email protected]

CHAPTER 1: Introduction


8


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.

http://www.apache.org/licenses/



9

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



10

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.



11

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/

https://hostname/

CHAPTER 2: Integrating Apache Tomcat with SafeNet Luna HSM


12


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


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



13

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.



14

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 .



15

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.



16

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:


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.


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.



17

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 .



18

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/

Apache Tomcat...Gemalto and the Gemalto logo are trademarks and service marks of Gemalto N.V. and/or...

Documents

Transcript of Apache Tomcat...Gemalto and the Gemalto logo are trademarks and service marks of Gemalto N.V. and/or...