Enabling IBM MQ QM with SSL and configuring the MQ Assets in DevTest Workstation.
search cancel

Enabling IBM MQ QM with SSL and configuring the MQ Assets in DevTest Workstation.

book

Article ID: 390071

calendar_today

Updated On:

Products

Service Virtualization

Issue/Introduction

Setting up SSL for IBM MQ QM is a long and tedious process. Below are the overview of the steps need to be followed:

  1. Acquire Legitimate SSL Server certificate for the IBM MQ server machine
  2. Create a Key database file on IBM MQ Explore
  3. Import the SSL server certificate and issuing inter and root CA's public key certificate to the Key Database File created in Step 2
  4. Configure QM to use the Key DB file created in Step 2
  5. Configure "Server Connection" channel's SSL property with 'SSL Cipher Spec' 
  6. Start QM
  7. Configure WS side of things to make sure SSL connection works.

Environment

All supported releases of Service Virtualization.

Resolution

Step 1: Acquire Legitimate SSL Server certificate for the IBM MQ server machine
- Get an SSL Server certificate from the approved Certificate Authority, or Internal Security team.
Note: Make sure to have a P12 format certificate (This is the certificate that has the Public key cert + private Key)
 
Step 2: Create a Key database file on IBM MQ Explore
Need to work with the MQ Admin for Steps 2-5.
  • Open IBM MQ Explorer UI
  • Right click on 'IBM MQ' from left NAV tree and choose the option 'Manage SSL Certificates'


  • The following Dialog will pop up


  • Follow the screenshots to create a new 'Key Database File'


  • Retain the Key Database type as 'CMS' and if needed change the file name and location. Click OK


  • Pay utmost attention to the next step. When prompted for 'Password', enter the password that the KEY Database file to be secured with.
    MOST IMPORTANTLY, MAKE SURE YOU CHECK THE OPTION "Stash password to a file"
    If this stashing option is missed, then the whole SSL configuration will go for a toss.


  • The files created after this step are:

    • The .kdb file is the keystore database file. Can compare this to a JKS file.

    • The .sth file is the Stash file. This file MUST exist in the same folder where .kdb file exists and should have the same name.
      THESE ARE UNWRITTEN RULES THAT IBM DIDNT DOCUMENT WELL

 
Step 3 Need to import the SSL server certificate and issuing inter and root CA's public key certificate to the Key Database File created in Step 2
NOTE: Very well a self-signed certificate can be used. In fact, within the UI shown below, there is an option to create a SELF-Signed cert. If it's self-signed, then no need to add signers certs.

  • Need to import the SSL Server certificate (Public and Private) as well as issuing CA's inter and root certificates in this step. 
    In the same 'IBM Key Management' dialog box. Choose the certificate type and use the import button to import the .p12 certificate of the SSL server cert that was obtained in Step 1

  • Will be prompted for a password to open the P12 certificate. Enter the password and the SSL Server cert would be imported to the KEY DB. 

  • Once entering the correct password, would be prompted to modify the LABEL of the certificate. This is similar to ALIAS in JKS file. 
    Make a note of the 'Label' with which this certificate is stored in KDB. 

  • Once imported, the certificate will appear in the UI

  • After this, need to import the 'Signer Certificates'. These are basically INTER and ROOT ca Public certs. Import INTER first followed by ROOT.

  • Will be prompted for a Label. Enter something meaningful. (Remember ALIAS in JKS )


  • After importing the certs, should see them listed as below.


  • This completes Step 3. Close the 'IBM Key Management dialog'

 

Step 4 - Configure QM to use the Key DB file created in Step 2

  • Create a new QM and configure it to use the 'Key DB File' created in Step 2






  • Once clicking Finish, the new QM 'SSLQMDemo' is created along with a 'Server connection channel' 

  • Locate the newly created QM in left NAV tree and then right click → Properties 

  • Choose 'SSL' section on the left side and make 2 important changes on the right side as shown below.

    1. Provide the complete path to the KDB file created in Step 2.
      DON'T ENTER THE FILE EXTENSION HERE. THIS ONE MISSTEP CAN CAUSE UNTOLD MISERY.

    2. Edit the Label to change its value to match what was given in step 3. (Remember the Alias thing). 


  • Click ok. Done with creating and configuring QM with SSL. Lets move on to configuring the 'Server Conn' channel.

 

Step 5 - Create and Configure "Server Connection" channel's SSL property with 'SSL Cipher Spec'

  • Expand the SSLQMDemo QM from the left NAV tree and go to 'Channels' object.

  • Right click and choose New → Server-connection channel


  • Choose the Cipher spec algorithm from the available list and a make a NOTE of what was chosen. Need this value when configuring WS side of things.



  • Make sure to delete the Channel Authentication Records as shown in the last screenshot


 

Step 6 - Start the Queue Manager 

For any errors in Connection verification from Workstation, refer to the files in this location: C:\ProgramData\IBM\MQ\qmgrs\SSLQMDemo\errors

  • Now, let's move on to the Workstation side.
    1. Login to Workstation

    2. Add IBM MQ Native → IBM MQ Native Queue Manager

    3. Provide the QM Properties as shown below

    4. The most important thing here is the 'SSL Cipher Suite'. Find out the name of Cipher Suite to use for the Cipher Spec selected on IBM MQ Side.
      Refer https://www.ibm.com/docs/en/ibm-mq/8.0?topic=ssl-ssltls-cipherspecs-ciphersuites for mapping.



    5. If the value is not in the standard set of values that show in the drop-down, then use the Direct Editor to Type the value

    6. Add the following property to workstation.vmoptions file: -Dcom.ibm.mq.cfg.useIBMCipherMappings=false
      This property will force IBM MQ Client libs to use Oracle JRE mapping

    7. Exit and login to workstation and then click the Green Test button:


    8. IF NEEDED, DEFINE THE SSL CONTEXT AND CONFIGURE TRUSTSTORE (import issuing CA Certs into a JKS file) and KEYSTORE (IF 2-WAY SSL IS NEEDED).

Additional Information

Troubleshooting

  1. For any connectivity failure, first thing, check the error log file on IBM MQ server C:\ProgramData\IBM\MQ\qmgrs\SSLQMDemo\errors
  2. Make sure set the 'SSL Authentication' to optional on Channel properties → SSL
  3. Ensure to use the correct LABEL name in QM SSL properties. If there is a mismatch with the label name in KDB file, then this will lead to errors
  4. Make sure the Cipher Spec Name mentioned in Channel property has a matching 'Cipher Suite' in QM definition in WS side

Check for more information in IBM Support on "Troubleshooting IBM MQ Java/JMS TLS SSL Configurations"

Powered by Wolken Software