An innovative way to enable SSL for WebSphere Message Broker on z/OS

This article shows you how to enable Secure Sockets Layer (SSL) in a way that is transparent to WebSphere Message Broker on z/OS, with no configuration steps required in Message Broker. This solution uses a service called Application Transparent Transport Layer Security (AT-TLS), which is part of z/OS Communication Server, to provide SSL services on behalf of Message Broker. To get the most out of this article, administrators for WebSphere Message Broker and for z/OS networking should work together.

Vicente Suarez (vicente_suarez@uk.ibm.com), Senior IT Specialist, IBM

Photo Vicente Suarez photoVicente Suarez is a Senior IT Specialist from the Hursley Lab Services Team. He has worked with distributed transactional middleware for eight years, and has extensive experience designing and implementing solutions using the Business Integration family of products with IBM customers world-wide.


developerWorks Contributing author
        level

17 March 2010

Introduction

The solution in this article uses IBM® WebSphere® Message Broker V6.1 or later (hereafter called Message Broker) running on z/OS V1.8 or later. To enable Secure Sockets Layer (SSL) on Message Broker, you need to complete the following steps:

  • Create Java keystores and truststores in JKS format.
  • Populate personal and trusted CA certificates in the keystores.
  • Change Message Broker properties to indicate the locations and passwords of the keystore and truststore.
  • Set HTTPS/SSL attributes on the HTTP or SOAP nodes in message flows running on Message Broker.

In z/OS, the above steps have the following disadvantages:

  • JKS keystores and truststores have to be created and managed using the Java command keytool. This tool is not very friendly to use and has many restrictions using HW cryptography cards.
  • z/OS security administrators usually do not like managing keystores and certificates outside of Resource Access Control Facility (RACF).

Application Transparent Transport Layer Security (AT-TLS) provides the following benefits when using SSL/TLS protocols with Message Broker on z/OS:

  • AT-TLS uses RACF key rings and certificates.
  • The Policy Agent (PAGENT) manages the rules and policies that define how SSL is used to connect to Message Broker.
  • PAGENT can distribute the rules and policies in a z/OS SYSPLEX environment.
  • The Message Broker administrator does not have to set any Message Broker properties for SSL.
  • HTTP or SOAP nodes in message flows can have standard HTTP settings (no SSL/HTTPS).

What is AT-TLS?

AT-TLS is a service provided by the z/OS Communication Server Policy Agent (PAGENT) and the TCPIP stack. The AT-TLS service manages SSL connections on behalf of applications that are running on z/OS. The z/OS applications are unaware that SSL is used in the connection with partner applications. The figure below shows how AT-TLS works:

Figure 1. AT-TLS components
Figure 1
  1. Represents a SSL connection when AT-TLS is not used, which requires that Message Broker and the partner application are both enabled for SSL.
  2. Represents the SSL handshake managed by AT-TLS in the TCP layer.
  3. Inbound or outbound application data received or sent in the clear by Message Broker. The TCP layer validates and decrypts inbound data from partner applications or encrypts outbound data to partner applications.
  4. Inbound or outbound application data protected by SSL.

AT-TLS components

RACF key ring
Contains the Message Broker personal certificate and the partner application signer certificate.
AT-TLS policies
This file has the rules and policies that control the SSL connections managed by AT-TLS. These policies are created by the network administrator, and are checked and enforced by the TCP network layer of the TCPIP stack.
Policy Agent
This component manages and distributes network policies, including AT-TLS policies, to the TCPIP stack or stacks. The policy agent is also called PAGENT. For AT-TLS to function, it requires that PAGENT is properly configured and operational.
TCPIP stack
The component that implements the AT-TLS services. The TCP network layer is where SSL connections are intercepted, the SSL handshake is performed, and data is decrypted and encrypted. The TCPIP stack uses RACF services to validate and accept certificates presented by the partner application during handshake. RACF retrieves the Message Broker personal certificate from the key ring.

Configuring AT-TLS

Here are the steps to configure AT-TLS on your z/OS environment for Message Broker:

  1. Create a RACF key ring.
  2. Configure and activate the policy agent (PAGENT).
  3. Define and install AT-TLS policies for Message Broker.
  4. Test and verify AT-TLS using Message Broker.

