CICS security control points

RACROUTE macros are used to call the external security manager (ESM). Theses macros are issued at a number of control points. Some calls might not always be issued, because CICS reuses entries for eligible user IDs that have already signed on in the CICS region.

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

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

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

  • Normal sign-on through EXEC CICS SIGNON.
  • Sign-on of the default user ID 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 user ID 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.
  • Sign-off 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 user ID on an attach request, for all operands of ATTACHSEC except LOCAL.
  • Sign-off because RACF notifies CICS of changes to a user profile, and an attached request associated with that signed-on user ID completes, for all operands of ATTACHSEC except LOCAL.
  • Sign-off because RACF notifies CICS of changes to a user profile, and a new attach request is made and the value in the USRDELAY system initialization parameter has not expired. This sign-off is followed by a sign-on.
RACROUTE REQUEST=VERIFYX
This macro creates and deletes an ACEE in a single call. This macro 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.
  • When a login process involving password verification, such as the EXEC CICS VERIFY PASSWORD or EXEC CICS VERIFY PHRASE command, is used to log in a user, and one of the following conditions applies:
    • The original attempt to verify the password using RACROUTE REQUEST=EXTRACT has failed. In this situation, RACROUTE REQUEST=VERIFYX is issued after RACROUTE REQUEST=EXTRACT.
    • The system initialization parameter SECVFYFREQ=USRDELAY is specified for the CICS region, and CICS is enforcing a full verification request for the user ID at this login. The value of the USRDELAY system initialization parameter for the CICS region is used as the interval between full verification requests at user login, although CICS applies a maximum limit of one day for this function. In this situation, RACROUTE REQUEST=VERIFYX is issued instead of RACROUTE REQUEST=EXTRACT.
RACROUTE REQUEST=FASTAUTH
This macro is issued during resource checking, on behalf of a user who is identified by an ACEE. This macro is the high-performance form of REQUEST=AUTH, using in-storage resource profiles, which does not cause auditing to be performed. This macro 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
RACROUTE REQUEST=AUTH
This macro provides a form of resource checking with a larger pathlength and causes auditing to be performed. This macro 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 option 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. This macro 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

This macro is issued when a login process involving password verification, such as the EXEC CICS VERIFY PASSWORD or EXEC CICS VERIFY PHRASE command, is used to log in a user. If the password cannot be verified using this macro, CICS then issues the RACROUTE REQUEST=VERIFYX macro. If the system initialization parameter SECVFYFREQ=USRDELAY is specified for the CICS region, and CICS is enforcing a full verification request for the user ID at this login, CICS issues the RACROUTE REQUEST=VERIFYX macro in place of the RACROUTE REQUEST=EXTRACT macro for the EXEC CICS VERIFY PASSWORD or EXEC CICS VERIFY PHRASE command.

If RACF APARs BA43999 for z/OS 1.13 or CA43999 for z/OS 2.1 are installed, then the R_Password service is used in place of the RACROUTE REQUEST=EXTRACT.

R_Password callable interface is used for VERIFY PASSWORD, VERIFY PHRASE, and SIGNON (if RACF APARs BA43999 for z/OS 1.13 or CA43999 for z/OS 2.1 are installed).

The RACROUTE REQUEST=EXTRACT macro is also issued with the SEGMENT=CICS,CLASS=USER parameters and with the SEGMENT=BASE,CLASS=USER parameters to obtain the national language and user name, at all of the following control points:
  • Normal sign-on through EXEC CICS SIGNON
  • Sign-on of the default user ID 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 those previously mentioned.
  • Sign-on associated with the user ID on an attach request, for all operands of ATTACHSEC except LOCAL

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

The macro can be used to verify the password of the user when an entry in the user table is reused within the USRDELAY period.

The REQUEST=EXTRACT parameter has no associated RACF user exit, and no installation parameter data is passed. You use the MVS router exit, ICHRTX00, for customization.

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