SSL configuration in WebSphere Message Broker

What this exercise is about

This article shows you how to set up SSL communication in WebSphere Message Broker on Windows System. It also includes an example of testing the SSL using a flow.

In the first part of the exercise you will go through steps involved in configuring SSL

In the second part of the exercise you will go through How to Configure Message Broker to serve HTTP/HTTPS requests

In the third part of the exercise you will go through How to Set up ports exclusively for execution groups

In the fourth part of the exercise you will go through How to Set up JVM attributes for execution groups

In the fifth part of the exercise you will go through Testing SSL with MB.

What you should be able to do

At the end of the exercise you will be able to :

• Generate a .jks keystore.
• Generate a certificate signing request (CSR) for the existing keystore.
• Import a root or intermediate Certificate Authority (CA) certificate to the existing keystore of extension “.crt”.
• Import a signed certificate of extension “.cer”to the existing keystore.
• Validate the certificate details.
• Testing the SSL

Introduction

     Java Keytool is a key and certificate management utility which allows users to manage their own public/private key pairs and certificates. It also allows users to cache certificates. Java Keytool stores the keys and certificates in what is called a keystore. By default the Java keystore is implemented as a file. It protects private keys with a password. A Keytool keystore contains the private key and any certificates necessary to complete a chain of trust and establish the trustworthiness of the primary certificate.

    Each certificate in a Java keystore is associated with a unique alias. When creating a Java keystore you will first create the .jks file that will initially only contain the private key. You will then generate a CSR and have a certificate generated from it. Then you will import the certificate to the keystore including any root certificates. Java Keytool also several other functions that allow you to view the details of a certificate or list the certificates contained in a keystore or export a certificate.

Part 1: Steps for Configuring SSL

Step 1:- Generate a Java keystore and key pair

keytool -genkey -alias mydomain -keyalg RSA -keystore keystore.jks -keysize 2048

Inorder to issue this command,open IBM Command console & change the path as per your requirement

where

<Keytool> is a key & certificate management utilityu tool

<genkey> Generate a pair of keys ( Private key and Public key)

<alias> is the alias name used for the private key for security.

<keyalg> identifies the algorithm we used

<keystore> identifies the keystore.

<keysize> specifies the size in bits format.

2048 is the bit structure used.It also depends on the OS used.

On issuing this command it prompts for Keystore password.Then it asks for some more security questions.This command generates a keystore.jks file in the specified path.

Step 2:- Generate a certificate signing request (CSR) for an existing Java keystore

keytool -certreq -alias mydomain -keystore keystore.jks -file mydomain .csr

After entering the password,if no errors were found within the command,it moves to path without showing any message ,otherwise it displays error message like “keyttool error”

where

<certreq> Location where csr file is stored.Used to generate a certificate request to send to the certificate authority

<alias> is the alias used for the key. By default set to “mykey”.

<keystore> using the -genkey command to generate a key pair (public and private key)

<file> indicates the file name with path.

Step 3:- Import a root or intermediate CA certificate to the existing keystore

Here we have to send the .csr file to the Certificate Authority team to get the certificates generated.For this visit www.verisign.com & get free trials.Then it asks for some personal details like our email id & server name.Then we have to upload our csr file.The generated crt file will then be sent to our email id.

After receiving the signed certificate from the CA, save it in notepad with extension.crt & proceed with the following steps:

keytool -import -trustcacerts -alias root -file Cert.crt -keystore MBV7Broker.jks

where

<keystore> file name is MBV7Broker.jks and the intermediate CA cert is Cert.crt.This file can be generated by using third party CA's like GlobalSign and VeriSign.

<trustcacerts> used to provide additional certificates for the chain of trust, namely the certificates

<file> indicates the file name with path.

<keystore> using the -genkey command to generate a key pair (public and private key)

<printcert> Reads the certificate from the file cert_file, and prints its contents in a human-readable format.

Step 4:-Import a signed primary certificate to an existing Java keystore

keytool -import -trustcacerts -alias MBV7Broker -file certificate.der -keystore MBV7Broker.jks

where

<trustcacerts> used to provide additional certificates for the chain of trust, namely the certificates

Step 5:- Validate the certificate details

To List all certificates available in the keystore

keytool -list -keystore miracle.jks

Part 2 :- Configuring Message Broker to serve HTTP/HTTPS requests

1. To List the broker registry

mqsireportproperties MBV7Broker -o BrokerRegistry -r

where

o – objects

r – includes listing of child elements also if present.

2. Import root certificates and server certificates to the broker truststore

keytool -import -trustcacerts –alias Certificate.Cert -file “C:\IBM\MQSI\7.0\Cert.crt”

-keypass <password> -keystore cacerts –storepass changeit

3. Enable SSL on the broker instance

This command enables SSL for the HTTP listener object:

mqsichangeproperties MBV7Broker -b httplistener -o HTTPListener -n enableSSLConnector -v true

4. Modify broker properties to point to the keystore file

