IBM Websphere MQ

Set up On-Premise Luna HSM

Set up IBM WebSphere MQ

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 on used by IBM MQ.

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:

C:\Program Files\SafeNet\LunaClient>lunacm.exe

Upon successful execution, you should observe an output similar to the example provided below:

lunacm.exe (64-bit) v10.4.0-417. Copyright (c) 2021 SafeNet. All rights reserved. 
Available HSMs:
Slot Id ->                           0
Label ->                             TPA01
Serial Number ->                     1312109862201
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
Current Slot Id: 0

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

If using a PED-authenticated HSM, enable Partition Policy 22 (Activation) and Partition Policy 23 (Auto-Activation) to allow the partition to be activated and auto-activated.

Verify that the Luna HSM is operating in FIPS mode.

Open the Luna HSM client configuration file (typically Chrystoki.conf or Chrystoki.ini, depending on the OS).

Add or update the following entry under the Misc section:

Misc = {
    RSAKeyGenMechRemap = 1;
}

This setting ensures that older RSA key generation requests (e.g., RSA PKCS or X9.31) are remapped to FIPS 186-3-compliant mechanisms when FIPS mode is enabled.

Save the file and restart any relevant services or applications that rely on the HSM.

Check if IBM WebSphere MQ is using the CKM_SHA1_RSA_PKCS mechanism for signing operations. If so, and your Luna SA firmware version is 7.x.x, proceed to the next step.

Upgrade the Luna SA firmware to version 7.7.0 or later to enable the CKM_SHA256_RSA_PKCS mechanism, which is supported in FIPS mode.

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.

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.

Ensure that the target machine meets all prerequisites for IBM WebSphere MQ installation.

Create the required user ID and group ID according to IBM MQ requirements before proceeding with the installation.

Download and install IBM WebSphere MQ (Server or Client) on the target system.

(Optional) Install IBM WebSphere MQ Explorer on a Windows or Linux system.

IBM MQ Explorer is a graphical tool that allows you to view, manage, and configure MQ objects.

It can also connect remotely to queue managers hosted on other supported platforms.

After installation, verify that MQ services are running and that you can access the MQ command-line or GUI tools.

Refer to the official IBM WebSphere MQ documentation for detailed installation and platform-specific instructions: https://www.ibm.com/docs/en/ibm-mq

Configure SSL/TLS for IBM WebSphere MQ using Luna HSM

Verify SSL/TLS connectivity between MQ Server and MQ Client

Start the Queue Manager

Generate TLS Certificates Using Luna HSM

Configure SSL/TLS on the Queue Manager

Configure SSL/TLS on the MQ Client

Log in to the IBM MQ server as a user with administrative privileges (e.g., Administrator on Windows or a user in the mqm group on Linux).

Set the IBM MQ environment variables.

Linux:

$ . /opt/mqm/bin/setmqenv -s

Windows:

This step is not required if you are using the IBM MQ Command Prompt.

Create a new queue manager (if not already created).

Linux:

$ /opt/mqm/bin/crtmqm QM1

Windows:

C:\Program Files\IBM\MQ\bin>crtmqm.exe QM1

Replace QM1 with the desired name for your queue manager.

Start the queue manager.

Linux:

$ /opt/mqm/bin/strmqm QM1

Windows:

C:\Program Files\IBM\MQ\bin>strmqm.exe QM1

Log in to the IBM MQ Server (or Client) using an account with administrative privileges—such as Administrator on Windows or a user in the mqm group on Linux.

Create a luna.cfg configuration file that defines how the system connects to Luna HSM via the PKCS#11 interface. Save this file in a known location on the local system.

• On Windows, use the following configuration:

  name = LUNA
  library = C:\Program Files\SafeNet\LunaClient\cryptoki.dll
  description = Luna config
  slotListIndex = 0

  attributes (*, CKO_PRIVATE_KEY, *) = {
    CKA_SENSITIVE = true
    CKA_SIGN = true
    CKA_DECRYPT = true
  }

  attributes (*, CKO_PUBLIC_KEY, *) = {
    CKA_VERIFY = true
    CKA_ENCRYPT = true
  }

  attributes (*, CKO_SECRET_KEY, *) = {
    CKA_SENSITIVE = true
    CKA_ENCRYPT = true
    CKA_DECRYPT = true
    CKA_SIGN = true
    CKA_VERIFY = true
  }

  disabledMechanisms = {
    CKM_SHA1_RSA_PKCS
  }
  

• On Linux, use the same configuration, but replace the library line with:

  library = /usr/safenet/lunaclient/lib/libCryptoki2_64.so
  

Open the java.security file located at the IBM MQ JRE path: <IBM MQ installation path>/lib/security/java.security.

