Previous topic |
Next topic |
Contents |
Contact z/OS |
Library |
PDF
ICHRTX00 — MVS Router Exit z/OS MVS Installation Exits SA23-1381-00 |
||||||||||
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
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 RoutineTo 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 EnvironmentICHRTX00
receives control in the following environment:
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 ProcessingNormally, 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 ConsiderationsICHRTX00 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:
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 z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/. 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 SpecificationsThe MVS router
passes to the exit routine (in Register 1), the address of a doubleword
area that contains the addresses of:
Registers at Entry: The contents of the registers on entry to the exit are as follows.
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 z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for a mapping of the SAFP data area. Return SpecificationsA 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.
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 RoutineA copy of a sample ICHRTX00 exit routine is provided in SYS1.SAMPLIB (in member RACINSTL). |
Copyright IBM Corporation 1990, 2014
|