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
-
To List the broker registry
mqsireportproperties MBV7Broker -o BrokerRegistry -r
where
o – objects
r – includes listing of child elements also if present.
-
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
-
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”
-
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
-
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 groupsWhen 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
|
(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
|
|
|
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:
-
Create a message flow with the nodes MQInput->HTTPRequest->Compute->MQOutput.
-
On the MQInput node, set the queue name to “q1” and create the WebSphere MQ queue.
-
On the MQOutput node, set the queue name to “q2” and create the WebSphere MQ queue.
-
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.
-
On the Advanced properties tab of the HTTPRequest node, set the Response message location in tree property to OutputRoot.BLOB.
- 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:
/* 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:
-
After Succesful creation of request & response flow.
-
Deploy the HTTPRequest message flow.
-
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.
& 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:-
IIB Developer 