CICS TCP/IP Listener CSKL and its security exit

Technote (FAQ)


Question

CICS® TCP/IP Listener CSKL and its security exit

Answer

This entry is to give some background about the security exit of CSKL related
to the IODM and IPFAF.

The CICS TCP/IP Listener sections from the IP CICS Socket Guide (SC31-8518) are
included here provide more details. The section 6.6.3 has information related to the CICS TCP/IP Listener security exit. The table 8 contains the data format received by this exit.

IODM provides a sample program which can be found in SEKCSRC1(EKCCICSE). Its
copy book SEKCCPY1(EKCTSEPM) which defines the DFHCOMMONAREA passed to the exit (see table 8 below). There is a 40 byte field for the client data. In this exit, it calls the IODM
module EKCTSECR (IODM access exit) to validate the IP address in the workstation configuration table by setting the TCSE-PERMIT bit in the DFHCOMMONAREA passed to the EKCTSECR. The EKCCICSE and EKCTSEPM are included at the end of this entry.

IPFAF API does not provide an sample source for this exit. However, the
customer can use the EKCCICSE as a starting point to write their own exit. The statement, CALL 'EKCTSECR' USING DFHEIBLK DFHCOMMAREA, in the EKCCICSE should be removed prior to using.

To find out what client data that WARPI is sending to the IODM or the IPFAF API
region, you need to refer to the WRAPI readme file. I have included a section of this readme file here after the CICS TCP/IP Listener sections. You will notice that byte 5 - 38 of the data stream that WRAPI sends to IODM, the CSKL in the IODM region will pass the data to the listener security exit and you will also notice that byte 3 - 34 of the data stream that WRAPI sends to IPFAF API, the CSKL in the IPFAF API region will pass the data to the listener security exit. Note: IPFAF API region can be IPFAF FWA region.

In a TCP/IP protocol environment, when the WRAPI sends data to the IODM or
IPFAF, it always include the client data and the CSKL transaction in the region always receives it as part of data stream.

The CICS TCP/IP listener security exit can make RACF call to check for the user
ID and password or check any tables maintained by the IODM or the IPFAF.

The IPFAF API RAPI Configuration Table (EYPTCFG) has an field for the WRAPI
authorization exit. The exit name is EYPRAZU. The sample code is in SEYPMAC9(EYPRAZU). The common area used by this exit has more information relate to the IPFAF. Therefore, it can be used for IPFAF API relatedaccess/control.

Attachments:

OS/390 eNetwork Communications Server: IP CICS Sockets Guide SC31-8518-00
ƒ Copyright IBM Corp. 1994, 1998

Version 6.6 The Listener
ƒ Copyright IBM Corp. 1994, 1998

In a CICS system based on SNA terminals, the CICS terminal management
modules perform the functions of a concurrent server. Because the TCP/IP
interface does not use CICS terminal management, CICS TCP/IP provides
these functions in the form of a CICS application transaction, the
Listener. The CICS transaction ID of the Listener is CSKL.

The Listener performs the following functions:

1. It issues appropriate TCP/IP calls to "listen" on the port specified
in the Configuration file and waits for incoming connection requests
issued by clients. The port number must be reserved in the
hlq.TCPIP.PROFILE.

2. It registers and deregisters with WLM for load balancing in a sysplex
environment.

* WLM registration is performed immediately after the listener
socket is activated. It is performed by invoking EZACIC12, which
checks the Configuration File record for the presence of WLM Group
Names and performs registration for those groups specified.

* WLM deregistration is performed for any of the following
conditions:

- Request of a Listener Quiesce, either via an EZAO STOP or a
CEMT PERFORM SHUTDOWN command. In this case, deregistration is
done when the listening socket is closed.

- Request for an Immediate Shutdown via an EZAO STOP. In this
case, deregistration is done when the listener detects the
request.

- Abnormal termination of the listener:

- Fatal error related to the listening socket.

- Abend of the subtask.

- CICS immediate termination.

- CICS Abend.

In these cases, deregistration is done when the listener
detects the error:

3. When an incoming connection request arrives, the Listener accepts it
and obtains a new socket to pass to the CICS child server application
program.

4. It starts the CICS child server transaction based on information in
the first message on the new connection. The format of this
information is given in "Listener Input Format" in topic 6.6.1.

5. It waits for the child server transaction to take the new socket and
then issues the close call. When this occurs, the receiving
application assumes ownership of the socket and the Listener has no
more interest in it.

The Listener program is written so that some of this activity goes on in
parallel. For example, while the program is waiting for a new server to
accept a new socket, it listens for more incoming connections. the
process of starting 49 child servers simultaneously. The starting process
begins when the Listener accepts the connection and ends when the Listener
closes the socket it has given to the child server.

6.6.1 Listener Input Format
ƒ Copyright IBM Corp. 1994, 1998

The Listener requires the following input format from the client in its
first transmission. The client should then wait for a response before
sending any subsequent transmissions. Input can be in uppercase or
lowercase. The commas are required.

>>--tran--,--│----------------│--,--│----│--,--│--------│---------------><
                   │-client-in-data-│     │-IC-│     │-hhmmss-│
                                                   │-ic-│
                                                   │-TD-│
                                                   │-td-│

tran
The CICS transaction ID (in uppercase) that the Listener is going to
start. This field can be 1 to 4 characters.

client-in-data
Optional. Application data, used by the optional security exit (9)

or the server transaction. The maximum length of this field is 35
characters.

IC/TD
Optional. Startup type that can be either IC for CICS interval control
or TD for CICS transient data. These can also be entered in lowercase
(ic or td). If this field is left blank, startup is immediate.

hhmmss
Optional. Hours, minutes, and seconds for interval time if the
transaction is started using interval control. All 6 digits must be
given.

Note: TD ignores the timefield.

