Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

Guides

JBoss Application Server

search

JBoss Application Server

This guide outlines step-by-step instructions for seamlessly integrating JBoss Application Server with a Luna HSM device or Luna Cloud HSM service. JBoss Application Server is a suite of offerings tailored for enterprise customers, offering preconfigured profiles of JBoss Enterprise Middleware components that have undergone rigorous testing and certification to deliver a seamlessly integrated experience. It serves as the open-source implementation of the Java EE suite of services.

The key benefits of this integration are:

  • Secure generation, storage, and protection of the identity signing private keys using either FIPS 140-2 or FIPS 140-3 Level 3 validated hardware.

  • Full life cycle management of the keys to ensure their integrity and reliability throughout their usage.

  • Maintenance of a comprehensive HSM audit trail for transparency and accountability in key operations. It's important to note that Luna Cloud HSM service does not have access to this secure audit trail.

  • Significant performance enhancements by offloading cryptographic operations from application servers.

Supported Platforms

This integration has been tested and verified on the following platforms:

HSM Type Platform Tested
Luna HSM RHEL
Luna Cloud HSM RHEL

If you're using JDK 11 with Luna Client:
- For Luna Client version 10.3.0 or newer, no additional patches are needed.
- For Luna Client version 10.2.0, a specific patch (DOW0005918) is required. You can download it from the Thales Customer Support portal.
- Luna Client versions older than 10.2.0 do not support JDK 11.

Prerequisites

The prerequisites for this integration are:

Set up Luna HSM

Set up Java for JBoss and Java KEYTOOL Utility

Set up JBoss

Set up Luna HSM

As the first step to accomplish this integration, you need to set up either On-Premise Luna HSM or Luna Cloud HSM.

Set up On-Premise Luna HSM

Follow these steps to set up your on-premise Luna HSM:

Ensure that the HSM is set up, initialized, provisioned, and ready for deployment. For more information, refer to Luna HSM documentation.

Create a partition that will be later used by JBoss.

Create and exchange certificate between the Luna 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.

Run the following command to verify that the partition has been successfully registered and configured: 

/usr/safenet/lunaclient/bin/lunacm

Take note of the output, which should resemble the example below:

lunacm (64-bit) v10.5.0-470. Copyright (c) 2022 Luna. All rights reserved.
Available HSMs:
Slot Id ->              0
Label ->                jboss1
Serial Number ->        1312109862213
Model ->                LunaSA 7.7.1
Firmware Version ->     7.7.1
Bootloader Version ->   1.1.2
Configuration ->        Luna User Partition With SO (PW) Key Export With Cloning Mode
Slot Description ->     Net Token Slot
FM HW Status ->         Non-FM  

Slot Id ->              1
Label ->                jboss2
Serial Number ->        1280780175898
Model ->                LunaSA 7.7.1
Firmware Version ->     7.7.2
Bootloader Version ->   1.1.2
Configuration ->        Luna User Partition With SO (PW) Key Export With  Cloning Mode
Slot Description ->     Net Token Slot
FM HW Status ->         Non-FM

Slot Id ->              8
HSM Label ->            HA
HSM Serial Number ->    11312109862213
HSM Model ->            LunaVirtual
HSM Firmware Version -> 7.7.1
HSM Configuration ->    Luna Virtual HSM (PW) Key Export With Cloning Mode
HSM Status ->           N/A - HA Group

Current Slot Id: 0

Enable partition policies 22 and 23 to allow activation and auto-activation, in case you are using PED-authenticated HSMs.

Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.

Set up Luna HSM High-Availability Group

Refer to Luna HSM documentation for HA steps and details regarding configuring and setting up two or more HSM boxes on host systems. You must enable the HAOnly setting in HA for failover to work so that if the primary goes down due to any reason, all calls get automatically routed to the secondary until the primary recovers and starts up.

This integration has undergone testing in both HA and FIPS modes.


Managing User Access to Your HSM

Initially, only the root user can access the Hardware Security Module (HSM). However, you can grant access to specific non-root users by including them in the hsmusers group. This group is automatically created when you install the client software. Even if you later uninstall the client software, the hsmusers group remains intact, ensuring you can upgrade your software without losing your user access settings.

To add users to the hsmusers group

If you wish to permit non-root users or applications to interact with the HSM device, you must assign these users to the hsmusers group. Make sure that the users you intend to add to the hsmusers group are already established on the client workstation. Only users added to the hsmusers group will be granted access to the HSM device. Follow these steps to add a user to the hsmusers group:

