Security product router

The following is guidance information for programmers implementing a non-RACF external security-manager product.

If RACF® is not present in the system, an installation can use an external (non-RACF) security product to provide system-security functions. An external security product supplies a security-product router module to handle security requests from SAF.

When a control point issues the RACROUTE macro to request a security function that is not completely processed by SAF, the SAF router passes control to the security-product router.

SAF completely processes the following:

REQUEST=TOKENMAP, REQUEST=TOKENBLD, and REQUEST=TOKENXTR.
REQUEST=VERIFY when building or deleting ACEEs for trusted-system address spaces.
REQUEST=VERIFYX for trusted-system address spaces.
REQUEST=VERIFYX and REQUEST=VERIFY when the security product is not installed, or is not active. (In this case, a default UTOKEN is created and the ACEERACF bit is off.)

SAF also partially processes REQUEST=VERIFYX.

For example, SAF:

Performs user ID propagation for batch jobs to be executed on the local node.
Performs user ID propagation during spool-reload functions of JES when the security product does not support the RACF 1.9 work-unit identity functions (that is, when RCVTWUID is off).
Turns a VERIFYX into a VERIFY with ENVIR=CREATE, which it then calls the security-product router module to perform. SAF extracts the UTOKEN from the ACEE and calls the security-product router module to do a VERIFY with ENVIR=DELETE.

In general, SAF processing or partial processing of requests should be transparent to the security product. When SAF completely processes the request, the security product is not called. When SAF does not do any processing for the request, it calls the security-product router to do the processing required for that request type and those parameters. When SAF partially processes the request, it modifies the request type and the parameters when necessary, and calls the security-product router to do the appropriate processing as needed for the resulting request type and parameters.

The external security product must place the address of the security-product router module (which must be in common storage) into field SAFVRACR in the router vector table (mapped by ICHSAFV). The router vector table is built during SAF initialization, but the field SAFVRACR should be filled during the initialization of the external product. The following illustrates the location of field SAFVRACR.

Requirements for the security product router

The following general requirements apply for the security-product router module.

Authorization:

Supervisor state or problem state, in any PSW key. Generally, this is the state and key of the RACROUTE issuer. However, if SAF is partially processing the request (as explained above), SAF might have switched to supervisor state and key 0 before calling the security-product router.

Dispatchable unit mode:

Task mode or SRB mode, as determined by the issuer of RACROUTE.

Cross-memory mode:

PASN = HASN = SASN except for:

RACROUTE REQUEST=TOKENMAP with XMREQ=YES
RACROUTE REQUEST=TOKENXTR with XMREQ=YES
RACROUTE REQUEST=FASTAUTH

Amode:

24-bit or 31-bit, as determined by the issuer of RACROUTE

ASC mode:

Primary

Locks:

No locks held, except the LOCAL lock can be held when REQUEST=FASTAUTH, and CLASS=PROGRAM, REQSTOR=PADSCHK and SUBSYS=CONTENTS are specified. When called with the LOCAL lock held, the security product must not release the lock.

Linkage conventions:

Standard

Input parameters to the security product router

On entry to the security-product router module, register 1 contains the address of the following areas:

Offset	Length	Description
0	4	Parameter-list address points to the RACROUTE parameter list (mapped by macro ICHSAFP). See data area SAFP in "SAFP: SAF Router Parameter List" in z/OS Security Server RACF Data Areas.
4	4	Work-area address points to the RACROUTE parameter list (mapped by macro ICHSAFP). See data area SAFP in "SAFP: SAF Router Parameter List" in z/OS Security Server RACF Data Areas.

The field SAFPRACP in the RACROUTE parameter list contains the offset from the base address of ICHSAFP to the request-specific portion of the parameter list. The format of the request-specific portions varies, depending on the REQUEST= parameter coded on the RACROUTE invocation. The following table shows which request-specific parameter list is assigned to each REQUEST= keyword:

Table 1. RACROUTE macro keywords and their request-specific parameter lists
RACROUTE REQUEST type	Request-specific parameter list
REQUEST=AUDIT	AUL
REQUEST=AUTH	ACHKL
REQUEST=DEFINE	RDDFL
REQUEST=DIRAUTH	DAUT
REQUEST=EXTRACT	RXTL
REQUEST=FASTAUTH	FAST
REQUEST=LIST	RLST
REQUEST=SIGNON	SGNPL
REQUEST=STAT	STAT
REQUEST=TOKENBLD	RIPL
REQUEST=TOKENMAP	TSRV
REQUEST=TOKENXTR	TSRV
REQUEST=VERIFY	RIPL
REQUEST=VERIFYX	RIPL