(9) (See "Writing Your Own Security Link Module for the
Listener" in topic 6.6.3)

6.6.1.1 Examples
ƒ Copyright IBM Corp. 1994, 1998

The following are examples of client input and the Listener processing
that results from them. The data fields referenced can be found in
"Listener Output Format" in topic 6.6.2. Note that parameters are
separated by commas.

Sample Listener Response
TRN1,userdataishere It starts the CICS transaction TRN1 using task control, and passes to it the data userdataishere in the filed CLIENT-IN-DATA.
TRN2,,IC,000003 It starts the CICS transaction TRN2 using interval control, without user data. There is a 3-second delay between the initiation request from the Listener and the transaction startup in CICS.
TRN3,userdataishere It writes a message to the transient data queue named TRN3 in the format described by the structure TCPSOCKET-PARM, described in "Listener Output Format" in topic 6.6.2. The datacontained in userdataishere is passed in this field CLIENT-IN-DATA.  This queue must be an intrapartition queue with trigger-level set to 1.  It causes the initiation of the transaction TRN3 if it is not already active. This transaction should be written to read the transietn data queue and process requests until the queu is empty.

This Mechanism is provided for those servers transactions that are used very frequently and for which the overhead of initiating a separate CICS transaction for each server request could be a performance concern.
TRN3,,TD It causes data to be placed on transient data queue TRN3, which in turn causes the start or continued processing of the CICS transaction TRN3, as described in the TRN3 previous example. There is no user data passed.
TRN4 It starts the CICS transaction TRN4 using task control. There is no user data passed to the new transaction.


 
   

6.6.2 Listener Output Format
ƒ Copyright IBM Corp. 1994, 1998

Table 7 shows the format of the Listener output data area passed to the
child server. The Listener program uses the following COBOL definition:

01 TCPSOCKET-PARM.
05 GIVE-TAKE-SOCKET PIC 9(8) COMP.
05 LSTN-NAME PIC X(8).
05 LSTN-SUBNAME PIC X(8).
05 CLIENT-IN-DATA PIC X(35).
05 FILLER PIC X(1).
05 SOCKADDR-IN-PARM.
15 SIN-FAMILY PIC 9(4) COMP.
15 SIN-PORT PIC 9(4) COMP.
15 SIN-ADDRESS PIC 9(8) COMP.
15 SIN-ZERO PIC X(8).


Table 7. Listener Ouput Format

Description Format Value
Socket Descriptor Fullword binary The socket descriptor to be used by the child server in the TAKESCOCKET command
z/OS Address space identifier 8-byte character space Name of the Listener's address
TCP/IP task identifier 8-byte character space Listener's task identifier
Data area 35-byte character plus 1-byte filler Client-indata from Listener input received from the client.
Socket Address Structure containing remaining 4 fields See ach field
TCP/IP addressing family Halfword binary 2, indicating AF-INET
Port descriptor Halfword binary Descriptor of the port bound to the socket (Listener's port number from CSYS).
32 bit IP address Fullword binary IP address of the socket's host machine network byte order.
Unused Doubleword Binary zeros


6.6.3 Writing Your Own Security Link Module for the Listener
ƒ Copyright IBM Corp. 1994, 1998

The Listener process provides an exit point for those users who want to
write and include a module that performs a security check before a CICS
transaction is initiated. The exit point is implemented so that if a
module is not provided, all valid transactions are initiated.

If you write a security module, you can name it anything you want, as long
as you define it in the configuration dataset. (In previous releases, you
needed to name the module EZACICSE; you can still use that module with
this release). You can write this program in COBOL, PL/I, or assembler
language and must provide an appropriate entry in the CICS program
processing table (PPT).

Specifying in EZAC: Specify the name of the security module in the
SECexit field in Alter or Define. If you don't name the module,
CICS will assume you don't have one. See Figure 48 in topic 2.5.2.1
for more information.

Just before the task creation process, the Listener invokes the security
module by a conditional CICS LINK passing a COMMAREA. The Listener passes
a data area to the module that contains information for the module to use
for security checking and a 1-byte switch. Your security module should
perform a security check and set the switch accordingly.

When the security module returns, the Listener checks the state of the
switch and initiates the transaction if the switch indicates security
clearance. The module can perform any function that is valid in the CICS
environment. Excessive processing, however, could cause performance
degradation.

Table 8 shows the data area used by the security module.

Table 8. Security Exit Data

Description Format Value
CICS transaction identifier 4-byte character CICS transaction requested by the client.
Data area 40-byte character User data received from the client
Action 2-byte character Method of starting the task:
IC Interval control
KC Task control
TD Transient data
Interval control time 6-bytes character Interval request for the IC start has the form hhmmss
Address family Halfword binary Network address family. A valoe 2 must be set.
Port Halfworld binary Th port number of the requestor's port.
Address Fullword binary The IP address of the requester's host.
Switch 1-byte character Switch:
1 Permit the transaction
Not 1 Prohibit the transaction
Switch-2 1 byte character Switch:
1 listener sends message to client.
Not 1 Security Exit program sends message to client.
Terminal identification 4-byte character LOW-VALUES and binary zeros if a CICS terminal is not associated with the new task.

CICS terminal identifier if a CICS terminal is associated with the new task.
Socket descriptor Halfword binary Current socket descriptor
User ID 8-byte character User who have CICS/ESA V4 and later can return a USERID value which is used in starting th eserver transaction. This enables the CICS V4+ security features.

                                                                                   
     


ftp://public.dhe.ibm.com/ps/products/imageplus/fixes/wrapi/fix0999/Readme.txt

The following describes the data which is sent to the host CICS TCPIP
Listener program by the WRAPI calls. The IODM information has not been
changed by this update, but is included for completeness. This information
is needed for those customers who are supplying a security exit for the
CICS TCPIP Listener.

IODM

Bytes 0 - 3 Host Transaction name to start
(i.e. "SRET")
Byte 4 A comma
(i.e. ",")
Bytes 5 - 6 A flag to indicate WRAPI ("01") versus IWP ("00")
(i.e. "01")
Bytes 7 - 14 The IODM Terminal Id (max 8 characters) padded with blanks
(i.e. "TERMID ")
Bytes 15 - 22 The IODM User Id (max 8 characters) padded with blanks
(i.e. "USERID ")
Bytes 23 - 30 The IODM Password (max 8 characters) padded with blanks
(i.e. "PASSWORD")
Bytes 31 - 38 The New IODM Password (max 8 characters) padded with blanks.
This will only be sent on the "STAT" transaction which is
sent when a FafSessionConnect() API is called. In all
other cases, these bytes are not sent.
(i.e. "NEWPSWD ")
IPFAF

Bytes 0 - 3 Host Transaction name to start
(i.e. "RAP1")
Byte 4 A comma
(i.e. ",")
Bytes 5 - 6 The FAF Application Id as a number (NOT EBCDIC)
(i.e. 01)
Bytes 7 - 14 The FAF User Id (max 8 characters) padded with blanks
(i.e. "USERID ")
Bytes 15 - 34 The FAF Password (max 20 characters) padded with blanks
(i.e. "PASSWORD")

'ODM310.SEKCSRC1(EKCCICSE)'

BROWSE ODM310.SEKCSRC1(EKCCICSE) - 01.57 Line 00000125 Col
Command ===> Scroll ==
011400
011500 L I N K A G E S E C T I O N
011600
011700 LINKAGE SECTION.
011800 01 DFHCOMMAREA.
011900 SECURITY EXIT COMMAREA PASSED FROM CSKL
012000 COPY EKCTSEPM.
012100
012200 P R O C E D U R E D I V I S I O N
012300
012400 PROCEDURE DIVISION.
012500 100-MAINLINE.
012600
012700 Call EKCTSECR (ODM Access Exit)
012800
012900
013000 CALL 'EKCTSECR' USING DFHEIBLK DFHCOMMAREA.
013100

'ODM310.SEKCCPY1(EKCTSEPM)'

000010 00001013
000020 00002016
000030 NAME: EKCTSEPM 00003013
000040 00004013
000050 STATUS: VERSION 3 RELEASE 1 00005013
000060 00006013
000101 THIS COPYBOOK MAPS DFHCOMMAREA AS PASSED TO THE CICS 00010113
000102 TCP/IP SECURITY EXIT (EZACICSE) FROM EZACIC02 (CSKL). 00010213
000103 THIS IS DESCRIBED ON PAGE 62 OF THE CICS TCP/IP 00010313
000120 SOCKET INTERFACE GUIDE AND REFERENCE (SC31-7131-02). 00012013
000121 00012113
000122 00012213
000200 05 TCSE-TRAN PIC X(04). 00020000
000201 00020113
000210 CICS SAYS 40 BYTES GETS PASSED TO EZACICSE, BUT 00021013
000211 ONLY 35 BYTES GETS PASSED IN THE USER AREA TO THE 00021114
000220 CHILD SERVER ON THE START TRANSACTION...SO DO NOT 00022014
000221 CONFUSE THIS MAPPING WITH THE MAPPING ON PAGE 61. 00022114
000230 00023013
000300 05 TCSE-USERDATA. 00030004
000310 10 TCSE-USER-APID PIC X(2). 00031003
000311 00031113
000312 THE FOLLOWING FIELDS, USER-USERID, USER-PASS, 00031213
000313 AND USER-FILLER ARE RESERVED FOR FUTURE USE 00031313
000314 BY IODM. 00031413
000315 10 TCSE-USER-TERMID PIC X(8). 00031515
000316 10 TCSE-USER-USERID PIC X(8). 00031615
000317 10 TCSE-USER-PASS PIC X(8). 00031712
000318 10 TCSE-USER-NEW-PASS PIC X(8). 00031815
000320 10 TCSE-USER-FILLER PIC X(6). 00032015
000330 00033013
000400 05 TCSE-ACTION PIC X(02). 00040000
000410 05 TCSE-ICTIME PIC X(06). 00041000
000420 05 TCSE-AFNET PIC X(02). 00042001
000421 05 TCSE-CLIPORT PIC X(02). 00042101
000430 05 TCSE-IPADDR PIC 9(08) BINARY. 00043007
000431 05 TCSE-IPADDR-HEX REDEFINES 00043103
000432 TCSE-IPADDR PIC X(04). 00043203
000440 05 TCSE-PERMIT PIC X(01). 00044000
000450 05 TCSE-MSGSEND PIC X(01). 00045000
000460 05 TCSE-TERMID PIC X(04). 00046000
000500 05 TCRO-SOCK-DESC PIC 9(04) BINARY. 00050000

Rate this page:

(0 users)Average rating

Document information


More support for:

DB2 ImagePlus for z/OS
OS/390 Server

Software version:

3.1.0

Operating system(s):

OS/390

Reference #:

1002636

Modified date:

2011-06-21

Translate my page

Machine Translation

Content navigation