7 Administering the Gateway

This chapter describes the basic administration tasks for Oracle Transparent Gateway for DB2, including implementing security strategies and enabling diagnosis and error reporting. Refer to Appendix A, "OSDI Subsystem Command Reference", for the subsystem administration tasks requiring OSDI commands and parameters.

This chapter includes the following sections:

Operation of the Gateway Subsystem with OSDI
Controlling Access to OSDI Subsystem Commands
Controlling Access to OSDI Services
Gateway Security
SAF Router Considerations
Gateway User Exit Facility
Sample Exit Programs

7.1 Operation of the Gateway Subsystem with OSDI

Starting and stopping the gateway service is accomplished by using OSDI operating commands . They are normally issued by using a z/OS system operator command interface. The target subsystem is specified by using the command prefix associated with the subsystem, or the subsystem name. All the operating commands take a gateway service name as the first positional parameter. This service name must be the name of a defined service.

START

The START command initiates execution of an address space for a specified service. For a gateway service, the service must not already be running.

The command structure for starting a gateway service is shown in the following example:

/ssn START name [ PARM( string ) ]

Refer to Appendix A, "OSDI Subsystem Command Reference" for the complete syntax of the START command.

STOP

The STOP command requests termination of a running service. The normal mode of stop changes the service state to stopping and posts the stop request to the service; it is up to the service to comply, presumably after allowing current requests to complete and performing the required cleanup. A force option causes the service address spaces to be terminated involuntarily. The force form of stop requires that a normal stop be issued first. This command has no effect when the service is not running.

The command structure for stopping a service is shown in the following example:

/ssn STOP name [ FORCE ]

Refer to Appendix A, "OSDI Subsystem Command Reference" for the complete syntax of the STOP command.

7.2 Controlling Access to OSDI Subsystem Commands

OSDI subsystem command processing includes an authorization check to confirm that the console or the user is allowed to issue the command. You control access to commands by defining resource profiles to the security subsystem and then by granting access (for specific consoles and users) to those resources. If you do not define resource profiles, then the authorization check returns a "resource unknown" indication to OSDI, and OSDI then allows the command to be processed. Thus, the default behavior (in the absence of any profile definitions) is that any command is allowed from any source. This is not chaotic, as it may sound, because access to command-issuing mechanisms themselves (such as consoles) is usually controlled in most z/OS installations. Base your decision to define profiles and to activate the authorization mechanism upon the security standards and procedures at the installation.

The resource profiles that are used to protect commands should be defined in the resource class that you specified in the cmd-class field of the INIT record in the subsystem parameter file. If you elected to accept the default, then this will be the FACILITY class. Otherwise, it will be a class name that you chose and configured for your SAF-compliant security software.

The command authorization resource names are of the form:

ssn.cmdverb

where ssn is the OSDI subsystem name, and cmdverb is the full-length OSDI command verb. (Verb abbreviations, such as DEF and ALT, must not be used in the resource name.)

The level of authorization that must be granted to users or to consoles in order to enable commands depends on the command. The following table lists all of the command verbs and the authorization level required for each:

Table 7-1 Command Verbs and their Authorization Level

Verb	Authorization Level
`DEFINE`	Update
`ALTER`	Control
`SHOW`	Read
`START`	Read
`DISPLAY`	Read
`DRAIN`	Read
`RESUME`	Read
`STOP`	Read

7.3 Controlling Access to OSDI Services

OSDI bind processing, which establishes connections between z/OS address spaces, performs an authorization check to confirm that the binding address space (the "client") is allowed to access the target service.

In the case of Oracle gateways, the only potential sensible case is that "the client" is the OSDI integrating database server and the target service is the Oracle gateway.

In order for the check for a given target service to be meaningful, resource profiles must be defined to a SAF-compliant security server, such as RACF. The profile names incorporate the OSDI service name so that access to each service is separately controlled. When profiles are defined, the z/OS user ID that is associated with the client address space must have READ authorization on the target service's profile in order for the bind to be allowed.

If you do not define resource profiles for a service, then all binds from all address spaces are permitted. Oracle Corporation recommends that you define resource profiles for all services so that bind access is controlled through standard z/OS security mechanisms.

The resource profiles that are used to protect binds should be defined in the resource class that you specified in the bind-class field of the INIT record in the subsystem parameter file. If you elected to accept the default, then this will be the FACILITY class. Otherwise, it will be a class name that you chose and configured for your SAF-compliant security software.

The name structure for the managed binds used by Oracle database links is:

ssn.service.BIND

where ssn is the OSDI subsystem name, service is the target service name (which is the gateway), and BIND is a constant indicating managed binds.

7.4 Gateway Security

The Oracle user ID and password are passed over the database link to the gateway to authorize gateway users to DB2 objects. If the CONNECT TO clause is specified when creating the database link, then the user ID and password sent to the gateway are those specified in this clause. If the CONNECT TO clause is omitted from the database link specification, then the Oracle user ID and password using the database link are passed to the gateway for authorization.

When the Oracle gateway receives the user ID and password from the database link, a security environment is established that is local to the z/OS and DB2 systems. The following steps occur when establishing a gateway security environment:

A gateway security user exit is called by the gateway to verify that the database link user ID and password are valid for z/OS and to set up the security environment for the gateway. The sample user exit delivered with the gateway is called G4RRSAF. One of the tasks of G4RRSAF is to create an ACEE for the current TCB that contains the DB2 primary and secondary authorization ids. This is used by the DB2 RRSAF signon processing.
The gateway initiates a connection to DB2 by using a DB2 RRSAF SIGNON .

