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

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:

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:

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:

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:

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

   
   
   
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

   
   
   
3. Enable AT-TLS technology:
   • Click Stack TCPIP.
   • Click AT-TLS technology.
   • Click Enable.

   Figure 4. Enable AT-TLS technology

   
   
   
4. Configure AT-TLS technology:
   • Click Configure.

   Figure 5. 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.

   
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.

   
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.

   
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.

   
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

   
   
   
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

    
    
    
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

    
    
    
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

    
    
    
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

    
    
    
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

    
    
    
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

    
    
    
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

    
    
    
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

    
    
    
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

    
    
    
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.

    
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.

    
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.

    
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.

    
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

    
    
    

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

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

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

• IBM Configuration Assistant for z/OS Communication Server
  Java GUI application to configure AT-TLS rules.
  
  
• z/OS Communication Server: IP Configuration Guide
  z/OS documentation on how to configure AT-TLS and PAGENT.
  
  
• z/OS Communications Server: IP Diagnosis Guide
  z/OS documentation on problem determination for AT-TLS and PAGENT.
  
  
• WebSphere Message Broker developer resources page
  Technical resources to help you use WebSphere Message Broker for connectivity, universal data transformation, and enterprise-level integration of disparate services, applications, and platforms to power your SOA.
  
  
• WebSphere Message Broker product page
  Product descriptions, product news, training information, support information, and more.
  
  
• WebSphere Message Broker V7 information center
  A single Web portal to all WebSphere Message Broker V7 documentation, with conceptual, task, and reference information on installing, configuring, and using your WebSphere Message Broker environment.
  
  
• What's new in WebSphere Message Broker V7
  Through its simple programming model and a powerful operational management interface, WebSphere Message Broker V7 makes complex application integration solutions much easier to develop, deploy, and maintain. This article describes the major enhancements in V7.
  
  
• Download free trial version of WebSphere Message Broker V7
  WebSphere Message Broker V7 is an ESB built for universal connectivity and transformation in heterogeneous IT environments. It distributes information and data generated by business events in real time to people, applications, and devices throughout your extended enterprise and beyond.
  
  
• WebSphere Message Broker documentation library
  WebSphere Message Broker specifications and manuals.
  
  
• WebSphere Message Broker forum
  Get answers to your technical questions and share your expertise with other WebSphere Message Broker users.
  
  
• WebSphere Message Broker support page
  A searchable database of support problems and their solutions, plus downloads, fixes, problem tracking, and more.
  
  
• Redbook: Patterns: SOA design using WebSphere Message Broker and WebSphere ESB
  Patterns for e-business are a group of proven, reusable assets that you can use to more quickly develop and deploy e-business applications. This Redbook shows you how to use WebSphere Message Broker with WebSphere ESB to implement an ESB within an SOA. Includes a scenario to demonstrate design, development, and deployment.
  
  
• developerWorks WebSphere developer resources
  Technical information and resources for developers who use WebSphere products. developerWorks WebSphere provides product downloads, how-to information, support resources, and a free technical library of more than 2000 technical articles, tutorials, best practices, IBM Redbooks, and online product manuals.
  
  
• developerWorks WebSphere application connectivity developer resources
  How-to articles, downloads, tutorials, education, product info, and other resources to help you build WebSphere application connectivity and business integration solutions.
  
  
• developerWorks WebSphere SOA and Web services developer resources
  How-to articles, downloads, tutorials, education, product info, and other resources to help you design and build WebSphere SOA and Web services solutions.
  
  
• Most popular WebSphere trial downloads
  No-charge trial downloads for key WebSphere products.
  
  
• WebSphere forums
  Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
  
  
• WebSphere on-demand demos
  Download, watch, and learn what WebSphere products and WebSphere-related technologies can do for your company.
  
  
• developerWorks WebSphere weekly newsletter
  The developerWorks newsletter gives you the latest articles and information only on those topics that interest you. In addition to WebSphere, you can select from Java, Linux, Open source, Rational, SOA, Web services, and other topics. Subscribe now and design your custom mailing.
  
  
• WebSphere-related books from IBM Press
  Convenient online ordering through Barnes & Noble.
  
  
• WebSphere-related events
  Conferences, trade shows, Webcasts, and other events around the world of interest to WebSphere developers.
  
  
• developerWorks blogs
  Join a conversation with developerWorks users and authors, and IBM editors and developers.
  
  
• developerWorks Webcasts
  Free technical sessions by IBM experts that can accelerate your learning curve and help you succeed in your most difficult software projects. Sessions range from one-hour Webcasts to half-day and full-day live sessions in cities worldwide.
  
  
• developerWorks on Twitter
  Check out recent Twitter messages and URLs.
  
  

About the author

Vicente 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.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• What is AT-TLS?
• AT-TLS components
• Configuring AT-TLS
• 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 for Message Broker
• Problem determination
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Message Broker
• Briefing: WebSphere flexible business processes
• Buy: WebSphere Message Broker

Dig deeper into WebSphere on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers