Transport security

Transport security for IBM® System z® applications

EntireX SSL/TLS overview

The Secure Socket Layer (SSL) and Transport Layer Security (TLS) are the most widely deployed TCP-based security protocol(s) used today. EntireX uses SSL/TLS and public key encryption to establish and verify the identities of users and applications in order to secure a channel over public or private networks. You will want to read this if your organization needs to comply with internal, regional, national or international regulations concerning data privacy, security and integrity.

The imperative
In today’s world of mixing private and public information together into one form factor (aka the Internet of everything), it is not only important to provision information access protection but also wise to protect sensitive data from surreptitious “eavesdropping,” IP address spoofing or session hijacking. Proper SSL practices and digital certificate management is an imperative and should be orchestrated with your z/OS® security team’s participation.
[Please note that EntireX SSL is NOT affected by the Heartbleed security bug in the OpenSSL cryptography library that potentially compromises private information to indiscriminate attackers.]  

SSL overview
TLS is a client-server cryptographic protocol based on the earlier SSL specification. The terms SSL and TLS are used interchangeably in this document.
One of the technology benefits of SSL/TLS is that it is data- or application-agnostic and can be applied to virtually any socket-based application. Although SSL implementation features are included with most EntireX components, it is important to understand the z/OS environment, how it works and what run-time impacts might be encountered.
During the SSL handshake, session authentication for the server endpoint uses a concept of certificate stores called trust-store (to verify credentials) and key-store (to provide credentials). Client session authentication (mutual authentication) using a similar concept is optional. SSL then negotiates a cipher suite used to protect data payload from eavesdropping along with renew time parameters.
The EntireX certificate examples include an encrypted self-signed certificate (one signed with its own private key) that speeds processing by requiring only the Certificate Authority (CA) and the certificate holder to exchange keys. The information below assists users in registering this example certificate (PKCS12) in a key-store and shows how to configure the EntireX Broker with this self-signed certificate for its SSL handshake.  

Managing digital certificates
Certificates are the keys that digitally bind an organization’s security policy in an orderly fashion to express a trustful relationship. There are many types and flavors but the most important thing is to follow your organization’s certificate policy before deploying certificates through EntireX. 
From a platform perspective, the Resource Access Control Facility’s (RACF) CA feature manages SSL certificates, verifies credentials and handles the security binding while being transparent to the application. It is common for EntireX Broker for z/OS users to use self-signed certificates in the Public-Key Cryptography Standard (PKCS) format managed through the RACF CA.
If your organization already has a certificate and keyring registered in RACF, you can skip down to the section titled Configuring z/OS EntireX Broker SSL Listener. If you want to use the EntireX example certificates, then you will need to register both in the CA as explained below.
You can test your client certificate with your server certificate using a tool such as OPENSSL. There is a good example of this distributed utility in the “Additional Considerations for Public Key Infrastructure” section of the EntireX documentation for distributed systems.

Random number generator for SSL server
Although optional, an important element in cryptographic systems is provisioning a good Random Number Generation (RNG) method. EntireX running on z/OS offers a random number generator “seed feature,” which is a private, unpredictable sequence of bytes that is transformed and used to set the initial state of the z/OS generator. This start-up step ensures that each unique instance of a generator produces a unique stream of bits that is handed to the SSL server (aka EntireX).
Here’s an example of how a RNG seed works with EntireX Broker SSL as a z/OS Started Task:
Create a member (RANDOM) in <HLQ>.EXX.SRCE with a record of 32 to 80 bytes of ‘unique matter’ for each SSL server. Use the following as the last card in each of your EntireX Broker startup decks to use this file as the RNG seed:

Registering certificates in the RACF CA
Certificates managed by RACF can only be accessed through the RACF keyring container. A keyring is a collection of certificates that identify a networking trust relationship (also called a trust policy). In an SSL client-server network environment, entities identify themselves using digital certificates called through a keyring. Server applications on z/OS that wish to establish network connections to other entities can use keyrings and their certificate contents to determine the trustworthiness of the client or peer entity. 
Note that certificates can belong to more than one keyring, and you can assign different users to the same keyring. Because of the way RACF internally references certificates, they must not only be uniquely identifiable by owner and label, they must also be unique by serial number plus DataSet Name (DSN).
The following contains a summary of steps for adding certificates to RACF and connecting them to an existing keyring using the sample certificates. These steps are associated with batch jobs included with the EntireX for z/OS install image (job name = member name). Important—you will need administrator privileges in order to run any of these RACF-related steps:
  • Job EXXALCPS copies the two sample certificates to sequential files for RACF import as keys cannot be stored directly in RACF. Note that the PKCS12 format member (APPP12) was generated as a container for the necessary private keys and is encrypted. Unlike distributed platforms, the private key is contained in the PKCS12 certificate.
  • Job EXXCEADD adds the public certificate to the RACF keyring and lists the contents of the CaCert afterwards. The example uses a public certificate with the label ExxCaCert.
  • Job EXXCEA12 checks and adds the private certificate ExxAppCert and its private keys (PKCS12 format) to RACF then lists the ExxAppCert contents. 
  • Run the EXXKRCON job to connect the certificates to the keyring. Just as users are connected with different levels of RACF authority, certificates are connected to keyrings with different types of RACF usage. The EXXRING keyring should look like this:

