Using the service to generate a secured signon session key

To allow RACF® to create a secured signon session key, the non-RACF z/OS application calls the secured signon session key generator service.

The secured signon session key generator service:

Is branch-entered by callers
Is not supported in cross-memory mode
Requires that the caller be in task mode, system key zero (0), and primary ASC mode

Before calling the secured signon session key generator service, the application must locate the address of the service. This address can be found in field RCVTSKGN 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 secured signon session key generator service works

The service:

Uses standard linkage
Uses the PassTicket as input for the algorithm
Returns the session key in general purpose register 0 (4 bytes) and general purpose register 1 (4 bytes)
Provides return codes

Note:

The secured signon session key generator service uses either the current task level or address space level ACEE unless an ACEE address is passed on the input parameter list.
If an application is using a RACF PassTicket to authenticate users and wants to derive a session key for securing application-to-user communication, the application must establish a task level ACEE for its client or point to the client's ACEE. The following calls must be made in this sequence:
1. A RACROUTE REQUEST=VERIFY,ENVIR=CREATE request to authenticate and create a task level ACEE for the application's client. (This request can be omitted if the client's ACEE was previously created by a RACROUTE REQUEST=VERIFY.)
2. Construct a secured signon session key generator parameter list and branch to the address pointed to by RCVTSKGN.
Register 13 points to a standard save area.
No additional recovery processing is provided by the secured signon session key generator service beyond what is already in effect for the invoking program.

Invoking the secured signon session key generator service

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

LA   1,MY_APPL_PLIST
L    15,RCVTSKGN
CALL (15),(1)

Displacement	Description
+0	A pointer to the RACF PassTicket used for user authentication
+4	A pointer to a one-byte length field followed by up to 8 characters which is the APPLID
+8	A pointer to the address of the user ID's ACEE that was created during PassTicket evaluation. If the address is zero, the task level ACEE (TCBSENV) is used if it exists. If not, the address space level ACEE (ASXBSENV) is used.

Return codes from the secured signon session key generator service

The secured signon session key generator service produces the following return codes in register 15:

Note: The values shown are in hexadecimal.

Return Code	Description
0	Successful completion. The resulting session key is contained in general purpose registers 0 and 1.
4	Incorrect PassTicket
8	No PTKTDATA profile found for the application
C	No task or address space ACEE found, and the ACEE pointer was not specified on the input parameter list.
10	Caller is not authorized
14	The RACF PTKTDATA class is not active
18	Error in the session key generator process