RACROUTE REQUEST=FASTAUTH (standard form)

The standard form of the RACROUTE REQUEST=FASTAUTH macro instruction is written as follows.

Note: For additional parameters that are required and additional keywords that you can code on the RACROUTE request, but that are not specific to this request type, see RACROUTE (standard form).

Note:

RACROUTE REQUEST=FASTAUTH requires an ACEE. For most applications, the system creates an ACEE to represent the active user. However, for special cases where no ACEE exists, the invoker must create one before invoking RACROUTE REQUEST=FASTAUTH.

The most common way to create an ACEE is to issue a RACROUTE REQUEST=VERIFY, specifying ENVIR=CREATE. After all RACROUTE invocations are complete, the invoker should issue RACROUTE REQUEST=VERIFY with ENVIR=DELETE specified to delete the ACEE previously created.

Macro parameter	Classification and notes

`name`	`name`: Symbol. Begin `name` in column 1.

␣	One or more blanks must precede RACROUTE.

RACROUTE

␣	One or more blanks must follow RACROUTE.


REQUEST=FASTAUTH

,CLASS=`‘class name’`	`class name`: 1–8 character class name
,CLASS=`class name addr`	`class name addr`: A-type address or register (2) – (12)

,ENTITY=`entity addr`	`entity addr`: A-type address or register (2) – (12)
,ENTITYX=`extended profile name addr`	`extended profile name addr`: A-type address or register (2) – (12)

,WKAREA=`area addr`	`area addr`: A-type address or register (2) – (12)

,ACEE=`acee addr`	`acee addr`: A-type address or register (2) – (12)

,ACEEALET=`alet addr`	`alet addr`: A-type address or register (2) – (12)

,APPL=`‘applname’`	`applname`: 1–8 character name
,APPL=`applname addr`	`applname addr`: A-type address or register (2) – (12)

,ATTR=READ	Default: ATTR=READ
,ATTR=UPDATE
,ATTR=CONTROL
,ATTR=ALTER
,ATTR=`reg`	`reg`: Registers (2) – (12)

,AUTHCHKS=ALL	Default: AUTHCHKS=ALL
,AUTHCHKS=CRITONLY

,CRITERIA=`criteria addr`	`criteria addr`: A-type address or register (2) – (12)

,ENVRIN=`envr data addr`	`envr data addr`: A-type address or register (2) – (12)

,INSTLN=`parm list addr`	`parm list addr`: A-type address or register (2) – (12)

,LOG=ASIS	Default: LOG=NONE
,LOG=NOFAIL
,LOG=NONE

,LOGSTR=`logstr addr`	`logstr addr`: A-type address or register (2) – (12)
,LOGSTRX=YES \| NO	Default: LOGSTRX=NO

,MF=S

The parameters are explained as follows:

,ACEE=acee addr

Specifies the address of the ACEE to be used to check authorization. If the caller is in cross-memory mode, the specified ACEE must reside in the HOME address space unless the ACEEALET= keyword specifies a different address space.

To use this keyword, the calling program must not specify the ENVRIN= keyword.

See RACROUTE REQUEST=FASTAUTH: Verify access to resources for more information about nested ACEEs.

This ACEE might also be used to locate the profile protecting the resource. The profiles that are brought into storage by RACROUTE REQUEST=LIST are anchored in an ACEE. The ACEE used to access the profile protecting the resource is determined as follows:

	Cross-memory request		Non-cross-memory request
	GLOBAL=NO	GLOBAL=YES	GLOBAL=NO	GLOBAL=YES
ACEEALET, ENVRIN, or CRITERIA is specified.	Main ACEE in primary address space		Main ACEE in primary address space
Neither ACEEALET, ENVRIN, or CRITERIA is specified.	Main ACEE in primary address space		1) Input ACEE 2) Task ACEE 3) Main ACEE¹	1) Input ACEE if system key or supervisor state 2) Task ACEE 3) Main ACEE²

¹: If the input ACEE is not specified, then RACF® uses the TASK ACEE (TCBSENV) pointer in the TCB. If there is no TCB (which is the case in SRB mode), or if the TASK ACEE pointer is zero, then RACF uses the main ACEE for the address space.
²: If the FASTAUTH caller is in system key or supervisor state, RACF uses the input ACEE if specified. If not, RACF uses the TASK ACEE. If there is no TCB (which is the case in SRB mode), or if the TASK ACEE pointer is zero, RACF uses the main ACEE for the address space.

