Securing IBM Integration Bus on z/OS without changing the integration node configuration

This article shows you how to configure AT-TLS for IBM Integration Bus message flows on z/OS, including the policy agent and TCP/IP stack configuration on z/OS. Simple HTTP-based message flows let you quickly test the setup from a distributed system such as Windows server.

Pabitra Mukhopadhyay (pabmukho@in.ibm.com), Software Engineer, IBM

Photo of Pabitra MukhopadhyayPabitra Mukhopadhyay has seven years of experience with IBM mainframes (System z) application development, testing, and systems programming. He is currently working with the IBM India Software Labs System z Competency team as a z/OS and middleware systems programmer. He has co-authored developerWorks articles involving messaging products and z/OS. You can contact Pabitra at pabmukho@in.ibm.com.



18 June 2014

Also available in Chinese

Introduction

IBM® Integration Bus (formerly known as IBM WebSphere® Message Broker) is an enterprise service bus (ESB) providing connectivity and universal data transformation for SOA and non-SOA environments. While ESBs and messaging are critical to many businesses, the convenience and speed are accompanied by security threats, including content that can seriously compromise the organization. You can enhance the security of an IBM Integration Bus environment with SSL authentication by using Java™ keystores and truststores in JKS format and configuring Integration Bus to specify the paths and passwords of the keystore and truststore. However, it can be challenging to manage the keys using the Java command keytool on IBM z/OS®, and z/OS system programmers usually prefer to maintain keys in IBM Resource Access Control Facility (RACF).

An alternative way to manage keys for SSL connections on z/OS is to implement Application Transparent -- Transport Layer Security (AT-TLS), which is a part of z/OS Communication Server. AT-TLS provides SSL services on behalf of applications running on z/OS (including IBM Integration Bus on z/OS) and has many advantages over the conventional methods just mentioned. AT-TLS is based on policy, and uses RACF-managed digital certificates and keyrings. Middleware systems programmers do not have to set any SSL-related configuration for IBM Integration Bus running on z/OS. The use of SSL by partner applications transacting with IBM Integration Bus on z/OS is transparent to them.

Prerequisites

To benefit from this article, you should have basic knowledge of:

  • IBM Integration Bus message flow development using IBM Integration Bus Toolkit and administration.
  • z/OS and RACF.
  • HTTP and SSL

The examples and samples in this article use the following setup and configuration:

  • System z LPAR MVS0 running on z/OS V1R13 and configured with RACF and FTP.
  • Queue manager PM02 running on WebSphere MQ V7.1 on MVS0.
  • Integration node PM02BRK running on IBM Integration Bus V9 on MVS0, with PM02 as its queue manager. An Integration Server EG01 has been created and started in PM02BRK integration node.
  • Queue manager DEMOQM running on WebSphere MQ V7.5.0.1 on Microsoft Windows 7.
  • Integration node DEMOBRK with default integration node running on IBM Integration Bus V9 with DEMOQM as its queue manager.
  • Integration Toolkit V9 on Microsoft Windows 7.
  • IBM Configuration Assistant for zCS V1R13 installed on Microsoft Windows 7. Communication Assistant is also available in z/OSMF for z/OS V1R11 and above.

Creating simple HTTP-based message flows without SSL security

Before proceeding with AT-TLS configuration and SSL connections, first create a simple HTTP flow to establish a non-secured connection between a service requestor flow on Windows server and a service provider flow on z/OS. The consumer flow sends two integers to the service provider in a HTTP request. The service provider adds the integers within the service provider message flow and returns the result back.

Download the project interchange file Demo01PI.zip file at the bottom of the article and import it to the Toolkit. The imported message flow project contains two message flows: HTTP Provider message flow and HTTP Consumer message flow.

HTTP Provider message flow

Open HTTPProviderMF message flow in the Toolkit:

HTTP Provider message flow
Figure showing HTTP Provider message flow
  1. Right click on HTTP Input node and select Properties.
  2. Select the Basic tab in the Properties view and make a note of the Path suffix for URL /Demo01.
  3. If the /Demo01 path is already in use on the z/OS LPAR, then change the path name and save the message flow changes in the Toolkit.
  4. The default IBM Integration Bus HTTP port of 7080 has been used in this example. If this port is already in use, then change the IBM Integration Bus HTTP port of the z/OS integration node PM02BRK to some other available port. You can do this by tailoring BIPCHPR member in <hlq>.SBIPPROC IIB PDSE on z/OS, to execute the command:
    mqsichangeproperties broker_name 
        -b httplistener -o HTTPConnector -n port -v port_number
  5. To verify the HTTP port number change, issue the mqsireportproperties command by tailoring BIPRPPR member in <hlq>.SBIPPROC IIB PDSE on z/OS:
    mqsireportproperties broker_name -b httplistener -o HTTPConnector -a