Certificate Label Name             Cert Owner     USAGE      DEFAULT
--------------------------------   ------------   --------   -------
ExxCaCert                          CERTAUTH       CERTAUTH     NO  
ExxAppCert                         SITE           PERSONAL     NO
There are more sample jobs associated with certificate and keyring management documented in the README member of the CERT file contained in the EntireX z/OS install image.   
The remaining information will guide you through SSL use cases for EntireX Broker on z/OS, CICS RPC Server, and the EntireX Adapter using RPC (Broker) and Direct RPC (non-Broker) features. Please use the product documentation for Natural RPC SSL configuration and other use cases.             

Configuring z/OS EntireX Broker SSL listener
The following SSL-specific parameters need to be adapted in the attribute member of the EntireX Broker Started Task (as pointed to by the ETBFILE dd statement in the JCL):    
  TRANSPORT = TCP-SSL              * uses both TCP and SSL transports
DEFAULTS = SSL                     *                                 
  HOST          = localhost        * HOST                            
  KEY-LABEL     = ExxAppCert       * RACF KEYRING LABEL              
* KEY-FILE      =                  * ETB PRIVATE KEY     (external file) 
* KEY-PASSWD    =                  * FOR PRIVATE KEY     (file password)        
* KEY-STORE     =                  * CA CERT             (ExxAppCert)
  PORT          = 22223            * SSL PORT NO         (1025-65535)
You may need to adapt the RACF 'FACILITY' class resource rule entry to allow the EntireX Broker started task access to the keyring that is not belonging to their own started task ids (the example above shows the id as ‘EXX’). Note: The 'UPDATE' authority for the RACF class 'FACILITY' is mandatory!
When EntireX Broker starts, you should see the following entries in the Broker’s log file indicating the SSL is initiated and the listener is active (SMH will also show an SSL object for your Broker):       
Diagnostic Values:                   
Listen address                       
IP Address....               
Family........ AF_INET               
Port.......... 22223                 
Communicator ready for communications
Configuring SSL for the EntireX CICS RPC Server 
The SSL feature for CICS RPC Server is based on the z/OS Communication Server supplied component called Application Transparent-Transport Layer Security (AT-TLS).  AT-TLS provides SSL/TLS encryption as an add-on wrapper for most socket applications and runs as a segment of the TCP/IP protocol stack. The benefit is that it runs as a by-product within the TCP/IP stack and is application transparent.
Using the AT-TLS basic mode, the CICS RPC Server is portraying an SSL client-requester so it will need the public key to send to its SSL server-responder counterpart (such as the EntireX Adapter below). 
The Configuration Assistant for z/OS Communications Server is a downloadable desktop app that manages the AT-TLS policies. You can configure an AT-TLS policy for assigning the RACF keyring to an outbound TCP port that the CICS RPC Server will then transparently use to connect to a Direct RPC listener. The AT-TLS policy is then read, parsed, and installed into the TCP/IP stack by the z/OS Communications Server Policy Agent referred to as PAGENT.

Configuring EntireX Adapter for SSL
A. Connecting through an RPC Broker SSL listener:
The SSL parameters are defined in the host connection string (URL style) as name value pairs separated by an ampersand ('&').  You always have to specify trust_store=file, where file is the path name of a Java® keystore file which contains the list of trusted certificate authorities and must match the certificate cipher bound to the SSL listener on the server side (see example below).  Specify verify_server=no, if you do not want to check that the certificate of the SSL server is issued for the specified hostname.  
Here is an Adapter example connection string for talking to a z/OS EntireX Broker SSL listener (22223) that has a service registered to a CICS RPC Server via a standard TCP/IP connection (client-broker-server): 
BrokerId = ssl://zhst:22223?trust_store=C:\SoftwareAG\EntireX\etc\ExxCACert.jks&verify_server=no
Server Address = RPC/SRV1/CALLNAT
Note that the certificate is a client public certificate and the Broker will be assigned the SSL server certificate on this port.
B. Connecting an RPC Server to a Direct RPC SSL listener
Note that the Adapter connection will be set up as an SSL server and the RPC Server will be set up as an SSL client, each with proper certificates assigned. Important: You must adjust any firewall settings to allow an inbound connection to the listener port on the Adapter machine.
First, create a keystore alias in the IS using your Java keystore certificate file. This alias will be referenced by the EntireX adapter connection service when it initializes the Direct RPC listener. You will need the keystore password used to generate the Java key store (.jks) file to register it in webMethods Integration Server. 
Define the ‘Broker’ parameter on the RPC Server with the Adapter machine and port defined (e.g., MCCHRISP01:6022). The RPC Server should behave as if it is talking to a Broker. From the Adapter Web admin, you should now see the Server registration (class\server\service) in the Direct RPC administration page.                           

Using the EntireX SSL feature will ensure your sensitive data is protected from prying eyes over private or public networks. Keeping your digital certificates up to your organization’s security standards is literally “key” to making your application data secure and stakeholders sleep at night. 
z/OS’s RACF offers a robust certificate authority for managing and generating digital certificates and, when coupled with EntireX’s SSL feature, offers a secure message transport solution for your most critical and sensitive information. 
Deploying SSL with EntireX RPC can be simple if you can associate certificate type (public or private) with SSL type (client or server).
Please read more about EntireX Security here:  EntireX Security – Authentication, Authorization and Encryption  by describing SSL and showing how to use and maintain secure communications across EntireX boundaries.
Additional Information