How to install the CA-Panvalet interface for External Security with CA-ACF2
Article ID: 28117
Updated On:
Products
Issue/Introduction
Introduction:
CA-Panvalet is a program management system that controls all source and object programs and has a reporting feature that permits status tracking of all programs.
Interface Support
CA-Panvalet provides an appropriate security exit. CA Technologies provides code for this security exit to let CA-Panvalet interface with the external security provided by CA-ACF2.
CA-ACF2 CA-Panvalet Interface Summary
The CA-ACF2 CA-Panvalet interface can replace the internal CA-Panvalet security completely provided that all access codes are removed from the CA-ACF2-protected library. You must install CA-Panvalet 11.0 or higher before installing the CA-ACF2 CA-Panvalet interface. After the interface is installed and completely tested, we recommend that you remove all access codes from the CA-ACF2-protected CA-Panvalet libraries.
The Generalized Exits section of the CA-Panvalet System Management Manual is prerequisite background reading for the successful use of this interface.
The CA-ACF2 CA-Panvalet interface provides the following features:
- CA-Panvalet Function Validation
When a CA-Panvalet command is issued, the CA-ACF2 CA-Panvalet interface uses the CA-Panvalet security exit $MEM001 to intercept the CA-Panvalet command before execution. The function and command name are available to the exit in data-ID FUNCTION. The Generalized Exits section of the CA-Panvalet System Management Manual defines the functions and commands that can appear in this field for the various CA-Panvalet programs.
The interface then validates the user's authority to issue the command by checking a privilege attribute in the user's logonid. If the user has the required privilege, the CA-Panvalet command continues.
The site must define the privilege attribute associated with a group of CA-Panvalet commands and define the CA-Panvalet command groupings. You can find information on defining CA-Panvalet command groupings in step 5 of the "Installing the CA-ACF2 CA-Panvalet Interface" section. You can find additional information on defining the privilege attribute in step 4 of the same section. - CA-Panvalet Member Validation
When a CA-Panvalet command requesting access to a CA-Panvalet member is issued, the CA-ACF2 CA-Panvalet interface intercepts the command through the CA-Panvalet security exit $MEM001. A CA-ACF2 resource rule validation determines the user's authority to access the CA-Panvalet member.
The key of the resource rule is a resource name consisting of input values (data items) passed to the CA-ACF2 CA-Panvalet security exits. The site must define the specific data items that make up the resource name.
The site can define the fields (or parts of fields) that make up a resource. The resource is validated against the resource rules. The default uses the FUNCTION and MBRNAME fields available in the $MEM001 exit. The type code assigned to the resource comes from another macro that gives a list of CA-Panvalet libraries and the type code associated with each.
You must define an ACFPLIB macro for each CA-Panvalet library that CA-ACF2 protects. In addition, you must define an ACFPRKEY macro to determine the $MEM001 fields to use in the resource name. Your choice of parameters determines the complexity of the resource rules written based on the ACFPRKEY macro definition. - Maintenance Facility
The maintenance facility allows the site to assign a maintenance attribute in the logonid record of the CA-Panvalet maintenance person. The CA-Panvalet maintenance person with this authority is not subject to CA-ACF2 resource rule validation when issuing commands that the site has defined as CA-Panvalet maintenance commands. (Refer to step 5 in the Installing the CA-ACF2 CA-Panvalet Interface section.)
Your site must define the logonid privilege attribute associated with CA-ACF2 CA-Panvalet maintenance authority. Even if a user has the maintenance facility, he is still subject to command validation. You can find further information on defining the maintenance facility attribute in step 4 of the Installing the CA-ACF2 CA-Panvalet Interface section. - Trace Facility
The trace facility provides diagnostic information if the CA-ACF2 CA-Panvalet interface is not functioning correctly. The input to the CA-Panvalet security exit, $MEM001, is written to the job log so you can review it. This lets you determine whether the CA-ACF2 CA-Panvalet interface errors are due to an interface malfunction or incorrect input. To use the trace facility, turn on the trace attribute in the user's logonid. Turn the trace attribute on only for diagnostic purposes because it produces a large amount of output. Your site must define the logonid attribute to associate with the CA-ACF2 CA-Panvalet trace indicator.
Installing the CA-ACF2 CA-Panvalet Interface instructions:
To install the CA-ACF2 CA-Panvalet interface, perform the following tasks.
Step 1: Choosing Undefined Library Action
The first task is choosing the course of action to take when a CA-Panvalet library is undefined to the external security interface. The interface uses the ACFLOPT macro coded in ACF2.CAX1MAC0(ACFA3PAC) to provide three courses of action when a CA-Panvalet library is undefined. The choices are:
Validate access to an undefined library against a default resource type
Grant access to an undefined library
Abort access to an undefined library
The syntax for the ACFLOPT macro is:
ACFLOPT [VALIDATE|ALLOW|ABORT,TYPE=type]
The first parameter is positional and specifies the course of action. The possible values are:
VALIDATE--Validate against the default resource type.
ALLOW--Grant access.
ABORT--Prevent access.
The second parameter, TYPE, specifies the type code, where type specifies the default resource type for validation. It must be one to three characters long. This type corresponds to the type code used in the resource rule. TYPE is valid only when you specify the VALIDATE function. For example, to validate against PAN rules by default, the macro would be coded as follows:
ACFLOPT VALIDATE,TYPE=PAN
Step 2: Defining Libraries and Selecting Resource Types
The interface uses the ACFPLIB macro to define CA-Panvalet libraries. If you do not define a library, action is chosen in accordance with the value coded in the ACFLOPT macro. The interface uses the ACFPLIB macro to associate a three-character resource type with a CA-Panvalet library. There must be one ACFPLIB entry for each library that you want the interface to protect.
The syntax for the ACFPLIB macro is:
ACFPLIB type,dsn
Where:
type specifies the CA-ACF2 resource type code. The type is one to three characters long and is user-defined. While you can use any resource type code desired, to avoid confusion in writing and validating the resource rules each type code assign should be unique. You can specify the same type more than once, but you cannot mask it. Refer to the CA-ACF2 Administrator Guide for more further information.
dsn specifies the CA-Panvalet data set name, which is up to 44 characters
long. You cannot mask this field.
ACF2.CAX1MAC0(ACFA3PAC) contains the default CA-Panvalet library definitions. These defaults are:
ACFPLIB PAN,SYS1.PANTEST
ACFPLIB PN1,SYS1.PANPROD
Step 3: Defining the Resource Name ($KEY)
The interface validates CA-Panvalet member access by using CA-ACF2 resource rules. A resource rule set that the interface uses for validation is based on the following model:
$KEY(resource-name) [TYPE(type)]
[UID(uid-mask)] [SERVICE(ADD,READ,UPDATE,DELETE)] -
[ALLOW|LOG|PREVENT]
In this rule set, TYPE is the resource type code as defined in the interface CA-Panvalet library definitions. The $KEY of the resource rule set is a user-defined resource name. This resource name consists of one or more data items in the control block available to each CA-Panvalet exit. The Generalized Exits section of the CA-Panvalet System Management Manual for MVS contains information on the data items available to each exit.
The interface uses the $MEM001 and the associated control blocks: EVENTBLK, ENVIRBLK, and DATALIST. The syntax for defining the resource name is:
ACFPRKEY list,DEFAULT=,TYPE=
Where:
list specifies the data item name, length to use, and the offset to start at in the data item. You must specify these parameters in triplets. (This is similar to a substring operation.)
DEFAULT specifies the default fill character to use when a data item is not found. The default character is also a pad character when two or more data items make up the resource name and the values of the data items do not fill the required space. Note: No imbedded blanks are permitted in the resource names; however, trailing blanks are not padded.
TYPE specifies the resource name is for CA-Panvalet. If no TYPE is
specified, the default is CA-Panvalet. Do not confuse this parameter with the TYPE in the resource rule set. They are not the same.
The maximum length of the resource name ($KEY) is 40 bytes. The member ACFA3PAC in ACF2.CAX1MAC0 contains the following default resource name definition:
ACFPRKEY (FUNCTION,8,0,MBRNAME,8,0),DEFAULT=X
This definition is used with the CA-Panvalet commands that drive the $MEM001 exit. The CA-Panvalet commands driving these exits accesses CA-Panvalet libraries. Your site chooses data items available to this CA-Panvalet security exit (that is, data items in DATALIST for $MEM001) to build into the resource name ($KEY).
If the same CA-ACF2 resource rules are used for CA-PanExec interface support, be careful to choose data items available to both interfaces. See the documentation for the CA-ACF2 CA-PanExec interface for more information.
The following example illustrates how a resource rule is built using the defaults specified above. In this example, a user is trying to update MEMBER1 in SYS1.PANPROD. Using the default resource name construction as outlined in the ACFPRKEY macro for CA-Panvalet libraries above, the following applies:
FUNCTION is UPDATE.
MBRNAME is MEMBER1.
The default fill character is X. The fill character fills the imbedded blanks in the resource name. The fill character does not fill trailing blanks. Therefore, the $KEY for this resource rule set is:
$KEY(UPDATEXXMEMBER1)
Since the library in this example is SYS1.PANPROD, the TYPE of the resource rule is PN1. A completed rule covering this situation might look like the following:
$KEY(UPDATEXXMEMBER1) TYPE(PN1)
UID(***USER1) SERVICE(READ) LOG
You can mask any part of the $KEY if the resource type is globally resident as specified in the GSO INFODIR record. See the CA-ACF2 Administrator Guide for more information on the GSO INFODIR record.
The CA-ACF2 CA-PanExec interface uses an asterisk (*) as the default fill character. For conformity, consider using an asterisk as the default fill character for CA-Panvalet.
Step 4: Defining Logonid Privileges
Your site must define a logonid attribute for the maintenance facility. This attribute can be any bit field in the logonid record. The default attribute name is PAMAINT. ACF2.CAX1MAC0(PANACFDE) contains the default specifications:
@CFDE PAMAINT,LIDPAFLG,BIT,
AUTH=PANISO,ALTER=ALL,
LIST=ALL,FLAGS=NULL,
BITMAP=LIDPAMNT,PRTN=3,RRTN=3,GROUP=2
Your site must also define a logonid attribute for the trace facility. This attribute can be any bit field in the logonid record. The default attribute name is PATRACE. ACF2.CAX1MAC0(PANACFDE) contains the default specifications:
@CFDE PATRACE,LIDPAFLG,BIT,
AUTH=PANISO,ALTER=ALL,
LIST=ALL,FLAGS=NULL,
BITMAP=LIDPATRC,PRTN=3,RRTN=3,GROUP=2
In addition, your site must define the logonid attributes associated with each CA-Panvalet command or command grouping as defined in section 5 below. The table below shows the default @CFDE entries for these attributes. ACF2.CAX1MAC0(PANALID) contains the default user field definitions.
Refer to CA-ACF2 Implementation Guide for instructions on adding user logonid fields and CFDE macros. If your site uses the provided default CA-Panvalet logonid attributes and the @CFDE macro definitions are not currently in the CA-ACF2 Field Definition Record (ACFFDR), you must regenerate the ACFFDR, and then reload it into LLA and CA-ACF2 using the following operator commands:
F LLA,ACFFDR
F ACF2,NEWMOD(ACFFDR)
Step 5: Defining CA-Panvalet Command Groupings
You must define CA-Panvalet commands to the interface to be executable. If a CA-Panvalet command is not defined, its execution is aborted. The interface checks the user's logonid for the attribute that gives the user the authority to issue a CA-Panvalet command. Therefore, each command definition must include the external name of the logonid attribute the user must have to execute the CA-Panvalet command.
Command definitions must also include the SERVICE (that is, READ, ADD, UPDATE, or DELETE) associated with each CA-Panvalet command. The syntax of the command definitions is:
ACFPCMD NAME=,CFDE=,SERVICE=,TYPE=,ENVIR=,ACTION=
NAME specifies one or more command names of the same group. The maximum length of any command name is eight characters.
CFDE indicates the external name of the @CFDE entry in the ACFFDR that is associated with this group of commands.
SERVICE indicates the process associated with this group of commands. This refers to the SERVICE keyword used in the CA-ACF2 resource rules. The valid values are READ, ADD, UPDATE, or DELETE. You can specify only one.
TYPE specifies whether the commands are maintenance commands. The only valid specification is MAINT. The default is NOMAINT. (When commands are considered maintenance commands, users who have the maintenance attribute bypass resource rule validation.)
ENVIR specifies the environment. Valid environments values are TSO, ISPF, and COMPARE. If you do not specify this parameter, batch CA-Panvalet is assumed.
ACTION refers to the pending action that is supplied to the exit as a data list item. Valid values for this parameter are READ or WRITE. Commands that drive the exit twice, such as COPY, use this parameter. The pending action must be set for the specified command entry to match. This parameter is optional and the default is blanks.
ACFA3PAC in ACF2.CAX1MAC0 contains the following default command groupings:
PAN1 COMMANDS
ACFPCMD NAME=(COPY),CFDE=PANONE,SERVICE=READ,ACTION=READ
ACFPCMD NAME=(COPY),CFDE=PANONE,SERVICE=ADD,ACTION=WRITE
ACFPCMD NAME=(ADD,ALLOCATE,ATTACH),CFDE=PANONE,SERVICE=ADD
ACFPCMD NAME=(LOCK,UNLOCK),CFDE=PANONE,SERVICE=UPDATE
ACFPCMD NAME=(RENAME,STATUS,LEVEL,USER,COMMENT,FORMAT,RESEQ,
UPDATE),CFDE=PANONE,SERVICE=UPDATE
ACFPCMD NAME=(TRANSFER),CFDE=PANONE,SERVICE=READ,ACTION=READ
ACFPCMD NAME=(TRANSFER),CFDE=PANONE,SERVICE=UPDATE, ACTION=WRIT
ACFPCMD NAME=(WRITE,SELECT,INCLUDE,I),CFDE=PANONE,
SERVICE=READ
PAMS COMMANDS
ACFPCMD NAME=(PSRCH,PREAD),CFDE=PANONE,SERVICE=READ
ACFPCMD NAME=(DETACH),CFDE=PANONE,SERVICE=DELETE
PAN2 COMMANDS
ACFPCMD NAME=(DUMP),CFDE=PANTWO,SERVICE=READ,TYPE=MAINT
ACFPCMD NAME=(BYPASS,PRINT),CFDE=PANTWO,SERVICE=READ
ACFPCMD NAME=(RESTORE),CFDE=PANTWO,SERVICE=UPDATE,TYPE=MAINT
ACFPCMD NAME=(REPLACE,TRANSFER),CFDE=PANTWO,SERVICE=UPDATE
ACFPCMD NAME=(LOCK,UNLOCK),CFDE=PANTWO,TYPE=MAINT,
SERVICE=UPDATE
ACFPCMD NAME=(DELETE),CFDE=PANTWO,SERVICE=DELETE
PAN7 COMMANDS
ACFPCMD NAME=(XREFMAIN,XREFINCL),CFDE=PANTWO, SERVICE=READ,TYPE=MAINT
PAN8 COMMANDS
ACFPCMD NAME=(REP),CFDE=PANTWO,SERVICE=UPDATE,TYPE=MAINT
ACFPCMD NAME=(SCAN),CFDE=PANTWO,SERVICE=UPDATE,TYPE=MAINT
PAN TSO COMMANDS
ACFPCMD NAME=(COPY),CFDE=PANTSO,SERVICE=READ,ACTION=READ,
ENVIR=TSO
ACFPCMD NAME=(COPY),CFDE=PANTSO,SERVICE=ADD,ACTION=WRITE,
ENVIR=TSO
ACFPCMD NAME=(ADD),CFDE=PANTSO,SERVICE=ADD,ENVIR=TSO
ACFPCMD NAME=(RENAME,STATUS,LEVEL,USER,COMMENT),
CFDE=PANTSO,SERVICE=UPDATE,ENVIR=TSO
ACFPCMD NAME=(WRITE),CFDE=PANTSO,SERVICE=READ,ENVIR=TSO
ACFPCMD NAME=(UPDATE),CFDE=PANTSO,SERVICE=UPDATE,ENVIR=TSO
ACFPCMD NAME=(FORMAT),CFDE=PANTSO,SERVICE=UPDATE,ENVIR=TSO
ACFPCMD NAME=(TRANSFER),CFDE=PANTSO,SERVICE=READ,ACTION=READ,
ENVIR=TSO
ACFPCMD NAME=(LOCK,UNLOCK),CFDE=PANTSO,ENVIR=TSO, SERVICE=UPDATE
PAN ISPF COMMANDS
ACFPCMD NAME=(COPY),CFDE=PANISPF,SERVICE=READ,ACTION=READ, ENVIR=ISPF
ACFPCMD NAME=(COPY),CFDE=PANISPF,SERVICE=ADD,ACTION=WRITE, ENVIR=ISPF
ACFPCMD NAME=(ADD),CFDE=PANISPF,SERVICE=ADD,ENVIR=ISPF
ACFPCMD NAME=(UPDATE,RENAME,STATUS,LEVEL,USER,COMMENT),
CFDE=PANISPF,SERVICE=UPDATE,ENVIR=ISPF
ACFPCMD NAME=(WRITE),CFDE=PANISPF,SERVICE=READ,ENVIR=ISPF
ACFPCMD NAME=(FORMAT),CFDE=PANISPF,SERVICE=UPDATE,ENVIR=ISPF
ACFPCMD NAME=(TRANSFER),CFDE=PANISPF,SERVICE=READ,ACTION=READ,
ENVIR=ISPF
ACFPCMD NAME=(TRANSFER),CFDE=PANISPF,SERVICE=UPDATE,ACTION=WRITE,
ENVIR=ISPF
PAN COMPARE COMMANDS
ACFPCMD NAME=(COMPARE),CFDE=PANCOMP,SERVICE=READ,ENVIR=COMPARE
PAN PVSUBSYS COMMANDS
ACFPCMD NAME=(SEQSSI),CFDE=PAMAINT, SERVICE=UPDATE,ENVIR=PVSUBSYS
ACFPCMD NAME=(PANVSSI),CFDE=PAONE,SERVICE=READ,ENVIR=PVSUBSYS,
ACTION=READ
PAN PANVSSI COMMANDS
ACFPCMD NAME=(SEQSSI),CFDE=PAMAINT,SERVICE=UPDATE, ENVIR=PANVSSI
ACFPCMD NAME=(PANVSSI),CFDE=PAONE,SERVICE=READ,ENVIR=PANVSSI,
ACTION=READ
When a CA-Panvalet command is about to access a CA-Panvalet member, the interface uses the command definition to supply the SERVICE value for resource rule validation.
Refer to the following for the @CFDE definitions and logonid fields for the default CA-ACF2 CA-Panvalet interface logonid attributes and fields in the user portion of the logonid record.
@CFDE PANISO,LIDPAFLG,BIT,ALTER=SECURITY,
LIST=SECURITY+ACCOUNT+AUDIT,
FLAGS=NULL+RESTRICT,BITMAP=LIDPAISO,
PRTN=3,RRTN=3,GROUP=2
@CFDE PANONE,LIDPAFLG,BIT,
AUTH=PANISO,ALTER=ALL,
LIST=ALL,FLAGS=NULL,
BITMAP=LIDPAPN1,PRTN=3,RRTN=3,GROUP=2
@CFDE PANTWO,LIDPAFLG,BIT,
AUTH=PANISO,ALTER=ALL,
LIST=ALL,FLAGS=NULL,
BITMAP=LIDPAPN2,PRTN=3,RRTN=3,GROUP=2
@CFDE PANTSO,LIDPAFLG,BIT,
AUTH=PANISO,ALTER=ALL,
LIST=ALL,FLAGS=NULL,
BITMAP=LIDPATSO,PRTN=3,RRTN=3,GROUP=2
@CFDE PANISPF,LIDPAFLG,BIT,
AUTH=PANISO,ALTER=ALL,
LIST=ALL,FLAGS=NULL,
BITMAP=LIDPAISP,PRTN=3,RRTN=3,GROUP=2
@CFDE PANCOMP,LIDPAFLG,BIT,
AUTH=PANISO,ALTER=ALL,
LIST=ALL,FLAGS=NULL,
BITMAP=LIDPACOM,PRTN=3,RRTN=3,GROUP=2
@CFDE PAMAINT,LIDPAFLG,BIT,
AUTH=PANISO,ALTER=ALL,
LIST=ALL,FLAGS=NULL,
BITMAP=LIDPAMNT,PRTN=3,RRTN=3,GROUP=2
@CFDE PATRACE,LIDPAFLG,BIT,
AUTH=PANISO,ALTER=ALL,
LIST=ALL,FLAGS=NULL,
BITMAP=LIDPATRC,PRTN=3,RRTN=3,GROUP=2
LIDPAFLG DS XL1 *** Panvalet FLAGS
LIDPAISO EQU X'80' *** Panvalet ISO
LIDPAPN1 EQU X'40' *** PAN1 COMMANDS
LIDPAPN2 EQU X'20' *** PAN2 COMMANDS
LIDPATSO EQU X'10' *** PAN TSO COMMANDS
LIDPAISP EQU X'08' *** PAN ISPF COMMANDS
LIDPACOM EQU X'04' *** PAN COMPARE COMMANDS
LIDPAMNT EQU X'02' *** PAN MAINTENANCE
LIDPATRC EQU X'01' *** Panvalet TRACE ATTRIBUTE
Step 6: Assemble the Interface
After steps 1 through 4 have been completed, run PANAASM in ACF2.CAX1JCL0. This job assembles the interface. Each assembly must have a return code of zero.
Step 7: Link Edit the Interface
After successfully assembling the interface, run PANALINK in ACF2.CAX1JCL0. This job will link the interface into a staging library. Each module linked must have a return code of zero.
After linking the interface, the CA-ACF2 portion of the installation is complete. The balance of the installation consists of defining the interface exits to CA-Panvalet and moving the exits into the CA-Panvalet security exits library. To do this:
- Assemble and link the EXITDEF macro to identify ACFA3MEM as the module to invoke for the $MEM001 event.
- Assemble and link the PVOPT macro to set the installation security code to zero.
- Set the library security code to zero with a ++CONTROL.
- Rebuild each CA-Panvalet library to eliminate any ++SUPPRESS commands.
Administration of the CA-ACF2 CA-Panvalet Interface
To successfully use the interface, the security administrator must understand how to set the privilege attributes for users of CA-Panvalet.
When the suggested default @CFDE definitions are used, various authorities are required to set the attributes described in the Defining the Logonid Attributes section. The relationship between these authorities is described as follows. Under the default definitions, an unscoped security administrator is the only person who can grant the privilege of PANISO. In turn, a user with the PANISO attribute is required to set the PANONE, PANTWO, PANTSO, PANISPF, PANCOMP, PATRACE, and PAMAINT attributes.
This method of setting authority enables the security administrator to delegate authority over the interface to a CA-Panvalet security administrator responsible only for the administration of the interface. If your site requires a different chain of administrative authority, you should define the appropriate CFDE entries rather than using the defaults.
Interface Support
CA-Panvalet provides an appropriate security exit that allows CA-ACF2 to interface with CA-Panvalet.
Disclaimer
A security exposure can still exist in dealing with CA-Panvalet. A table mechanism describes the CA-Panvalet exits. This table and the exit loader can reside on any JOBLIB or STEPLIB DD statement. A user could load an exit table without the $MEM001 exit. This bypasses CA-ACF2 and CA-ACF2 never knows it because CA-Panvalet never takes the exit. This is a design constraint of the current CA-Panvalet exit facility.
A temporary solution is to place the exit table, the exit loader, and the other CA-Panvalet programs into a protected library. Using the CA-ACF2 program pathing facility, you can restrict access to this library through specific execute-only programs.
Environment
Component: ACF2MS
Resolution
-
Feedback
