IBM WebSphere Developer Technical Journal: Securing connections between WebSphere Application Server and WebSphere MQ -- Part 1

Using the WebSphere MQ JMS provider

Configure IBM® WebSphere® MQ and IBM WebSphere Application Server to properly make the communication path between the two environments authenticated, authorized, and encrypted.

Sree Anand Ratnasinghe (sreer@us.ibm.com), Certified IT Specialist, IBM

Sree Anand Ratnasinghe is an IBM and Open Group Certified IT Specialist with the Technology Practice team in IBM Software Services for WebSphere (ISSW). She has implemented proofs-of-concept and mentored customers interested in the WebSphere Application Server and the WebSphere family of products. She currently leads technical enablement programs for IBM Consultants as well as curriculum architecture for conferences on WebSphere products. Sree holds an MS in Information Networking from Carnegie Mellon University.



Patrick Nogay (nogay@us.ibm.com), Consulting IT Specialist, IBM Software Services for WebSphere

Patrick Nogay is a Consulting IT Specialist for IBM Software Services for WebSphere.



18 January 2006

Also available in Chinese

From the IBM WebSphere Developer Technical Journal.

Introduction

When configuring a secure environment, you must make sure that every component provides for appropriate authentication, authorization, and encryption of network traffic. When deploying applications to IBM WebSphere Application Server that use IBM WebSphere MQ as a JMS provider, we must concern ourselves with how to ensure that this important communication path is properly secured.

In this article, we will explain how to configure WebSphere MQ and WebSphere Application Server so that the communication path between the two environments is properly authenticated, authorized, and encrypted. The procedure explained here can be used to secure a WebSphere Application Server environment, and to employ MQ SSL server and client authentication between WebSphere Application Server and a local or remote WebSphere MQ queue manager. By default, WebSphere MQ does not provide for secure access when using client mode, which communicates over TCP/IP (See JMS transport security, Part 1 for the differences between client mode and bindings mode). Failure to secure the communications to WebSphere MQ would leave WebSphere MQ open to illegal unauthenticated remote access.

WebSphere Application Server V6 can be connected to WebSphere MQ through one of two options:

  • Setting up WebSphere MQ as a JMS Provider in the WebSphere Application Server administrative console, which is useful when you want to link into a large existing WebSphere MQ infrastructure.
  • Using the WebSphere Application Server service integration bus and MQLink.

This article will explore the former option, and Part 2 will describe the latter. (In the meantime, see this introduction to the service integration bus.)

For more on WebSphere Application Server strengthening security in general, see WebSphere Application Server V6 advanced hardening.

Prerequisites

This article assumes a basic knowledge of WebSphere Application Server V6 Network Deployment concepts and configuration, WebSphere MQ concepts and configuration, and a basic understanding of SSL and security concepts, as covered in Configuring SSL Connections between JMS Clients and the WebSphere MQ JMS Provider; specifically, the sections on security concepts and secure sockets.

The steps in this article were tested using WebSphere Application Server Network Deployment V6.0.2 and WebSphere MQSeries Versions 6.0 and 5.3 on Windows®. Our setup steps focus on WebSphere MQ V6.0, but include information on running the examples with WebSphere MQ V5.3. Your WebSphere Application Server installation should be at V6.0.2 or later to ensure the presence of important JMS fixes. Also, apply WebSphere MQ V6.0 CSD 1, which also contains a key fix for running this example.


Special considerations when installing WebSphere MQ V6

A few important details must be emphasized when installing and configuring WebSphere MQ and setting up connectivity with WebSphere Application Server:

  • WebSphere MQ V5.3 and V6 cannot coexist. When installing WebSphere MQ V6.0, it will overwrite any existing older version of WebSphere MQ.

  • The WebSphere MQ V6 administration user interface is now an Eclipse plug-in. Therefore, the Eclipse 3.0 SDK must be installed prior to installing WebSphere MQ V6. Eclipse 3.0 SDK is located on the install CD-ROM, in the image/prereqs/IES directory.

  • Apply WebSphere MQ CSD 1 or higher.

  • Although the WebSphere Application Server V6 System Management and Configuration Handbook advises to use the WebSphere MQ V5.3 client JAR files shipped with WebSphere Application Server V6 in the directory ${WAS_INSTALL_ROOT}/lib/WMQ, you will need to set your MQ_INSTALL_ROOT environment variable in WebSphere Application Server to point to your WebSphere MQ V6 install root, so that the V6 client JAR files will be used. (The V5.3 JARs will fail sending a JMS message.) Set this variable in the WebSphere Application Server administrative console, under Environment => WebSphere Variables.


Solution overview

Securing the WebSphere Application Server to WebSphere MQ connections requires a number of subtle steps. It is easy to get lost in the details, so we will first outline our approach, then provide detailed steps.