Locate the entry for IBMPKCS11Impl and update it to reference the full path of your luna.cfg file.

Replace the placeholder <Path to luna.cfg file> with the actual location of the configuration file you created in the previous step.

For example:

security.provider.7=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl C:\\Luna\\luna.cfg

Below is a sample snippet showing the correct ordering:

security.provider.1=com.ibm.fips.jsse.IBMJSSEFIPSProvider
security.provider.2=com.ibm.crypto.fips.provider.IBMJCEFIPS
security.provider.3=com.ibm.jsse2.IBMJSSEProvider2
security.provider.4=com.ibm.crypto.provider.IBMJCE
security.provider.5=com.ibm.security.jgss.IBMJGSSProvider
security.provider.6=com.ibm.security.cert.IBMCertPath
security.provider.7=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl 
security.provider.8=com.ibm.security.sasl.IBMSASL
security.provider.9=com.ibm.xml.crypto.IBMXMLCryptoProvider
security.provider.10=com.ibm.xml.enc.IBMXMLEncProvider
security.provider.11=com.ibm.security.jgss.mech.spnego.IBMSPNEGO
security.provider.12=sun.security.provider.Sun
security.provider.13=com.ibm.security.cmskeystore.CMSProvider

Be sure to use double backslashes (\\) in the file path on Windows.

Launch the IBM Key Management utility (strmqikm) from the MQ installation directory.

• On Windows:

  C:\Program Files\IBM\MQ\bin\strmqikm.exe
  

• On Linux:

  $ /opt/mqm/bin/strmqikm
  

When the IBM Key Management GUI appears, go to Key Database File > Open to access or create your key repository.

In the IBM Key Management window, select PKCS11Config from the Key database type drop-down list, then click OK.

When prompted, enter the partition password in the Cryptographic Token Password field.

Select Create new secondary key database file, then click Browse to choose a location and name for the new key.kdb file. Click OK to proceed.

When the password prompt appears, create a password for the key.kdb file.

Select the checkbox Stash password to a file, then click OK to confirm and store the password securely.

To create the self-signed certificate, go to Create > New Self-Signed Certificate. In the Key Label field, enter the label in lowercase using the format:

ibmwebspheremq

Replace <queuename> with the actual name of your queue manager (e.g., ibmwebspheremqqm1).

Fill in the remaining certificate fields as required, then click OK.

Log in to the IBM MQ Client system using an account with administrative privileges—either the Administrator account on Windows or a user in the mqm group on Linux.

Repeat Steps 2 through 15 on the MQ Client system to generate the client certificate using Luna HSM. When entering the Key Label during certificate creation, use lowercase letters in the following format:

ibmwebspheremq

Replace <logged_in_user> with the username used to run the MQ Client. Once completed, both MQ Server and MQ Client certificates will be stored on the same or respective Luna HSM partitions and will appear under Personal Certificates in the Key Management tool.

For demonstration purposes in this guide, the same Luna HSM partition and self-signed certificate is used for both the MQ Server and Client. However, in production environments, it is strongly recommended to use separate HSM partitions and CA-signed certificates for enhanced security and proper identity separation.

Export the MQ Server certificate: In the IBM Key Management window, select the certificate under Personal Certificates, click Extract Certificate…, choose a location to save the exported certificate file, and transfer this file to the MQ Client system.

Import the MQ Server certificate into the MQ Client’s key database: Set the CMS Key database content to Signer Certificates, click Add…, and browse to select the exported server certificate file. Click OK to import.

When prompted, enter a label for the imported server certificate and click OK.

Repeat Steps 19 to 21 to export the MQ Client certificate and import it into the MQ Server’s key database under Signer Certificates.

If you are using CA-signed certificates, make sure the MQ Client’s key database contains the CA certificate that signed the MQ Server’s certificate, and the MQ Server’s key database contains the CA certificate that signed the MQ Client’s certificate.

Log in to the IBM MQ Server using an account with administrative privileges—such as the Administrator account on Windows or a user in the mqm group on Linux.

Launch MQ Explorer from the MQ installation directory.

• On Windows:

C:\Program Files\IBM\MQ\bin\MQExplorer.exe

• On Linux:

$ /opt/mqm/bin/MQExplorer

In the MQ Explorer – Navigator pane, expand IBM MQ > Queue Managers.

Right-click the queue manager you created earlier, and select Properties… from the context menu.

In the Queue Manager – Properties window, click SSL, then select Configure… under the Cryptographic hardware section.

In the configuration dialog:

• Select Other (PKCS11) as the cryptographic provider.

• Enter the Driver path for your platform:

For Windows:

