Extending Security Through Site Security Exits

CA Top Secret lets you create security checks which bypass, replace, or enhance normal security validation with TSSINSTX. You can use TSSINSTX to:
  • Provide additional job card parameter validations:
    • JES2 Initiator class authorizations
    • Job priority authorizations
    • Account number information
  • Limit TSO usage by department.
  • Maintain CA-Roscoe usage statistics based on the time-of-day session-Roscoe/ * * signoff.
  • Verify voice/image for online session signon.
  • Provide implicit data set prefix security for DASD management archiving data sets.
  • Use “pseudo data set names” to provide other resources with the flexibility of data set name security. This is useful in controlling access to members in a library management package (for example, CA Panvalet, CA Librarian, or CA Endeavor).
  • Eliminate the logging of BYPASS events as desired by the installation to reduce ATF logging.
Sample code for these uses is in the AAKOSRC0 member TSSINST1.
TSSINSTX is a single load module with a single entry point. There are 26 different processing routines which are entered based upon the function code passed on entry. The load module must reside in a LINKLST library and must be named TSSINSTX. The link-edit must specify AMODE(31),RMODE(ANY).
TSSINSTX is supplied in the AAKOSRC0 file member TSSINSTX. An activation matrix at the beginning of the TSSINSTX module defines which exit points are invoked. The matrix contains a one byte flag for each function (point of user entry). If the flag byte is non-zero, CA Top Secret calls the installation exit point for the function.
It is the responsibility of the site programmer to place the customized installation code in the appropriate exit routine within TSSINSTX.
TSSINSTX Characteristics
To assemble the sample exit provided in the AAKOSRC0 file as member TSSINST1, the SYSLIB concatenation should include the following data sets:
    z/OS target macro library.
    JES2 distribution macro library.
    z/OS distribution macro library.
  • cai.CAKOMAC0
    CA Top Secret for z/OS macro file.
  • cai.CAKOSRC0
    CA Top Secret for z/OS source file.
With the exception of the COMMAND exit, TSSINSTX normally runs in the user address space under the security SVC. In the case of the COMMAND exit, TSSINSTX runs in the CA Top Secret address space. The exit is entered in supervisor state, key 0. The exit can issue any SVC and perform I/O unless otherwise noted below (when cross memory mode is involved).
TSSINSTX is protected by an error recovery routine (in most cases). In the event of an abend, an SVC dump is taken and the exit is disabled with a message issued to the security and master consoles. Any variations to this rule are noted below in this section.
CA Top Secret loads the installation exit (TSSINSTX) as specified on the module's linkedit attributes. The installation exit should be linked as RMODE(ANY), so that it is loaded above the line. Because most parameters passed to the exit now exist above the line, RACROUTE calls must be issued for all security checks. TSSINST1, supplied in CAI.AAKOSRC0, contains examples of proper coding of RACROUTE requests.
Because the exit can issue any SVC and perform I/O, different exits are called when in cross memory mode. A FASTAUTH call that would ordinarily call the RESOURCE, RESOURCE POST VALIDATION, MESSAGE, or VIOLATION exit points instead calls CROSS MEMORY versions of these exits if the FASTAUTH is issued in cross memory mode. These exit points may not issue SVCs or perform I/O.
If a validation is processed for a facility with resource translation, the translation of resource classes occurs before an exit point is invoked. The values communicated to TSSINSTX for TXA#RTYP and TXARTYP2 correspond to the translated resource type.
Common Exit Parameters
This list contains common parameters passed to all exit points. Some parameter fields may not be valid at some exit points. For example, the TXA#DRC parameter field will not contain valid information for the PREINIT exit point since the security processing has not completed.
    @ ACID that initiated the security event.
    @ ACEE for the ACID that initiated the security event.
    @ Detailed Reason Code for this security event.
    @ Facility matrix table entry for the facility under which the ACID signed on. The facility matrix table entry is mapped by the #FACMATX macro definition supplied in the CAI.OPMAT file on the product installation tape.
    @ Feedback area address, if present.
    @ Flag for communication with TSSINSTX.
    @ ACID installation data area (INSTDATA). The area contains a length byte and a zero separator followed by the actual data (up to 256 bytes). This field cannot be updated for TSSINSTX. Any actual change to an ACID's installation data would be accomplished through the use of the CA Top Secret Application Interface, or TSS administrative commands.
    @ Installation-wide installation data field (eight-byte). The initial contents of this field are determined by the setting for the INSTDATA() control option. This field may be overwritten through the use of the installation exit but any change will only be maintained for the life of the current TSS started task. Once TSS is restarted, TXA#INST is reset to the value specified in the INSTDAT() control option.
    @ One word (four-byte) work area that may be set and modified by the installation exit TSSINSTX. This field remains available throughout the life of the user's current session. The field is never stored permanently to the security file.
    @ Jobname that initiated the security event.
    @ Mode byte for this event.
    @ Initiating programs for this event (from PRB).
    @ SECREC for the ACID that initiated the security event.
    @ SVCs in control when the security event was initiated.
    @ Terminal/source for the ACID initiating the security event.
    @ Generic job type field from the facility under which the ACID signed on. This value is the type= value from Facility control option definition.
  • TXA#@RFP
    @ @RACF Parameter List.
  • TXA#@SFP
    @ @SAF Parameter List.
    @ Language indicator.