Essentially, what we are trying to achieve is fairly simple: we want WebSphere MQ to require authenticated SSL connections. By doing this, we can ensure that only trusted parties connect to WebSphere MQ. To make this work, we have to configure WebSphere Application Server to use SSL connections (including a client certificate) to connect to WebSphere MQ. As with any SSL communication path, we must make sure that each side of the communication channel:

  • has a personal certificate, and
  • possesses the signing certificate that corresponds to its peer's personal certificate.

That way, when WebSphere Application Server communicates with WebSphere MQ and WebSphere MQ identifies itself, WebSphere Application Server will be able to validate the certificate. The same holds true in reverse. We limit the certificates we accept through two steps:

  • by limiting the number of trusted signers
  • by specifying the exact certificate subject expected.

The rest is just a lot of details, so try not to get too lost in them. To help out, here is a summary of the major steps in the process we will describe in the remainder of this article:

  1. Install the sample application. (The sample application is for demonstration purposes only and is not representative of a production quality JMS application.)
  2. Configure WebSphere MQ and WebSphere Application Server to enable communication. At this point, the communication is insecure.
  3. Create personal certificates for WebSphere MQ and WebSphere Application Server so that they can talk to each other using SSL, and so they can authenticate using certificates.
  4. Share the signing certificates among the various key and trust stores.
  5. Configure WebSphere MQ (V5.3 and V6.0) to accept SSL requests and deny non-SSL connections.
  6. Configure WebSphere MQ to accept requests only from specific clients; in this case, WebSphere Application Server.
  7. Configure WebSphere Application Server to use the updated key stores. (This step is not required if WebSphere Application Server has already been changed to not use the default key store.) Whatever certificate is used by WebSphere Application Server, make sure that the corresponding signer is available in WebSphere MQ's key store.
  8. Update WebSphere Application Server's messaging configuration to use SSL.
  9. Test the results.

Install the sample application

It is not mandatory that you follow the sample application, although it is provided for the convenience of verifying your set up of the ConnectionFactory, queue, and JNDI naming.

The sample application we will use for this article is a simple one that submits a JMS message and browses the contents of a queue. The application is included in the JmsTestEAR.zip download file.

Our sample application is made of these components:

  • BrowseAq.jsp displays the contents of a JMS queue using ConnectionFactory reference jms/SendCFRef and queue reference jms/destQRef.
  • SendMsg servlet invokes a stateless session bean (MessageSender) to send a JMS message using ConnectionFactory reference jms/SendCFRef and queue reference jms/destQRef.

To install the sample application:

  1. Update the MQ install root variable.

    1. Start the application server, and login to the WebSphere Application Server administrative console.
    2. Navigate to Environment => Manage WebSphere Variables.
    3. Edit the variable MQ_INSTALL_ROOT to point to the root directory of your MQSeries client; for example, C:\Program Files\WebSphere MQ. (See the WebSphere Application Server Information Center for configuring WebSphere variables.)
  2. Create a ConnectionFactory named SendCF under the WebSphere MQ JMS Provider, with a JNDI name of jms/SendCF. (Make sure the resource is created either under cell scope, or under the appropriate scope for your application server node. The default scope displayed in the console is that of the deployment manager node.) The key fields here are:

    • Queue manager name: set to the name of the remote WebSphere MQ queue manager.
    • Host: the TCP/IP hostname of the queue manager machine
    • Port: usually 1414
    • Channel: the name of the MQ server connection channel.

    If nothing is specified for the channel, it defaults to SYSTEM.DEF.SVRCONN. Transport type should be changed to CLIENT. Even if the queue manager is co-located with the WebSphere Application Server, you must use client mode to communicate with it because bindings mode does not support SSL connections. (See Figures 1 and 2.)

    Figure 1. MQ as JMS provider ConnectionFactory
    MQ as JMS provider ConnectionFactory
    Figure 2. ConnectionFactory settings NonSSL
    ConnectionFactory settings NonSSL
  3. Create the physical queue FROMWASQ on the queue manager.

    1. On the queue manager machine, verify that the queue manager and the listener are started.
    2. Create a queue called FROMWASQ, by using either runmqsc or WebSphere MQ Explorer. The listener status and port number can be viewed using WebSphere MQ Services.
  4. Create the FROMWASQ administered object in WebSphere Application Server. Create a queue named FROMWASQ under the WebSphere MQ JMS Provider with a JNDI name of jms/destQ. The base queue name is FROMWASQ (the name for it in MQ). It is not necessary to enter any other fields. (See Figures 3 and 4.)

    Figure 3. Creating MQ JMS queue destination
    Creating MQ JMS queue destination
    Figure 4. MQ provider queue destination
    MQ provider queue destination
  5. Install the application.

    1. Install the JmsTestEAR.ear from the download ZIP file, using the application installation wizard and accepting the defaults on all options. Notice that the default bindings set jms/SendCFRef to the jms/SendCF ConnectionFactory and jms/destQRef to the jms/destQ queue, as we defined above. If you get a warning message stating that The resources that are assigned to the application are beyond the deployment target scope, you can ignore this message and Continue.
    2. When the installation is finished, save your changes and restart the server for the configuration changes to take affect.
  6. Test the application

    1. Launch the application from a Web browser with the URL: http://localhost:9080/JmsTestWeb/BrowseAq.jsp. A page similar to Figure 5 will display. This page shows the contents of the FROMWASQ queue, and enables you to submit a JMS message to the queue.
    2. Select Send a JMS Message, then verify the success message shown in Figure 6.
    3. Select Browse Input Queue to see the new contents of the queue.

    This test verifies connectivity between WebSphere Application Server and WebSphere MQ using WebSphere MQ as a JMS provider.

    Figure 5. Browsing queue
    Browsing queue
    Figure 6. SendMsg page
    SendMsg page
  7. Enable WebSphere Application Server global security (if it is not yet enabled).

    The remainder of this article will use the key and trust stores defined in the DefaultSSLSettings SSL repertoire, which are used when WebSphere Application Server global security is enabled in a WebSphere Application Server Network Deployment (ND) environment. To enable global security, refer to the WebSphere Application Server Information Center.

    If you are not testing this application in a WebSphere Application Server ND environment, you will need to set the following JVM custom properties to point to the key and trust stores defined later in this article:

    • javax.net.ssl.keyStore
    • javax.net.ssl.keyStorePassword
    • javax.net.ssl.trustStore
    • javax.net.ssl.trustStorePassword

    See Using the Java Secure Socket Extension in WebSphere Application Server to learn why this is necessary.


