Using the RCVTPTGN service to generate a PassTicket

To allow RACF® to authenticate a user with a PassTicket instead of a password, the non-RACF function performing the authentication calls the Start of change RCVTPTGN End of change service to build a PassTicket.

The

RCVTPTGN

service:

Is branch-entered by callers.
Is not supported in cross-memory mode. Access register (AR) mode must use address space control (ASC).
Is not supported in SRB mode.
Requires that the caller be in key zero.
Is unable to generate PassTickets using the PTKTDATA profiles which are qualified by user id and / or group. It can only generate PassTickets using profiles which match the application name.
Supports generation of legacy PassTickets or enhanced PassTickets based on RACF configuration.

Before calling the Start of change PassTicket-generation End of change service, the application must locate the address of the service. You can find this address from field RCVTPTGN in the RACF communications vector table (RCVT). The ICHPRCVT macro maps the RCVT and field CVTRAC points to it in the MVS™ communications vector table (CVT).

How the PassTicket-generation service works

The service:

Uses standard linkage
Uses the current system time, expressed in Greenwich Mean Time (GMT), ¹ as input for the algorithm
Returns the PassTicket in general purpose register 0 (the leftmost four characters) and general purpose register 1 (the rightmost four characters)
The type of PassTicket returned is based on the keys configured in the associated PTKTDATA class profile:
- An enhanced PassTicket is returned when an enhanced PassTicket key label is configured with the EPTKEYLABEL keyword.
- A legacy PassTicket is returned when a legacy PassTicket key is configured with the KEYMASKED, KEYENCRYPTED or KEYLABEL keywords and no enhanced PassTicket key label is configured.
- In the case where a PTKTDATA class profile is configured to contain both a legacy PassTicket key and enhanced PassTicket key, an enhanced PassTicket is returned.

Provides return codes

If a PassTicket is produced, register 15 contains a return code of 0

If a PassTicket is not produced, register 15 contains return code of 8 Start of change

Register 0 contains a reason code. The 1st byte of the reason code indicates the problem, the other 3 bytes may contain additional information:

Value (decimal)	Meaning	Bytes 2-4
12	ICSF CSNBENC service failed	Byte 2=ICSF RC Byte 3 and 4=ICSF RSN
16	RACROUTE REQUEST=EXTRACT, TYPE=ENCRYPT failed	Byte 2=SAFRC from RACROUTE Bytes 3 and 4=0
20	PTKTDATA class inactive	0
24	No profiles defined to the PTKTDATA class	0
28	Unable to load ICSF CSFACEE or CSFIQF service	Byte 2=Reason code from z/OS LOAD macro
36	PTKTDATA profile representing the APPL not found or the PTKTDATA profile does not have a key saved in the SSIGNON segment	0
52	Caller not in key 0	0
56	ICSF not initialized	Byte 2=ICSF RC Byte 3 and 4=ICSF RSN
60	ICSF CSNBHMG service failed.	Byte 2=ICSF RC Byte 3 and 4=ICSF RSN
Other = Internal error

Notes:

Register 13 must point to a standard save area.
No additional recovery processing is provided by the PassTicket-generation service beyond what is already in effect within the invoking program.

Invoking the PassTicket-generation service

Following is an example of a generalized programming technique you can use with assembler language to invoke a service. It is not intended to be syntactically correct.

L 15,RCVTPTGN
CALL (15),(userid,appname)

where:

userid: Is the RACF user ID of the user the PassTicket authenticates. This field is a maximum of 9 bytes. The first byte contains the length of the non-blank portion of the userid field that follows. Bytes 2 through 9 contain the user ID and must be in uppercase and left-justified in the field.
appname: Is the application name that the PassTicket-generation service uses to locate the key used in the PassTicket generator algorithm. This field is a maximum of 9 bytes. The first byte is the length of the non-blank portion of the appname field that follows. Bytes 2 through 9 contain the application name and must be in uppercase and left-justified in the field.
When the service is invoked, only the appname (not the userid or group) is used to locate the PassTicket key. It is not possible to use the RCVTPTGN service to generate PassTickets using keys which are stored in user id or group id qualified profiles.