RACF PassTicket for IMS Connect client connections to IMS DB

You can use RACF PassTickets to authenticate IMS Connect client connections to IMS DB. PassTickets are an alternative to RACF passwords and password phrases and provide better security because PassTickets remove the need to send passwords and password phrases across the network in clear text.

When RACF PassTickets are used to authenticate user access from a DRDA client to IMS DB, the PassTickets can be generated by the SQL Batch utility. If you use another DRDA client instead of the SQL Batch utility to access IMS DB, you can use another method that uses the RACF PassTicket generator algorithm to generate and evaluate PassTickets for your DRDA client.

The following high-level process describes how an IMS Connect client connection to IMS DB is authenticated with a RACF PassTicket if the client uses DRDA:

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.

Tips:

If RACF is not enabled in the IMS Connect instance, do not configure the DRDA client to generate PassTickets. The IMS Connect instance does not perform security checking and ignores any PassTicket data that is sent when RACF=N. Creating a PassTicket on the DRDA client side wastes processing resources.
Do not use RACF PassTickets with non-persistent connections because doing so incurs significant processing overhead. A new PassTicket is generated and sent each time a new connection is established.

Procedure

To secure connections from a DRDA client to IMS DB by using a RACF PassTicket, perform the following steps:

Define to RACF the PassTicket class, application profile, application name, and user ID:
1. Activate the PTKTDATA class. The PTKTDATA class is the class to which all profiles that contain PassTicket information are defined. To activate the class and the function, enter the following command:
```
SETROPTS CLASSACT(PTKTDATA) RACLIST(PTKTDATA)
```
2. Enter the following commands to define the name of the application that users require access to by using the PassTicket:
```
RDEFINE APPL <applname> UACC(NONE)
SETROPTS CLASSACT(APPL)
SETROPTS GENERIC(PTKTDATA)
```
  Where:
  
  applname
  
  Is a 1- to 8-character name for the application.
3. Enter the RDEFINE command to define a profile for the application that users can gain access to with the PassTicket. The profile associates a secret secured sign-on application key with an application.
```
RDEFINE PTKTDATA <applname> SSIGNON(<key_description>(<key>))
```
  Where:
  
  applname
  
  Is the 1- to 8-character application name that you defined in step 1.b.
  
  key_description
  
  Specifies the method RACF is to use to protect the secured signon application key in the RACF database on the host. You can specify one of the following values:
  
  KEYMASKED
  
  Masks the secured signon application key.
  
  KEYENCRYPTED
  
  Encrypts the secured signon application key.
  
  key
  
  The secured signon application key, which is a user-supplied, 16-character hexadecimal value (0 – 9 and A – F).
4. Enter the PERMIT command to permit a user ID to the application:
```
PERMIT APPLNAME CLASS(APPL) ID(<userid>) ACCESS(UPDATE)
```
  Where:
  
  userid
  
  The user ID that is permitted to access the application. If you are using the SQL Batch utility to generate the PassTicket, the user ID must be the z/OS® user ID that is associated with the batch job.
5. If you are using the SQL Batch utility to generate the PassTicket, enter the following command to permit the application to use the RACF PassTicket Generator service:
```
RDEFINE PTKTDATA IRRPTAUTH.<applname>.* UACC(NONE)
PERMIT IRRPTAUTH.<applname>.* CLASS(PTKTDATA) ID(<userid>) ACCESS(UPDATE)
```
  Where:
  
  applname
  
  Is a 1- to 8-character name for the application defined in step 1.b.
  
  userid
  
  The user ID that is permitted to access the application. If you are using the SQL Batch utility to generate the PassTicket, the user ID must be the z/OS user ID that is associated with the batch job.
6. Refresh the PTKTDATA class and the to activate the changes by entering the following commands:
```
SETROPTS RACLIST(APPL) REFRESH
SETROPTS RACLIST(PTKTDATA) REFRESH
```
Ensure that RACF=Y is specified in the HWS statement of the HWSCFGxx member.
Use one of the following methods to specify in the APPL= parameter of the ODACCESS statement the application name that is defined to RACF in the PTKTDATA class. That is, specify in the APPL= parameter the application name that you defined in step 1.b. The application name that is specified on the APPL= parameter is used, in addition to the user ID and the RACF PassTicket, by IMS Connect on the RACF call RACROUTE REQUEST=VERIFY to authenticate DRDA client connections to IMS DB.
- Directly add the APPL= parameter to the ODACCESS statement of the HWSCFGxx member.
- Issue the following IMS type-2 command:
```
UPDATE IMSCON TYPE(CONFIG) SET(ODBMAPPL(applname))
```
  Where applname is the application name that is defined to RACF in the PTKTDATA class.
If the APPL= parameter is not specified, the value of the ID= parameter of the HWS statement, which is in the HWSCFGxx member, is used instead by IMS Connect in the RACF call RACROUTE REQUEST=VERIFY. Therefore, if the APPL= parameter is not specified, ensure that the application name that is defined in the PTKTDATA class is specified instead on the ID= parameter of the HWS statement.
Generate the PassTicket for the DRDA client.

If you use the SQL Batch utility to generate the PassTicket, specify the applname URL property of the DriverManager.getConnection method.

If you do not use the SQL Batch utility to generate the PassTicket, see Generating and evaluating a PassTicket for information on other methods to generate and evaluate a PassTicket by using the RACF PassTicket generator algorithm.
To use the generated PassTicket to authenticate the user of the IMS Connect client with RACF, use the SECCHK command (X'106E') to send the user ID and the PassTicket to IMS Connect. In the SECCHK command (X'106E'), include the user ID in the code point, X'11A0', for the USRID parameter of the command and include the PassTicket in the code point, X'11A1', for the PASSWORD parameter of the command.