Ensure that you possess sudo privileges on the client workstation.

Add a user to the hsmusers group using the command:

sudo gpasswd --add <username> hsmusers

Replace username with the actual username you want to include in the hsmusers group.

To remove users from the hsmusers group

If you need to withdraw a user's authorization to access the HSM device, you can remove them from the hsmusers group. Carry out the following steps to remove a user from the hsmusers group:

Confirm that you hold sudo privileges on the client workstation.

Eliminate a user from the hsmusers group using the command:

sudo gpasswd --add <username> hsmusers

Replace username with the specific username you want to exclude from the hsmusers group. To observe the changes, you will need to log in again.

Any user you remove will retain access to the HSM device until the client workstation is rebooted.

Set up Luna Cloud HSM

Follow these steps to set up your Luna Cloud HSM:

Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means

This integration has been certified on the RHEL platform.

Extract the .zip file into a directory on your client workstation.

Extract or untar the appropriate client package for your operating system. Do not extract to a new subdirectory; place the files in the client install directory.

tar -xvf cvclient-min.tar

Run the setenv script to create a new configuration file containing information required by the Luna Cloud HSM service.

source ./setenv

To add the configuration to an already installed UC client, use the –addcloudhsm option when running the setenv script.

Run the LunaCM utility and verify that the Cloud HSM service is listed.

If your organization requires non-FIPS algorithms for your operations, ensure that the Allow non-FIPS approved algorithms check box is checked. For more information, refer to Supported Mechanisms.

Set up Java for JBoss and Java KEYTOOL Utility

To ensure integration with JBoss and utilize the Java KEYTOOL utility, follow these steps to set up the necessary environment variables:

Identify the directory where Java is installed on your system. This directory will contain the necessary Java executables and libraries.

Open your command prompt and execute the following command:

export JAVA_HOME=<Path to Java installation Directory>

Add the Java binaries directory to your system's PATH variable. Execute the following command:

export PATH=$JAVA_HOME/bin:$PATH

Set up JBoss

To proceed with the integration process, it's essential to have the JBoss server installed on your target machine. Below are the steps to ensure you have JBoss set up correctly:

Ensure that you have JBoss server installed on your system. If you haven't already installed it, you can find detailed installation instructions in the official JBoss documentation. This documentation will guide you through the installation process.

After installing JBoss, open your command prompt and execute the following command:

export JBOSS_HOME=<Path to JBoss installation directory>

Run the following command to start the JBoss server:

sh $JBOSS_HOME/bin/standalone.sh

Once you've installed and started JBoss, ensure that the server is functioning correctly by opening a web browser and navigating to the following URL: http://localhost:8080. This verification step ensures that your JBoss installation is up and running smoothly, setting the stage for successful integration with Thales Luna HSM or Luna Cloud HSM.

Integrate JBoss using JDK 11 or above

SSL configuration for JBoss ensures secure communication by setting up SSL keys and certificates stored in the keystore. JBoss leverages Java JSSE for SSL/TLS support. To enable JBoss to use Luna keystore for SSL keys and certificates, follow these steps:

Navigate to the $JAVA_HOME/conf/security directory to locate the Java Security Configuration file named java.security. Once you've found the file, proceed to add the Luna Provider configuration as demonstrated in the example below.

security.provider.1=SUN
security.provider.2=com.safenetinc.luna.provider.LunaProvider
security.provider.3=SunRsaSign
security.provider.4=SunEC
security.provider.5=SunJSSE
security.provider.6=SunJCE
security.provider.7=SunJGSS
security.provider.8=SunSASL
security.provider.9=XMLDSig
security.provider.10=SunPCSC
security.provider.11=JdkLDAP
security.provider.12=JdkSASL
security.provider.13=SunPKCS11

Change the current directory to the JBoss configuration directory by executing the following command:

cd $JBOSS_HOME/standalone/configuration/

Create a keystore configuration file named lunastore in the JBoss configuration directory. Include the following entry, replacing <Partition Label> with your Luna HSM partition label:

tokenlabel:<partition_label>

Save the lunastore file in the $JBOSS_HOME/standalone/configuration/ directory.

Generate a key pair within the Luna keystore using the Java keytool utility. This process will create a key pair specifically within the registered partition of the Luna HSM. Utilize the following command template:

keytool -genkeypair -alias <key label> -keyalg <key algorithm> -keysize <size of key> -sigalg <signing algorithm> -keypass <key password> -keystore <keystore name> -storetype Luna -storepass <partition password> -providerpath <lunaprovider jar file> -providerclass <luna class path> -J-Djava.library.path=<luna JSP lib path> -J-cp -J<lunaprovider jar file>

For instance: 

keytool -genkeypair -alias jbosskey -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -keypass userpin1 -keystore lunastore -storetype Luna -storepass userpin1 -providerpath "/usr/safenet/lunaclient/jsp/lib/LunaProvider.jar" -providerclass com.safenetinc.luna.provider.LunaProvider -J-Djava.library.path=/usr/safenet/lunaclient/jsp/lib/ -J-cp -J/usr/safenet/lunaclient/jsp/lib/LunaProvider.jar

Follow the prompts to enter the necessary details to generate the key and certificate. The key pair and certificate will be generated on the Luna HSM.

Generate a certificate request from a key generated in the Luna keystore. Execute the following command, providing the keystore password when prompted:

keytool -certreq -alias jbosskey -sigalg SHA256withRSA -file certreq_file -keystore lunastore -storetype Luna -providerpath "/usr/safenet/lunaclient/jsp/lib/LunaProvider.jar" -providerclass com.safenetinc.luna.provider.LunaProvider -J-Djava.library.path=/usr/safenet/lunaclient/jsp/lib/ -J-cp -J/usr/safenet/lunaclient/jsp/lib/LunaProvider.jar

The certificate request file (certreq_file) will be generated in the current directory.

Submit the Certificate Signing Request (CSR) file to your CA for authentication. The CA will 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 into the keystore:

keytool -trustcacerts -importcert -alias rootca -file root.cer -keystore lunastore -storetype Luna -providerpath "/usr/safenet/lunaclient/jsp/lib/LunaProvider.jar" -providerclass com.safenetinc.luna.provider.LunaProvider -J-Djava.library.path=/usr/safenet/lunaclient/jsp/lib/ -J-cp -J/usr/safenet/lunaclient/jsp/lib/LunaProvider.jar

Enter the keystore password when prompted. Here, root.cer is the CA Root Certificate.

Import the signed certificate reply or certificate chain:

keytool -trustcacerts -importcert -alias jbosskey -file certchain.p7b -keystore lunastore -storetype Luna -providerpath "/usr/safenet/lunaclient/jsp/lib/LunaProvider.jar" -providerclass com.safenetinc.luna.provider.LunaProvider -J-Djava.library.path=/usr/safenet/lunaclient/jsp/lib/ -J-cp -J/usr/safenet/lunaclient/jsp/lib/LunaProvider.jar

Enter the keystore password when prompted. Here, certchain.p7b is the signed certificate chain.

View the generated key materials and ensure they are generated on the Luna partition:

keytool -list -v -keystore lunastore -storetype Luna -providerpath <Luna JAR file location> -providerclass <Luna class path> -J-Djava.library.path=<Luna JSP lib path> -J-cp -J<Luna provider JAR file>

For instance: 

keytool -list -v -keystore lunastore -storetype Luna -providerpath "/usr/safenet/lunaclient/jsp/lib/LunaProvider.jar" -providerclass com.safenetinc.luna.provider.LunaProvider -J-Djava.library.path=/usr/safenet/lunaclient/jsp/lib/ -J-cp -J/usr/safenet/lunaclient/jsp/lib/LunaProvider.jar

Enter the keystore password when prompted.

Create a luna/main/lib/linux-x86_64 directory to define the Luna module for use with JBoss.

mkdir -p $JBOSS_HOME/modules/system/layers/base/org/wildfly/luna/main/lib/linux-x86_64

Copy the LunaProvider.jar file into the luna/main directory created in the previous step:

cp /usr/safenet/lunaclient/jsp/lib/LunaProvider.jar $JBOSS_HOME/modules/system/layers/base/org/wildfly/luna/main/

Copy the file libLunaApi.so into the directory "luna/main/lib/linux-x86_64":

cp /usr/safenet/lunaclient/jsp/lib/libLunaAPI.so $JBOSS_HOME/modules/system/layers/base/org/wildfly/luna/main/lib/linux-x86_64/

Navigate to the luna/main directory:

cd $JBOSS_HOME/modules/system/layers/base/org/wildfly/luna/main

Create a file named module.xml with the following entries to define LunaProvider.jar as a Luna module and specify its dependencies:

<module name="org.wildfly.luna" xmlns="urn:jboss:module:1.9">
    <resources>
        <resource-root path="LunaProvider.jar"/>
    </resources>
    <dependencies>
        <module name="java.logging"/>
        <module name="org.wildfly.security.elytron"/>
    </dependencies>
</module>

Modify the <providers> section of the standalone.xml configuration file, found in the $JBOSS_HOME/standalone/configuration directory, to include the Luna provider.

<providers>
    <aggregate-providers name="combined-providers">
        <providers name="elytron"/>
        <providers name="openssl"/>
        <providers name="luna"/>
    </aggregate-providers>
    <provider-loader name="elytron" module="org.wildfly.security.elytron"/>
    <provider-loader name="openssl" module="org.wildfly.openssl"/>
    <provider-loader name="luna" class-names="com.safenetinc.luna.provider.LunaProvider" module="org.wildfly.luna"/>
</providers>

Proceed to configure the <tls> section of the standalone.xml configuration file located in the $JBOSS_HOME/standalone/configurationdirectory. Define <server-ssl-contexts> to utilize <key-managers> that utilize Luna as a <key-store>. Inside the <tls> section, ensure that <server-ssl-contexts> are defined appropriately to utilize Luna as the key store. 

<tls>
    <key-stores>
        <key-store name="lunaKS">
            <credential-reference clear-text="userpin1"/>
            <implementation type="luna"/>
            <file path="lunastore" relative-to="jboss.server.config.dir"/>
        </key-store>
    </key-stores>
    <key-managers>
        <key-manager name="lunaKM" key-store="lunaKS">
            <credential-reference clear-text="userpin1"/>
        </key-manager>
    </key-managers>
    <server-ssl-contexts>
        <server-ssl-context name="lunaSSC" key-manager="lunaKM"/>
    </server-ssl-contexts>
</tls>

Replace "userpin1" with the actual value of keystore and key passwords.

To finalize the SSL configuration, modify the standalone.xml file located in $JBOSS_HOME/standalone/configuration. Within the <server name="default-server"> section, find the <https-listener> configuration. Replace the ssl-context attribute of the <https-listener> element with the value lunaSSC, pointing to the previously defined server-ssl-context. By making this change, the HTTPS listener will use the SSL context configured to utilize the Luna provider and keys stored in the Luna partition, ensuring secure communication.

<http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
<https-listener name="https" socket-binding="https" ssl-context="lunaSSC" enable-http2="true"/>

Ensure all modifications are saved. Start the server by running the following command:

sh $JBOSS_HOME/bin/standalone.sh

Open a web browser and enter the following URL:

https://<hostname or IP address>:8443

Open the web console and accept the SSL certificate. This action confirms the successful SSL configuration on JBoss, ensuring the security of both the Private Key and SSL Certificate stored on the Thales Luna HSM.

Integrate JBoss using JDK 8 or below

To enable SSL acceleration within JBoss, you need to follow these steps for a smooth configuration process:

Copy the libLunaAPI.so and LunaProvider.jar files from /usr/safenet/lunaclient/jsp/lib to $JAVA_HOME/jre/lib/ext/ using the following commands:

cp /usr/safenet/lunaclient/jsp/lib/libLunaAPI.so $JAVA_HOME/jre/lib/ext/
cp /usr/safenet/lunaclient/jsp/lib/LunaProvider.jar $JAVA_HOME/jre/lib/ext/

Locate the java.security file at $JAVA_HOME/jre/lib/security and add the Luna Provider to the security providers list using these entries:

security.provider.1=com.safenetinc.luna.provider.LunaProvider
security.provider.2=sun.security.provider.Sun
security.provider.3=sun.security.rsa.SunRsaSign
security.provider.4=sun.security.ec.SunEC
security.provider.5=com.sun.net.ssl.internal.ssl.Provider
security.provider.6=com.sun.crypto.provider.SunJCE
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

Navigate to the configuration directory at $JBOSS_HOME/standalone/configuration/ and create a keystore file. Include the entry tokenlabel:<Partition_Name> in it, where <Partition_Name> is the name of the partition on the Luna HSM.

Utilize the Java Keytool utility to initiate the creation of a fresh keystore. This keystore will employ the Luna Provider to generate both a key and a certificate within the Luna HSM partition. Execute the following command, replacing the placeholders with the appropriate values:

keytool -genkey -keystore <keystore name> -storepass <partition password> -alias <key label> -keypass <partition password> -keyalg <key algorithm> -keysize <size of key> -sigalg <signing algorithm> -validity <no. of days> -storetype <name of keystore>

