Oracle® Transparent Gateway for DB2 Installation and User's Guide
10g Release 1 (10.1) for IBM z/OS (OS/390)
Part No. B13531-01
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.
The following topics are included:
Starting and stopping the gateway service is accomplished using OSDI operating commands. They are normally issued 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 of the operating commands take a gateway service name as the first positional parameter. This service name must be the name of a defined service.
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 complete syntax of the START command.
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 required cleanup. A force option causes the service address space(s) 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 complete syntax of the STOP command.
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 your 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:
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:
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 userid 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 ar permitted. Oracle Corporation recommends that you define resource profiles for all services so that bind access is controlled via 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"
where ssn is the OSDI subsystem name, service is the target service name (which is the gateway), and a BIND is a constant indicating managed binds.
The Oracle userid and password is 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 userid 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 userid and password using the database link are passed to the gateway for authorization.
When the Oracle gateway receives the userid 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 the database link userid and password is 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 DB2 RRSAF signon processing.
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.
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 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 userid 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
|work area||char/4k||set to all x'00' before every call to the exit|
|userid||char/1+||userid to be validated (number of bytes varies)|
|userid length||bin/2||length of userid|
|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 username (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, TP/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). Avoiding opening data sets, writing to the operator with a reply (WTOR), and creating enqueues.
Any resources that are 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.
Sample Exit Programs are supplied in the
The DB2 RRSAF logon security exit is shipped as an executable called G4RRSAF in the AUTHLOAD library. You need to customize the DLL for your installation. 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.