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®.
- 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
- When an authentication process that involves password verification is used, and one of the
following conditions applies:
- 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.
- Requires z/OS 2.2, or z/OS 2.1 with the PTF for APAR CA43999 applied.