Note: If the search of the ACEE(s) determines that the class is not RACLISTed by RACROUTE REQUEST=LIST, and the caller is in supervisor state or system key (0–7), FASTAUTH uses profiles that are brought into storage by the SETROPTS RACLIST command.

,ACEEALET=alet addr

Specifies the address of the 4-byte ALET to be used to access the ACEE specified on the ACEE= keyword. When you use A-type or RX-type notation, alet addr specifies the name of a 4-byte field that contains the ALET. When you use register notation, alet addr specifies a register that contains the address of a 4-byte field that contains the ALET. If this keyword is not specified, the ACEE is located as defined in the ACEE= keyword description.

Keyword requirements:

Run in supervisor state or system key (0–7).
Ensure that the address space identified by ACEEALET= is marked non-swappable.
Ensure that the specified ALET represents a valid entry in the DU-AL of the work unit or the PASN-AL of the current primary address space.
Specify the ACEE= keyword.
Specify RELEASE=2.4 or later.

,APPL=‘applname’

,APPL=applname addr

Specifies the name of the application that is requesting the authorization checking. This information is not used for the authorization-checking process but is made available to the installation exit or exits. If an address is specified, it should point to an 8-byte area containing the application name, left-justified, and padded with blanks if necessary.

,ATTR=READ

,ATTR=UPDATE

,ATTR=CONTROL

,ATTR=ALTER

,ATTR=reg

Specifies the access authority that the user must obtain for the resource profile. The following definitions apply:

READ: RACF user or group can open the resource only to read.
UPDATE: RACF user or group can open the resource to read or write.
CONTROL: For VSAM data sets, RACF user or group has authority equivalent to the VSAM control password.
For non-VSAM data sets and other resources, RACF user or group has UPDATE authority.
ALTER: RACF user or group has total control over the resource.

For multilevel- secure environments:

When ATTR=READ, it is treated as a read-only request for purposes of mandatory access control (MAC) checking.
When ATTR=UPDATE, CONTROL, or ALTER, it is treated as a read/write request for purposes of mandatory access control (MAC) checking.
Note that for REQUEST=AUTH, ATTR=ALTER is treated as a read-only request for purposes of mandatory access control (MAC) checking.

If a register is specified, the register must contain one of the following codes in the low-order byte of the register:

X'02': READ
X'04': UPDATE
X'08': CONTROL
X'80': ALTER

The default is READ.

,AUTHCHKS=ALL

,AUTHCHKS=CRITONLY

Specifies the access checks that RACROUTE REQUEST = FASTAUTH performs. The following definitions apply:

ALL

All RACROUTE REQUEST=FASTAUTH access checks are performed. This value is the default.

CRITONLY

The following subset of RACROUTE REQUEST=FASTAUTH checks are performed:

Enforcement of the rules for SETROPTS MLQUIET, when SETROPTS MLQUIET is in effect
Security label authorization checks, when the SECLABEL class is active.
Security level and security category authorization checks, when the SECLABEL class is not active and the SECDATA class is active.
Search of the conditional access list for a matching criteria as specified by the CRITERIA keyword

For more information about the authorization checking performed by RACROUTE REQUEST=FASTAUTH requests, see the topic in z/OS Security Server RACF Security Administrator's Guide on debugging problems in the RACF database.

Note: AUTHCHKS has meaning only when the CRITERIA keyword is specified. When the AUTHCKS=CRITONLY keyword is used without assigning a value for the CRITERIA keyword, AUTHCHKS=CRITONLY is ignored.

Keyword requirements: Specify RELEASE=7730 or later.

,CLASS=‘class name’

,CLASS=class name addr

Specifies that RACF authorization checking is to be performed for a resource of the specified class. If an address is specified, the address must point to an 8-byte field containing the class name, left-justified, and lastly padded with blanks.

,CRITERIA=criteria-area addr

Specifies the address of a data structure containing the additional criteria that are used to determine whether the user has access to the resource. The criteria-area data structure is a 4-byte number of criteria entries, followed by that number of entries. The number of criteria entries must be 1. Each criteria entry consists of an 8-byte criteria-name, assumed to be in uppercase, a 4-byte value length, and the criteria-value. The criteria-name, padded at the end with blanks if it is less than 8-bytes, should be made up of alphabetic, numeric, and # (X'7B'), $ (X'5B'), or @ (X'7C') characters and does not contain blanks (X'40'). The criteria-value, whose length must be in the range of 1 to 235, can contain any character but should not end with trailing blanks. The case of the characters is important. They must match what the security administrator enters on the PERMIT command.

One criteria must be specified. The PERMIT command with the WHEN(CRITERIA(…)) is used to add criteria-expressions to the conditional access list of a general resource profile. A complete list of supported criteria-names can be found in z/OS Security Server RACF Command Language Reference with the description of the PERMIT command. Access to a resource can be granted when a criteria expression on the conditional access list of a covering profile matches the expression on the call to FASTAUTH.

This processing applies only to general resource classes.

Keyword requirements:

Run in supervisor state or system key (0-7).
Specify RELEASE=7730 or later.
The criteria area must be in the primary address space.

,ENTITY=entity addr

Specifies that RACF authorization checking is to be performed for the resource whose name is pointed to by the specified address. The resource name is a 6-byte volume serial number for CLASS=DASDVOL or CLASS=TAPEVOL. The name must be left-justified and padded with blanks. The length of all other resource names is determined from the class descriptor table. See RACROUTE REQUEST=FASTAUTH: Verify access to resources for more information about nested ACEEs.

,ENTITYX=extended profile name addr

Specifies the address of a structure that consists of two 2-byte length fields, followed by the entity name. The first 2-byte field specifies a buffer length that can be from 0 to 255 bytes. This length field refers to the length of the buffer that contains the entity name; it does not include the length of either length field. The second 2-byte field specifies the actual length of the entity name. This length field includes the length of the actual name without any trailing blanks; it does not include the length of either length field.

These two length fields can be used in several different ways. If you know the length of the entity name, you can specify 0 in the first field and the length of the entity name in the second field. Note that each byte counts when you specify the second field. The entity name that you specify must match the entity name on the RACF database. If you choose to place the entity name in a buffer area, specify the length of the buffer in the first field. For the second field, do one of the following:

If you know the length of the entity name, specify the length in the second field. The length of the first field can be from 0 to 255, but must be equal to or greater than the length of the second field.
If you do not know the length of the entity name, specify 0 in the second field, and have RACF determine the number of characters in the entity name. In this case, the entity name must be bounded at the end by a blank, unless its length is the length of the buffer itself.
Use of ENTITYX requires RELEASE=2.6 or later.

See RACROUTE REQUEST=FASTAUTH: Verify access to resources for more information about nested ACEEs.

,ENVRIN=envr data addr

Specifies the data structure that contains the information necessary to re-create the security environment to be used for authorization checking.

The data structure describes the storage location for the ENVR object. While the format of the data structure pointed to by the ENVRIN keyword is known to the RACROUTE invokers, the content of the ENVR object is determined by the external security product. Both the data structure, and the storage location for the ENVR object are expected to be in the PRIMARY address space.

When the ENVRIN keyword is used, in-storage profiles RACLISTed by RACROUTE REQUEST=LIST are located using the ACEE of the address space in the primary address space. If no RACROUTE REQUEST=LIST was done for the requested class, but the class was processed using SETROPTS RACLIST, then those profiles are used.

To use this keyword the calling program must:

Run in supervisor state or system key (0–7)
Not specify the ACEE= keyword
Specify RELEASE=2.6 or later.

The data structure that the ENVRIN keyword points to is defined in the keyword description for ENVROUT on the RACROUTE REQUEST=VERIFY macro.

For more information about nested ACEES, see RACROUTE REQUEST=FASTAUTH: Verify access to resources.

,INSTLN=parm list addr

Specifies the address of an area that contains information for the RACROUTE REQUEST=FASTAUTH installation exit. This address is passed to the exit routine when the exit is given control. The INSTLN parameter is used by application or installation programs to pass information to the RACROUTE REQUEST=FASTAUTH installation exit.

