Network security credential propagation enhancement

In IMS 15, you can associate the security credentials that are entered by a user in a distributed environment with the end-to-end processing of a transaction in IMS. The distributed security credentials can even be propagated to synchronous callout requests that are initiated by the ICAL call of the IMS DL/I interface.

With the network security credential propagation enhancement, when network security credentials are entered by a user in a distributed environment and are passed to IMS, the security credentials are audited in IMS log records. Previously, when a user initiated an IMS transaction in a distributed environment and entered security credentials, the credentials were not propagated to IMS and were therefore excluded from IMS log records.

The distributed network security credentials can include a network user ID and a network session ID.

Network user ID: The distributed identity of the user. The maximum length of a network user ID is 246 bytes. For users of the IMS TM Resource Adapter, the network user ID is a Distinguish Name (DN) in the X.500 series of standards.
Network session ID: The session identity of the distributed user. The maximum length of a network session ID is 254 bytes. For users of the IMS TM Resource Adapter, the network session ID is a domain name, realm, or registry name.

Network security credentials can be propagated from user-written IMS Connect client applications that use the HWSSMPL0 or the HWSSMPL1 user message exit routines. Two new IRM extension specifications are added with this enhancement to enable applications that use the HWSSMPL0 or the HWSSMPL1 user message exit routines to pass network security credentials to IMS. An IRM extension with an ID of *NETUID* can be used to pass a network user ID to IMS and an IRM extension with an ID of *NETSID* can be used to pass a network session ID to IMS. If network security credentials are included in an IMS callout request, the RESUME TPIPE call of the IMS Connect client application can be defined to support the credentials.

IMS TM resource adapter client applications that use the HWSJAVA0 user message exit routine can also propagate network security credentials to IMS. An extendable Java™ Authentication and Authorization Service (JAAS) login module is provided with IMS TM resource adapter to enable network security credentials to be passed from a Java EE application that uses the HWSJAVA0 user message exit routine to IMS. The activation specification is enhanced with the resumeTpipeNsc property to enable IMS TM resource adapter to support network security credentials in IMS synchronous callout messages. To enable IMS TM resource adapter to support network security credentials in asynchronous callout messages, the IMS interaction specification is enhanced with the setResumeTpipeNSC property.

Migration considerations

If the security-data section of the OTMA message prefix contains network security credentials, the size of the OTMA message can increase by up to 504 bytes. Therefore, consider increasing the size of the SHMSG and LGMSG message queue data sets and the size of the message queue pool.
If both of the following situations occur, you might need to modify code that includes the HWSOMPFX macro:
- The Network Session ID (NETSID) section or the Network User ID (NETUID) section, or both, is included in the security section of the OTMA message header.
- Either the DSECT=ALL or the DSECT=NO option is specified with the HWSOMPFX macro.
The size of the NETUID and NETSID sections can vary, causing the locations of the fields that are below the security section to change. However, if the DSECT=ALL or the DSECT=NO option is specified, a contiguous DSECT, the HWSOMPFX DSECT, is generated that does not account for sections that vary in size. Therefore, the fields in the OTMA message header that are below the security section might become inaccessible.
For the fields of the OTMA message header that are below the security section to be accessed, you need to map the HWSOMUSR, HWSOMAPP, or HWSOMAPX DSECTS of the HWSOMPFX macro to the changed locations of the fields.

For more information about the fields of the OTMA message header, see OTMA header fields used by IMS Connect.
In IMS 15, processing by the HWSJAVA0 user message exit routine of the user data section that is in the OTMA message header is updated. If the OTMA message header contains network security information and the HWSOMPFX macro is used, the HWSJAVA0 exit routine specifies both the DSECT= and the NETSEC_OPT=YES options for the HWSOMPFX macro. The DSECT= and the NETSEC_OPT=YES options cause the following behaviors:
- An individual DSECT is generated for each section of the OTMA message header.
- The HWSECDNDS DSECT, or the HWSECARDS DSECT, or both, is generated to map network security information.
- The HWSOMPFX DSECT is not generated.

Coexistence considerations

Network security credentials can be passed to IMS and audited in IMS log records only if both IMS Connect and IMS are Version 15 or later. If network security credentials are passed between IMS and client applications of IMS TM resource adapter in inbound and outbound, or callout, messages, IMS TM resource adapter must also be V15 or later.

