RACROUTE REQUEST=FASTAUTH: Verify access to resources

NOT programming interface information

Use of CLASS='PROGRAM' with RACROUTE REQUEST=FASTAUTH is not part of the intended programming interface. It is intended for use only by z/OS® itself, and follows different rules and has different restrictions than uses of RACROUTE REQUEST=FASTAUTH with other class names. For more information, including effects on SAF exits, see System authorization facility (SAF) and SAF exits and SAF interface to an external security product.

End of NOT programming interface information

The RACROUTE REQUEST=FASTAUTH macro is used to check a user's authorization for access to a resource. RACROUTE REQUEST=FASTAUTH verifies access to those resources whose RACF® profiles have been brought into main storage by the RACROUTE REQUEST=LIST service or by SETROPTS RACLIST. If the profiles were not RACLISTed by RACROUTE REQUEST=LIST but were processed using SETROPTS RACLIST, and the caller is in supervisor state or system key (0–7), FASTAUTH uses the SETROPTS profiles RACLISTed for the authorization check. Using SETROPTS RACLIST instead of RACROUTE REQUEST=LIST to bring profiles into storage can simplify application design. However, to get optimum performance from calls to RACROUTE REQUEST=FASTAUTH, the class should be RACLISTed using RACROUTE REQUEST=LIST.

RACROUTE REQUEST=FASTAUTH does limited parameter validation, and does not gather statistics or issue SVCs. Therefore, use of RACROUTE REQUEST=FASTAUTH is recommended only for applications that have stringent performance requirements.

The RACROUTE REQUEST=FASTAUTH caller must be authorized (supervisor state or system key 0–7) for certain keywords. See the keyword descriptions for authorization requirements.

Note: The caller must not hold any locks when issuing RACROUTE REQUEST=FASTAUTH. Programs that issue RACROUTE REQUEST=FASTAUTH while holding a lock might experience unpredictable results.

When a nested ACEE (or ENVR object for an ACEE created with the NESTED option of RACROUTE REQUEST=VERIFY) is passed to RACROUTE REQUEST=FASTAUTH by a supervisor-state or system-key caller and the access request is for a delegated resource (a resource defined with the RACF-DELEGATED string in the APPLDATA field), FASTAUTH processing retries the access request using the nested identity (usually, a daemon) when the primary identity has insufficient access authority.

You can use the installation exits associated with RACROUTE REQUEST=FASTAUTH to make additional security checks or to instruct RACROUTE REQUEST=FASTAUTH to either accept or fail the request. You can write an application that uses RACROUTE REQUEST=LIST and RACROUTE REQUEST=FASTAUTH for authorization checking on a resource class and associated resource group that your installation defines.

RACROUTE REQUEST=FASTAUTH is SRB-compatible. When issuing RACROUTE REQUEST=FASTAUTH in SRB mode for RACLISTed classes, you must ensure that the jobstep task pointed to by the ASCBXTCB field in the target address space is active when you schedule the SRB, and remains active until the SRB completes.

Rule: In order to ensure that the SRB does not run after the ASCBXTCB task completes, it is necessary to enable purgeDQ to deal with that SRB. In particular:

If using SCHEDULE, SRBPASID must be set to the ASID, and SRBPTCB must be set to the contents of ASCBXTCB.
If using IEAMSCHD, PURGESTOKEN must be specified with the STOKEN of the space, and PTCBADDR must be specified with the contents of ASCBXTCB.

When the task terminates, the purgeDQ issued causes the SRB's resource manager termination routine (RMTR) to be driven if the SRB has not begun to run, or waits for the SRB to complete if the SRB has begun to run.

RACROUTE REQUEST=FASTAUTH can also be invoked from a cross memory environment, when in task or SRB mode. The ACEE used for authority checking must reside in the HOME address space (unless ACEEALET specifies a different address space), but that ACEE is not used to locate the profiles RACLISTed. The main ACEE in the PRIMARY address space is used to locate the profiles.

Restriction: When RACROUTE REQUEST=FASTAUTH is invoked in SRB mode, WHEN (PROGRAM) conditional access checking for profiles in the SERVAUTH class is bypassed.

RACROUTE REQUEST=FASTAUTH provides support for auditing. FASTAUTH determines that auditing is necessary if at least one of the following conditions is met:

The user represented by the ACEE or ENVR object is being audited (UAUDIT option),
The profile protecting the resource indicates that auditing is to be done (AUDIT, GLOBALAUDIT, and WARNING options),
The pre- or post-installation exits indicate that auditing is to be done, or
SETROPTS SECLABELAUDIT is in effect.

The type of auditing support provided is based on the value of the LOG keyword. Either a reason code indicating whether or not logging needs to be done can be returned to the caller or RACROUTE REQUEST=FASTAUTH can perform the auditing itself. Applications can determine whether the cross-memory support and the support enabling RACROUTE REQUEST=FASTAUTH to perform the auditing itself is available by examining the flag bit RCVTXMFR in the RCVT data area.

Restrictions:

Callers in cross-memory mode must be in primary ASC mode when they issue the RACROUTE request.
The RACROUTE REQUEST=FASTAUTH macro executes in the addressing mode of the caller. Therefore, to access profiles that reside above 16MB, the program that issues RACROUTE REQUEST=FASTAUTH must be running in 31-bit addressing mode when it issues RACROUTE REQUEST=FASTAUTH.