Overview of SSL keystore and truststore setup

In our example, WebSphere Application Server is the "client" in the SSL handshake, and WebSphere MQ is the "server". For the WebSphere MQ server certificate, we will obtain a trial certificate from VeriSign, called ibmwebspheremqqm_example. For WebSphere Application Server, we will use a self-signed certificate, called jmsclient. We will perform both server and client authentication. Client authentication will ensure that only those clients (in this case, only WebSphere Application Server) that can prove their identity will be able to connect to the queue manager. Without client authentication, it would be possible for any application on the network to submit or retrieve messages from the WebSphere MQ queue manager.

The following table shows the key repositories that we will be setting up on each node and the artifacts they will contain:

Deployment managerApplication serverWMQ Queue Manager

Keystore

  • jmsclient self-signed certificate and private key

Truststore

  • jmsclient self-signed certificate (public key)
  • VeriSign Trial CA certificate

Keystore

  • jmsclient self-signed certificate and private key

Truststore

  • jmsclient self-signed certificate(public key)
  • VeriSign Trial CA certificate

Combined keystore/truststore

  • jmsclient self-signed certificate(public key)
  • VeriSign Trial CA certificate
  • Server cert for queue mgr issued by VeriSign, labeled ibmwebspheremq<your qmgr name>

Keep in mind that:

  • There could be other artifacts (certificates and keys) in these key repositories, but this table shows only those required for our sample application.

  • A node here is a logical entity; for our simple example, all three of these nodes could be on the same physical computer.

  • For convenience, we have chosen to use self-signed certificates for WebSphere Application Server and CA-issued certificates for WebSphere MQ. This is not a requirement; you can use either type of certificate for either side.

In the case of WebSphere Application Server, the truststore is used for validation (public key), and the keystore is used for private keys (public/private key pairs). In our example, we will use the DefaultSSLSettings repertoire (configuration), but we will change the default names of the keystore and truststore; DummyServerKeyFile and DummyServerTrustFile contain dummy server keys common to all WebSphere Application Server installations and should never be used in production.

At various points, the WebSphere Application Server deployment manager and node agent communicate with one another over SSL connections. As is expected, server authentication is performed when a client opens a connection to a server (WebSphere Application Server does not use client authentication by default). When, for example, the deployment manager contacts a node agent, the node agent presents its certificate (jmsclient) to the deployment manager, and the deployment manager validates it in the usual way against its truststore (specifically, it finds the jmsclient signer). This is why we update the WebSphere Application Server key rings to ensure that they still work during this initial handshake.