mqsichangeproperties MBV7Broker -b httplistener -o HTTPSConnector -n keystoreFile -v “C:\IB\MQSI\7.0\ MBV7Broker.jks”

5. Add broker keystore file to broker registry

mqsichangeproperties MBV7Broker -o BrokerRegistry -n brokerKeystoreFile

-v “C:\IBM\MQSI\7.0\ MBV7Broker.jks”

6. Add broker truststore file to broker registry

mqsichangeproperties MBV7Broker -o BrokerRegistry -n brokerTruststoreFile -v “C:\IBM\MQSI\7.0\jre16\lib\security\cacerts”

7. Set the registry password for keystore

mqsisetdbparms MBV7Broker -n brokerTruststore::password -u temp -p changeit

8. Associate the broker with keystore password

mqsichangeproperties MBV7Broker -b httplistener -o HTTPSConnector -n keystorePass -v <password>

9. Associate a port for broker to serve HTTPS requests

mqsichangeproperties MBV7Broker -b httplistener -o HTTPSConnector -n port -v 7094

10. Associate a port for broker to serve HTTP requests

mqsichangeproperties MBV7Broker -b httplistener -o HTTPConnector -n port -v 7091

11. Change the JVM attributes

You can change JVM heap sizes according to your requirements by modifying the object ComIbmJVMManager:

mqsichangeproperties MBV7Broker -o ComIbmJVMManager -n jvmMaxHeapSize -v 1048576000

mqsichangeproperties MBV7Broker -o ComIbmJVMManager -n jvmMinHeapSize -v 134217728

12. Verify the broker properties

mqsireportproperties MBV7Broker -b httplistener -o HTTPConnector -n port 7091

mqsireportproperties MBV7Broker -b httplistener -o HTTPSConnector -n port 7094

13. Restart the broker

 mqsistop MBV7Broker
 mqsistart MBV7Broker
 mqsistop MBV7Broker
 mqsistart MBV7Broker

Part 3:- Setting up ports exclusively for execution groups

To serve the HTTP requests, a port needs to be configured at the execution group (EG) level.

1. Configure the SSL protocol
First tell the EG which SSL protocol type are using. SSLv3 is the default SSL protocol.

mqsichangeproperties MBV7Broker -e <EG Name> -o HTTPSConnector -n sslProtocol -v SSLv3

2. Associate the keystore file with the broker EG

The keystore file created earlier needs to be associated with the broker instance in order for it to know its repository file. To avoid confusion, do not have multiple keystore files on the server.

mqsichangeproperties MBV7Broker -e default -o HTTPSConnector 
    -n keystoreFile -v “C:\IBM\MQSI\7.0\MBV7Broker .jks”

3. Associate the keystore type.

You should configure the keystore type on the broker, because there are several other keystore types supported by broker. Information on these types is outside the scope of this article, which uses a Java Keystore (JKS).

mqsichangeproperties MBV7Broker -e default -o HTTPSConnector -n keystoreType -v JKS

4.Associate the keystore password

Associate the keystore password to the broker so that it can save it in its registry for authentication purpose, which is required when querying the new requests:

mqsichangeproperties MBV7Broker -e default -o HTTPSConnector -n keystorePass -v <password>

Part 4 : Setting up JVM attributes for execution groups

When an execution group is started in WebSphere Message Broker, it creates a JVM that is primarily used by the IBM primitive nodes that make use of Java functionality. The DataFlowEngine JVM can be configured either by passing parameters to it directly, or through the broker. When using the broker JVM by any of the means above, the DataFlowEngine memory may continue to grow and may cause resource problems. Use the following few commands to set up your min and max JVM heap size:

mqsichangeproperties MBV7Broker -e default -o ComIbmJVMManager -n keystoreFile 
    -v “C:\IBM\MQSI\7.0\MBV7Broker.jks”


mqsichangeproperties MBV7Broker -e default -o ComIbmJVMManager -n keystoreType 
    -v JKS

mqsichangeproperties MBV7Broker -e default -o ComIbmJVMManager -n keystorePass 
    -v brokerKeystore::password


mqsichangeproperties MBV7Broker -e default -o ComIbmJVMManager -n truststoreFile 
    -v “C:\IBM\MQSI\7.0\MBV7Broker.jks”

In this command, the keystore file type is associated with the ComIbmJVMManager object.

mqsichangeproperties MBV7Broker -e default -o ComIbmJVMManager -n truststoreType -v JKS

When querying new requests, associate the keystore password with the broker’s ComIbmJVMManager object so that it can be saved it in its registry for authentication purposes:

mqsichangeproperties MBV7Broker -e default -o ComIbmJVMManager -n truststorePass 
    -v brokerTruststore::password

Testing SSL using a Message flow:-

Message Flow Creation

Request Flow

Inorder to fire a message,we used MQInput node where we give some BLOB data to fire the flow.The HTTPRequest invokes the service at http://localhost:7091/test1 where 7091 is the port no. which we have configured earlier using commands.