When generating RSA Keys, the command looks like this:

keytool -genkey -keystore mykeystore -storepass userpin1 -alias jboss -keypass userpin1 -keyalg RSA -keysize 2048 -sigalg SHA1withRSA -validity 365 -storetype luna

Similarly, when generating ECDSA Keys, the command looks like this:

keytool -genkey -keystore mykeystore -storepass userpin1 -alias jboss -keypass userpin1 -keyalg EC -keysize 256 -sigalg SHA1withECDSA -validity 365 -storetype luna

Proceed to create both a key and certificate within the Luna Network HSM, while also generating a keystore in the current directory. During this process, you will be prompted to provide the necessary details.

If the HSM operates in FIPS mode, make sure to substitute SHA1withRSA and SHA1withECDSA signature algorithms with SHA256withRSA and SHA256withECDSA, respectively.

Generate a Certificate Signing Request (CSR) using the key that you've generated. Depending on whether you are working with RSA or ECDSA keys, use the appropriate command as shown below:


For RSA Keys: 

keytool -certreq -alias <key label> -file <request file> -keypass <partition password> -keystore <keystore name> -storepass <partition password> -sigalg <signing algorithm> -storetype <name of keystore>

For example, when generating a CSR for RSA Keys, use this command:

keytool -certreq -alias jboss -file cert.csr -keypass userpin1 -keystore mykeystore -storepass userpin1 -sigalg SHA1withRSA -storetype luna

For ECDSA Keys: 

keytool -certreq -alias <key label> -file <request file> -keypass <partition password> -keystore <keystore name> -storepass <partition password> -sigalg <signing algorithm> -storetype <name of keystore>

For example, for generatng a CSR for ECDSA keys, use this command: 

keytool -certreq -alias jboss -file cert.csr -keypass userpin1 -keystore mykeystore -storepass userpin1 -sigalg SHA1withECDSA -storetype luna

If your HSM is set to FIPS mode, make sure to substitute SHA1withRSA and SHA1withECDSA signature algorithms with SHA256withRSA and SHA256withECDSA, respectively.

Depending on your Java version, update the java.security file located at $JAVA_HOME/jre/lib/security with the following security provider entries:


For JAVA version 1.8.0_261 and above:

security.provider.1=sun.security.provider.Sun
security.provider.2=sun.security.ec.SunEC
security.provider.3=com.sun.net.ssl.internal.ssl.Provider
security.provider.4=com.sun.crypto.provider.SunJCE
security.provider.5=com.safenetinc.luna.provider.LunaProvider
security.provider.6=sun.security.rsa.SunRsaSign
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

For JAVA versions below 1.8.0_261:

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

Submit the contents of the generated CSR to a Certificate Authority (CA) for signing the certificate request.

Save the root certificate and signed certificate obtained from the CA in the current directory as RootCA.cer and jboss.cer, respectively.

Import the CA root certificate into the keystore using the following command:

keytool -import -trustcacerts -alias rootCA -file RootCA.cer -keystore mykeystore -storepass <password> -storetype luna

Import the signed certificate into the keystore using the following command:

keytool -import -trustcacerts -alias jboss -keypass <partition password> -file jboss.cer -keystore mykeystore -storepass <keystore password> -storetype luna

Prior to importing the certificate into the keystore, ensure that you have already imported the CA root certificate and, if applicable, any intermediate certificates.

Edit the <ssl> configuration under the <management> <security-realms> section in the standalone.xml file located at $JBOSS_HOME/standalone/configuration, as indicated below:

<security-realm name="ApplicationRealm">
    <server-identities>
        <ssl>
            <keystore path="mykeystore" relative-to="jboss.server.config.dir"
                      provider="luna"                             
                      keystore-password="userpin1"
                      alias="jboss" key-password="userpin1"/>
        </ssl>
    </server-identities>
</security-realm>

Here, "userpin1" refers to the Luna HSM partition pin, which ensures secure access.

Start the JBoss server using the command:

sh $JBOSS_HOME/bin/standalone.sh

Access the SSL-enabled server by entering the following URL in a web browser:

https://<hostname or ip address>:8443

Open the web console by accepting the certificate, confirming the successful SSL configuration in JBoss, while ensuring the security of the Private Key and SSL Certificate on the Thales Luna HSM.

With this, the integration between JBoss and Thales Luna HSM or Luna Cloud HSM has been successfully achieved.

On this page