The MVS router

SAF provides your installation with centralized control over security processing, by using a system service called the MVS™ router. The MVS router provides a common system interface for all products providing resource control. The resource-managing components and subsystems (such as CICS®) call the MVS router as part of certain decision-making functions in their processing, such as access control checking and authorization-related checking. These functions are called control points. This single SAF interface encourages the use of common control functions shared across products and across systems.

If RACF® is available in the system, the MVS router may pass control to the RACF router, which in turn invokes the appropriate RACF function. (The parameter information and the RACF router table, which associates router invocations with RACF functions, determine the appropriate function.) However, before calling the RACF router, the MVS router calls an optional, installation-supplied security-processing exit, if one has been installed.

The MVS router exit

The MVS router provides an optional installation exit that is invoked whether or not RACF is installed and active on the system. If your installation does not use RACF, you can use the router exit to pass control to your own ESM. If you do use RACF, you could use the exit for preprocessing before RACF is invoked.

The MVS router exit routine is invoked whenever CICS (or another component of your system) issues a RACROUTE macro. The router passes a parameter list (generated by the RACROUTE macro) to the exit routine. In addition, the exit receives the address of a 150-byte work area.

On entry to the exit routine, register 1 contains the address of the area described in Table 42.

Table 42. Area addressed by register 1, on entry to exit routine
Offset Length Description
0 4 Parameter list address: points to the MVS router parameter list. (See The MVS router parameter list.)
4 4 Work area address: points to a 150-byte work area that the exit can use.
 

The exit must be named ICHRTX00 and must be located in the link pack area (LPA).

Note:
During signon processing, CICS Transaction Server for z/OS®, Version 3 Release 1 issues the RACROUTE REQUEST=VERIFY macro with the ENVIR=VERIFY option, in problem-program state. (For an explanation of why CICS does this, see Using early verification processing.) RACF requires RACROUTE calls with the ACEE option to be issued in supervisor state. Therefore, if you use an ICHRTX00 exit that intercepts CICS RACROUTE calls, and replaces them with its own RACROUTE requests, your exit program should not assume that a REQUEST=VERIFY call was made in supervisor state.

When intercepting a REQUEST=VERIFY call, your exit program should check the settings of the two high-order bits of the byte at offset 3 in the RACINIT parameter list. If ENVIR=VERIFY was specified on the call (as in CICS early verification), these bits are both set on. If this is the case, your exit program should not issue any further RACROUTE macros. To do so could cause abends in RACF.

The MVS router parameter list

The MVS router parameter list is generated when the RACROUTE macro is issued, and describes the security processing request by providing the request type. If the router exit routine exists, the router passes the parameter list to this exit. (If it does not exist, and if RACF is active, the router passes the parameter list to the RACF router.)

You can map the MVS router parameter list using the ICHSAFP macro. Its format is shown in the OS/390 Security Server External Security Interface (RACROUTE) Macro Reference manual.

Router exit return codes

Your exit routine must return a return code in register 15. The hexadecimal values of the return code are shown in Table 43.

Table 43. MVS router exit return codes
Code Meaning
0 The exit has completed successfully. Control proceeds to the RACF front-end routine for further security processing and an invocation of RACF.
C8 The exit has completed successfully. The MVS router translates this return code to a router return code of ‘0’ and returns control to the issuer of the RACROUTE macro (CICS), bypassing RACF processing. (See the next section.)
CC The exit has completed successfully. The MVS router translates this return code to a router return code of ‘4’ and returns control to CICS, bypassing RACF processing. (See the next section.)
D0 The exit has completed successfully. The MVS router translates this return code to a router return code of ‘8’ and returns control to CICS, bypassing RACF processing. (See the next section.)
Other If the exit routine sets any return code other than those described above, the MVS router returns control directly to CICS and passes the untranslated code as the router return code. Further RACF processing is bypassed.

Passing control to a user-supplied ESM

Normally, a caller (such as CICS) invokes the MVS router and passes it request type, requester, and subsystem parameters via the RACROUTE exit parameter list. Using these parameters, the MVS router calls the router exit which, on completing its processing, passes a return code to the router. If the return code is ‘0’, as defined above, the router invokes RACF. RACF reports the result of that invocation to the router by entering return and reason codes in register 15 and register 0 respectively. The router converts the RACF return and reason codes to router return and reason codes and passes them to the caller. The router provides additional information to the caller by placing the unconverted RACF return and reason codes in the first and second words of the router input parameter list.

If your installation does not use RACF, you can make the MVS router exit pass control to an alternative ESM. However, if you do so you must still provide CICS with the RACF return and reason codes that it expects to receive. You set the router exit return code, as defined in Table 43, so that RACF is not invoked; and you simulate the results of a RACF invocation by coding the exit so that it places the RACF return and reason codes in the first and second fullwords of the router input parameter list. RACF return and reason codes are documented in the MVS Authorized Assembler Programming Reference manual.

Note:
Remember that it is possible for a subsystem other than CICS to call the MVS router by issuing a RACROUTE macro. (Application programs too, may issue RACROUTE macros directly.) Your router exit program can establish whether the caller is CICS by checking the "eyecatcher" fields (UXPARROW, UXPDFHXS, and UXPBLKID) in the installation data parameter list--see The installation data parameter list.

Related concepts
An overview of the CICS-ESM interface
Related tasks
Using ESM exit programs to access CICS-related information
Using early verification processing
Related reference
CICS security control points
[[ Contents Previous Page | Next Page Index ]]