ICHRTX00 — MVS Router Exit

Topics for This Exit Appear as Follows:

The system authorization facility (SAF) provides an installation with centralized control over system security processing through a system service called the MVS™ router. The MVS router provides a focal point for all products that provide resource management. The resource management components and subsystems call the MVS router as part of security decision-making functions in their processing, such as access control checking and authorization-related checking. These functions are called “control points”. SAF supports the use of common control points across products and across systems.

To use the MVS router, a resource management component or subsystem issues the RACROUTE macro. The RACROUTE macro accepts all valid parameters for any of the independent RACF® system macros (RACDEF, RACINIT, RACHECK, RACLIST, RACXTRT, and FRACHECK). RACROUTE verifies that only valid parameters have been coded and then passes the parameters to the MVS router.

For more information on the RACROUTE macro and programming requirements for the ICHRTX00 exit, see z/OS Security Server RACROUTE Macro Reference.

The RACROUTE macro invokes the MVS router. When it is invoked, the MVS router first calls an optional installation exit routine. If an external security product (such as RACF) is active and installed on the system, the MVS router calls it next. This process is shown in Figure 1.

Figure 1. RACROUTE macro invokes the MVS router
RACROUTE macro invokes the MVS router

If an external security product is not available, you can use the MVS router exit as an installation-written security processing (or routing) routine. If an external security product is available, you can use the MVS router exit as a preprocessing exit routine for the security product. The MVS router exit routine is ICHRTX00.

After MVS system initialization is complete, ICHRTX00 receives control for all subsequent requests for the duration of the IPL. See Programming Considerations for information on coding ICHRTX00.

Installing the Exit Routine

To install ICHRTX00, name the exit ICHRTX00 and load it into the link pack area (LPA). For general instructions on installing an exit routine, see Link editing an Installation Exit Routine into a Library.

Exit Routine Environment

ICHRTX00 receives control in the following environment:
  • Is entered via a branch and link macro. Therefore, the exit routine runs in the same key and state as the issuer of the RACROUTE macro.
  • Enabled for interrupts.
  • Must be linkedited with AMODE(ANY) and RMODE(24).
  • Can be invoked with the local lock held.
  • Caller's address space.
  • Can be invoked in SRB mode. If the routine is invoked in SRB mode, the exit routine must follow SRB conventions.
  • Can be invoked in cross-memory mode. If the routine is invoked in cross-memory mode, system services that invoke SVC routines cannot be used.

Exit Recovery: An installation must provide its own recovery routine for ICHRTX00. If the exit routine terminates abnormally, the recovery routine will get control first.

Exit Routine Processing

Normally, a caller invokes the MVS router and passes it class, requestor, and subsystem parameters via the RACROUTE parameter list. Using those parameters, the MVS router invokes ICHRTX00. ICHRTX00 returns to the MVS router with a return code that indicates whether further security processing is to occur.

If the return code is 0, the MVS router invokes the external security product by calling its router, ICHRFR00. ICHRFR00 will then invoke the other external security product processing and will report the results of that invocation to the MVS router by placing a return code in register 15 and the detailed RACF-compatible return and reason codes in the first and second words (respectively) of the RACROUTE parameter list. For more information on the return codes the exit routine can set, see the description of registers at exit in Return Specifications.

Simulating a Call to RACF: Instead of invoking the external security product, your installation may choose to have ICHRTX00 respond to the caller's request. In that case, you must still provide the caller with the RACF-compatible return and reason codes that it expects to receive. To do so, set the exit routine return code so that the external security product is not invoked (as described in Return Specifications). However, you must simulate the results of an external security product invocation by coding ICHRTX00 so it places the RACF-compatible return and reason codes in the RACROUTE parameter list.

RACF return and reason codes are documented in z/OS Security Server RACROUTE Macro Reference.

Programming Considerations

ICHRTX00 must be reentrant.

In addition to the address of the RACROUTE parameter list, ICHRTX00 also receives the address of a 152-byte work area.

SAF performs functions other than being a router, such as creating security tokens for certain RACROUTE request types, propagating userids, and creating default control blocks (ACEEs) when an external security product is not available to the system. IBM® recommends that, in coding ICHRTX00, you do not bypass these SAF functions. SAF creates and returns control blocks (tokens or ACEEs) whenever the RACROUTE request types are issued:
  • REQUEST=VERIFYX
  • REQUEST=TOKENMAP
  • REQUEST=TOKENXTR
  • REQUEST=TOKENBLD

SAF also creates default ACEEs for REQUEST=VERIFY when an external security product is not available on the system. System code, such as JES, requires these control blocks. Therefore, if your ICHRTX00 exit routine bypasses SAF security functions, your installation must construct and return the control blocks that SAF would have created. If you do not provide the required control blocks, problems can result. The token fields are mapped by macro ICHRUTKN (data area RUTKN). For a mapping of the RUTKN data area, see z/OS MVS Data Areas in the z/OS Internet library.

Macro Instructions and Restrictions: Do not install an exit routine that issues the WAIT macro or calls a service that issues a WAIT, such as WTOR. WAITs and implied WAITs can cause the system console or JES to stop functioning.

Entry Specifications

The MVS router passes to the exit routine (in Register 1), the address of a doubleword area that contains the addresses of:
  • The RACROUTE parameter list and
  • A work area that the exit routine can use.

Registers at Entry: The contents of the registers on entry to the exit are as follows.

Register
Contents
0
Not applicable
1
Address of the following area:
Offset Length Description
0 4 Parameter list address: points to the RACROUTE parameter list
4 4 Work area address: points to a 152-byte work area that ICHRTX00 can use.
2-12
Not applicable
13
Register save area
14
Return address
15
Entry point address of the exit

Parameter Descriptions: The RACROUTE parameter list (SAFP) is mapped by macro ICHSAFP (data area SAFP). If an ICHRTX00 exit routine exists, the MVS router passes the SAFP to the exit. See z/OS MVS Data Areas in the z/OS Internet library for a mapping of the SAFP data area.

Return Specifications

A return code from the exit routine indicates whether the external security product is to be given control or further security processing is to be bypassed.

Registers at Exit: Upon return from the exit processing, the register contents must be as follows.

Register
Contents
0-14
Restored to contents at entry.
15
One of the following return codes:
Hex/Dec
Explanation
X'0' (0)
The exit has completed successfully. Control proceeds to the external security product router (ICHRFR00) for further security processing and an invocation of the external security product.
X'C8' (200)
The exit routine has completed successfully. The MVS router translates this return code to an MVS router return code of 0 and returns control to the issuer of the RACROUTE macro, bypassing further SAF and any external security product processing. (See note.)
X'CC' (204)
The exit routine has completed successfully. The MVS router translates this return code to an MVS router return code of 4 and returns control to the issuer of the RACROUTE macro, bypassing further SAF and any external security product processing. (See note.)
X'D0' (208)
The exit routine has completed processing. The MVS router translates this return code to an MVS router return code of 8 and returns control to the issuer of the RACROUTE macro, bypassing further SAF and any external security product processing. (See note.)
Other
If the exit routine sets any other return code, the MVS router returns control directly to the issuer of the RACROUTE macro and passes the untranslated code as the MVS router return code. Further SAF and any external security product processing is bypassed.
Note: The installation is responsible for putting RACF-compatible return and reason codes in the first 2 fullwords, respectively, of the RACROUTE parameter list (SAFP). If the exit routine does not issue a specific reason code, it should issue a zero reason code.

Coded Example of the Exit Routine

A copy of a sample ICHRTX00 exit routine is provided in SYS1.SAMPLIB (in member RACINSTL).