C:\Program Files\SafeNet\LunaClient\cryptoki.dll

For Linux:

/usr/safenet/lunaclient/lib/libCryptoki2_64.so

• Provide the Token Label and Token Password for your Luna HSM partition.

Click OK, then click Apply to save the configuration. Once the settings are applied, close the SSL properties window.

Right-click the Queue Manager, navigate to Security, and select Refresh SSL…

When prompted to confirm the SSL refresh, click Yes to apply the updated settings.

Open the MQSC console to run commands for your queue manager.

• On Windows:

  C:\Program Files\IBM\MQ\bin\runmqsc.exe QM1
  

• On Linux:

  $ /opt/mqm/bin/runmqsc QM1
  

Replace QM1 with the actual name of your queue manager.

If you have already configured the cryptographic hardware settings using MQ Explorer, you can skip to Step 15.

Set the cryptographic hardware configuration (SSLCRYP) using the ALTER QMGR command. Use the following format:

ALTER QMGR SSLCRYP('GSK_PKCS11=;;;symmetric_cipher_setting')

Example:

ALTER QMGR SSLCRYP('GSK_PKCS11=/usr/safenet/lunaclient/lib/libCryptoki2_64.so;TPA02;userpin1;SYMMETRIC_CIPHER_OFF;')

Ensure that you replace each placeholder with your actual values.

Set the key repository location (SSLKEYR) for the queue manager using the ALTER QMGR command. Use the following format:

ALTER QMGR SSLKEYR('/')

Do not include the .kdb extension in the keyfile name.

Example:

ALTER QMGR SSLKEYR('/opt/mqm/bin/key')

After applying the configuration changes, refresh the SSL settings on the queue manager by entering the following command in the MQSC console:

REFRESH SECURITY TYPE(SSL)

Type end and press Enter to exit the MQSC console.

Reopen the MQSC console to verify that the SSL settings have been correctly applied.

• On Windows:

  C:\Program Files\IBM\MQ\bin\runmqsc.exe QM1
  

• On Linux:

  $ /opt/mqm/bin/runmqsc QM1
  

Replace QM1 with the actual name of your queue manager.

Verify that the SSL settings have been correctly applied by running the following command in the MQSC console:

DISPLAY QMGR SSLCRYP SSLKEYR

Check that the values match the PKCS#11 configuration and key repository path you provided earlier.

Create a listener on the queue manager (QM1) to handle incoming client connections:

DEFINE LISTENER(QM1.TCP) TRPTYPE(TCP) PORT(1414) CONTROL(QMGR)

Replace QM1.TCP with your desired listener name, if different.

Start the listener:

START LISTENER(QM1.TCP)

Check the listener status to ensure it's running:

DISPLAY LSSTATUS(QM1.TCP)

Define a server-connection channel to establish a secure connection between the MQ Client and QM1. Use the appropriate command based on your platform:

• Windows:

  DEFINE CHANNEL(C1.TO.QM1) CHLTYPE(SVRCONN) TRPTYPE(TCP) MCAUSER('MUSR_MQADMIN') SSLCAUTH(REQUIRED) SSLCIPH(TLS_RSA_WITH_AES_128_CBC_SHA256) DESCR('Server channel using SSL from C1 to QM1')
  

• Linux:

  DEFINE CHANNEL(C1.TO.QM1) CHLTYPE(SVRCONN) TRPTYPE(TCP) MCAUSER('mqm') SSLCAUTH(REQUIRED) SSLCIPH(TLS_RSA_WITH_AES_128_CBC_SHA256) DESCR('Server channel using SSL from C1 to QM1')
  

Here, CHANNEL is your custom channel name, and MCAUSER is the user account that has been added to the mqm group on the MQ Server.

Start the server-connection channel:

START CHANNEL(C1.TO.QM1)

Define a client-connection channel to connect to the MQ Server. Replace the hostname with the actual IP address or FQDN of your MQ Server:

DEFINE CHANNEL(C1.TO.QM1) CHLTYPE(CLNTCONN) TRPTYPE(TCP) CONNAME('HSMNOI1INT-MA01.noidalab.local') QMNAME(QM1) SSLCIPH(TLS_RSA_WITH_AES_128_CBC_SHA256) DESCR('Client channel using SSL from C1 to QM1')

The channel name and SSL cipher specification must exactly match those defined in the server-connection channel.

Create a channel authentication rule to authorize the MQ Client connection based on its IP or hostname. Use the appropriate command for your platform:

• Windows:

  SET CHLAUTH(C1.TO.QM1) TYPE(ADDRESSMAP) ADDRESS('HSMNOI1INT-MA02.noidalab.local') MCAUSER('MUSR_MQADMIN')
  

