CICS security control points

CICS uses RACROUTE macros and RACF callable services to call the external security manager (ESM). Theses calls 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 macros

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.
  • The first time a userid is authenticated each day.
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.
  • The first time a userid is authenticated each day.
RACROUTE REQUEST=VERIFYX
This macro creates and deletes an ACEE in a single call. This macro is issued at the following control points:
  • When an authentication process that involves password verification is used, and one of the following conditions applies:
    • The password is invalid (following an R_Password or RACROUTE REQUEST=EXTRACT).
    • The previous attempt to log in was invalid.
  • 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).
  • Changing a password or password phrase
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 used in place of R_Password if R_Password is not available (see note 1).
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.

z/OS Security Services RACF Callable Services

CICS uses the following callable interfaces for different purposes when calling ESM.

deleteUSP (IRRSDU00): Delete USP
Used for HFS file security.
initACEE (IRRSIA00): Initialize ACEE
Used to obtain userids from a certificate.
initUSP (IRRSIU00): Initialize USP
Used for HFS file security.
R_admin (IRRSEQ00): RACF administration API
Used to validate a certificate label.
R_cacheserv (IRRSCH00): Cache services
Used to obtain or delete an ICRX associated with an ACEE.
R_datalib (IRRSDL00): OCSF data library
Used to extract the information of certificates from the CICS key ring.
R_dcekey (IRRSDK00): Retrieve or set a non-RACF password
Used in LDAP processing.
R_GenSec (IRRSGS00): Generic security API interface
Used for Kerberos support. CICS provides Kerberos support through the VERIFY TOKEN and SIGNON TOKEN API commands, and through web services configuration.
R_kerbinfo (IRRSMK00): Retrieve or set security server network authentication
Used for Kerberos support to obtain the principle name of a region.
R_ticketserv (IRRSPK00): Parse or extract
Used for Kerberos support. CICS provides Kerberos support through the VERIFY TOKEN and SIGNON TOKEN API commands, and through web services configuration.
R_usermap (IRRSIM00): Map application user
Used to obtain a user associated with a Kerberos token in Kerberos verification. CICS provides Kerberos support through the VERIFY TOKEN and SIGNON TOKEN API commands, and through web services configuration.
R_Password (IRRSPW00): Evaluate or encrypt a clear-text password or password phrase
Used for VERIFY PASSWORD and VERIFY PHRASE API commands, and for the SIGNON API command with PASSWORD or PHRASE specified (see note 1).

For a detailed description of these calls, see z/OS Security Server RACF Callable Services.

Note:
  1. Requires z/OS 2.2, or z/OS 2.1 with the PTF for APAR CA43999 applied.