Introduction

This article is for developers and systems integrators who want to quickly learn how to use MQ clusters to provide secure JMS transport for WebSphere applications. It focuses on securing MQ in bindings mode. Examples are provided for securing a MQ cluster running on AIX®, OS/400®, Linux, and Windows platforms.

It is assumed that you've read "Part 1: Use WebSphere MQ to provide a secure JMS transport for WebSphere Application Server," are familiar with MQ clustering technology, and have a basic understanding of Secure Sockets Layer (SSL) security encryption techniques. Encryption details are discussed in "Choosing the right cryptography for your e-business application."

Business case

The business case in our series is based on the article "Integrating business processes to streamline the supply chain, Part 1." For the example, in this article, a fictitious company supplying kite boarding equipment has decided to streamline their supply chain process directly with its suppliers. Currently, they use WebSphere MQ at all locations and wish to create a secure MQ cluster for JMS transport with WebSphere Application Server for all of their EIS systems. The company wants to switch from expensive, privately leased communications between suppliers, to using the Internet on a secure gateway. Thus, security is necessary. As shown in Figure 1, this company has WebSphere MQ at every location. They have also named the queue managers based on their location.

Software required

The project referenced in this article requires the following software:

• gsk6cmd - security package for AIX available with WebSphere MQ with SSL
• OpenSSL - Open Source SSL Program

The following rpm packages were required by gsk6bas when running on Linux. You can load them from Linux distribution CDs, or find them using an rpmfind server on the Internet. The proper levels are dependent on your level of gsk6bas code.

• libgcc-3.0.4-1.i386.rpm
• gcc3-3.0.4-1.i386.rpm
• libstdc++3-3.0.4-1.i386.rpm

Back to top

Security enablement overview

We'll assume you have already installed WebSphere Application Server and MQ on all servers in your cluster. You also should have configured each WebSphere Application Server server with queue connection factories required for JMS. See the WebSphere Application Server Information Center for more details.

It is highly recommended that you first verify that all components of your configuration are functioning correctly with security disabled prior to enabling MQ security. You can verify this by sending and receiving test JMS messages in your cluster. The following steps* are required to enable MQ security in bindings mode:

1. Create a self-signed certificate. This step should be done only once.
2. Generate a request for a signed certificate using OpenSSL.
3. Submit the request to a signing provider, or sign it yourself.
4. Create a keystore for every MQ server in your cluster, and import the signed certificate to each server.
5. Enable MQ security settings.
6. Verify, test, and debug.

*You will need to do Steps 2 - 6 for every queue manager in your cluster.

Back to top

Step 1. Create a self-signed certificate

We will use OpenSSL for certificate management on the Linux platform. Our goal is to import a common signed certificate to every MQ server in our cluster. Since our cluster is on a secure private intranet, we can sign our own certificate. Instead of requesting a certificate authority for signing, we will act as our own certificate authority.

Before we can do this, a private key must be generated, which will be used in creating our own certificate authority. Step 1 needs to be done only once.

