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 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.
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).
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 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.
Your exit routine must return a return code in register 15. The hexadecimal values of the return code are shown in Table 43.
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. |
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.