• Linux:

  SET CHLAUTH(C1.TO.QM1) TYPE(ADDRESSMAP) ADDRESS('HSMNOI1INT-MA02.noidalab.local') MCAUSER('mqm')
  

Here, ADDRESS is the hostname or IP address of the MQ Client, and MCAUSER is the user authorized to access the channel.

If default channel authentication rules block admin access, create an override rule to allow admin-level users: SET CHLAUTH(C1.TO.QM1) TYPE(BLOCKUSER) DESCR('Override *MQADMIN block on this channel') USERLIST('nobody') ACTION(REPLACE)

Refer to IBM MQ documentation for other CHLAUTH types.

Create a local queue on the queue manager:

DEFINE QLOCAL(QM1.LQ)

Replace QM1.LQ with your preferred queue name.

Type END and press Enter to close the MQSC console.

Restart the queue manager to apply all changes:

• On Windows:

  C:\Program Files\IBM\MQ\bin>endmqm.exe QM1
  C:\Program Files\IBM\MQ\bin>strmqm.exe QM1
  

• On Linux:

  $ /opt/mqm/bin/endmqm QM1
  $ /opt/mqm/bin/strmqm QM1
  

Log in to the IBM MQ Client system using an account with administrative privileges—either the Administrator account on Windows or a user in the mqm group on Linux.

Edit the mqclient.ini file to define the hardware cryptographic token and specify the location of the key repository.

• On Windows, the file is located at: C:\ProgramData\IBM\MQ\mqclient.ini

• On Linux, the file is located at: /var/mqm/mqclient.ini

Add the following SSL stanza to the file:

• For Windows:

  SSL:
    SSLCryptoHardware=GSK_PKCS11=C:\Program Files\SafeNet\LunaClient\cryptoki.dll;ibmmq;userpin1;SYMMETRIC_CIPHER_OFF
    SSLKeyRepository=C:\ProgramData\IBM\MQ\key
  

• For Linux:

  SSL:
    SSLCryptoHardware=GSK_PKCS11=/usr/safenet/lunaclient/lib/libCryptoki2_64.so\;ibmmq\;userpin1\;SYMMETRIC_CIPHER_OFF
    SSLKeyRepository=/var/mqm/key
  

Here, SSLCryptoHardware specifies the HSM driver path, token label, token password, and cipher setting; and SSLKeyRepository defines the full path to the key repository, without the .kdb extension.

Copy the Client Channel Definition Table (AMQCLCHL.TAB) from the MQ Server to the MQ Client. This file defines the client connection channel configuration.

• On Windows MQ Server, the file is located at:

  C:\ProgramData\IBM\MQ\qmgrs\QM1\@ipcc\AMQCLCHL.TAB
  

• On Linux MQ Server, the file is located at:

  /var/mqm/qmgrs/QM1/@ipcc/AMQCLCHL.TAB
  

Copy the AMQCLCHL.TAB file to the appropriate location on the MQ Client—C:\ProgramData\IBM\MQ\ on Windows or /var/mqm/ on Linux.

Log in to the IBM MQ Client system using an account with administrative privileges—either the Administrator account on Windows or a user in the mqm group on Linux.

Open a command prompt or terminal and set the required environment variables based on your platform.

• On Windows:

  set MQCHLLIB=C:\ProgramData\IBM\MQ
  set MQCHLTAB=AMQCLCHL.TAB
  set MQSAMP_USER_ID=MUSR_MQADMIN
  

• On Linux:

  export MQCHLLIB=/var/mqm
  export MQCHLTAB=AMQCLCHL.TAB
  export MQSAMP_USER_ID=mqm
  

Here, MQCHLLIB specifies the location of the Client Channel Definition Table, MQCHLTAB is the name of the channel table file copied from the MQ Server, and MQSAMP_USER_ID is the authorized user defined in the MQ Server's channel authentication record.

Run the following command on the MQ Client to send a test message over the SSL/TLS connection to the MQ Server queue:

• On Windows:

  C:\Program Files\IBM\MQ\bin\amqsputc.exe QM1.LQ QM1
  

• On Linux:

  /opt/mqm/samp/bin/amqsputc QM1.LQ QM1
  

Any message entered in this prompt will be securely transmitted to the MQ Server using the configured SSL/TLS channel.

Log in to the IBM MQ Server using the Administrator account or a user in the mqm group.

Use the following command to retrieve and display the message sent from the client:

• On Windows:

  C:\Program Files\IBM\MQ\bin\amqsget.exe QM1.LQ QM1
  

• On Linux:

  /opt/mqm/samp/bin/amqsget QM1.LQ QM1