Node Name	Node type	Properties
MQInput	MQInput	(Basic) Queue Name : q1 (Input Message parsing) Message Domain : BLOB : For messages with an unspecified format (Security) Identity Token Type : Transport Default
HTTPRequest	HTTPRequest	(Basic) Web service URL : http://localhost:7091/test1 (Input Message parsing) Message Domain : XMLNSC : For XML messages (namespace aware, validation, low memory use) (SSL) SSLProtocol:SSLV3 Enable SSL Certificate Hostname Checking - check this box (Advanced) Response Message Location in Tree - OutputRoot.BLOB
Compute	Compute	Default Properties
MQOutput	MQOutput	(Basic) Queue Name : q2

Response Flow

HTTPInput	HTTPInput	(Basic) Path Suffix for URL:/test1 Use HTTPS - check it
HTTPReply	HTTPReply	Default Properties

Configuring an HTTPRequest node to use SSL

Creating a message flow to make HTTPS requests

The following message flow creates a generic message flow for converting a WebSphere® MQ message into an HTTP Request:

1. Create a message flow with the nodes MQInput->HTTPRequest->Compute->MQOutput.
2. On the MQInput node, set the queue name to “q1” and create the WebSphere MQ queue.
3. On the MQOutput node, set the queue name to “q2” and create the WebSphere MQ queue.
4. On the HTTPRequest node, set the Web Service URL to point to the HTTP server to call. To call the HTTPInput node, use http://localhost:7091/test1.
5. On the Advanced properties tab of the HTTPRequest node, set the Response message location in tree property to OutputRoot.BLOB.
6. On the Compute node, add the following ESQL code:
   

The message flow is now ready to be deployed to the broker.

Configuring HTTPInput and HTTPReply nodes to use SSL

For this we have to Configure the HTTPInput and HTTPReply nodes to communicate with other applications that use HTTPS by creating a keystore file, configuring the broker to use SSL, and creating a message flow to process HTTPS requests.

Creating a message flow to process HTTPS requests

Create a simple message flow to use HTTPS by connecting an HTTPInput node to an HTTPReply node. The two most important properties to set on the HTTPInput node are:

• Path suffix for URL; for example, /* or /testHTTPS.
• Use HTTPS.
  

/* means that the HTTPInput node matches against any request that is sent to the HTTP listener on a designated port.
You can now deploy the message flow to the broker. If you have completed all the documented steps, message BIP3132 is written to the local system log (on Windows, the event log), stating that the HTTPS listener has been started.
You can now test the system.

Testing the example

To test that the example works, complete the following steps:

1. After Succesful creation of request & response flow.
2. Deploy the HTTPRequest message flow.
3. Put a message to the WebSphere MQ queue HTTPS.IN1. If successful, a message appears on the output queue. If the process fails, an error appears in the local error log (which is the event log on Windows).

Testing your configuration

The simplest method of testing whether HTTPS is configured correctly is to use a Web browser to make a request to the broker over HTTPS.
Start a Web browser and enter the following URL:

 http://localhost:7091/test1

Change values in the URL to reflect the changes that you have made in your broker configuration; for example, the port number. When a window is displayed asking you to accept the certificate, select Yes. The browser refreshes the window and displays an empty HTML page:

• In Mozilla browsers, the empty HTML page looks like the following example:
  

• In Internet Explorer, the following information is displayed:
  

XML document must have a top level element. Error processing resource
'http://localhost:7091/test1'

These responses mean that a blank page was returned, indicating that the setup worked correctly. To add content to the empty page, you can add a Compute node to the flow.
You can use another HTTPS client to process HTTPS requests. Read the documentation for the client to find out how to configure it to make client connections over SSL.
You can also use another HTTPS client, such as a Java or .net client, instead of the Web browser. Depending on the type of client, you might need to export the certificate (which was created with keytool) from the keystore file associated with the HTTP listener, then import it into the keystore for the client. Read the client documentation to find out how to configure the client to make client connections over SSL.

We can also test this Flow by using SOAPUI or by pasting url in the address bar and hitting enter key.

1.On pasting the url “http://172.17.5.110:7091/test1” into the address bar,the response flow begins

& then it displays a message on the browser like

2.Using SOAPUI tool:-

Open SOAPUI tool then goto file -->preferences to do all the necessary configurations for ssl.

Then a preferences window appears like this:-

It asks for jks path along with keystore password along with port no.which we configured earlier.

Then start the request flow by putting some sample BLOB message in MQInput nodeThen the flow starts

then click on “submit request to specific endpoint URL” from SOAPUI tool

Then it hits the response flow

then again back to the request flow to process the compute node

and finally the message is sent to the MQOutput node.

After processing we can see the response in the SOAPUI Tool

Installing Certificates in Internet Explorer

Step1:-Goto Tools → Internet Options

Step 2:- Browse to Content Tab and in the Certificates are click certificates button

Step 3:-The certificates window opens there find Import button & click on it

Step 4:- Goto path where you stored the certificates

and click open..

Step 5:- Here choose Automatically select the certificate store based on the type of certificate

Finally click on Finish...

Then you see this window.

Finally To check whether our certificate was imported successfully into the browser:-