Using ESM exit programs to access CICS-related information

When CICS® invokes the ESM, it passes information about the current CICS environment, for use by an ESM exit program, in an installation data parameter list. How your exit programs access the installation data parameter list depends on whether or not your ESM is RACF®.

For non-RACF users -- the ESM parameter list

CICS (or another caller) passes information to your external security manager in the ESM parameter list, the address of which can be calculated using field SAFPRACP of the MVS™ router parameter list.

When the caller is CICS, the "INSTLN" field of the ESM parameter list points to the installation data parameter list, which contains CICS-related information that can be used by ESM exit programs.

The format of the ESM parameter list, and the actual name of the "INSTLN" field, vary, depending on which CICS security event is being processed. (The "request type" field (SAFPREQT) of the router parameter list shows why the ESM is being called by indicating the RACROUTE REQUEST type.) Table 44 shows how some formats of the ESM parameter list can be mapped using MVS macros.

Table 44. Mapping the ESM parameter list
RACROUTE
REQUEST type
Parameter list
mapping macro
INSTLN
field name
VERIFY IRRPRIPL INITIPTR (X'10')
AUTH ICHACHKL ACHKIN31 (X'20')
FASTAUTH Not available Offset X'18'
LIST Not available Offset X'0C'
EXTRACT Not available None
Note:
The INSTLN field points to the installation parameter list only if you specify INSTLN on the ESMEXITS system initialization parameter. The default value of this parameter is NOINSTLN, which means that no installation data is passed.

For RACF users -- the RACF user exit parameter list

If you are a RACF user, you can find the address of the installation data parameter list directly from the RACF user exit parameter list. The name of the relevant field in the user exit parameter list varies according to the RACROUTE REQUEST type and the RACF user exit that is invoked. The relationships between REQUEST type, exit name, and field name are shown in Table 45.

Table 45. Obtaining the address of the installation data parameter list
RACROUTE
REQUEST type
 
RACF exit
Exit list
mapping macro
Parameter list
field name
VERIFY ICHRIX01 ICHRIXP RIXINSTL
VERIFY ICHRIX02 ICHRIXP RIXINSTL
AUTH ICHRCX01 ICHRCXP RCXINSTL
AUTH ICHRCX02 ICHRCXP RCXINSTL
FASTAUTH ICHRFX01 ICHRFXP RFXANSTL
FASTAUTH ICHRFX02 ICHRFXP RFXANSTL
LIST ICHRLX01 ICHRLX1P RLX1INST
LIST ICHRLX02 ICHRLX2P RLX2PRPA
See note 2.
EXTRACT Not available Not available None
Notes:
  1. The "xxxINSTL" field points to the installation parameter list only if you specify INSTLN on the ESMEXITS system initialization parameter. The default value of this parameter is NOINSTLN, which means that no installation data is passed.
  2. RLX2PRPA contains the address of the ICHRLX01 user exit parameter list (RLX1P). Field RLX1INST of RLX1P in turn points to the installation data parameter list.

For full descriptions of the RACF exit parameter lists, see the OS/390 Security Server (RACF) Security Administrator’s Guide manual. For more information about CICS security processing using RACF, see the CICS RACF Security Guide.

The installation data parameter list

The installation data parameter list gives your ESM exit programs access to the following information:

You can map the installation parameter list using the macro DFHXSUXP. The DSECT DFHXSUXP contains the following fields:

UXPLEN
A halfword containing the length of this parameter list in bytes.
UXPARROW
Arrow "eyecatcher" (>).
UXPDFHXS
The name of the owning component (DFHXS).
UXPBLKID
The name of the block identifier (UXPARMS).
UXPPHASE
Address of a 1-byte code that indicates the reason for the call to the ESM (that is, the security event being processed). The code can have one of the following values:
DEFAULT_SIGN_ON (X'01')
Signon of default userid
PRESET_SIGN_ON (X'02')
Signon of preset security terminal
IRC_SIGN_ON (X'03')
Link signon for IRC (MRO) links
LU61_SIGN_ON (X'04')
Link signon for LUTYPE6.1 links
LU62_SIGN_ON (X'05')
Link signon for APPC links
XRF_SIGN_ON (X'06')
XRF tracking of signon
ATTACH_SIGN_ON (X'07')
Attach-time signon of link user
NON_TERMINAL_SIGN_ON (X'08')
Signon of a non-terminal userid
USER_SIGN_ON (X'10')
Normal user signon
PRESET_SIGN_OFF (X'22')
Sign-off when terminal deleted
LINK_SIGN_OFF (X'25')
Sign-off when link is closed
XRF_SIGN_OFF (X'26')
XRF tracking of sign-off
ATTACH_SIGN_OFF (X'27')
End-of-task sign-off of link user
NON_TERMINAL_SIGN_OFF (X'28')
Sign-off of a non-terminal userid
USER_SIGN_OFF (X'30')
Normal user sign-off
TIMEOUT_SIGN_OFF (X'31')
Sign-off forced by the terminal abnormal condition program, or time-out by the CSSC transaction
USRDELAY_SIGN_OFF (X'32')
Sign-off caused by expiry of USRDELAY interval
DEFERRED_SIGN_OFF (X'33')
Sign-off deferred to task end
USER_ATTACH_CHECK (X'40')
Transaction attach check for user
LINK_ATTACH_CHECK (X'41')
Transaction attach check for link
EDF_ATTACH_CHECK (X'42')
Transaction attach check for CEDF
USER_COMMAND_CHECK (X'50')
Command checking for user
LINK_COMMAND_CHECK (X'51')
Command checking for link
EDF_COMMAND_CHECK (X'52')
Command checking for EDF
USER_RESOURCE_CHECK (X'60')
Resource checking for user
LINK_RESOURCE_CHECK (X'61')
Resource checking for link
EDF_RESOURCE_CHECK (X'62')
Resource checking for EDF
USER_SURROGATE_CHECK (X'68')
Surrogate checking for user
LINK_SURROGATE_CHECK (X'69')
Surrogate checking for link
EDF_SURROGATE_CHECK (X'6A')
Surrogate checking for EDF
USER_QUERY_CHECK (X'70')
Query checking for user
LINK_QUERY_CHECK (X'71')
Query checking for link
EDF_QUERY_CHECK (X'72')
Query checking for EDF
INITIALIZE_SECURITY (X'80')
Initialization of CICS security
REBUILD_SECURITY (X'81')
CEMT or command-level SECURITY REBUILD
XRF_TRACK_INITIALIZE (X'82')
XRF tracking of initial or rebuild.
UXPSUBSY
Address of an area containing the CICS subsystem identifier.
UXPAPPL
Address of an area containing the CICS application ID.
Note:
When CICS is a member of a VTAM generic resource, the area pointed to by UXPAPPL contains the generic, not the specific, applid.
UXPCWA
Address of the Common Work Area.
UXPTRAN
Address of an area containing the transaction identifier.
UXPPROG
Address of an area containing the program name. The address may be zero if no program name can be identified.
UXPTERM
Address of an area containing the terminal identifier. The address may be zero if no terminal is associated with the request.
UXPLUNAM
Address of an area containing the VTAM LU name. The address may be zero if no terminal is associated with the request, or the area may be blank if the terminal is not a VTAM terminal.
UXPTCTUA
Address of the TCT user area.
UXPTCTUL
Address of a fullword containing the length of the TCTUA.
UXPCOMM
Address of a 2-word communication area.

Related concepts
An overview of the CICS-ESM interface
Related tasks
Using early verification processing
Related reference
The MVS router
CICS security control points
[[ Contents Previous Page | Next Page Index ]]