HTTP Consumer message flow

Open HTTPConsumerMF message flow in the Toolkit, then tailor the message flow as instructed below.

HTTP Consumer message flow
Figure showing HTTP Consumer message flow
  1. Right click on HTTP Request node and select Properties.
  2. Select the Basic tab in the Properties view and provide the IP address or the fully qualified domain name of z/OS LPAR in the Web Service URL field.
  3. The port number in the URL is 7080, the default IBM Integration Bus HTTP port. If you have configured a different HTTP port for the integration node on z/OS, update the value in the URL.
  4. Save the changes made in the HTTPConsumerMF message flow in the Toolkit.

Deploying and invoking the message flows

  1. Before deploying the message flows, define the queues used in the HTTP Consumer message flow:
    runmqsc DEMOQM
    define qlocal(INQ)
    define qlocal(OUTQ)
    define qlocal(ERRORQ)
    define qlocal(FAILQ)
  2. Deploy HTTPConsumerMF message flow in the default integration server DEMOBRK integration node.
  3. Deploy HTTPProviderMF message flow in the EG01 integration server PM02BRK integration node.
Message flows deployed in respective integration servers
Message flows deployed in integration servers

Testing the message flows

  1. Put the sample input XML request message shown below in the INQ queue of the DEMOQM queue manager:
    <AddNumbersReq><num1>10</num1><num2>20</num2></AddNumbersReq>
  2. Get the response message from OUTQ queue of the DEMOQM queue manager. In case of error or failure, the output message will end up in ERRORQ or FAILQ respectively.

The figure below shows how to invoke the message flows with the input XML message in INQ and retrieve the response from the OUTQ. The output received from OUTQ confirms that these non-secured HTTP based message flows perform as expected.

Invoking the message flows
Invoking the message flows

Configuring AT-TLS on z/OS

Configuring AT-TLS on z/OS involves four steps:

  1. Creating digital certificates and keyrings in RACF that will be used by AT-TLS.
  2. Creating AT-TLS policy using IBM Configuration Assistant for zCS and transferring the policy to z/OS Unix System Services (USS).
  3. Modifying TCP/IP profile and setup policy agent PAGENT task and configuration files.
  4. Setting up RACF to run the policy agent.

Creating digital certificates and keyrings in RACF

Execute the following RACF commands in sequence to set up digital certificates and keyring:

  1. Create the CA certificate:
    RACF commands to create CA certificate
    RACDCERT CERTAUTH GENCERT            +
    SUBJECTSDN(                          +
    CN('MVS0 IIB PM02BRK CA')            +
    O('IBM') L('BLR') C('IN') )          +
    TRUST                                +
    SIZE(1024)                           +
    NOTBEFORE(DATE(2013-09-01))          +
    NOTAFTER(DATE(2023-09-01))           +
    WITHLABEL('MVS0 IIB PM02BRK CACERT') +
    KEYUSAGE(CERTSIGN)
  2. Create the personal certificate and sign it with the CA certificate created above:
    RACF command to create personal certificate and associate it with userid of PM02BRK task
    RACDCERT ID(SYSTASK) GENCERT             +               
    SUBJECTSDN(                              +               
    CN('MVS0 IIB PM02BRK HTTP PCERT')        +               
    O('IBM') L('BLR') C('IN') )              +                
    SIZE(1024)                               +                
    NOTBEFORE(DATE(2013-09-01))              +              
    NOTAFTER(DATE(2023-09-01))               + 
    WITHLABEL('MVS0 IIB PM02BRK HTTP PCERT') +
    KEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN)  +
    SIGNWITH(CERTAUTH LABEL('MVS0 IIB PM02BRK CACERT'))
  3. Export the CA certificate to a dataset. You will need to FTP this dataset containing the CA certificate at a later stage.
    RACF command to export the CA certificate to a dataset
    RACDCERT CERTAUTH                          +             
    EXPORT(LABEL('MVS0 IIB PM02BRK CACERT'))   +               
    DSN('PABMUKH.MVS0.IIB.PM02BRK.CACERT.B64') +             
    FORMAT(CERTB64)
  4. Create a keyring and associate it with the userid of the PM02BRK task:
    RACF command to create a keyring
    RACDCERT ID(SYSTASK) ADDRING(MVS0PM02BRKRING)
  5. Connect the digital certificates to the keyring and list the certificates:
    RACF commands to connect digital certificates to a keyring and list them
    RACDCERT ID(SYSTASK)                              +
    CONNECT(CERTAUTH LABEL('MVS0 IIB PM02BRK CACERT') +
    RING(MVS0PM02BRKRING) )                            
    RACDCERT ID(SYSTASK)                              + 
    CONNECT(LABEL('MVS0 IIB PM02BRK HTTP PCERT')      +
    RING(MVS0PM02BRKRING)                             +
    DEFAULT)                                           
    RACDCERT ID(SYSTASK) LISTRING(MVS0PM02BRKRING)