1. Create a RACF key ring

Each RACF key ring has its own name up to 237 characters long and is associated with a user id. A RACF key ring is connected to a set of personal certificates and trusted certificates stored in the RACF database. The RACF command RACDCERT is used to create and delete key rings and to connect or disconnect certificates to the key rings. RACF key rings are also called System Authorization Facility (SAF) key rings. SAF is an open standard to access security services.

Here are the steps to create a RACF key ring to be used by AT-TLS on behalf of Message Broker:

Generate RACF certification authority (CA) certificate

A common practice among z/OS users is to use RACF as CA to generate and sign personal certificates for their internal systems or applications. This certificate has to be created once, and it is used sign every personal certificate generated by RACF. The example below shows how to generate a RACF CA certificate:

Listing 1. RACF command to generate a CA certificate
RACDCERT CERTAUTH GENCERT +                          
  SUBJECTSDN(CN('MQRootCA') +                        
  OU('ISSW') +                                       
  O('IBM') +                                         
  L('HURSLEY') SP('WINCHESTER') C('GB')) +           
  KEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN CERTSIGN) + 
  WITHLABEL('MQRootCA') +                            
  NOTAFTER(DATE(2020/01/30)) +                       
  SIZE(1024)

Generate a personal certificate for Message Broker

This certificate identifies a specific instance of Message Broker. This certificate is presented to the partner application during the SSL handshake. This certificate must be associated with the user id that Message Broker is running under. The example below shows how to generate the personal certificate for a message broker called WI02BRK running under user id WI02USR:

Listing 2. RACF command to generate a personal certificate
RACDCERT ID(WI02USR) +                         
   GENCERT SUBJECTSDN(CN('WI02BRK') +          
   OU('ISSW') O('IBM') +                       
   L('HURSLEY') SP('WINCHESTER') C('GB')) +    
   WITHLABEL('WI02BRK') SIZE(1024) +           
   SIGNWITH(CERTAUTH LABEL('MQRootCA')) +      
   KEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN) +   
   NOTAFTER(DATE(2012/01/30))

Create RACF key ring and connect certificates to key ring

The RACF key ring must be associated with a user id (in this case the Message Broker user id); it must have a name (in this case the same name as the broker); and the Message Broker personal certificate must be connected to the key ring. The example below shows how to create a key ring and connect the Message Broker personal certificate:

Listing 3. RACF command to create key ring
RACDCERT ID(WI02USR) ADDRING(WI02BRK)                
RACDCERT ID(WI02USR) +                               
 CONNECT(ID(WI02USR) LABEL('WI02BRK') RING(WI02BRK)) 
RACDCERT ID(WI02USR) LISTRING(WI02BRK)

For RACF to be able to validate a partner application certificate, you must import the signer certificate of the CA that generated and signed the personal certificate of the partner application. Normally, this certificate is extracted from the partner application keystore, transferred to z/OS as a data set (WI02USR.VSR1BK.DER), imported to RACF, and connected to the RACF key ring as signer (trusted) certificate. The example below shows how to add a signer certificate to RACF and connect it to the RACF key ring:

Listing 4. RACF command to add trusted certificate to key ring
RACDCERT CERTAUTH ADD('WI02USR.VSR1BK.DER') +   
WITHLABEL('VSR1BK') TRUST                       
RACDCERT CERTAUTH LIST(LABEL('VSR1BK')          
RACDCERT ID(WI02USR) +                            
 CONNECT(CERTAUTH LABEL('VSR1BK') RING(WI02BRK))
RACDCERT ID(WI02USR) LISTRING(WI02BRK)

2. Configure and activate the policy agent (PAGENT)

Here is a summary of the steps to enable PAGENT for AT-TLS. For a more detailed description of installation and configuration of PAGENT, see Policy-based networking in the z/OS Communication Server documentation.

Update TCPIP profile

The TCPIP profile requires two changes to enable AT-TLS:

  • Add statement TCPCONFIG TTLS to activate the functionality of AT-TLS inside the TCPIP stack.
  • Add PAGENT to the AUTOLOG list.

Grant RACF permissions to TCPIP resources

Users require permissions to the following resources as part of activating PAGENT:

  1. Define PAGENT as a started task with its own user id.
  2. The EZB.INITSTACK.sysname.tcpprocname resource profile controls which users can have access to the TCPIP stack before PAGENT is active. READ access should be given to all users who do not require PAGENT policies to access the TCPIP stack. For example, PAGENT, NETVIEW, DB2, and so on.
  3. The EZB.PAGENT.sysname.tcpprocname.* resource controls which users can start, stop, and refresh PAGENT. Give READ access to the users allowed to execute the TSO/Unix commands Pagent or pasearch.
  4. The user id of PAGENT needs to have READ access to the BPX.DAEMON facility.

For more detailed information about the RACF permissions, check the sample EZARACF in the TCPIP.SEZAINST library.

Prepare PAGENT startup JCL

Copy the sample JCL PAGENT in TCPIP.SEZAINST library to the system procedure library (for example SYS1.PROCLIB).

Edit the JCL according to your installation standards. Specify the location of the pagent configuration file (for example /etc/pagent/pagent.config). One way to specify the location and name of the configuration file is to set the environment variable PAGENT_CONFIG_FILE=/etc/pagent/pagent.config. The environment variables for the TCPIP stack are normally specified in a member (for example ENVVARS) of the TCPIP parameters library (for example TCPIP.PARMS). The PAGENT JCL has ddname STDENV that points to the member with the environment variables definitions.

The PAGENT configuration file (/etc/pagent/pagent.config) specifies the location and name of the PAGENT stack-specific configuration file using the statement TcpImage: TcpImage TCPIP /etc/pagent/TCPIP.image FLUSH NOPURGE 1800.

The stack-specific configuration file (/etc/pagent/TCPIP.image) specifies the location and name of the AT-TLS policies file using the statement TTLSConfig: TTLSConfig /etc/pagent/TCPIP_TTLS.policy.

Activate system log daemon (syslogd)

Syslogd acts as the central message logging facility for PAGENT and AT-TLS. Syslogd is not specific to the policy infrastructure, but the policy infrastructure depends on syslogd to provide a central logging facility to maintain an audit trail. If you do not start syslogd, messages are lost. Start one syslog daemon per LPAR.

3. Define and install AT-TLS policies for Message Broker

You can create the AT-TLS using the IBM Configuration Assistant for z/OS Communications Server, which is a Java™ GUI application that you can download from IBM.

Here are the steps to define the policies required to enable SSL support on behalf of WebSphere Message Broker for z/OS running SOAPInput and SOAPRequest nodes:

  1. Start configuration assistant:
    • Select Start => All Programs => IBM Configuration Assistant for z/OS => Configuration Assistant V1R10.
    • Click Add New z/OS image.
    • Enter name: YourLPAR.
    • Enter description: Your description.
    • Click OK.
    Figure 2. Start configuration assistant
    Start configuration assistant
  2. TCPIP stack information:
    • Click Image YourLPAR.
    • Click Add New TCP/IP Stack.
    • Enter stack name = TCPIP.
    • Enter description = Your description.
    • Click OK.
    Figure 3. TCPIP stack information
    TCPIP stack information
  3. Enable AT-TLS technology:
    • Click Stack TCPIP.
    • Click AT-TLS technology.
    • Click Enable.
    Figure 4. Enable AT-TLS technology
    Enable AT-TLS technology
  4. Configure AT-TLS technology:
    • Click Configure.
    Figure 5. Configure AT-TLS technology
    Configure AT-TLS technology
  5. Start connectivity rule wizard:
    • Click Add to start the connectivity rule wizard.
    • Click Next.

    Figure 6. Start connectivity rule wizard -- click to see larger image.

    Click to see larger image
  6. Specify the local and remote IP addresses for this rule:
    • For Local data endpoint, select ALL_IP_Addresses.
    • For Remote data endpoint, select ALL_IP_Addresses.
    • Enter a suffix for the name of the rules, such as Name: WI02BRK.
    • Click Next. Keep the rule as generic as possible during the initial testing. Later it can be made as specific as required.

    Figure 7. Specify the local and remote IP addresses for this rule -- click to see larger image.

    Click to see larger image
  7. Create a new Requirement Map:
    • Click Add to create a new Requirement Map, which is used to map the type of IP traffic with the security level to be implemented by AT-TLS.

    Figure 8. Create a new Requirement Map -- click to see larger image.

    Click to see larger image
  8. Enter the Requirement Map name and description:
    • Name: WI02BRK
    • Description: Your description
    • Click Work with the Traffic Descriptor. Two traffic descriptors are required: one for the inbound SOAP requests (Broker is server) and another for the outbound SOAP requests (Broker is client).

    Figure 9. Enter the Requirement Map name and description -- click to see larger image.

    Click to see larger image
  9. Create a new Traffic Descriptor:
    • Click Add to create a new Traffic Descriptor.
    • Enter Name = SOAP_Server, and Description = Your description.
    • Click OK to add details of the Traffic Descriptor.
    Figure 10. Create a new Traffic Descriptor
    Create a new Traffic Descriptor
  10. Enter Inbound Traffic Descriptor details:
    • Select Single Local Port.
    • Port: 7800 (Broker SOAPInput node normally listens on this port).
    • Select All remote ports.
    • Indicate TCP connect direction: Inbound only.
    • Jobname: *.
    • User ID: *.
    • AT-TLS handshake role: Server.
    • Click AT-TLS Advanced.
    Figure 11. Enter Inbound Traffic Descriptor details
    Enter Inbound Traffic Descriptor details
  11. Enter the label of the Message Broker personal certificate:
    • Label: WI02BRK
    • Click OK.
    • Click OK to save the traffic details for Inbound SOAP traffic.
    • Click OK to create the Traffic Descriptor for Inbound SOAP.
    Figure 12. Enter the label of the Message Broker personal certificate
    Enter the label of the Message Broker personal certificate
  12. Create a new Traffic Descriptor:
    • Click Add to create a new Traffic Descriptor.
    • Enter name = SOAP_Server, and Description = Your description.
    • Click OK to add details of the Traffic Descriptor.
    Figure 13. Create a new Traffic Descriptor
    Create a new Traffic Descriptor
  13. Enter Outbound Traffic Descriptor details:
    • Select All Local Ports.
    • Select single remote port.
    • Port: 7843 (Remote Windows Broker).
    • Indicate TCP connect direction: Outbound only.
    • Jobname: *.
    • User ID: *.
    • AT-TLS handshake role: Client,
    • Click AT-TLS Advanced.
    Figure 14. Enter Outbound Traffic Descriptor details
    Enter Outbound Traffic Descriptor details
  14. Enter the label of the Message Broker personal certificate:
    • Label: WI02BRK.
    • Click OK.
    • Click OK to save the traffic details for Outbound SOAP traffic.
    • Click OK to create the Traffic Descriptor for Outbound SOAP.
    • Click Close.
    Figure 15. Enter the label of the Message Broker personal certificate
    Enter the label of the Message Broker personal certificate
  15. Create a security level for Message Broker:
    • Click Work with Security Levels.
    • Click Add to create a new security level.
    Figure 16. Create a security level for Message Broker
    Create a security level for Message Broker
  16. Enter security level name and type:
    • On the Name and Type tab, enter Name = WI02BRK_SEC_LEVEL and Description = Your description.
    Figure 17. Enter security level name and type
    Enter security level name and type
  17. Enter security level ciphers:
    • On the Ciphers tab, select Use TLS V1 and Use SSL V3.
    • Use System SSL defaults.
    • Click OK.
    Figure 18. Enter security level ciphers
    Enter security level ciphers
  18. Add traffic descriptors to Requirement Map. In the objects list:
    • Select Traffic Descriptor SOAP_Server and click <=Add.
    • Select Traffic Descriptor SOAP_Client and click <=Add.
    Figure 19. Enter security level ciphers
    Enter security level ciphers
  19. Associate a AT-TLS security level to each traffic descriptor:
    • From the drop-down menu select WI02BRK_SEC_LEVEL for each of the traffic descriptors selected in the requirement map.
    • Click OK.

    Figure 20. Add traffic descriptors to Requirement Map -- click to see larger image.

    Click to see larger image
  20. Set the optional advanced settings:
    • Click Next to advance to Optional Connectivity Rule Settings, which are used to set tracing levels, tuning parameters, and timings when the rule is in effect.
    • Click Finish.

    Figure 21. Set the optional advanced settings -- click to see larger image.

    Click to see larger image
  21. Save all changes to the AT-TLS rules:
    • Click Apply changes.
    • Click Main perspective.

    Figure 22. Save all changes to the AT-TLS rules -- click to see larger image.

    Click to see larger image
  22. Install the AT-TLS policy:
    • Select AT-TLS technology.
    • Click Install.
    • Click FTP to send policy rules to LPAR.

    Figure 23. Install the AT-TLS policy -- click to see larger image.

    Click to see larger image
  23. Enter FTP parameters:
    • Hostname: YourLPARHostname.
    • Port number: 21.
    • User ID: YourUserID.
    • Password: ********.
    • Enter AT-TLS policy file location and name: /etc/pagent/TCPIP_TTLS.policy.
    • Select Default transfer mode.
    • Click Send. Wait for FTP to finish and check for successful file transfer.
    • Click Close.
    • After FTP, refresh or stop and restart PAGENT. Now the AT-TLS policies have been created and deployed.
    Figure 24. Enter FTP parameters
    Enter FTP parameters

4. Test and verify AT-TLS for Message Broker

Use the following scenario to test and verify AT-TLS with Message Broker:

Figure 25. AT-TLS test and verification scenario
AT-TLS test and verification scenario

This scenario has the following components:

  • One instance of Message Broker running on z/OS.
  • Another instance of Message Broker running on Windows.
  • SOAP node sample flows from the Message Broker Toolkit sample gallery are deployed to the two Message Broker instances.
  • Th broker instance running on z/OS is not enabled to use SSL. The SSL services are provided by AT-TLS.
  • AT-TLS policies are active and PAGENT is running.
  • The broker instance running on Windows is enabled to use SSL, and it has keystores defined with personal and signer certificates loaded.

The flows receive or send SOAP inbound and outbound requests between the two Message Brokers. The SOAP consumer flow in one broker sends requests to the SOAP provider flow in the other broker. The SOAP nodes on the Windows broker are SSL enabled. Figure 2 above shows the URLs that are configured on the SOAP request node on each broker.

For more information on how to configure, deploy, and run the Sample SOAP nodes flows, see the documentation in the Message Broker Toolkit Samples Gallery, as shown below.

Figure 26. Sample SOAP node flows
Sample SOAP node flows

Problem determination

To help with problem determination with PAGENT and AT-TLS, activate tracing and logging. PAGENT has its own log file with the default name /tmp/pagent.log, which contains messages about loading AT-TLS rules. Any invalid rules are rejected and errors are written to the PAGENT log file. You can specify different levels of logging in the PAGENT configuration file using the statement LogLevel. LogLevel 511 gives the most verbose logging.

The TCPIP stack and the AT-TLS service log messages use SYSLOGD. The AT-TLS level of tracing is specified using the advanced options in the connectivity rules. The highest (more verbose) level of tracing is 255.

The name and location of the log files are specified in the configuration file of the SYSLOGD (/etc/syslog.conf). Here is the configuration used during the tests for this article: *.* /var/log/%Y/%m/%d/errors.

This syslogd configuration creates log files with names like /var/log/2010/03/20/errors. Every time syslogd is restarted, it creates a new directory based on the current date. A good procedure is to restart syslogd once a day at midnight.

Conclusion

This article has shown you how to use the Application Transparent Transport Layer Security (AT-TLS) service of the z/OS Communication Server to implement SSL on behalf of WebSphere Message Broker for z/OS. AT-TLS provides the following advantages:

  • Using RACF key rings and certificates.
  • AT-TLS and RACF can use cryptographic hardware to optimize performance.
  • No need to configure SSL in WebSphere Message Broker.
  • You can manage PAGENT rules and policies in a centralized manner and distribute them to the TCPIP stacks in a SYSPLEX environment.

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=474712
ArticleTitle=An innovative way to enable SSL for WebSphere Message Broker on z/OS
publish-date=03172010