This document covers the interfaces to the various Security Systems on the market as well as how they interface with the Com-plete Security System. A good understanding of the relevant system is essential as we can only discuss the Com-plete side of the interfaces here. For the purposes of this description, ACF2, RACF and TOP SECRET are known as "external security systems" and Com-plete Security is known as COMSEC. Com-plete also has an interface to the Natural Security system for logon validation.
This information is provided under the following headings:
Through the SECSYS sysparm, you can choose which security system is to be used. The currently available choices are RACF, ACF2, and TOP SECRET, and/or COMSEC.
Com-plete uses the System Authorization Facility (SAF) to interface to the external security system. All logons and logoffs are verified/notified via the external security system and access to data sets is also verified through the specified security system via the SAF interface. Com-plete uses this interface as it is common to all systems, therefore, except for a few small exceptions, the sysparm specification is only used where it is necessary to identify the external security system name.
Com-plete identifies itself as the caller via the SUBSYS keyword on the RACROUTE call. The format of the ID is as follows...
SAGCOMvr
where "vr" is the current Com-plete version release level. This has implications for the various external security systems which are discussed later.
As various users will run within the same address space, the external security system must be aware of that fact (for example, ACF2 must know the Com-plete address space as Multiple User Address Space "MUSASS") otherwise, requests will be given the authority of the actual address space which is normally too high for the general user.
The Com-plete module issuing the SAF requests runs with AMODE=31 and RMODE=ANY. This means that the ACEEs built by the security can exist above the 16 MB line if the external security system supports this.
Com-plete Security holds all information on an Adabas file. When the security system is loaded, the data is stored in tables within the address space to be queried as to the access that a user may have to various resources. Refer to the Com-plete Security documentation for more details on defining access rules.
The only current duplication between these two is access to data sets and system entry validation. The access calls that are made are made to an internal security routine which then calls the various exits or products installed. The application therefore gets no indication of who fails the request, it simply knows that it failed. In the case where both are specified, one OR the other has the chance to fail the request. To avoid unnecessary duplication, you should allow anybody running under that Com-plete have access to the data sets, while using the other system to actually validate the access.
If an external security system is installed, you will have all user IDs defined there. Therefore, the logon request is ignored by Com-plete Security and issued through the external security system.
An interface is also available to the Natural Security System. In this case, if the user ID is not defined to Com-plete, Com-plete checks the user ID and password against the Natural Security System file. If found, the user is logged on with the entered user ID and with a model user ID of "SYSNAT" from the Com-plete user ID file. If the user ID exists, but the password check fails and an external security system has been specified at startup, the password violation is ignored and the password is verified via the external security system.
An interface is also available to the Natural Security System. To use this interface, do not define any user ID in Com-plete. Com-plete will check the user ID and password against the Natural Security System file. If the system finds the user, he is logged on with the user ID that was entered as well as with a model user ID of "SYSNAT" from the Com-plete user ID file; for this to happen SECSYS=NO must be set in the sysparms. If you have defined RACF/TOPSECRET as external security system, another check is made against this if an incorrect password was used or even if NSC returned without errors.
To use this feature of Com-plete, the following steps must be taken.
Add a model user ID SYSNAT using the Com-plete user ID maintenance utility.
Specify the Com-plete sysparms NATSECDB and NATSECFN to identify the Natural Security System file to be used.
If you have defined password rules in Natural Security and use a modified NTSCTAB to include UPPER/LOWER definitions for national characters, you can make Com-plete aware of these definitions using the following steps:
Assemble your modified NTSCTAB into the Com-plete userload.
//JOB JOB
//**********************************************************************
//* *
//* Create module NTSCTAB for Com-plete *
//* *
//* Modify the Dataset names according to your environment *
//* Modify the JOB card according to your standards *
//* *
//**********************************************************************
//ASM EXEC PGM=ASMA90,PARM='OBJECT,NODECK'
//SYSPRINT DD SYSOUT=X
//SYSUT1 DD SPACE=(CYL,(5,2)),UNIT=VIO,DISP=(NEW,PASS)
//SYSLIN DD UNIT=SYSDA,SPACE=(TRK,(30,20),RLSE),
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=400),DISP=(NEW,PASS)
//SYSLIB DD DISP=SHR,DSN=sag.user.source <--- your modified NTSCTAB
// DD DISP=SHR,DSN=sag.nat.source <--- delivered NAT source
//SYSIN DD *
GBLA &CMTABL
&CMTABL SETA 5
CMTABT CSECT
CMTABT RMODE ANY
CMTABT AMODE 31
NTSCTAB ,
END
/*
//LINK EXEC PGM=HEWL,
// PARM='NCAL,RENT,LIST,XREF,LET,MAP,SIZE=(1024K,96K)'
//SYSPRINT DD SYSOUT=*
//SYSLIN DD DSN=*.ASM.SYSLIN,DISP=(OLD,DELETE)
//SYSUT1 DD DSN=*.ASM.SYSUT1,DISP=(OLD,DELETE)
//SYSLMOD DD DISP=SHR,DSN=com.user.load(NTSCTAB) <--- COM userload
/*
The created loadmodule NTSCTAB should be defined as RESIDENTPAGE in the Com-plete sysparms.
As stated previously, Com-plete uses the SAF facility. Therefore, the ACF2 SAF exit must be installed and active on the system. This can be checked by entering the command T C(GSO) followed by LIST OPTS in the TSO ACF command. Options SAF and STC must be specified (they are not specified by default). Please refer to the ACF2 documentation for more information. The user ID assigned to the Com-plete must be defined with the following privileges.
JOBFROM MUSASS NO-SMC STC
For Job Submission, Com-plete inserts the /*JOBFROM control card in the second line to ensure that the Com-plete supplied card is seen first by ACF2. This means that the user does not need to supply a user ID and password in the JCL and it also means that Com-plete does not have to remember the password to insert it for the user.
Assuming that most installations run as advised by the ACF2 installation documentation, the "SAFSAFE" record lets all SAF requests through without checking, as with the following "SAFSAFE" definition.
CLASSES(-) CNTLPTS(-) SUBSYS(-)
the following "SAFPROT" definition is required for Com-plete:
CLASSES(-) CNTLPTS(THREAD-) SUBSYS(SAGCOMvr)
where vr is the current version release for Com-plete.
The SAF interface in ACF2 has changed. You must use ACF2 conversion facilities to switch your old definitions to match the new version (the old definitions can remain, but will be ignored). The following SAFDEF definition is an example of what is required for Com-plete:
SAFDEF COMvr LAST CHANGED BY BHD ON 23/9/97-15:51 FUNCRET(4) FUNCRSN(0) ID (COMvr) MODE(GLOBAL) RACROUTE(SUBSYS=SAGCOMvr REQSTOR=-) RETCODE(4)
As stated previously, Com-plete uses the SAF facility. Standard RACF installation results in the installation of the RACF SAF routines.
No changes to the RACF definition are necessary for Com-plete.
For Job Submission when the USERID and PASSWORD cards are not provided on the Job Card, Com-plete can save both values at your logon and add them to the Job Card to identify the job submitter. If you set applymod 83 to avoid this, the SAF system uses the ACEE of the submitting user.
The following describes the steps required to define Com-plete to a CA-TOP SECRET security system. For the sake of clarity, the following examples do not take advantage of techniques such as the defining of profiles, etc. Where examples are given, you are also referred to the relevant CA-TOP SECRET documentation where you will find more information.
Com-plete is defined as a system facility by CA-TOP SECRET by default. This is described in the TOP SECRET documentation CA-TOP SECRET Implementation: Other Interfaces Guide, section Com-plete. The modifications described in the subsection Required Modifications are no longer necessary, as Com-plete interfaces with TOP-SECRET via the SAF interface as described above. To avoid confusion, an update request for this section has been issued.
You must change this facility definition using the TSS MODIFY FACILITY command to set the following options:
NOABEND TENV
For more information, see the CA-TOP SECRET z/OS Control Options Guide.
You now must create an ACID to identify this Com-plete release and link this ACID to the Facility. The name we have chosen for this ACID is the same as that used for the subsystem name we use on the RACROUTE calls documented previously. This is simply as a naming convention and is not necessary for the operation of this interface. You can choose your own names if you so wish. For our example, the ACID we use is SAGCOMvr (where "vr" is the Com-plete Version and Release). The ACID is created with a TSS command as follows:
TSS CREATE(SAGCOMvr) TYPE(USER) NAME('COMPLETE vr')
DEPT(RDDEPT) PASS(NOPW) FAC(ALL) MASTFAC(COMPLETE)
For more information, see the CA-TOP SECRET z/OS Implementation documentation.
Each Com-plete startup procedure must use the relevant ACID. The ACID that should be used can be identified with the following TSS command:
TSS ADD(STC) PROC(pppppppp) ACID(SAGCOMvr)
where pppppppp is the procedure name.
For more information see the CA-TOP SECRET z/OS Implementation documentation.
Users must then be authorized to logon to Com-plete. This can be done with the following TSS command:
TSS ADD(uuuuuuuu) FAC(COMPLETE)
where uuuuu is the user ID.
For more information see the CA-TOP SECRET z/OS Implementation documentation.
For Job Submission, Com-plete inserts the constant "x'FF',c'TSS'" followed by the address of the user's ACEE in columns 73-80 of the Job Card. In this way, the user does not have to supply a user ID and password in the JCL and it also means that Com-plete does not have to remember the password to insert it for the user.
Unfortunately, the program execution permissions defined in the standard SAF class PROGRAM are not effective under Com-plete, as this class is always checked against the user ID associated with the Com-plete address space, and not against the user ID associated with the subtask at the moment when a program is invoked.
To overcome this limitation, you can either define a separate SAF class, or you can define a special resource dedicated to Com-plete within the PROGRAM class. You then declare both the class name and the resource name to Com-plete, using the sysparm
SECSYS-EXECUTIONCONTROL=(class_name,resource_name)
If this sysparm is present, Com-plete calls SAF for each application invocation, verifying the permissions of the current user in regard to the application being invoked, using the class and resource names as specified.
Verification is performed in the following situations:
Thread initialization. A thread is initialized in the following situations:
a user’s startup program is invoked;
a program is invoked from the Com-pass menu or Com-plete command prompt;
a program is invoked by another program using one of the Com-plete API functions ATTACH or FETCH.
Start of a CGI program via the HTTP server.
Note:
No verification is performed when one program loads or calls
another program.
Class definition:
NODE / CLASMAP.COMPROG
ENTITYLN(0) MUSID() RESOURCE(COMPROG) RSRCTYPE(COP)
NODE / SAFDEF.COMPROG
FUNCRET(4) FUNCRSN(0) ID(COMPROG) MODE(GLOBAL)
RACROUTE(REQUEST=AUTH CLASS=COMPROG) RETCODE(4)
Resource definition:
$KEY(PROGRAM) TYPE(COP) *__ HTML utilities: only JIM and JOE may use them W- UID(****************JIM ) SERVICE(READ) ALLOW W- UID(****************JOE ) SERVICE(READ) ALLOW *___anyone else: no permission - UID(-) SERVICE(READ) PREVENT
Sysparm:
SECSYS-EXECUTIONCONTROL=(COMPROG,PROGRAM)
Adding a SAF class is something one usually tries to avoid because it requires an IPL. But in most cases some existing class like FACILITY or others with a MAXLNTH value (maximum resource name length) of at least 17 can be used, and resources added to it. This is an example for RACF, assuming an existing class MYCLASS:
RDEFINE MYCLASS COMPROG.* OWNER(SECADMIN) UACC(NONE) RDEFINE MYCLASS COMPROG.WCTRL OWNER(SECADMIN) UACC(NONE) PERMIT COMPROG.* CLASS(MYCLASS) ID(ALLUSERS) ACCESS(READ) PERMIT COMPROG.WCTRL CLASS(MYCLASS) ID(ADMINS) ACCESS(READ)
Sysparm:
SECSYS-EXECUTIONCONTROL=(MYCLASS,COMPROG)