Creating AT-TLS policy using IBM Configuration Assistant for zCS

  1. Launch the IBM Configuration Assistant for zCS, right-click on the z/OS images, and select Add new z/OS image: Adding new z/OS image
  2. Provide the z/OS image name and description, and then select the z/OS version from the dropdown: New z/OS image details
  3. Provide the TCPIP stack name and description for the z/OS image: TCPIP stack name
  4. Select the AT-TLS technology in the table, then right-click and select Enable: Enabling AT-TLS technology
  5. With AT-TLS technology selected in the table, click Configure: Configuring AT-TLS
  6. To add a new rule, click Add: Adding a new rule
  7. Click Next on the Connectivity Rule Wizard: New connectivity rule wizard
  8. Provide the connectivity rule name as IIB_AT-TLS_PM02BRK, and select the address groups: New connectivity rule data endpoints
  9. Select Create a new requirement map and enter the new requirement map name PM02BRK, as shown below. Then click Traffic Descriptors: New requirement map
  10. Click Add to create a new traffic descriptor object: Traffic descriptor objects
  11. Specify the name for the new traffic descriptor as IIB_HTTP_Server and a description for this object, and then click Add: New traffic descriptor
  12. On the New Traffic Type -- TCP GUI, select the Details tab and then:
    • Select Single Port and provide the port number specified in the HTTP Request node URL of the HTTPConsumerMF message flow.
    • Select the Inbound only option for TCP connect direction.
    • Specify * for Jobname and User ID fields.
    • Select Server for AT-TLS handshake role.
    New Traffic Type - TCP
    New Traffic Type - TCP
  13. On the New Traffic Type -- TCP GUI, select the Key Ring tab. As shown below, select Use a Simple name (as in an SAF product or PKCS #11 Token format) and specify the RACF keyring name MVS0PM02BRKRING that you created before: New Traffic Type - TCP
  14. You should see a new entry created in the New Traffic Descriptor GUI, as shown below. Click OK: New Traffic Descriptor
  15. Now you should see IIB_HTTP_Server entry created in the Traffic Descriptor Objects table, as shown below. Click Close: Traffic Descriptor Objects
  16. Click Security Levels on the New Connectivity Rule - Select Requirement Map GUI: Select Requirement Map
  17. On the Security Level Objects GUI, click Add: Security Level Objects
  18. Specify the name for the new security level as IIB_HTTP_Server_Sec and a description for this object. Click Next: New Security Level Object
  19. Select all the versions of ciphers, select Use System SSL defaults, and then click Next: Select the ciphers
  20. Select the option to turn off FIPS 140 support, as shown below, then click Finish:
    Advanced settings for Security level
    Advanced settings for Security level
  21. You should see the new security level object IIB_HTTP_Server_Sec created, as shown below. Click Close: New security level object created
  22. From the Mappings table entry drop-down, select the Traffic Descriptor as IBM_HTTP_Server and the corresponding Security Level as IIB_HTTP_Server_Sec. Remove the additional rows from the mappings table, if any, as shown below, and then click Next: Select the requirement in the mapping table
  23. On the New Connectivity Rule GUI, click Finish: Completing new connectivity rule creation
  24. You should see a new AT-TLS rule IIB_AT-TLS_PM02BRK created and enabled, as shown below. Click Apply Changes: Applying the AT-TLS changes
  25. Under the Navigation Tree, select the entry marked as Incomplete Image:
    Completing the AT-TLS image level settings
    Completing the AT-TLS image level settings
  26. Select Simple name (as in an SAF product or in PKCS #11 Token format) and retain the default Key ring name tlsKeyring. Click OK: Default AT-TLS key ring database
  27. Click Main Perspective to go back to the Main Perspective: Back to the Main Perspective
  28. On the Main Perspective, AT-TLS technology status has changed from Incomplete to Enabled. Click Install to install this policy on the z/OS image: Installing the AT-TLS policy
  29. Select the configuration file from the list and click Install:. Installing the AT-TLS policy
  30. Specify the Install file path and the FTP login information to install the AT-TLS policy in the z/OS image: FTP the AT-TLS policy file to the z/OS image USS
  31. Once the AT-TLS policy has been installed, you should see FTP file transfer was successful, as shown below. Click Close: Successful AT-TLS policy installation
  32. Provide an optional comment for this AT-TLS policy installation, then specify the user name and click OK:
    Saving the AT-TLS policy installation history log
    Saving the AT-TLS policy installation history log
  33. Notice that the status of the configuration file has changed from Needs install to Installed. Click Close:
    Completing the AT-TLS policy installation
    Completing the AT-TLS policy installation
  34. This completes the AT-TLS policy creation and installation. Click Close to close the IBM Configuration Assistant for zCS.

Modifying TCPIP profile and policy agent configuration

Update the profile member for TCPIP address space in the TCPIP parameter dataset by uncommenting or adding the following statement. A sample SAMPPROF is present in target library <HLQ>.SEZAINST. To identify the active profile file, look at the PROFILE statement of the TCPIP started task.

Updating TCPIP parameter member to enable AT-TLS
TCPCONFIG TTLS; TO ENABLE AT-TLS SUPPORT IN TCP LAYER OF TCPIP

To activate the change, either restart the TCPIP started task, or issue the command VARY TCPIP with OBEYFILE, and the DSN parameter pointing to the TCPIP profile member. To set up the policy agent, complete the following steps:

  1. Create pagent.mvs0.env policy agent environment file in Unix system services /etc directory for policy agent. Here are the contents of this file:
    Contents of policy agent environment file
    PAGENT_CONFIG_FILE=/etc/pagent.mvs0.conf
    PAGENT_LOG_FILE=/tmp/pagent.mvs0.log
    PAGENT_LOG_FILE_CONTROL=300,3
  2. Create pagent.mvs0.conf policy agent configuration file in Unix system services /etc directory for policy agent. Here are the contents of this file:
    Contents of policy agent configuration file
    TcpImage TCPIP /etc/mvs0.tcpip_image.conf
  3. Create mvs0.tcpip_image.conf TCPIP image configuration file in Unix system services /etc directory for policy agent. Here are the contents of this file:
    Contents of TCPIP image configuration file
    TTLSConfig /etc/cfgasst/v1r13/TCPIP/tlsPol
  4. Copy the PAGENT started task procedure from the <HLQ>.SEZAINST library to the system or user proclib dataset, and customize it as shown below:
    1. Update EXEC statement to:
      //PAGENT   EXEC PGM=PAGENT,REGION=0K,TIME=NOLIMIT,                 
      //     PARM='POSIX(ON) ALL31(ON) ENVAR("_CEE_ENVFILE=DD:STDENV")/
    2. Update STDENV statement to:
      //STDENV   DD PATH='/etc/pagent.mvs0.env',PATHOPTS=(ORDONLY)
  5. Optionally, you can also enable AUTOLOG (if not already enabled) in the profile member for TCPIP address space. Include PAGENT in the AUTOLOG statement.

Setting up RACF to run the policy agent

  1. Create RACF definitions for the PAGENT started task by executing the following commands:
    RDEF STARTED PAGENT.* OWNER(owner_userID) STDATA(USER(SYSTASK))
    SETR RACLIST(STARTED) REFR
  2. Set up the TTLS Stack Initialization access control by executing the following commands:
    SETROPTS CLASSACT(SERVAUTH)
    SETROPTS RACLIST (SERVAUTH)
    SETROPTS GENERIC (SERVAUTH)
    RDEFINE SERVAUTH EZB.INITSTACK.MVS0.TCPIP UACC(NONE)
    PERMIT EZB.INITSTACK.MVS0.TCPIP CLASS(SERVAUTH) ID(*) ACCESS(READ) +
    WHEN(PROGRAM(PAGENT,EZAPAGEN))
    SETROPTS GENERIC(SERVAUTH) REFRESH
    SETROPTS RACLIST(SERVAUTH) REFRESH
    SETROPTS WHEN(PROGRAM) REFRESH
  3. z/OS will not let any socket-based applications start before PAGENT is up and running, in order to make sure that all security policies are enforced. But some essential applications need to start before PAGENT, and therefore you must define a resource profile EZB.INITSTACK.sysname.tcpprocname in the SERVAUTH class.

Starting policy agent address space and testing the message flow

To start the policy agent started task PAGENT, issue the /S PAGENT command from the z/OS console. Any error messages during the startup of the PAGENT address space are logged in /tmp/pagent.mvs0.log.

Invoke the message flows by putting an input message in the INQ queue of the DEMOQM queue manager. With AT-TLS configured on the z/OS image and the policy agent started task PAGENT up and running, the input message is not received by the integration node, because the integration node DEMOBRK is not yet configured to establish an SSL connection. The figure below shows that the input XML message has been received in FAILQ. Any SSL handshake errors from AT-TLS are logged in the USS syslog.

Invoking the message flows with only AT-TLS setup
Invoking the message flows with only AT-TLS setup

Configuring the DEMOBRK integration node to establish an SSL connection

  1. FTP the dataset containing the CA certificate from the z/OS image to the Windows server. Ensure that you FTP the dataset in ASCII mode, and set the extension of the file received file as .arm (for example PM02BRK_CACERT.arm).
  2. Launch the IBM Key Management application and create a new keystore, as shown below. Select the Key Database Type as JKS from the dropdown. Specify the file name as MVS0PM02BRK.jks and a location for this keystore. Click OK, and when prompted, specify the password for this keystore.
    Creating a new keystore
    Creating a new keystore
  3. Import the CA certificate PM02BRK_CACERT.arm in the MVS0PM02BRK.jks keystore. As shown below, select Signer Certificates from the Key database content dropdown and click Add. When prompted, specify the file name as PM02BRK_CACERT.arm and its location, and then click OK:
    Importing CA certificate PM02BRK_CACERT.arm
    Importing CA certificate PM02BRK_CACERT.arm
  4. You will be prompted to specify a label name for this CA certificate. Specify MVS0 IIB PM02BRK CACERT:
    Label for CA certificate PM02BRK_CACERT.arm
    Label for CA certificate PM02BRK_CACERT.arm
  5. Once imported, the CA certificate will be listed in the keystore with its label:.
    Listing imported CA certificate PM02BRK_CACERT.arm
    Listing imported CA certificate PM02BRK_CACERT.arm
  6. Update the HTTPConsumerMF message flow:
    • Open the HTTPConsumerMF message flow in the Toolkit.
    • Select the HTTP Request node.
    • Select the Basic tab in the Properties view.
    • Update http in the Web service URL field to https. Save the message flow change in the toolkit.
    • Deploy the updated HTTPConsumerMF message flow in the default Integration server DEMOBRK integration node.
  7. Issue the following commands to configure DEMOBRK to use the MVS0PM02BRK.jks keystore. Then restart the integration node DEMOBRK to pick up these configuration changes.
    mqsichangeproperties DEMOBRK -o BrokerRegistry 
        -n brokerKeystoreFile -v D:\MVS0PM02BRK.jks
    mqsisetdbparms DEMOBRK -n brokerKeystore::password 
        -u ignore -p keystore_password
    mqsichangeproperties DEMOBRK -o BrokerRegistry 
        -n brokerTruststoreFile -v D:\MVS0PM02BRK.jks
    mqsisetdbparms DEMOBRK -n brokerTruststore::password 
        -u ignore -p keystore_password
    mqsistop DEMOBRK
    mqsistart DEMOBRK
  8. To verify the integration node property changes, issue the following command:
    mqsireportproperties DEMOBRK -o BrokerRegistry -a

    In this example, SSL has been enabled at the integration node level. You can also implement these changes at the integration server level. For more information about the mqsichangebroker command and its syntax, see the IBM Integration Bus information center.
  9. Invoke the message flows once again by putting an input message in the INQ queue of the DEMOQM queue manager. DEMOBRK is now configured to establish an SSL connection with AT-TLS, and hence PM02BRK should be able to receive the requests from DEMOBRK. Here is the response message received in OUTQ of DEMOQM:
    Invoking the message flows with SSL enabled in DEMOBRK and AT-TLS on z/OS
    Invoking the message flows with SSL enabled in DEMOBRK and AT-TLS on z/OS
    As part of AT-TLS setup on z/OS, the PM02BRK configuration has not been changed, and the HTTPProviderMF message flow has not been modified for an SSL connection, thus verifying that the SSL connection between DEMOBRK and AT-TLS is transparent to PM02BRK, thereby allowing PM02BRK to run in non-secured mode.

Acknowledgments

The author would like to thank Avinash Jhawar, IBM Integration Bus Post-GA Test and Lifecycle Team Lead, for his help in reviewing this article.


Download

DescriptionNameSize
Code sampleDemo01PI.zip4 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=974771
ArticleTitle=Securing IBM Integration Bus on z/OS without changing the integration node configuration
publish-date=06182014