Log record changes

Because distributed network security credentials are passed to IMS in the security-data section of the OTMA message prefix, all IMS log records that contain information about the message prefix, such as log records X'01' and X'03', include the distributed security credentials.

If a Fast Path message contains network security credentials and is processed by the Fast Path expedited message handler (EMH) on the local IMS system, the credentials are logged in the X'5901' log record.

If a Fast Path message that contains network security credentials is processed by using the EMH queue (EMHQ) in a shared-queues environment, in the front-end IMS system, the credentials are included in the X'5911' log record. In the back-end IMS system, which is the processing IMS system, the credentials are included in the X'5901' log record.

Requirements

The following prerequisites must be enabled for IMS TM resource adapter client applications, except for the client applications that use the IMS service provider in IBM® z/OS® Connect Enterprise Edition (z/OS Connect EE), to support network security credentials:

One of the following application servers:
- WebSphere® Application Server Version 8.0 or later
- WebSphere Liberty Version 8.5.5.9 or later
Container-managed security.
An external user account registry, such as an LDAP server, that contains authorized users.

Restrictions

Distributed network security credentials from DataPower®, IMS Connect API, and SOAP Gateway clients are not supported by IMS Connect and therefore are not audited in IMS log records.

When the IMS Connect Recorder Trace facility is active, IMS Connect takes a snapshot of the first 670 bytes of messages at key points during IMS Connect processing. Because messages that contain network security credentials might be larger than 670 bytes, the information for the network user ID and the network session ID might not be included in an IMS Connect Recorder trace record.

Changes to installing and defining IMS

The LOGSTR= parameter is added to the OTMA client descriptor in the DFSYDTx member of the IMS™ PROCLIB data set. You can use the LOGSTR= parameter to specify whether the first 255 bytes of network security credentials, which includes a network user ID or network session ID, or both, is included in the RACF® SMF process records.

Changes to programming for IMS

The IMS OTMA Callable Interface (OTMA C/I) is enhanced with the otma_send_receivey and otma_send_asyncx APIs. You can use these APIs to pass the network user ID and the network session ID to IMS. For each API, up to 100 bytes for the network user ID and up to 100 bytes for the network session ID can be passed to IMS.

The INQY call with the MSGINFO subfunction is enhanced to return the network user ID and the network session ID that are submitted to IMS. IMS application programs can use the INQY MSGINFO call to identify the distributed user who initiated a transaction.

Changes to troubleshooting for IMS

Recommendation: If network security credentials are included in IMS Connect client input messages, enable the BPE External Trace facility for the IMS Connect Recorder Trace facility. If network security credentials are passed to IMS Connect, the size of both input and output messages to and from IMS Connect might be larger than 670 bytes and the BPE External Trace facility would be required to capture the data of the entire message.

For a list of the messages and codes that are new or changed for this enhancement, see the IMS messages and codes row in the table in Documentation changes.

For a complete list of all of the new, changed, and deleted messages, and abend codes in IMS 15, see Message and code changes in IMS 15.

Changes to exit routines

The following IMS Connect user message exit routines are enhanced to propagate network security credentials between IMS and applications in a distributed environment:

HWSSMPL0
HWSSMPL1
HWSJAVA0

The following transaction manager exit routines are enhanced to include the address of the security-data section of the OTMA message prefix. Because the OTMA security-data section can include a network user ID and a network session ID, you can use the following exit routines to access the network security credentials if the credentials are passed to IMS.

DFSYIOE0
DFSYPRX0
DFSYDRU0

The DFSCTRN0 exit routine is enhanced to add two OTMA fields, which include the addresses of the network user ID and the network session ID, in the storage area that is mapped the CTRNPARM DSECT.

Documentation changes

The following publications contain new or changed information for the IMS support for z/OS® distributed identity propagation enhancement. The links for a publication can be listed on two separate rows, with links to topics that have new content on one row and links to changed content on another. Publications that are not impacted by the enhancement are not included in the table.