WebSphere MQ SSL handshake flow:

  1. When JMS connection factory is initialized, WebSphere Application Server opens an SSL connection to WebSphere MQ, which results in it sending its jmsclient certificate.

  2. WebSphere MQ queue manager validates the WebSphere Application Server client certificate using the jmsclient public key present in the queue manager's keystore.

  3. WebSphere MQ uses the SSLPEER attribute on the channel to check which distinguished name (DN) values of client certificates it can accept. In this case, the WebSphere Application Server client certificate matches the DN cn=jmsclient, ou=ISSW, o=IBM, c=US (which is listed on the SSLPEER attribute, so it is a trusted identity to WebSphere MQ). Without SSLPEER being set, WebSphere MQ could accept any other client certificate issued by the VeriSign trial CA.

  4. Queue manager sends its server certificate, issued by the VeriSign trial CA, to WebSphere Application Server.

  5. WebSphere Application Server receives the WebSphere MQ server certificate, looks in its truststore, and uses the VeriSign trial CA certificate to verify the server certificate. If the SSL peer name is set on the WebSphere Application Server JMS connection factory, then it must match the DN of the WebSphere MQ certificate.

  6. The SSL handshake is now complete.


Obtaining digital certificates

As mentioned above, we will use a demonstration certificate obtained from VeriSign for the WebSphere MQ server certificate, and a self-signed certificate for the client certificate.

Certificates are stored in repositories that vary based on the operating system and the tools used to access them. We use the IBM key management tool ikeyman where possible for certificate storage and retrieval.

