CICS security control points

This topic contains Product-sensitive Programming Interface and Associated Guidance Information.

This section summarizes the RACROUTE macros used by CICS® to invoke the ESM, and the control points at which they are issued.

Some of these calls may not always be issued, because CICS reuses entries for users already signed on.

RACROUTE
This is the "front end" to the macros described below; it invokes the MVS™ router.
RACROUTE REQUEST=VERIFY
This macro is issued at operator sign-on (with the parameter ENVIR=CREATE), and at signoff (with the parameter ENVIR=DELETE). It creates or destroys an ACEE (access control environment element). It is issued at the following CICS control points (it is also issued (with the parameter ENVIR=VERIFY) early in normal sign-on through EXEC CICS SIGNON, but this call is ignored by RACF®):

Each of the following control points relates to ENVIR=CREATE:

  • Normal sign-on through EXEC CICS SIGNON
  • Sign-on of the default userid DFLTUSER
  • Sign-on of preset-security terminal
  • Sign-on of MRO session
  • Sign-on of LU6.1 session
  • Sign-on of LU6.2 session
  • Sign-on for XRF tracking of any of the above
  • Sign-on associated with the userid on an attach request (for all operands of ATTACHSEC except LOCAL).
Each of the following control points relates to ENVIR=DELETE:
  • Normal sign-off through EXEC CICS SIGNOFF
  • Sign-off when deleting a terminal
  • Sign-off when TIMEOUT expires
  • Signoff when USRDELAY expires
  • Sign-off of MRO session
  • Sign-off of LU6.1 session
  • Sign-off of LU6.2 session
  • Sign-off for XRF tracking of any of the above.
  • Sign-off associated with the userid on an attach request (for all operands of ATTACHSEC except LOCAL).
RACROUTE REQUEST=VERIFYX
This macro creates and deletes an ACEE in a single call. It is issued at the following control points:
  • Sign-on, as an alternative to VERIFY, when an optimized sign-on is performed for subsequent attach sign-ons across an LU6.2 link with ATTACHSEC(VERIFY) or ATTACHSEC(PERSISTENT).
  • When an invalid password or PassTicket is presented.
  • Start of changeWhen a login process involving password verification, such as the EXEC CICS VERIFY PASSWORD command, is used to log in a user, and the original attempt to verify the password using the RACROUTE VERIFY=EXTRACT macro has failed.End of change
RACROUTE REQUEST=FASTAUTH
This macro is issued during resource checking, on behalf of a user who is identified by an ACEE. It is the high-performance form of REQUEST=AUTH, using in-storage resource profiles, which does not cause auditing to be performed. It is issued at the following CICS control points:
  • When attaching a local transaction
  • When checking link security for transaction attach
  • Transaction validation for an MRO task
  • CICS resource checking
  • Link security check for a CICS resource
  • Transaction validation for EDF
  • Transaction validation for the transaction being tested (by EDF)
  • DBCTL PSB scheduling resource security check
  • DBCTL PSB scheduling link security check
  • Remote DL/I PSB scheduling resource check
  • When checking a surrogate user authority
  • QUERY SECURITY with the RESTYPE option.
  • When an enterprise bean invokes the isCallerInRole() method.
  • When checking the authority of a user to invoke an enterprise bean method.
RACROUTE REQUEST=AUTH
This macro provides a form of resource checking with a larger pathlength, and causes auditing to be performed. It is used as follows:
  • After a call to FASTAUTH indicates an access failure that requires logging.
  • When a QUERY SECURITY request with the RESCLASS option is used. This indicates a request for a resource for which CICS has not built in-storage profiles.
RACROUTE REQUEST=LIST
This macro is issued to create and delete the in-storage profile lists needed by REQUEST=FASTAUTH. (One REQUEST=LIST macro is required for each resource class.) It is issued at the following CICS control points:
  • When CICS security is being initialized
  • When an EXEC CICS PERFORM SECURITY REBUILD command is issued
  • When XRF tracks either of these events.
RACROUTE REQUEST=EXTRACT

Start of changeThis macro is issued when a login process involving password verification, such as the EXEC CICS VERIFY PASSWORD command, is used to log in a user. If the password cannot be verified using this macro, CICS subsequently issues the RACROUTE REQUEST=VERIFYX macro. End of change

The RACROUTE REQUEST=EXTRACT macro is also issued, with the parameters SEGMENT=CICS,CLASS=USER, and with the SEGMENT=BASE,CLASS=USER parameters to obtain the national language and user name, at all the following control points:
  • Normal sign-on through EXEC CICS SIGNON
  • Sign-on of the default userid DFLTUSER
  • Sign-on of preset security terminal
  • Sign-on of MRO session
  • Sign-on of LU6.1 session
  • Sign-on of LU6.2 session
  • Sign-on for XRF tracking of any of the above
  • Sign-on associated with the userid on an attach request (for all operands of ATTACHSEC except LOCAL).
It can be used to verify the user's password when an entry in the user table is reused within the USRDELAY period.

It is also issued (with the parameters SEGMENT=SESSION,CLASS=APPCLU) during verification of LU6.2 bind security, at the CICS control point for bind of an LU6.2 sessions.

There is no RACF user exit for REQUEST=EXTRACT, and no installation parameter data is passed. Any customization must be done using the MVS router exit, ICHRTX00.

For a detailed description of these macros, see the z/OS Security Server RACROUTE Macro Reference.