Writing your own security or transaction link modules for the listener

The listener process provides an exit point for those users who want to write and include a module that performs the following:

Check to indicate whether the expanded security or transaction input format is used
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 or transaction module, you can name it anything you want, as long as you define it in the configuration data set. In previous releases, you needed to name the module EZACICSE; you can still use that module name. You can write this program in COBOL, PL/I, or assembler language, and you must provide an appropriate CICS program definition.

Note: Specify the name of the security or transaction module in the SECEXIT field in Alter or Define. If you do not name the module, CICS assumes you do not have this module. See Figure 2 for more information about this process.

Just before the child server task creation process, the listener invokes the security or transaction 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 or transaction module should perform a security check and set the switch accordingly. Included in this data is the OTE indicator which indicates when the IP CICS socket interface is using CICS's open transaction environment. The security exit should follow threadsafe programming practices to ensure that CICS continues to execute the listener on an open API TCB.

When the security or transaction 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.

A field is supplied to indicate if the expanded security or transaction input format is used. If used, fields also exist for the listener's IP address and port number, a data length field, and a second data area (up to MSGLENTH in length). Table 1 shows the data area used by the security or transaction module.

Table 1. security or transaction exit data
Description	Offset	Format	Value
CICS transaction identifier	0	4-byte character	CICS transaction requested by the client or supplied by the CSTRANID parameter.
Data area	+4	35-byte character	If the FORMAT parameter value is STANDARD, then this contains the 35-byte application data that was extracted from the client's initial data. Otherwise, it contains up to the first 35 bytes of data sent by the client (The MSGLENTH value determines the limit).
security or transaction exit data level	+39	1-byte character	Indicates whether or not this data area is in the expanded format: 1 Expanded format (the area in green is included) 0 Not expanded (the area in green is not included)
OTE indicator	+40	1-byte character	Indicates whether the IP CICS socket interface is using CICS's open transaction environment. 1 Using OTE 0 Using MVS™ subtasks
TTLS indicator	+41	1-byte character	Indicates whether this connection is secured using AT-TLS. 1 This connection is secured using AT-TLS 0 This connection is not secured using AT-TLS
Register Application Data	+42	1-byte character	Indicates that application data is registered against the accepted connection to be given. This flag has the value 1 when either the LAPPLD value is yes or the LAPPLD parameter inherited the APPLDAT=YES specification. 1 Application data is registered 0 Application data is not registered
Reserved	+43	1-byte character	Reserved for IBM® use.
Action	+44	2-byte character	Method of starting the task: IC Interval control KC Task control TD Transient data
Interval control time	+46	6-byte character	Interval requested for IC start. Has the form hhmmss.
Address family	+52	Halfword binary	Network address family. The value contains a 2 to indicate AF_INET and a 19 to indicate AF_INET6.
Client's port	+54	Halfword binary	The number of the requestor's port.
Client's IPv4 address	+56	Fullword binary	The IPv4 address of the requestor's host.
Switch	+60	1-byte character	1 Permit the transaction Not 1 Prohibit the transaction
Switch-2	+61	1-byte character	1 Listener sends message to the client Not 1 security or transaction exit sends message to client
Terminal identification	+62	4-byte character	Return binary zeroes if no terminal is to be associated with the new task. Otherwise, return the CICS terminal ID to be associated with the new task.
Socket descriptor	+66	Halfword binary	Current socket descriptor.
User ID	+68	8-byte character	A user ID can be returned so that it is associated with the new task. This is mutually exclusive from terminal ID. If the GETTID value is YES in the listener definition and the listener is able to obtain the user ID that is associated with the connection client's certificate, then this field is initialized using that user ID. Otherwise, it is initialized as binary zeroes. The security exit can use that user ID to identify the client. If the security exit permits the transaction and does not overwrite this field, then the child server task inherits this user ID (unless the start type is TD). If the security exit overwrites this field with nulls or blanks, then the child server inherits the listener task's user ID (unless the start type is TD). If the security exit overwrites this field with another user ID, then the child server task inherits that user ID (unless the start type is TD). The user ID under which the listener executes must have RACF® surrogate authority to use any user ID that can be specified by this field. See the z/OS Security Server RACF Security Administrator's Guide for details.
Listener's IPv4 address	+76	Fullword binary	The local IPv4 address associated with this new TCP/IP connection.
Listener's port	+80	Halfword binary	The listener's port number.
Listener's IPv6 address	+82	16 bytes binary	The local IPv6 address associated with this new TCP/IP connection.
Listener's scope ID	+98	Fullword binary	The scope ID of the listener's IPv6 address.
Client's IPv6 address	+102	16 bytes binary	The IPv6 address of the requestor's host.
Client's scope ID	+118	Fullword binary	The scope ID of the listener's IPv6 address.
Client's certificate length	+122	Halfword binary	Indicates whether the client's certificate exists.
Client's certificate address	+124	Fullword binary	The address of the client's certificate.
Reserved	+128	34 bytes	Reserved for future use.
Data length	+162	Halfword binary	The length of the data received from the client.
Data area - 2	+164	Length determined by the previous field	The data received from the client starting at position 1. If this is the enhanced listener, the first 35 bytes are the same as Data Area-1.
Note: The security/user exit can change the value of the following fields: CICS transaction identifier Data area Action Register Application Data Interval control time Address family Client's port Client's IPv4 address Switch Terminal identification (output only) User ID Client's IPv6 address Client's Scope ID Data length Data area -2 Although the security exit can alter the contents of the Data area, Data length, and Data area -2 fields when PEEK=YES, the changed values are not reflected to the child server in the listener input data. The child server must read the data itself if the listener is configured with PEEK=YES.

Use the EZACICSX assembler macro contained in the hlq.SEZACMAC dataset to format the security/user exit COMMAREA pass by the listener.