Before you start
This tutorial shows how to setup SSL-based communication between WebSphere MQ and WebSphere Message Broker products, using MQ SSL with Microsoft Windows on z/OS. It shows how to check various combinations of SSL Cipher Specification (SSLCIPH). It also demonstrates error scenarios like invalid certificates and expired certificates.
We perform all these tasks using panels on the z/OS platform, which makes it very easy for a relatively less experienced user on z/OS. At the end of the article, we list all the RACF commands on z/OS (like a create key ring, add a certificate to the key ring etc). These commands perform the same actions as the panels on z/OS for MQ SSL setup on z/OS platform.
- Set up MQ SSL on z/OS queue manager
- Establish one-way SSL communication between the z/OS queue manager and WebSphere Message broker toolkit
- Establish two-way SSL communication between the z/OS queue manager and WebSphere Message broker toolkit
- Demonstrate SSL communication for various combinations of SSLCIP
- Demonstrate error scenarios for invalid combination of SSLCIPH, invalid certificates and expired certificates).
You should be familiar with:
- The basics of z/OS
- Usage of various panels (ISPF,RACF etc) on z/OS
- IBM WebSphere MQ
- IBM WebSphere Message Broker (runtime and toolkit) concepts,
- Some familiarity with SSL on Microsoft Windows.
To implement the tasks listed in this tutorial, you need:
- A Microsoft Windows machine
- IBM WebSphere MQ V6 or above
- IBM WebSphere Message Broker V6 or V6.1
- IBM WebSphere Message Broker Toolkit V6 or V6.1
- A z/OS LPAR with RACF installed on it
- 2 hours
For your convenience, this section provides some key term definitions from the MQ Information Center.
SSL is an industry-standard protocol that provides a data security layer between application protocols and the communications layer, usually TCP/IP. SSL uses encryption techniques, digital signatures and digital certificates to provide message privacy, message integrity and mutual authentication between clients and servers.
In WebSphere MQ, you can use SSL for communication between two queue managers using a digital certificate on each of the queue managers.
SSLCIPH defines a single CipherSpec for an SSL connection. Both ends of a WebSphere MQ SSL channel definition must include the attribute and the SSLCIPH values must specify the same CipherSpec on both ends of the channel. The value is a string with a maximum length of 32 characters. This attribute is valid for all channel types. It is valid only for channels with a transport type (TRPTYPE) of TCP. If the TRPTYPE is not TCP, the data is ignored and no error message is issued. SSLCIPH is an optional attribute.
To learn more, see the SSL supported by WebSphere MQ.
SLCAUTH is used to define whether the channel needs to receive and authenticate an SSL certificate from an SSL client. Possible values are:
- OPTIONAL - If the peer SSL client sends a certificate, the certificate is processed as normal but authentication does not fail if no certificate is sent.
- REQUIRED - If the SSL client does not send a certificate, authentication fails.
The default value is REQUIRED.
You can specify a value for SSLCAUTH on a non-SSL channel definition, one on which SSLCIPH is missing or blank. You can use this to temporarily disable SSL for debugging without first having to clear and then re-input the SSL parameters.
SSLCAUTH is an optional attribute.
This attribute is valid on all channel types that can ever receive a channel initiation flow, except for sender channels. This attribute is valid for channel types of:
- * Server
- * Receiver
- * Requester
- * Server connection
- * Cluster receiver
The SSLPEER attribute is used to check the Distinguished Name (DN) of the certificate from the peer queue manager or client at the other end of a WebSphere MQ channel. If the DN received from the peer does not match the SSLPEER value, the channel does not start. SSLPEER is an optional attribute. If a value is not specified, the peer DN is not checked when the channel is started. On z/OS the maximum length of the attribute is 256 bytes. On all other platforms it is 1024 bytes. On z/OS the attribute values used are not checked. If you input incorrect values, the channel fails at startup, and error messages are written to the error log at both ends of the channel. A Channel SSL Error event is also generated at both ends of the channel. On platforms that support SSLPEER, other than z/OS®, the validity of the string is checked when it is first input. You can specify a value for SSLPEER on a non-SSL channel definition, one on which SSLCIPH is missing or blank. You can use this to temporarily disable SSL for debugging without having to clear and later re-input the SSL parameters.
You can find more information on these keywords in the WebSphere MQ Information Center.
The following sections provide steps and the screenshots for setting up an MQ SSL connection between the WebSphere Message Broker Toolkit (windows) and the WebSphere MQ queue manager on z/OS.
Assumption 1: The queue managers are created and are running, and the channel initiators are running. SSL setup is not yet activated.
Assumption 2: In this tutorial we use two user IDs: MA01USR and MA02USR for queue managers MA01 and MA02 respectively. These user IDs need to have access to issue a RACDERT command. Check with your system administrator to see if the user ID that you will be using has access to the RACDERT command. For more information on various profile definitions, please refer to the topic The RACDCERT COMMAND discussed at the end of this document.
In the below section, you will learn to create a key ring. A key ring can be thought of a repository which holds digital certificates. These certificates are used to ascertain the trustworthiness of the client system.