The RACROUTE REQUEST=FASTAUTH Call

Extending Security Through the z/OS Security Interface › The RACROUTE REQUEST=FASTAUTH Call

The RACROUTE REQUEST=FASTAUTH Call

The RACROUTE REQUEST=FASTAUTH call:

Can validate access to resources, user resources, fields, and LCF commands
Is a fast path mechanism used by online facilities to minimize performance impact
Provides an interface to log violations and activity to SMF or the Audit/Tracking File through indirect CSA buffering with the CA Top Secret address space

Important! If the FRACHECK macro is used instead of RACROUTE REQUEST=FASTAUTH, the contents of general purpose registers 0 through 5, 14 and 15 are destroyed and not restored by FRACHECK.

Class Name Format

CA Top Secret accepts the class name for a RACROUTE REQUEST=FASTAUTH:

As a character string—eight characters with blank padding. For example ABSTRACT, PROGRAM, and TERMINAL
As a hexadecimal value string that ends with a question mark (?). When specified in this format, the fifth byte must contain the hexadecimal resource code for the desired class as defined in the RDT. For example ABS‑UUU?, PGM‑PPP?, and TER‑TTT?

Code the class name in either format. The format used also effects how the access level and privilege program (PRIVPGM) information is specified.

Character String Class Name

When the class name is specified as a character string, access level information is passed to RACROUTE REQUEST=FASTAUTH through the ATTR= keyword. The RACROUTE macro supports the following values for ATTR=:

ALTER: Requests full (ALL) access
CONTROL: Requests control level access
UPDATE: Requests update level access
READ: Requests read level access, and is the default when no value has been specified

If these values are passed by a register, the value in the register must match the ATTR= values in the table below. In processing the ATTR= values, the value coded is translated to the following CA Top Secret internal access level value.

When you define your own resource classes ensure that the access levels defined match the following values for ATTR=.

ATTR= Keyword	ATTR= Hex value	Access Level Hex Value	Access Level Bit Value
ALTER	X'00000080'	X'FFFF'	B'11111111,11111111'
CONTROL	X'00000008'	X'0400'	B'00000100,00000000'
UPDATE	X'00000004'	X'8000'	B'10000000,00000000'
READ	X'00000002'	X'4000'	B'01000000,00000000'

The following table lists valid Class Names, their functions, and the required data. Class Names of general owned resources are identified by a ? in position 8 (offset +7).

Class Name	Function	Entity
ABSTRACT	Validate access to ABSTRACT user resources	8 character abstract resource name
XLCFCMD XLCFXCTN LCF	Determine if the command, transaction, monitor, or panel is owned as an OTRAN. If it is, perform an OTRAN check; if it is not, access to the resource as an LCF is checked.	8 character resource name
ABS‑UUU?	Validate access to an ABSTRACT resource *	+0(8) resource name +8(1) access mask +9(8) privileged program name
APL‑AAA?	Validate access to an IMS application	Same as above
AREAbbb?	Validate access to a CA‑IDMS database area	Same as above
CP‑888?	Validate access to VM CP commands	Same as above
DBD‑ddd?	Validate access to IMS DBD	Same as above
DCT‑EEE?	Validate CICS destination table	Same as above
DIAG999?	Validate VM diagnose codes	Same as above
FCT‑FFF?	Validate CICS FCT	Same as above
FLD‑RRR?	Validate database field level	Same as above
GUR‑MMM?	General use; UR1	Same as above
GUR‑NNN?	General use; UR2	Same as above
JCT‑JJJ?	Validate journal control table	Same as above
LCF	Check for OTRAN ownership of the command, transaction, monitor, or panel. If owned, perform an OTRAN resource check to determine if the user has access to the OTRAN resource. If unowned, perform an LCF resource check to determine if the user has access to the LCF resource.	8 character resource name
LCFONLY	Determine if the user has access to the command, transaction, monitor, or panel as an LCF resource. An OTRAN resource check is not performed here.	Same as above
OTRAN	Check for OTRAN ownership of the command, transaction, monitor, or panel. If owned, perform an OTRAN resource check to determine if the user has access to the OTRAN resource.	Same as above
NET‑000?	Validate VM RSCS nodename	Same as above
PGM‑PPP?	Validate O/S programs	Same as above
PPT‑QQQ?	Validate CICS transactions	Same as above
PSB‑SSS?	Validate DL/1 PSG	Same as above
SUB‑aaa?	Validate CA‑IDMS subschema	Same as above
TRM‑TTT?	Validate network terminal ID	Same as above
TST‑ZZZ?	Validate CICS temporary storage table	Same as above
USERxx	Validate unowned user resource	+0(8) resource name

For information about the ABSTRACT resource access mask see TSS.OPTIONAL.MATERIAL(TSSINST1) on the distribution tape.

This table lists the required data for user‑defined resources. The resources are created by adding them to the Resource Descriptor Table (RDT), and specifying the particular resource class name.

RACROUTE REQUEST=FASTAUTH For User‑Defined Class Names Table

Class Name

Entity

User‑Defined Resource in the RDT Record

+0(8) or +0(44) resource name

+8(1) or +44(1) access mask

+9(8) or +45(8) privileged program name

To support 44 character lengths, attach the LONG attribute.

This example creates a resource class name called @RESOURZ 44 characters in length:

TSS ADDTO(RDT) RESCLASS(@RESOURZ)
               RESCODE(hex code)
               ATTR(LONG)

Performance Shortcuts

CA Top Secret determines if a resource is protected by checking for ownership. If the resource is not owned, RACROUTE REQUEST=FASTAUTH returns Return Code 04 (accessible but not protected).

To increase system performance. CA Top Secret assumes that a resource is owned, if a ? is placed in position 5 (offset +4) of the Class Name.

For example:

If GUR‑NNN? is specified as the Class Name, CA Top Secret checks for ownership of the resource.
If GUR‑?NN? is specified as the Class Name, CA Top Secret assumes that the resource is protected; no ownership checking is performed. The specification of a question mark (?) forces the DEFPROT attribute to be used for the resource.

Return Codes

Return Code	Meaning
00	Access allowed, resource defined.
04	Resource not defined.
08	Access denied.

Examples: RACROUTE REQUEST=FASTAUTH Specification

This example is for a multiple user address space. The ACEE= parameter is not needed for a single user address space. This example determines if the transaction is executable by the user.

RACROUTE REQUEST=FASTAUTH,
         CLASS=LCF,
         ENTITY=command,             (8‑byte command name)
         WKAREA=workarea,            (64‑byte work area)
         WORKA=SAF‑workarea,         (512‑byte work area)
         ACEE=acee‑ptr               (address of ACEE)
LCF     DC   CL8'XLCFCMD'

This example is for a multiple user address space. The ACEE= parameter is not needed for a single user address space. This example determines if the user has UPDATE Access to the database field.

RACROUTE REQUEST=FASTAUTH CLASS=FIELD,                                         
               ENTITY=salary,              (field name,access,program)         
               WKAREA=workarea,            (64-byte work area)                 
               WORKA=SAF-workarea,         (512-byte work area)                
               ACEE=acee-ptr               (address of ACEE)                   
.../...                                                                        
FIELD    DC    C'FLD-?RR?'                 (field; assumed owned)              
SALARY   DC    CL44'SALARY91',X'60',CL8' ' (must be CL44, see RDT for class    
                                            FIELD)