RACF PassTicket support for DRDA clients enhancement

In IMS 15 with APAR PI99040 (PTF UI58288), you can use RACF® PassTickets to authenticate users who access IMS DB from IMS Connect clients that use the Distributed Relational Database Architecture™ (DRDA) protocol.

RACF PassTickets are one-time-only passwords and are an alternative to RACF passwords and password phrases. RACF PassTickets are also more secure than RACF passwords and password phrases because PassTickets remove the need to send passwords and password phrases across the network in clear text. Because this enhancement adds support for PassTickets for IMS Connect clients that connect to IMS DB by using DRDA, you can use this enhancement to improve the security of the DRDA client connections. Previously, when IMS Connect was configured to call RACF, access from IMS Connect clients to IMS DB could be authenticated by using only RACF passwords or password phrases.

With APAR PH02135 (PTF UI58345), the SQL Batch utility of the IMS Universal Java™ Database Connectivity (JDBC) driver is also enhanced to enable the utility to generate PassTickets for IMS DB access authentication. If you use another DRDA client instead of the SQL Batch utility to access IMS DB, ensure that a service that uses the RACF PassTicket generator algorithm is used to generate the PassTicket.

The following procedure is a high-level description of the end-to-end process, introduced with this enhancement, by which a RACF PassTicket is used to authenticate a user who accesses IMS DB from a DRDA client:

When the client connection is first established, the RACF PassTicket that is used to authenticate the connection to IMS DB is generated either by the SQL Batch utility or, for other DRDA clients, by a service that uses the RACF PassTicket generator algorithm.
The client application sends to IMS Connect the generated PassTicket and the ID of the user requiring access in the SECCHK command (X'106E'). The PassTicket is specified in the code point, X'11A1', for the PASSWORD parameter of the SECCHK command. The user ID is specified in the code point, X'11A0', for the USRID parameter of the SECCHK command.
IMS Connect issues the RACROUTE REQUEST=VERIFY call to RACF to authenticate the client connection. On the RACF RACROUTE REQUEST=VERIFY call, IMS Connect includes the following information:
- The RACF PassTicket and the user ID sent from the client application in the SECCHK command (X'106E').
- The application name as specified on the APPL= parameter of the ODACCESS statement, which is in the HWSCFGxx member of the IMS PROCLIB data set. If an application name is not specified on the APPL= parameter of the ODACCESS statement, IMS Connect uses instead the value that is specified on the ID= parameter of the HWS statement, which is also in the HWSCFGxx member.

Changes to installing and defining IMS

The APPL= parameter is added to the ODACCESS statement in the HWSCFGxx member of the IMS PROCLIB data set. To authenticate DRDA client connections to IMS DB by using PassTickets, you must specify on the APPL= parameter the application name that is defined to RACF in the PTKTDATA class. The value that is specified on this parameter is used, in addition to the user ID and the RACF PassTicket, by IMS Connect in the RACF call RACROUTE REQUEST=VERIFY to authenticate the IMS Connect client to IMS DB.

If a RACF PassTicket is passed from a DRDA client to IMS Connect but this parameter is not specified, the HWS ID from the ID= parameter of the HWS statement is used instead by IMS Connect in the RACF call RACROUTE REQUEST=VERIFY.

The APPL= parameter is used only if RACF=Y is specified in the HWS statement of the HWSCFGxx member.

Changes to programming for IMS

To enable you to use the SQL Batch utility to generate RACF PassTickets to authenticate user access to IMS DB from a JDBC application, the applName URL property is added to the DriverManager.getConnection method of the IMS Universal JDBC driver. On the applName parameter, you can specify the 1- to 8-character application name that is defined to RACF in the PTKTDATA class for DRDA clients that access IMS DB. The value that is specified on this parameter is used by the SQL Batch utility to generate the RACF PassTicket.

When a JDBC application connects to IMS DB by using the JDBC DriverManager interface, the connection can be authenticated by a PassTicket only when the SQL Batch utility is run.

If you do not use the SQL Batch utility to generate PassTickets, see Generating and evaluating a PassTicket for information on other methods that you can use to enable your DRDA client to generate and evaluate PassTickets.