The parameter lists exhibited in the previous tables are illustrated in z/OS Security Server RACF Data Areas.See this text for details on the format of these parameter lists.

Exit conditions from the security product router

On exit from the security-product router module and return to the SAF router:

Register 15 contains one of the following return codes:
Hex (Decimal)

Meaning

0   (0)

The requested function completed successfully.

4   (4)

The requested function was not processed.

8   (8)

The requested function was processed, and failed.
The RACROUTE parameter list (SAFP) contains the function return code in field SAFPRRET and the function reason code in field SAFPRREA for the requested function.
Register 1 can contain the address of a data area returned by the RACROUTE invocation. See each specific RACROUTE request type for details.

Programming considerations

When an external security product processes a RACROUTE REQUEST=VERIFY,ENVIR=CREATE request, SAF expects the product to build data area ACEE, which is mapped by macro IHAACEE. The ACEE address should be returned as follows:

If the RACROUTE REQUEST=VERIFY specified the ACEE= keyword, the address of the ACEE should be returned in the word specified by the ACEE= keyword;
Otherwise, the address should be returned in the TCB field TCBSENV. If the ASXB field ASXBSENV is 0, the address should be returned in ASXBSENV, too. Note that ACEEs whose addresses are in TCBSENV or ASXBSENV must be created in storage located below 16MB.

For token processing, SAF uses field ACEETOKP to reference the token. Token processing is not required but, to be fully compatible with MVS™, the security product should create a version 2 ACEE when invoked for RACROUTE REQUEST=VERIFY,ENVIR=CREATE, and should create a token and place its address in ACEETOKP. A security product that is prepared to do this should also set RCVTWUID on to indicate to SAF that it understands token processing and can handle all the token-related fields on a REQUEST=VERIFY call to the security-product router.

In order to be compatible with SAF and various IBM® program products, the security product should fill in any field in the ACEE that is listed as a General-Use Programming Interface, with the exception of ACEEFCGP.

In order to be compatible with SAF and various IBM program products, the security product should also process any of the RACROUTE requests and keywords that are listed as General-Use Programming Interfaces, and should provide the same return codes and reason codes as RACF would. If the security product cannot process a specific function, it should return a 4 in register 15, and should set the SAFPRRET and SAFPRREA fields to 0. However, the issuer of the RACROUTE macro is free to interpret return code 4 as desired, and can decide either to accept or to fail the processing that caused the RACROUTE to be issued.

A product can issue some RACROUTE requests in a non-authorized state. The security product must be sensitive to such calls and only invoke services that are allowed in the issuer's current state. In addition, some RACROUTE requests might be in a performance-sensitive path. If the security product causes a suspension of the caller (for example, a WAIT) then the performance of the caller might suffer. An example of this is CICS®, which issues a RACROUTE REQUEST=VERIFY,ENVIR=VERIFY in a non-authorized state and in a performance-sensitive path.

In general, a product that issues RACROUTE should document the minimum level of RACF that is required for the product to work correctly, and any other security product that a customer wishes to use must supply at a minimum the functions that level of RACF would supply. Also, where data is being returned, the data should be in the same format as RACF would return it. The exceptions to this are:

For RACROUTE REQUEST=EXTRACT,TYPE=EXTRACT or TYPE=REPLACE, the RELEASE=1.8 capabilities of FIELDS= do not have to be supported when the segment name specified or implied is BASE. Other segment names (such as DFP and TSO) should be supported, however, for compatibility with the RACF releases that support those segments.

In order to be further compatible with SAF and various IBM program products, the security product should fill in any field in the RCVT, which is listed as a General-Use Programming Interface. This includes the fields RCVTREXP and RCVTFRCP, which are used by the RACSTAT and FRACHECK macros. The security product should also assume that references to RACF in the general-use fields apply to other security products as well. For example, RCVTRNA, which is described as "RACF not active", should be interpreted as "Security product not active".

Also, although the preferred interface for security services is through RACROUTE, the security product should support the SVC-entered functions RACHECK, RACDEF, RACINIT, RACLIST, and RACXTRT. It should also support the branch-entered functions FRACHECK and RACSTAT. It is not necessary to support the ICHEINTY service, which is described in z/OS Security Server RACF Macros and Interfaces.