Table 1. Links to topics that have new or changed content for this enhancement
Publication	Links to topics
Release planning	General planning information for IMS 15>Coexistence with IMS 15>Specific coexistence considerations Network security credential propagation enhancement coexistence considerations (new) General planning information for IMS 15 > Migration to IMS 15 > Specific migration considerations > Migrating to IMS 15: System OTMA migration considerations IMS Connect migration considerations Migration considerations for network security credential propagation enhancement (new) Message and code changes in IMS 15 New messages and codes for IMS 15 Changed messages and codes for IMS 15 Log record changes in IMS 15 Network security credential propagation enhancement (new) (This topic)
System definition	Members of the IMS PROCLIB data set> DFSYDTx member of the IMS PROCLIB data set OTMA client descriptor syntax and parameters
Communications and connections	IMS Connect and TCP/IP communications IMS Connect security support Passing network security credentials through IMS Connect (new) HWSSMPL0 and HWSSMPL1 security actions IMS Connect support for callout requests > Configuring user-written IMS Connect clients for synchronous callout requests Retrieving synchronous callout requests with RESUME TPIPE IMS Connect message structures IRM structures for IMS Connect client messages Format of user portion of IRM for HWSSMPL0, HWSSMPL1, and user-written message exit routines Format of IRM extensions (new) Message structures and IMS Connect user message exit routines Output message to client Message structures Input message from client and passed to message exit Input message returned from message exit Output message from message exit to client Format of the PING response Format of the returned network security segments (new) OTMA header fields used by IMS Connect OTMA state data fields used by IMS Connect OTMA security data fields used by IMS Connect IMS Connect protocols > Retrieval of output on OTMA tpipe hold queues RESUME TPIPE/receive protocol Open Transaction Manager Access (OTMA) Enabling and using OTMA Managing system resources and OTMA IMS message queue data set size and OTMA OTMA security> Specifying OTMA security Security specifications in OTMA message prefixes Distributed network security credential support and OTMA (new) General OTMA security considerations Using DL/I calls in an OTMA environment OTMA message prefix State data section Transaction and callout messages Resume output for the hold queue for tpipe Security data section Explanation of OTMA security data fields
System administration	IMS system administration considerations and tasks IMS security Designing security for IMS DB/DC and DCCTL Propagating network security credentials (new) Propagating network security credentials for user-written IMS Connect client applications (new) Propagating network security credentials for IMS TM resource adapter client applications (new) Security for OTMA Security for IMS Connect Tuning the system Initializing z/OS and IMS parameters for tuning>IMS buffer pool tuning Message queue pool tuning
Application programming	IMS Transaction Manager Resource Adapter IMS Transaction Manager Resource Adapter overview IMS TM resource adapter features New features in IMS TM Resource Adapter Version 15 Requirements for the IMS TM resource adapter Developing an application for use with the IMS TM resource adapter Interacting with the IMS Transaction Manager>Programming models>Callout programming models>Managed callout programming model>Configuring a J2C activation specification IMSActivationSpec property configuration for message-driven beans Securing interactions with the IMS Transaction Manager IMS TM resource adapter security Network security credentials and IMS TM resource adapter (new) Configuring Websphere Application Server for distributed network security credentials (new) Configuring Websphere Liberty for distributed network security credentials (new) Enabling IMS TM resource adapter to support network security credentials in callout messages (new) Reference information IMS interaction specification properties Resume tpipe network security credentials (resumeTpipeNSC) (new)
Application programming APIs	DL/I calls reference Transaction management > DL/I calls for transaction management INQY call Database management > DL/I calls for IMS DB system services INQY call OTMA Callable Interface API calls OTMA C/I hints and tips otma_send_asyncx API (new) otma_send_receivey API (new)
Diagnosis	IMS Connect service aids IMS Connect traces
IMS messages and codes	DFS messages DFS2385E	IMS component codes Return and reason codes for IMS Connect exits OTMA C/I return codes
Exit routines	IMS control region exit routines> Transaction Manager exit routines OTMA Input/Output Edit user exit (DFSYIOE0 and other OTMAIOED type exits) OTMA Destination Resolution user exit (DFSYPRX0 and other OTMAYPRX type exits) OTMA User Data Formatting exit routine (DFSYDRU0) Transaction Authorization exit routine (DFSCTRN0) IMS Connect exit routines IMS TM Resource Adapter user message exit routine (HWSJAVA0)