VeriSign is a certification authority that offers demonstration certificates. Next, we will walk through the steps for obtaining a certificate for the WebSphere MQ queue manager. (If you already have a certificate for your queue manager, you can use that instead and skip to the next section.

To obtain a demonstration certificate from VeriSign, you must first generate a Certificate Signing Request (CSR). Instructions for generating the CSR are on the VeriSign Web site and repeated here for WebSphere Application Server. Be aware that we assume a Network Deployment installation of WebSphere Application Server; otherwise your default keystore behavior may be different. (See Using the Java Secure Socket Extension in WebSphere Application Server for more information.)

  1. Start key management utility ikeyman by opening WebSphere MQ Explorer and right-clicking on IBM Websphere MQ, then select Manage SSL Certificates.

  2. We will use the default location for the key database, which is <mqroot>\Qmgrs\<qmgrname>\ssl. The default name is key.kdb. Create the key database file by selecting Key Database File => New.

  3. Accept the default key database type of CMS.

  4. For Location, browse to <mqroot>\Qmgrs\<qmgrname>\ssl\ directory and call the file key.kdb (Figure 7).

    Figure 7. Create new key database for queue manager
    Create new key database for queue manager
  5. Select OK and, when prompted, enter an appropriate password. Select the option to stash the password to a file.

  6. Select Create => New Certificate Request. The Create New Key and Certificate Request panel displays (Figure 8).

  7. Enter a value for the Key Label name as ibmwebspheremq<yourqmgrname_inlowercase>. This will end up being the certificate name. Also enter values for Common Name (your host plus domain name), Organization, and all remaining fields that are labeled optional. You can leave the default Key Size of 1024. Enter a filename to store the request or leave the default certreq.arm. The certificate label name must follow this convention if using WebSphere MQ V6, otherwise the queue manager will not know which server certificate to use.

    Figure 8. ikeyman certificate request dialog
    ikeyman certificate request dialog

    Although the tool lists several of these fields as being optional, they are not considered optional to VeriSign. If values for these fields are not provided, you might get an error message such as Error 9508 - Certificate Signing Request contains empty field(s). (You may also need to spell out the name of the State/Province. A state name such as TX may be considered invalid by VeriSign, in which case you would receive the error The state value used in the submitted CSR is not valid.)

  8. Open the CSR file (certreq.arm) using a text editor that does not add extra characters (such as Notepad). We will use the contents of this file later in the demo certificate enrollment process.

Now that we have generated a CSR, we will use it to request a demo certificate.

  1. In your Web browser, launch the URL: http://www.verisign.com/products-services/security-services/ssl/buy-ssl-certificates/free-trial/index.html.

  2. On the Verisign Free SSL Certificate Trial page, click on Try Now (Figure 9).

    Figure 9. Get a VeriSign trial certificate
    Get a VeriSign trial certificate
  3. Click Continue. On the next panel, complete the technical contact information. The certificate will be sent to the e-mail address you provide. Click Continue again.

  4. On the Enter Certificate Signing Request form, select Server not listed for Select Server Platform, and then paste the contents of certreq.arm into the text area (Figure 10).

    Figure 10. Paste certificate signing request
    Paste certificate signing request
  5. Enter a challenge phrase that will not be the server's private key password, then click Continue.

  6. Verify the CSR information and click Accept.

  7. Within an hour you should receive an email with information on obtaining your trial 14 day certificate. Because this is a trial certificate, you will need to install the test CA root into your truststore so it can be used later in your servers. Follow the link in the email to the test CA root.

  8. We will not be importing the certificate into our Web browser; we will continue to use ikeyman, so follow the link to Secure Site Trial CA Root Certificate, and save the certificate contents into a .cer file (such as TrialCARoot.cer).

  9. Save the certificate contents sent to you by VeriSign into a .cer file (such as MQServer.cer). The certificate contents will be located at the bottom of the email from VeriSign, between:

    -----BEGIN CERTIFICATE-----

    and

    -----END CERTIFICATE-----

  10. Return to ikeyman to import the Trial CA root cert. Keep in mind that to successfully use the certificate sent by VeriSign, you must import both the VeriSign demonstration root certificate and the e-mailed certificate into the same key file from which you generated the certificate request. Ikeyman gives errors when you try to import the VeriSign certificate into a key file that does not contain the certificate request. Select Signer Certificates => Add from the drop-down tab.

  11. Accept the default Data type of Base 64 encoded ASCII Data.

  12. Browse to the location of your TrialCARoot.cer file and select OK.

  13. For the certificate label, enter something meaningful, such as VeriSign Test CA Root.

  14. Your certificate should now appear under Signer Certificates (Figure 11). At this point, it is a good practice to delete all other signer certificates from your truststore because each signer certificate is an issuance of trust.

    Figure 11. ikeyman test CA root
    ikeyman test CA root
  15. Import the WebSphere MQ server certificate. Select Personal Certificates => Receive from the drop-down tab. Accept the default data type, then browse to the location of your MQServer.cer file. Click OK. The certificate should now appear under Personal Certificates.


Create new keystore, truststore, and self-signed client certificate

If you already have a certificate for WebSphere Application Server (not the dummy server certificate), skip this section and use your current certificate.

We will create a new keystore and truststore rather than use the default DummyServerKeyFile.jks and DummyServerTrustFile.jks, because it is not a good security practice to use these defaults.

  1. Switch to the version of ikeyman that comes with WebSphere Application Server by launching <was root>\bin\ikeyman.bat.

  2. From the ikeyman menu, select Key Database File => New.

  3. On the Open dialog, for key database type, accept the default value of JKS (Java™ keystore).

  4. Save the file as WASServerKeyFile.jks in the <wasroot>\profiles\AppServer01\etc directory.

  5. When prompted to create a keystore password, select a valid password and confirm it.

  6. Delete all signer certificates from the Signer Certificates tab. As mentioned earlier, limiting signers limits risk.

  7. Switch to Personal Certificates, and click New Self-Signed.

  8. Enter data in the Create New Self-Signed certificate dialog (Figure 12) with values appropriate to the location of your application server. Set Key Label to a value of your choice.

    Figure 12. Create self signed certificate
    Create self signed certificate

    The jmsclient certificate should now appear under the ikeyman Personal Certificates tab.


Export the self-signed certificate

At this point, we have created a self-signed certificate for the WebSphere Application Server JMS client (a private key and certificate pair). We now need to extract the jmsclient certificate and place it in the trust file for WebSphere Application Server and WebSphere MQ, so that they can both use it as a signer.

  1. First, we will export the personal certificate. With the ikeyman database open to the WASServerKeyFile, and the jmsclient certificate selected, click Extract Certificate. This exports only the certificate (not the private key). Save the certificate and give it an appropriate name, such as was_jms_client.arm.

  2. While the WASServerKeyFile is used for private keys, we need a trust file which will be will be used for validating signers. We will now create this file and call it WASServerTrustFile. Using ikeyman, create a new key database by selecting Key Database File => New and call it <wasroot>\profiles\appserver01\etc\WASServerTrustFile.jks.

  3. Switch to the Signer Certificates tab and delete all unnecessary signers.

  4. Import the jmsclient certificate into the WebSphere Application Server truststore: switch to the Signer Certificates tab, press the Add button, browse to the location where you saved was_jms_client.arm, and import the certificate.

  5. Import the jmsclient certificate into the WebSphere MQ truststore: open ikeyman against <mq root>\qmgrs\<your qm>\ssl\key.kdb, switch to the Signer Certificates tab, press the Add button, browse to was_jms_client.arm, and import the certificate.

  6. Don't forget that we also need to import the VeriSign Test CA Root Certificate into the WebSphere Application Server truststore, so that the application server can validate the queue mgr certificate during the SSL handshake. Open ikeyman against the WASServerTrustFile again, browse to the location where you saved the TrialCARoot.cer, and import it.

Congratulations! All the certificates are now in the right places for your application server key and trust files. To verify, your application server key file should contain the jmsclient certificate, and the application server trust file should contain two signer certificates, as shown in Figure 13.

Figure 13. WASServerTrustFile
WASServerTrustFile

Configure the WebSphere MQ V6 queue manager for SSL

  1. In WebSphere MQ Explorer, start your queue manager.

  2. Right click on the <queue manager> => Properties => SSL.

  3. In the SSL properties, verify that the location of the key repository matches your key database name and location. For example: C:\Program Files\IBM\Wmq\qmgrs\QM_EXAMPLE\ssl\<key>. Here, <key> is the database name. In the ssl directory there should be four files:

    • key.kdb
    • key.sth
    • key rdb.
    • key.

At this point, then, the MQ key repository contains no signers except for the WebSphere Application Server signing certificate and the VeriSign test certificate (which would not be there in a production environment).


Configure the WebSphere MQ V6 queue manager for SSL

If using WebSphere MQ V5.3 for Windows, you need to perform these steps because the keystore format for WebSphere MQ V5.3 for Windows is not compatible with ikeyman. Also, the label for the certificate for WebSphere MQ V5.3 for Windows is not required to be ibmwebspheremq<yourqmgrname_inlowercase>:

  1. Use ikeyman to open the key repository (if you closed it earlier) that was used to import the VeriSign trial certificate (key.jks).

  2. Select Personal Certificates from the drop-down list, then select the demo certificate provided by VeriSign.

  3. Press the Export/Import button, select action type Export Key, change Key file type to PKCS12, and then browse to a location to store your private key (for example MQServer_privateKey.p12).

    Figure 14. WebSphere MQ 5.3 exporting Verisign private key
    WebSphere MQ 5.3 exporting Verisign private key
  4. Provide a password to protect your private key file.

  5. From the WebSphere MQ Explorer, right-click your queue manager, and select Properties.

  6. On the SSL tab, press Manage SSL Certificates button.

  7. Select all certificates not being used (in our case, all of them) and remove them from the keystore. This is done to limit the WebSphere MQ trust domain to only those clients presenting a certificate whose signer is the one we expect: WebSphere Application Server.

  8. Press Add.

  9. Select Import from a file and browse to the location of the private key file MQServer_privateKey.p12. Select it and enter the password you provided above.

  10. Select the MQServer certificate from VeriSign and press the Assign button.

  11. On the next dialog, select the MQServer certificate again and press Assign, then OK. You now have assigned the VeriSign private certificate for your MQ 5.3 queue manager.

  12. Now, add the WebSphere Application Server client signer by clicking the Add button, then select Import from a file, browse to was_jms_client.arm, and add the certificate.

  13. Continue with the next steps for configuring your channel.


Configure MQ SSL channel

Next, we will configure the channel with which the JMS client will communicate with the queue manager for SSL:

Note that "CN", "OU", "O", and so on, must be uppercase. Also note that PC (postal code) is not an accepted part of the DN in WebSphere MQ. Finally, although some areas of the documentation may mention that the DN values need to be in quotes, we found in our testing that quoted values such as CN='jmsclient' did not work in WebSphere MQ V6 for Windows.

  1. In MQ Explorer, select your queue manager, then select the Advanced folder, then the Channels folder, and right-click. Select New => Server Connection Channel.

  2. On the next dialog, enter a name for the channel (we use SSL.SVRCONN), then click Next.

  3. Switch to the SSL tab view, and specify a cipher specification. For this example, we will use RC4_MD5_US, but you should evaluate your organization's security needs and consider alternative, stronger ciphers if necessary. Notice that the default setting for Authentication of parties initiating connection is Required (Figure 15).

    Figure 15. Specify the new server connection channel
    Specify the new server connection channel
  4. We need to prevent the queue manager from accepting a certificate from simply any client that has a certificate issued by one of the CA's in the queue manager's keystore. To do so, we need to set the SSLPEER parameter on the channel. This parameter is used to check the Distinguished Name (DN) of the certificate from the client at the other end of a WebSphere MQ channel. If the DN received from the client does not match the SSLPEER value, the channel will not start. Set this by checking Only accept certificates with Distinguished Names matching these values, and enter the DN value that matches the client certificate, as shown in Figure 16. In our case, this would be: CN=jmsclient,OU=issw,O=ibm,C=US (based on how we generated the self-signed client certificate).

We have now configured the server connection channel that the JMS client will use to communicate with the queue manager. If you have not yet done so, you should tighten all channels to require SSL (or remove the channel), including channels such as SYSTEM.DEF.SVRCONN.

Certificate security warning

As you configure certificate keystores for WebSphere MQ, remember that each signing certificate in the keystore represents trust between you and that signer (typically a CA). In the most basic case, placing any signing certificate in the WMQ Server keystore without DN verification means that WebSphere MQ should accept all connects from any party that has a certificate from that CA. Unless you are using self-signed certificates or have a dedicated CA just for WebSphere MQ, that is almost completely insecure. Thus, we restrict the certificates to those with the matching DN value that we specify. That ensures that the identity in the certificate is really the identity that we expect. But, there is a catch. If two CA's were to issue certificates with the same DN, our security would again be compromised. That 'should not happen since a reputable CA wouldn't do such a thing, but two different CAs might issue certificates with the same subject, which is why you need to remove all of the certificates except for the certificate from the CA you expect.


Configure the WebSphere Application Server JMS client

This section describes configuring WebSphere MQ as a JMS provider. Another way to connect WebSphere Application Server V6 to WebSphere MQ is using the service integration bus, which is described in Part 2.

When WebSphere MQ is configured as a JMS provider, it will use the default key and trust stores for the application server. When global security is enabled in a WebSphere Application Server ND cell, the default key and trust stores are set in the default SSL repertoire configuration.

Distributing the key and trust files to other nodes

Now we need to copy the application server WASServerKeyFile and WASServerTrustFile to the deployment manager node, and to any other application server nodes that may be in your cell. When an application server talks to another application server or the deployment manager after this is done, the application server will present its new jmsclient certificate from the key file to the other party which will validate it against its trust file.

The server keyfile must contain exactly one personal key so that, when any WebSphere Application Server component tries to accept an SSL connection from another, it has only one identity to use. All other trust stores in the cell must contain the corresponding signer. Since the keyfile for the appserver01 node was modified to use a new personal key, this means that the deployment manager must possess the corresponding signer if the deployment manager initiates connections to the servers. If the servers initiate connections to the deployment manager then the servers need to have the signer that corresponds to the deployment manager personal key (which they already have).

Copying the application server WASServerKeyFile.jks and WASServerTrustFile.jks to the deployment manager and the other nodes is the simplest way to accomplish this. Copy these files to <was_root>\profiles\dmgr\etc and to the profile directory of any other application server nodes that may be in your cell.

We now need to edit the WebSphere Application Server default SSL configuration to point to the new files that we have created:

  1. In the WebSphere Application Server administrative console, navigate to Security => SSL. You should see two SSL configurations (DMNode/DefaultSSLSettings, and <yourAppServernode>/DefaultSSLSettings), more if you have other nodes.

  2. Select DMNode/DefaultSSLSettings. Change the Key file name to ${USER_INSTALL_ROOT}/etc/WASServerKeyFile.jks, and the Trust file name to ${USER_INSTALL_ROOT}/etc/WASServerTrustFile.jks. Update the Key file password and the Trust file password to the values you chose, as in Figure 16.

    Figure 16. Update DefaultSSLSettings repertoire
    Update DefaultSSLSettings repertoire
  3. When finished, click Apply.

  4. Make the same changes for SSLSettings for your application server node(s). When done, save the changes.

  5. You will need to restart the deployment manager, node agents, and your application servers for these changes to take affect.

Although not necessary for our example, if you are using any client programs such as wsadmin or a J2EE client, you need to update the client trust files on all nodes (DummyClientTrustFile by default) to contain the jmsclient certificate. Different clients use different configuration files: IIOP-based clients (such as a J2EE client) use the sas.client.props file; SOAP-based clients (such as wsadmin) use soap.client.props. If you are using any client application, you will need to edit its respective configuration file to specify the revised trustStore information. You should find the appropriate file (in the profile directory of each node), look for, and edit the following properties as appropriate for your environment:

com.ibm.ssl.trustStore=C:/Program Files/IBM/WAS6/profiles/Appserver01/etc/DummyClientTrustFile.jks
com.ibm.ssl.trustStorePassword={xor}CDo9Hgw\=

You will need to specify the name for your new client trust file (which you need to create using ikeyman) and, of course, the password for that trust file. You can use PropFilePasswordEncoder to encode passwords in the properties files, as described in the WebSphere Application Server Information Center.

Now that our key files are setup and SSL configurations edited, we need to configure SSL on the WebSphere Application Server and WebSphere MQ sides.


Define the ConnectionFactory and queue objects to WebSphere Application Server

From the JMS client's perspective, the client code is not aware of whether or not SSL is being used for the connection. The SSL configuration is done in the ConnectionFactory definition. We will now update the existing MQ connection factory that we created earlier to use SSL.

  1. Expand Resources => JMS Providers => WebSphere MQ. Under Additional Properties select WebSphere MQ connection factories (Figure 17).

    Figure 17. WebSphere MQ connection factory
    WebSphere MQ connection factory
  2. Select the existing SendCF ConnectionFactory so you can update it.

  3. Update the Queue manager, Port, and Channel to match the secured server connection defined in WebSphere MQ. Scroll to the middle of the ConnectionFactory properties and set the SSL cipher suite to SSL_RSA_WITH_RC4_128_MD5. (Again, evaluate your security needs and consider the use of stronger ciphers.)

  4. To ensure you are communicating with the correct WebSphere MQ instance, set the SSL peer name value to the DN of the MQ Server certificate, for example:

    CN=ibmwebspheremqqm_example, OU=Terms of use at www.verisign.com/cps/testca (c)05, 
    OU=ISSW, O=IBM, L=Dallas, ST=Texas, C=US

    then select OK. (If you are having trouble determining the DN, when you test your application and the SSL handshake fails, you can check the application server's SystemOut.log and find a very useful MQException:

    MQJE067: Peer name CN=.. , C=US did not match requested name CN=

    You can also view the full DN of the certificate using ikeyman.)

  5. If the SSL peer name is not set, WebSphere Application Server will not validate the WebSphere MQ certificate and will connect to any server presenting any valid certificate.

    Figure 18. ConnectionFactory SSL updates
    ConnectionFactory SSL updates
  6. If the secured queue manager does not have a queue defined named FROMWASQ, then update the WebSphere MQ queue destination named FROMWASQ by selecting it and changing the Base queue name to match the queue on the secured QueueManager.

  7. Save the settings and restart the application server to pick up the configuration changes. The JmsTestEAR application will remain mapped to JMS resources jms/SendCF and jms/destQ.


Test the sample application

All the setup is now complete, and you should be able to restart WebSphere Application Server and test the application as before, using URL: http://localhost:9080/JmsTestWeb/BrowseAq.jsp.

How to verify that SSL is working:

If you change the ConnectionFactory jms/SendCF using the WebSphere Application Server admin console to no longer include an SSL cipher suite (or a different one), then after restarting your application server you will get a JMS connection error because the handshake between the client and the queue manager will fail.

To verify that client authentication is working:

If you remove the public key from the queue manager's truststore (under signer certificates, remove was_jms_client), you will get a JMS connection error again.

To verify the client certificate authorization (which specific certificates are accepted), change the DN for the channel on the SSL tab to something other than what is on your certificate. The certificate should not be accepted.


Configure WebSphere MQ V5.3 for Windows

If you are using WebSphere MQ V5.3 instead of WebSphere MQ V6.0, then make these changes:

  1. Update the MQ_INSTALL_ROOT environment variable for each node to point to your WebSphere MQ V5.3 installation directory.

  2. Since WebSphere MQ V5.3 does not use ikeyman for configuring its key and trust stores, use WebSphere Application Server ikeyman to create the Verisign certificate request. The same database used to create the request must be used to import the VeriSign certificates and later used to export the certificates. There is no restriction on the label name for the WebSphere MQ certificate when using V5.3.

  3. The WebSphere MQ V5.3 Explorer is used for managing SSL certificates for the secured queue manager. From the queue manager properties, select the SSL tab and Manage SSL Certificate. Remove all certificates that are currently there and add the VeriSign private certificate and was_jms_client public key. Assign the VeriSign certificate to the queue manager.


Troubleshooting

  • You can enable logging of the SSL handshake by adding the following property to your application server's JVM custom properties: javax.net.debug=true. The SystemOut.log for your application server will contain SSL exchanges, but if global security is enabled, you may get much more logged than expected.

  • If you have trouble with rollbacks of "in doubt" transactions and WebSphere Application Server cannot connect to WebSphere MQ (and this is a test system), try deleting the tranlog directory for your application server and restart the application server to see if the WebSphere MQ SSL connection can be made if there are no prior transaction problems. The in-doubt transactions may be symptomatic of other problems and should still be investigated.

  • If you receive this error message when starting the WebSphere Application Server deployment manager or node agent:

    org.omg.CORBA.COMM_FAILURE: CAUGHT_EXCEPTION_WHILE_CONFIGURING_SSL_CLIENT_SOCKET: JSSL0080E:
    javax.net.ssl.SSLHandshakeException - The client and server could not negotiate the desired 
    level of security.  Reason: com.ibm.jsse2.util.g: No trusted certificate found

    then either the certificates in the deployment manager and node agent keyring files may not be in sync, or the files that you expect are not actually being used. Check the <was_root>\profiles\dmgr\config\cells\<yourcell>\security.xml and <was_root>\profiles\AppServer01\config\cells\<yourcell>\security.xml files, and verify that the values of "SecureSocketLayer_1" keyFileName and "SecureSocketLayer_xxxx" (where x is a string of digits) keyFileName match the values that you set in the WebSphere Application Server administrative console for the SSL repertoire key and trust files.


Conclusion

This article demonstrated how to configure SSL between WebSphere MQ and WebSphere Application Server when using WebSphere MQ as a JMS provider. Part 2 describes how to configure secure connections between WebSphere Application Server V6 and WebSphere MQ when using the MQ link from the service integration bus.


Acknowledgements

We would like to thank Keys Botzum, Tom Johnson, Martin Smithson, Graham Hopkins, David Currie, Bobby Woolf, and Roland Barcia for their extensive technical assistance and expertise. Also Kareem Yusuf for authoring the original article which serves as the basis for this paper. Portions of this article (Descriptions of SSL) are reprinted with permission from Kareem Yusuf.


Download

DescriptionNameSize
Code sampleJmsTestEAR.zip  ( HTTP | FTP )44 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=102216
ArticleTitle=IBM WebSphere Developer Technical Journal: Securing connections between WebSphere Application Server and WebSphere MQ -- Part 1
publish-date=01182006