The remaining sections of this chapter provide more specific information about gateway security, including:

z/OS Security Authorization Facility (SAF) considerations
Gateway User Exit Facility

7.5 SAF Router Considerations

The gateway uses the SAF router to validate userids and passwords. It is also used to check user access to the DB2 security profile, with CLASS set to DSNR and ENTITY set to db2_subsys.BATCH. The DB2 security profile is optional.

Security environments using the SAF interface include ACF2, RACF, and TOP SECRET. If your local security environment does not use the SAF interface, then your system programmer can replace the SAF calls where appropriate.

7.6 Gateway User Exit Facility

The gateway user exit facility provides gateway installations with a mechanism for passing control to installation-written code at user logon time.

The user exit module is not part of the gateway or OSDI. It is a z/OS load module (exit module). During OSDI startup, these user exit modules are loaded by OSDI dynamically into the gateway address space from one of these locations:

The OSDI STEPLIB
The system linklist (LNKLST00)

7.6.1 Specifying an Exit Module

Exit modules are specified to the gateway with the gateway region parameter, LOGON_AUTH, which is accessed at OSDI initialization time:

LOGON_AUTH(name)

where name is the exit module member name. G4RRSAF is supplied to provide the standard SAF security check.

To display the status of an EXIT, use the OSDI DISPLAY EXIT command.

The logon exit must reside in the STEPLIB or JOBLIB concatenation or in the linklist, and it must be in an authorized library.

A sample user logon exit is provided in oracle_hlq.SRCLIB library member G4SIGNON. It uses the z/OS SAF interface to invoke the z/OS security manager. If the z/OS security manager does not support the SAF interface, then the calls to RACROUTE in the exit must be replaced with the equivalent calls appropriate for the z/OS security manager.

The calling sequence for the logon exit uses standard z/OS assembler calling conventions. R15 is the entry point, R14 is the return address, R13 points to a standard 72-byte save area, and R1 is the address of a parameter list. The parameter list consists of a list of addresses of each parameter (all values are passed by reference, not by value), and the last parameter has the high-order bit set.

When returning, R15 should be set to 0 to indicate a successful verification of the user ID and password that were supplied, and should be set to any nonzero value to indicate any type of failure (4 would be an appropriate value).

The exit is called in 31-bit addressing mode, supervisor state, storage protection key 7, and in an authorized address space. The exit will be running in TCB mode with no locks held and with no ARRs, FRRs, or EUT-style FRRs set. The exit is called in primary addressing mode with HASN=PASN=SASN (home, not cross-memory mode).

The logon exit should be fully reentrant code.

The parameter list that is passed contains pointers to the following parameters, all of which are input only:

Table 7-2 Gateway Region Parameters

Field	Type/Length	Description
work area	char/4k	set to all x'00' before every call to the exit
userid	char/1+	user ID to be validated (number of bytes varies)
userid length	bin/2	length of user ID
password	char/1+	password to be validated (number of bytes varies)
password length	bin/2	length of password
z/OS jobname	char/8	z/OS jobname from JOB card of client
ASID	bin/2	address space id of client address space
OSDI session id	bin/4	a unique OSDI session id
OS username	char/8	the operating system user name (batch, TSO, CICS, and IMS only)
terminal name	char/8	terminal name
program name	char/8	program name
RACF group name	char/8	RACF group name
connection type	char/8	connection type (BATCH, TSO, CICS, IMS, TCP/IP, VTAM) to indicate environment of client
JES jobid	char/8	JES job identifier (such as JOB08237)
job card entry time	bin/4	entry (submission) time of job. Binary hundredths of a second since midnight
job card entry date	packed/4	entry (submission) date of job. Packed decimal 0CYYDDDF, where C-0 for 19, C=1 for 20, YY=year, DDD=day number within the year (Jan 1=1)
job card accounting info	char/145	from jobcard
network data (high bit set in parameter list)	char/2+	variable length NIV data (refer to Chapter 9, "Oracle SMF Data")

The only output of the logon exit is the R15 return code. No other value that is passed in the parameter list should be modified except the first one.

The first parameter is a 4096-byte work area that is set to all x'00' before every call to the logon exit. The logon exit can use this storage for anything that it needs. It should not be freed.

The logon exit can do any of the following:

call a security manager (SAF calls, RACF, Top Secret, ACF2, and so forth)
get and free storage using the STORAGE macro (the exit must keep track of all acquired storage and must make certain to free it before exiting)
call SMF to write SMF records
call WTO to write messages to the console

The logon exit should not do anything that would cause it to wait for any significant period of time (more than one-tenth of a second, for example). Avoid opening data sets, writing to the operator with a reply (WTOR), and creating enqueues.

Any resource that is acquired in the logon exit must be freed before it returns. There is no cleanup call made to the logon exit, so any resources that are not released will accumulate in the address space and could eventually cause resource shortages.

7.7 Sample Exit Programs

Sample Exit Programs are supplied in the oracle_hlq.SRCLIB data set.

The DB2 date exit is called DSNXVDTX. The sample JCL to assemble and link it is called XVDTXCL.

The DB2 RRSAF logon security exit is shipped as an executable called G4RRSAF in the AUTHLOAD library. If you need to customize the exit for the installation, then the source needed to build G4RRSAF is called G4SIGNON in the oracle_hlq.SRCLIB data set. The JCL to assemble and link G4SIGNON is in SIGNONCL.