,LOG=ASIS

,LOG=NOFAIL

,LOG=NONE

Specifies the types of access attempts to be audited. To use this keyword, you must also specify RELEASE=2.1 or later.

ASIS

RACF performs auditing if its authorization check results in success (RC=0) or failure (RC=8), and determines whether auditing is necessary based on the following conditions:

The user's UAUDIT setting
The AUDIT, GLOBALAUDIT, and WARNING options in effect for the resource
If SETR SECLABELAUDIT is in effect, then the AUDIT options in the resource SECLABEL profile.
The pre- or postprocessing installation exit's indication of whether to do auditing.

NOFAIL

If the authorization check fails, the attempt is not recorded. If the authorization check succeeds, the attempt is recorded as in ASIS.

NONE

The attempt is not recorded.

LOG=NONE suppresses both messages and SMF records regardless of MSGSUPP=NO.

Note: For LOG=NOFAIL and LOG=NONE, the caller should examine the reason code that is returned in SAFPRREA to determine whether auditing is required. If so, it is the caller's responsibility to ensure that auditing occurs, either by issuing RACROUTE REQUEST=AUTH with LOG=ASIS or RACROUTE REQUEST=FASTAUTH with LOG=ASIS.

,LOGSTR=logstr addr

Specifies information to be written in the system-management-facilities (SMF) data set. The format of this data is determined by the LOGSTRX keyword. For more information, see the following description of LOGSTRX.

,LOGSTRX=NO

,LOGSTRX=YES

Determines the format of the LOGSTR data.

NO

The LOGSTR area is a 1-byte length followed by the specified number of bytes of data. This data is treated as EBCDIC data by RACF SMF unload.

LOGSTRX=NO is the default.

YES

The LOGSTR area is a structure that consists of the following:

A 2-byte length field, which describes the size of the entire LOGSTR area, including the size of the length and identifier fields. The maximum length is 1100 bytes.
A 2-byte identifier, which describes the format of the log string.

x'0001

The log string is in CICS® client identity format. Following this 2-byte ID, the data is in type/length/data format where the type and the length fields are each 2 bytes. The following types are defined:

Table 1. CICS client identity format types
Type	Description	Format of the Data
x'0001	User ID of CICS Client	EBCDIC Data
x'0002	X500_IDN	EBCDIC Data
x'0003	X500_SDN	EBCDIC Data
x'0004	IDID User Identity	UTF8 Data
x'0005	IDID User Identity Format	Binary Data
x'0006	IDID Registry Identity	UTF8 Data
x'0007	APPLID (CICS Application ID)	EBCDIC Data
x'0008	TRANID (CICS Transaction ID)	EBCDIC Data

The log string can contain multiple type/length/data triplets, but there should not be more than one occurrence of any single type.

x'nnnn'

Any other 2-byte identifier is not supported for RACF SMF unload.

ID values x'0000' to x'0FFF' are reserved for IBM® use. An undefined 1-byte identifier value in the range that is reserved for IBM results in the RACROUTE REQUEST=FASTAUTH failing.
ID values x'1000' to x'1FFF' are reserved for vendors.Vendors should select a value of x’1000’+ nnn, where nnn is the vendor slot number that is assigned by IBM. Vendors who require a slot number can contact IBM Support to have one assigned.
ID values x'2000' to x'FFFF' are available for customer use.
LOGSTR data in the ID ranges reserved for vendors and customers is not unloaded by the RACF SMF unload utility.

Specifying LOGSTRX without LOGSTR results in the macro failing to assemble.

MF=S

Specifies the standard form of the RACROUTE REQUEST=FASTAUTH macro instruction.

,WKAREA=area addr

Specifies the address of a 16-word work area to be used by RACROUTE REQUEST=FASTAUTH. On return from RACROUTE REQUEST=FASTAUTH, the following fields contain:

Word 11: The high-order bit (bit 0) indicates whether a nested ACEE was used in the access decision.
Word 12: The RACF reason code.
Word 13: The RACF return code.
Word 14: The address of the in-storage profile used to determine authorization; if no profile was found or the profiles were RACLISTed using RACROUTE REQUEST=LIST, GLOBAL=YES, or SETROPTS RACLIST, word 14 contains zero. If a profile was found and not RACLISTed using RACROUTE REQUEST=LIST, GLOBAL=YES, or SETROPTS RACLIST, the profile address is passed to the caller in register 1.
Note that the profile can be mapped using the RACRPE structure found in the ICHPISP macro.
Word 15: A value that is provided by a pre- or postprocessing installation exit, or zero.

Return codes and reason codes

When you execute the macro, space for the RACF return code and reason code is reserved in the first two words of the RACROUTE parameter list. You can access them using the ICHSAFP mapping macro, by loading the ICHSAFP pointer with the label that you specified on the list form of the macro. When control is returned, register 15 contains the SAF return code and register 1 might contain the address of the profile protecting the resource.

Note: All return and reason codes are shown in hexadecimal. Also, note that SAF return code is presented as SAF RC and RACF return code is presented as RACF RC in the following topic.

SAF RC

Meaning

00

RACROUTE REQUEST=FASTAUTH has completed successfully.

RACF RC

Meaning

00

The user or group is authorized to use the resource.

Reason Code: Meaning
00: The invoker does not need to log the attempt.
04: The invoker should log the attempt.
The RACROUTE REQUEST=FASTAUTH caller should log the attempt using RACROUTE REQUEST=AUTH or RACROUTE REQUEST=FASTAUTH with LOG=ASIS.

04

The requested function could not be performed.

RACF RC

Meaning

00

No security decision could be made.

Reason Code

Meaning

00

RACF was not called to process the request because one of the following occurred:

RACF is not installed.
The combination of class, REQSTOR, and SUBSYS was found in the RACF router table, and ACTION=NONE was specified.
The RACROUTE issuer specified DECOUPL=YES and a RELEASE= keyword with a higher release than is supported by this level of z/OS®.

04

The resource or class name is not defined to RACF or the class has not been RACLISTed.

20

The class was RACLISTed by RACROUTE REQUEST=LIST, GLOBAL=YES, or SETROPTS RACLIST, but the data space cannot be accessed due to an ALESERV failure.

0C

RACF is not active.

1C

The class was RACLISTed by RACROUTE REQUEST=LIST, GLOBAL=YES, or SETROPTS RACLIST, but the data space has been deleted.

08

The requested function failed.

RACF RC

Meaning

08

The user or group is not authorized to use the resource.

Reason Code: Meaning
00: The invoker does not need to log the request.
04: The invoker should log the attempt.
The RACROUTE REQUEST=FASTAUTH caller should log the attempt using RACROUTE REQUEST=AUTH or RACROUTE REQUEST=FASTAUTH with LOG=ASIS.

10

A RACROUTE REQUEST=FASTAUTH installation exit error occurred.

18

Indicates the profile has a conditional access list, the port-of-entry field in the security token is blank-filled, and the port-of-entry class is active.

24

Parameter list error.

Reason Code: Meaning
8: The ACEEALET= keyword was specified, but the calling program is not running in supervisor state or system key.
0C: The ACEEALET= keyword was specified, but the ACEE= keyword was not specified.
10: The ENVRIN keyword was specified, but the calling program is not running in supervisor state or system key.
14: ENVRIN and ACEE were both specified (they are mutually exclusive keywords).
18: The CRITERIA keyword was specified, but the caller was not in supervisor state or system key (0-7).
1C: The LOGSTRX keyword has an incorrect length.
20: The LOGSTRX keyword has a type set that is not supported.
24: The LOGSTRX keyword has an unsupported tag in the triplet data.
28: The LOGSTRX keyword is not in the correct format.
2C: The LOGSTRX keyword contains duplicate tags in the triplet data.

64

Indicates that the CHECK subparameter of the RELEASE keyword was specified on the execute form of the RACROUTE REQUEST=FASTAUTH macro, however, the list form of the macro does not have the same RELEASE parameter. Macro processing terminates.

Class descriptor table (CDT) default return codes and reason codes

Normally, if a resource profile is not found, the function returns a return code of 4. However, if a resource profile is not found but a default return-code keyword is specified in the class descriptor table for the class specified on the RACROUTE REQUEST=FASTAUTH, the function returns that specified return code.