1. Create a private key for use in creating a self-signing certificate. The self-signing certificate will be used to sign a certificate request, since you will be acting as your own certificate authority. We will use a CA script supplied in the /misc directory of OpenSSL. In our environment, we installed OpenSSLL in the /var/openssl directory.

   Listing 1. The OpenSSL command for creating a private key

   mkdir /home/user1/CA cd /home/user1/CA /usr/share/ssl/misc/CA -newca CA certificate filename (or enter to create) Making CA certificate ... Using configuration from /usr/share/ssl/openssl.cnf Generating a 1024 bit RSA private key .......................++++++ ......++++++ writing new private key to './demoCA/private/./cakey.pem' Enter PEM pass phrase: Verifying password - Enter PEM pass phrase: ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. Country Name (2 letter code) [GB]:US State or Province Name (full name) [Berkshire]:NC Locality Name (eg, city) [Newbury]:RTP Organization Name (eg, company) [My Company Ltd]:KiteSurf_CA Organizational Unit Name (eg, section) []: Common Name (eg, your name or your server's hostname) []:KiteSurf Email Address []:

   
   

2. Sign a self-signed certificate, which will be used to sign all the certificate requests for our MQ queue managers. Create it using the following command. The -days parm specifies the number of days before the certificate expires.

   cd /home/user1/CA/demoCA Openssl x509 -in cacert.pem -days 1024 -out newca.pem -signkey private/cakey.pem

   
   

   The newca.pem will need to be copied to every queue manager that will be a member of the secure MQ cluster.

Back to top

Step 2. Generate a request for a signed certificate

A signed certificate request should be made for every queue manager that will be part of the secure cluster. The common Name parameter must be named according to MQ specifications. The common Name must follow this rule and the queue manager name must be folded in lower case. Information on additional security attributes can be found in Chapter 18 of WebSphere MQ Security.

For a queue manager named, QM1, the proper specification would be:

ibmwebspheremqqm1   

ibmwebspheremqXXXXX  XXXXX = queue manager name

AIX, Linux, and Windows

For AIX, Linux, and Windows platforms, do the following.

1. Using the example below, create a signed request for queue manager qm_rtp.

   Listing 2. Example of openSSL command for creating a signed certificate request

   cd /home/user1/CA /usr/share/ssl/misc/CA -newreq Using configuration from /usr/share/ssl/openssl.cnf Generating a 1024 bit RSA private key ....................................................++++++ .................++++++ writing new private key to 'newreq.pem' Enter PEM pass phrase: Verifying password - Enter PEM pass phrase: ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [GB]:US State or Province Name (full name) [Berkshire]:NC Locality Name (eg, city) [Newbury]:RTP Organization Name (eg, company) [My Company Ltd]:KiteSurf_manuf Organizational Unit Name (eg, section) []:Technology Common Name (eg, your name or your server's hostname) []:ibmwebspheremqqm_rtp Email Address []: Please enter the following 'extra' attributes to be sent with your certificate request A challenge password []: An optional company name []: Request (and private key) is in newreq.pem

   
   

2. Rename the inewreq.pem file to a unique filename. We renamed based on the common name specified, for example, qm_rtp_newreq.pem.
   
   
3. Repeat Step 2 for each of your queue managers.

After completing all requests, continue to Step 3 to sign your requests.

OS/400

The OS/400 system running on the iSeries uses its own native security management tool called DCR. Currently, the GSKit certificate management is unavailable on this platform, so we'll use the DCR tool. Start the DCR tool. Please note that the DCR tool will not allow the importing of a signed certificate unless a request has first been made. The tool also uses the OS/400 Unix file system.

OS/400 MQ directory structure:

QIBM/UserData/mqm/qmgrname/ssl

1. Launch DCR tool. Use your browser to start the tool using your host name: http://os400hostname.goes.here:2001/QIBM/ICSS/Cert/Admin. Select the Digital Certification Manager from the main menu. You should see the panel in Figure 2.
   Figure 2. DCM primary window
   
   
2. Create a certificate store prior to creating a request. Click Create New Certificate Store. Figures 3 and 4 will display.
   Figure 3. Example certificate store path
   
   
3. Click Create Certificate, then select Server or Client Certificate.
   Figure 4. Create certificate
   
   
4. Select Verisign or other Internet CA, as shown in Figure 5, then click Continue.
   Figure 5. CA Authority
   
   
5. Fill in your information as required, as shown in Figure 6.
   Figure 6. Create certficate request
   
   
6. You must now cut and paste your certificate request to a file, as shown in Figure 7. If a shared drive is not accessible, then transfer this file to the machine running OpenSSL. Name the file newreq.pem and save to the directory /home/user1/CA. newreq.pem.
   Figure 7. Certificate request created
   
   

Back to top

Step 3. Sign each certificate request

If you were going to submit your signed certificate requests to an actual CA, this step would not be performed.

All platforms

Run this step for each certificate request, and copy the resulting file containing your certificate to the proper MQ server.

Verify that your request files (we used newreq.pem) are located in your current directory. If not, then move the files. The OpenSSL script looks for a certificate request, using its default name, newreq.pem. To simplify the process, we copied each request file to this name prior to running the command to sign. An alternative would be to alter the OpenSSL supplied shell script.

Sign each certificate request by issuing the following command.

Listing 3. Sample command for signing the certificate request

cd /home/user1/CA
/usr/share/ssl/misc/CA -signreq

Using configuration from /usr/share/ssl/openssl.cnf
Enter PEM pass phrase:  password of the the private key you
Created earlier
Check that the request matches the signature
Signature ok
The Subjects Distinguished Name is as follows
countryName           :PRINTABLE:'US'
stateOrProvinceName   :PRINTABLE:'NC'
localityName          :PRINTABLE:'RTP'
organizationName      :T61STRING:'KiteSurf_manuf'
organizationalUnitName:PRINTABLE:'Technology'
commonName            :T61STRING:'ibmwebspheremqqm_rtp'
Certificate is to be certified until Jan 14 17:38:04 2005 GMT (365 days)
Sign the certificate? [y/n]:y
                                                                         
1 out of 1 certificate requests certified, commit? [y/n]y
Write out database with 1 new entries
 
Data Base Updated

NOTE: YOu will receive additional info about your certificate than 
specified here.
-----END CERTIFICATE-----
Signed certificate is in newcert.pem

You have created a signed certificate contained in file newreq.pem. Now, export the signed certificate in a transportable format, as shown in the example below.

[root]# openssl pkcs12 -export -in newcert.pem -out qm_rtp.p12 -in
key newreq.pem
Enter PEM pass phrase:
Enter Export Password:
Verifying password - Enter Export Password:

You must now repeat Step 3 for each queue manager that will be in the cluster. The common name in Step 1 is required to contain the string, ibmwebspheremqxxxxxxxx, where xxxxxxxx is your queue manager name. This value must be in lower case, even if your exact queue manage name is in upper case.

Back to top

Step 4. Create a keystore and import the signed certificates

The signed certificates should now be imported into the queue manager keystore. We use different processes dependent on the platform, so select the appropriate instructions for your system.

AIX and Linux

If you have problems creating a keystore in CMS format, your GSkit environment is probably not set up correctly. See Resources for information regarding setup.

1. To avoid improper GSKit operation, set the JAVA_HOME variable to the Java JRE, supplied with MQ, as follows:

   export JAVA_HOME=/usr/mqm/ssl/jre

   
   
2. Create a keystore. The following command will create a keystore in the default MQ directory. The password will be stashed in stashfile key.sth. This step is performed only once for each MQ AIX server.

   gsk6cmd -keydb -create -db /var/mqm/qmgrs/QM_RTP/ssl/key.kdb -pw password -type cms -expire 365 -stash

   
   
3. Import the public self-signed certificate by importing the public CA that was used to sign your private certificate. Use the command shown below. This public CA is the self-signed certificate you used to sign the certificate request. If you requested and received an actual signed certificate from an official CA, their public certificate would be entered here.

   gsk6cmd -cert -add -db key.kdb -label KiteSurf_CA -file newca.pem -format ascii

   
   
4. Import the signed certificate we previously created and exported, qm_rtp.p12, by entering the following command:

   gsk6cmd -cert -import -file qm_rtp.p12 -type pkcs12 -target key.kdb -target_type cms -target_pw password

   
   
5. You can now verify your certificates have been imported sucessfully. You should see both the CA and self-signed certificates.

   gsk6cmd -cert -list -db /tmp/keynew1.kdb password is required to access this key database. please enter a password: certificates in database: /tmp/keynew1.kdb KiteSurf_CA RSA Secure Server Certification Authority 1cn=ibmwebspheremqqm_rtp, ou=technology, o=kitesurf_manuf, l=rtp, st=nc, c=us

   
   

Windows

1. Keystores on windows have "sto" filetype. In our example, we used the default MQ keystore of key.sto.
   
   
2. Import the public CA you created, which is the self-signed certificate you used to sign the certificate request in Step 1. Open the MQ Explorer and select the following: Queue manager name > Properties > SSL TAB > Manage SSL Certificates > Add > Import from file, as shown in Figure 8. Then, select the file location for your newca.pem file.
   Figure 8. Add certificates on Windows platforms
   
   
3. Import the signed certificate by following the same steps as above, but specify the exported filename.

OS/400

1. Select the Certificate Store you created in Step 2 with the DCM tool. From the DCM tool, click Select Certificate Store > Other System Certificate Store. Enter the path filename of store, as shown in Figure 9.
   Figure 9. Import CA
   
   
2. Click Manage Certificates > Import Certificates > CA, then specify the location and filename (newca.pem) that you transfered the file to from your Linux machine. You will receive a message indicating success, as shown in Figure 10.
   Figure 10. CA import verification
   
   
3. Import your self-signed certificate. Click Manage Certificates > Import Certificates > Client or Server Certificate. Specify location and filename.

Back to top

Step 5. Enable WebSphere MQ security

This section covers all platforms, followed by some tips specific to OS/400.

Security for cluster repository queue managers

1. For each queue manager that will be a cluster repository, enable security for the MQ channel that is the cluster receiver. The SSLPEER is set using a specific Distinguised name attribute of our X509 certificate. Security will not be enabled unless the SSLCIPHR option is specified. Though we only used the organization name on the SSLPEER statement, additonal attributes can also be specififed. See WebSphere MQ Security for more information. Restart the channel, as follows, for the options to take effect.

   Alter channel(TO.QM_RTP) chltype(clusrcvr) SSLPEER('O=KiteSurf_manuf') SSLCIPHR(RC4_MD5_US)

   
   

   Specifying the SSLPEER setting restricts client queue managers from connection, unless they have the matching distinguished names in their certificate. We have specified RC4_MD5_US SSL encryption, which is just one of the encryption algorithms available. See Resources and the MQ documentation for discussions on additonal encryptions.

2. For each cluster repository, the sending channel must also have security enabled. Issue the following command.

   Alter channel(TO.QM_RTP) chltype(clussdr) SSLCIPHR(RC4_MD5_US)

   
   

Security for cluster queue managers

1. For each queue manager in the cluster that is not a cluster controller, only the sending channel must have security enabled for bindings mode. Issue the following command from the runmqsc shell.

   Alter channel(TO.QM_RTP) chltype(clussdr) SSLCIPHR(RC4_MD5_US)

   
   You can display or change the location and name of the keystore MQ used by using the MQ runmqsc shell command, as follows:

   display qmgr alter qmgr sslkeyr('c:\bin\key')

   
   
   
   
2. After making the MQ changes, you should stop and restart all MQ queue managers.
   
   
3. Verify that all channels become active. Use the display chstatus(*) command. See Problem determination and debugging for more information.
   
   
4. If channels are not active, try to restart them.
   
   
5. Restart the channel.

   stop channel(xxxxx), start channel(xxxx)

   
   

OS/400 tips

1. To enable the security options for the MQ channel that is the cluster receiver, you might find the WRKMQM facility on an OS/400 system easier to use than the MQ command shell. The password and user ID are required to be in quotes when altering the queue manager parameters, as shown in Figure 11.
   Figure 11. Enable security options
   
   

   SSLKEYR('/QIBM/UserData/ICSS/Cert/Server/MyKey') SSLKEYRPWD('password') USERID('xxxxx')

   
   
   
   
2. Now restart the queue manager from the MQ command shell.

   STRMQM MQMNAME('queue manager name')

   
   

Back to top

Step 6. Verify, test, and debug

After the certificates are added to the queue manager keystores, and queue managers are restarted, verification of queue manager connectivity to the cluster can take place. On the cluster repository queue managers, issue the command:

Listing 4. Sample command to verify, test, and debug

			display chstatus(*)
AMQ8417: Display Channel Status details.
CHANNEL(TO.QM_TOPSAIL)               XMITQ(SYSTEM.CLUSTER.TRANSMIT.QUEUE)
CONNAME(topsail(1420))               CURRENT
CHLTYPE(CLUSSDR)                     STATUS(RUNNING)
RQMNAME(QM_RTP)

CHANNEL(TO.QM_WPBCH)                 XMITQ(SYSTEM.CLUSTER.TRANSMIT.QUEUE)
CONNAME(wpbch(1420))                 CURRENT
CHLTYPE(CLUSSDR)                     STATUS(RUNNING)
RQMNAME(QM_RTP)

CHANNEL(TO.QM_MBSC)                  XMITQ(SYSTEM.CLUSTER.TRANSMIT.QUEUE)
CONNAME(mbcs(1420))                  CURRENT
CHLTYPE(CLUSSDR)                     STATUS(RUNNING)
RQMNAME(QM_RTP)

CHANNEL(TO.QM_RTP)                   XMITQ(SYSTEM.CLUSTER.TRANSMIT.QUEUE)
CONNAME(r(1420))                     CURRENT
CHLTYPE(CLUSSDR)                     STATUS(RUNNING)
RQMNAME(QM_RTP)

You should see a channel active for every queue manager in the cluster. On each of the cluster queue managers, issue the command:

			display chstatus(*)
CHANNEL(TO.QM_RTP)                  XMITQ(SYSTEM.CLUSTER.TRANSMIT.QUEUE)
CONNAME(rtp(1420))                  CURRENT
CHLTYPE(CLUSSDR)                    STATUS(RUNNING)
RQMNAME(QM_RTP)

You should see at least one sending channel active to the cluster repository queue manager.

If you see a channel in the retrying status, this is usually a sign that something is not set up correctly. Verify that the MQ security settings and certificate have been added to the keystore.

Problem determination and debugging

You can check the log files to investigate any error or warning messages. Log files are at /var/mqm/qmqrs/queuemanager/errors.

The table below lists some common problems we had when implementing MQ security solutions.

Back to top

Conclusion

We hope this article gave you insight into securing a MQ cluster environment for secure JMS transport for WebSphere Application Server applications. We outlined the steps and tools necessary for creating our own certificate authority, signing our request, and setting up a MQ cluster to use our certificates. Although security, in general, is quite complicated, we hope the techniques in this article simplified your MQ cluster security in bindings mode.

Back to top

Acknowledgments

Thank you to David Leigh, John Jones, and Mark Taylor for their contributions as technical reviewers.

Resources

• Linux OpenSSL Project provides an SSL toolkit.
  
  
• Series overview
  
  
• "JMS transport security, Part 1: Use WebSphere MQ to provide a secure JMS transport for WebSphere Application Server" (developerWorks, March 2004) discusses how to apply security among WebSphere Application Server and WebSphere MQ queue managers.
  
  
• "Integrating business processes to streamline the supply chain, Part 1: Use global repositories to manage synchronization of item data" (developerWorks, August 2003) explains supplier and customer architecture and describes item synchronization between suppliers and customers. The article also outlines how to use products in the WebSphere family to take either a buy-to-integrate or build-to-integrate approach to their scenario.
  
  
• WebSphere MQ Security, SC34-6079-01, describes the factors you need to consider when planning to meet your security requirements in a WebSphere MQ environment.
  
  
• "Choosing the right cryptography for your e-business application" (developerWorks, November 2001) discusses the popular cryptographic algorithms in widespread use today and suggests which ones might be best suited to your network or application as part of your Public Key Infrastructure (PKI) solution.
  
  
• Browse for books on these and other technical topics.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Security enablement overview
• Step 1. Create a self-signed certificate
• Step 2. Generate a request for a signed certificate
• Step 3. Sign each certificate request
• Step 4. Create a keystore and import the signed certificates
• Step 5. Enable WebSphere MQ security
• Step 6. Verify, test, and debug
• Conclusion
• Acknowledgments
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere MQ
• Briefing: WebSphere flexible business processes
• Buy: WebSphere MQ