Enabling the External Security Interface

How ESI Security Works
CA Endevor® SCM
External Security Interface (ESI) is an option that unifies security for
CA Endevor SCM
and your site security package (CA ACF2 for z/OS, CA Top Secret for z/OS, RACF). ESI lets you do the following tasks:
  • Extend your site security package to control and authorize access to components maintained by the product.
  • Secure user actions ranging from environment access to specific action checks.
  • Customize ESI security through a table-driven architecture.
ESI converts combinations of the product entities such as an environment name or an element name into pseudo data set names and queries your site security package for a ruling whether the user is allowed to access the data set. Examples of the product entities that you can map into your site security package rules are:
  • Actions
  • CCIDs
  • Elements
  • Environments
  • Stages
  • Systems/subsystems
Each node in a data set name only allows a maximum of eight characters per value; therefore, values greater than eight characters are truncated to eight characters (for example, EMERGENC).
ESI uses the product-provided security checkpoints (Exit 01) to determine whether to allow or deny a user access to an inventory, environment, function, or action. ESI processing is invoked at all security control points.
ESI uses a compiled table that is named the Name Equates Table to specify rules that map entity names to pseudo data set names when a security control point is encountered. ESI constructs the pseudo data set name and executes the operating system RACROUTE macro. The RACROUTE macro provides an application with access to the System Authorization Facility (SAF) which in turn communicates with your site security package (CA ACF2, CA Top Secret, RACF). SAF lets the product request authorization information for any site security package. The Name Equates Table consists of a set of ESI Defaults entries (ESIDFLTS), Function Equates entries (FUNCEQU) and Name Equates entries (NAMEQU) described in the following sections.
ESI Defaults Entries (ESIDFLTS)
This entry lets you establish the default behavior for all security call formats and tracing. The entry also includes an option to improve performance. For more information about the defaults entry, see How to Define ESI Diagnostics.
Function Equates Entries (FUNCEQU)
This entry lets you map product actions to authorization values or keywords for your site security package. For more information, see Map Authorization Values.
Name Equates Entries (NAMEQU)
This entry become the pseudo data set names that are sent to the RACROUTE macro. Each entry corresponds to a specific security control point that you can secure. Six different security call formats exist for pseudo data sets. The following table shows the correlation of the pseudo data set formats to security control points:
Security Control Point
Where the Security Check Occurs
(formerly FORMAT1)
Before building the Environment Selection menu
When you change the current environment through a panel
During batch processing to validate your environment access
Primary Options
(formerly FORMAT2)
Before building the Environments Primary Options menu
During LOAD/UNLOAD/RELOAD processing
During batch package processing
Foreground Options
(formerly FORMAT3)
Before building the Foreground Options menu for the environment
Action Initiation
ACTION_INITIATION-standard and extension
(formerly FORMAT4 and FORMAT5)
Before performing the requested action
Before cast, during package processing if PKGCSEC=Y
Before inspect, during package processing if PKGISEC=Y
During package verification processing
Package Actions
Before performing the requested package action
Concurrent Action Processing
Before initiating concurrent batch actions
Security Processing Model
The following figure shows how
CA Endevor SCM
ESI works with a site security package such as CA ACF2, CA Top Secret, RACF.
This figure illustrates the security processing model.
The following list describes the security processing model.
  1. CA Endevor SCM
    calls Exit 01 processing, which calls ESI.
  2. Exit01 calls ESI.
  3. ESI constructs the data set name (DSN) and authorization level from the Name Equates Table.
  4. ESI issues a RACROUTE request with the DSN and authorization levels. RACROUTE requests are routed to the System Authorization Facility (SAF).
  5. SAF routes the RACROUTE request directly to the site security package.
  6. The security package interprets the request by looking up the request in the security database.
  7. SAF returns to ESI and the request either passes or fails.
  8. ESI returns to Exit 01 processing.
  9. The product Exit 01 processing runs other user exits.
  10. Exit 01 processing may return to the product.
User Exit Modules
You can define a user exit module at exit point 1 to do the following tasks:
  • Supplement the menu-building checks the system makes at each security control point.
  • Supplement the action-request authorization that occurs at each security control point.
Exit 01 can only further restrict security, it cannot override restrictions that are imposed by your site security package (CA ACF2, CA Top Secret, RACF).
Name Equates Table
This table lets you specify security rules that map the product entity names to pseudo data set names. The following entry is a sample Name Equates Table:
  If the LATSIZE parameter is coded in the ESI Defaults macro (ESIDFLTS) in your Name Equates table, the parameter is ignored for processing, but appears in the trace. PTF SO00990 made LATSIZE obsolete.
         TITLE 'BC1TNEQU - EXTERNAL SECURITY INTERFACE TABLE.' *********************************************************************** *        DEFINE ESI DEFAULTS                                          * *********************************************************************** BC1TNEQU ESIDFLTS WARN=NO,                                             +                TITLE='BC1TNEQU SECURITY INTERFACE TABLE',              +                HEADER=YES,                                             +                LATSIZE=2,                                              +                DESC=6,                                                 +                ROUTCDE=11 *********************************************************************** *        MAP E/MVS AUTHORITIES TO SAF AUTHORITIES FOR                 * *        ACTION_INITIATION AND PACKAGE_ACTIONS FORMAT CALLS.          * *        NOTE: ENVIRONMENT_ACCESS, PRIMARY_OPTIONS AND                * *              FOREGROUND_OPTIONS FORMAT CALLS ALWAYS USE READ        * *              AUTHORITY AND CANNOT BE MODIFIED.                      * ***********************************************************************          FUNCEQU SAFAUTH=READ,                                         +                C1ACTNS=(ADD,ARCHIVE,DELETE,                            +                DISPLAY,ENVRNMGR,GENERATE,MOVE,                         +                PBACKOUT,PCAST,PCOMMIT,PCREATE,PDISPLAY,PDYNAMIC,       +                PEXECUTE,PLIST,PMODIFY,PREVIEW,PSHIP,                   +                PUTILITY,RETRIEVE,SIGNIN,SIGNOVR,UPDATE) *********************************************************************** *        SAMPLE SYNTAX OF OTHER SUPPORTED FUNCEQU AUTHORITIES LEVELS  * *********************************************************************** *        FUNCEQU SAFAUTH=NONE,                                        + *        FUNCEQU SAFAUTH=UPDATE,                                      + *        FUNCEQU SAFAUTH=CONTROL,                                     +          FUNCEQU SAFAUTH=ALTER,                                        +                C1ACTNS=(ALTER)                                          *********************************************************************** *        END OF FUNCEQU SECTION                                       * ***********************************************************************          FUNCEQU TYPE=END          SPACE 2 *********************************************************************** *        SPECIFY SAF DATASET NAME FORMATS                             * ***********************************************************************          NAMEQU ENVIRONMENT_ACCESS,                                    +                L1=('C1'),                                              +                L2=('ENVIRON'),                                         +                L3=(ENVIRONMENT)          NAMEQU PRIMARY_OPTIONS,                                       +                L1=('C1'),                                              +                L2=(ENVIRONMENT),                                       +                L3=('PMENU'),                                           +                L4=(MENUITEM)          NAMEQU FOREGROUND_OPTIONS,                                    +                L1=('C1'),                                              +                L2=(ENVIRONMENT),                                       +                L3=('FORACTN'),                                         +                L4=(MENUITEM)          NAMEQU ACTION_INITIATION,                                     +                L1=('C1'),                                              +                L2=(ENVIRONMENT),                                       +                L3=(SYSTEM),                                            +                L4=(SUBSYSTEM)          NAMEQU ACTION_INITIATION,                                     +                L1=('C1'),                                              +                L2=(MENUAUTH) ***********************************************************************         *        SAMPLE SYNTAX FOR EXPLICIT CONTROL OF INIDIVIDUAL ACTIONS    *         *        NOTE: MAKE SURE YOUR SECURITY RULES MATCH OR ARE GENERIC     *         ***********************************************************************         *              L3=(MENUITEM)                                                    ***********************************************************************         *        SAMPLE SYNTAX FOR THE ALTERFLD KEYWORD FOR THE ALTER ACTION  *         ***********************************************************************         *              L4=(ALTERFLD)                                                    ***********************************************************************              NAMEQU PACKAGE_ACTIONS,                                       +                L1=('C1'),                                              +                L2=('PACKAGE'),                                         +                L3=(MENUITEM),                                          +                L4=(PKGSUBFC),                                          +                L5=(PKGID)          NAMEQU CONCURRENT_ACT_PROC,                                   +                CLASS='DATASET',                                        +                WARN=NO,                                                +                LOG=NONE,                                               +                L1=('C1'),                                              +                L2=('CAP')                                                ********************************************************************** * *        SAMPLE SYNTAX OF OTHER SUPPORTED NAMEQU PACKAGE_ACTIONS       * *        SYMBOLIC PARAMETERS                                           * ******************************************************************* **** *              LN=(PKGAPPGR),                                          + *              LN=(PKGBOE),                                            + *              LN=(PKGSHR),                                            + *              LN=(PKGSTAT),                                           + *              LN=(PKGTYPE),                                           + *              WARN=NO *********************************************************************** *        END OF NAMEQU SECTION                                        * ***********************************************************************          NAMEQU TYPE=END          END 
The following entries are coded in the Name Equates Table:
    Improves performance and establish the default behavior for all formats and traces.
    CA Endevor SCM
    access levels to authorization values for the RACROUTE attr=auth parameter.
    Creates the ENVIRONMENT_ACCESS through CONCURRENT_ACT_PROC pseudo data set names. This entry creates the entity=dsname value that is used by the RACROUTE request.