The SECCHK command (X'106E') is also enhanced to allow the PassTicket to be passed to IMS Connect, regardless of whether the PassTicket is generated by the SQL Batch utility or by another service. To pass the generated PassTicket to IMS Connect to authenticate a user to access IMS DB from a DRDA client, include the PassTicket in the code point, X'11A1', for the PASSWORD parameter of the command. The user ID must also be specified in the code point, X'11A0', for the USRID parameter of the command. IMS Connect uses, in addition to value of the APPL= parameter of the ODACCESS statement, the user ID and the PassTicket that are received on the SECCHK command to call RACF for user authentication.

Changes to commands

The following commands are enhanced:

QUERY IMSCON TYPE(CONFIG)

The ODBMAPPL filter is added to this command to display the value that is specified on the APPL= parameter of the ODACCESS statement:

QUERY IMSCON TYPE(CONFIG) SHOW(ODBMAPPL)

UPDATE IMSCON TYPE(CONFIG)

The ODBMAPPL keyword option is added to this command. You can use this keyword option to set the application name that is used by IMS Connect on the

RACROUTE
REQUEST=VERIFY

RACF call to verify DRDA client connections to IMS DB:

UPDATE IMSCON TYPE(CONFIG) SET(ODBMAPPL(applname))

Changes to exit routines

The IMS Connect DB security user exit routine (HWSAUTH0) is enhanced with the AUTPM_AAppl field in the HWSAUTPM parameter list. This field includes the application name that is specified on the APPL= parameter of the ODACCESS statement.

Changes to utilities

The SQL Batch utility is enhanced to generate RACF PassTickets to authenticate users of JDBC applications to access IMS DB. To enable the utility to generate RACF PassTickets, you must specify the name of the application that the user requires access to on the applName URL property of the DriverManager.getConnection method.

To use the SQL Batch utility to generate RACF PassTickets, in addition to specifying the application name in the applName property of the DriverManager.getConnection method, you must also ensure that the following conditions are met:

Both the IRRRacf.jar and ibmjzos.jar files are in the job's class path.
The following values are the same as each other:
- The value of the applName URL property of the DriverManager.getConnection method.
- The value of the APPL= parameter of the ODACCESS statement, which is in the HWSCFGxx member of the IMS PROCLIB data set.
On the JOB statement of the JCL for the SQL Batch utility, the z/OS® user ID that is associated with the job is specified.

Coexistence considerations

To use the updates to the QUERY IMSCON TYPE(CONFIG) and UPDATE IMSCON TYPE(CONFIG) commands that are delivered with this enhancement in a mixed-version IMSplex that includes both IMS 14 and IMS 15, apply the IMS 15 APAR/PTF for this enhancement before you apply the IMS 14 APAR/PTF. That is, apply IMS 15 APAR PI99040 (PTF UI58288) on IMS 15 systems before you apply IMS 14 APAR PI99038 (PTF UI58287) on IMS 14 systems.

Documentation changes

The following table lists the publications that contain new or changed topics for the RACF PassTicket support for DRDA clients enhancement. Publications that are not impacted by this 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 Command changes in IMS 15 IMS IMS 15 enhancements IMS 15 system continuous delivery functions RACF PassTicket support for DRDA clients enhancement (new) (this topic)
System definition	Members of the IMS PROCLIB data set > HWSCFGxx member of the IMS PROCLIB data set HWS statement ODACCESS statement
Communications and connections	IMS Connect and TCP/IP communications Overview of IMS Connect Overview of IMS Connect security IMS Connect security support IMS Connect security for clients of IMS DB IMS Connect password management IMS Connect support for RACF PassTicket RACF PassTicket for IMS Connect client connections to IMS TM RACF PassTicket for IMS Connect client connections to IMS DB (new)
System administration	Using RACF PassTickets Creating and using a RACF PassTicket Security for IMS Connect
Application programming	Connecting to an IMS database by using the JDBC DriverManager interface
Application programming APIs	SECCHK command (X'106E')
IMS commands	QUERY IMSCON TYPE(CONFIG) command UPDATE IMSCON TYPE(CONFIG) command
Exit routines	IMS Connect DB security user exit routine (HWSAUTH0)
Database utilities	SQL Batch utility