The SSL/SSLI line driver's are the security code provided with Encryption for Entire Net-Work on the mainframe. It includes SSL/SSLI DRIVER and LINK statements.
This document covers the following topics:
The SSL/SSLI DRIVER statement has the syntax shown below. The SSLCAFIL, SSLVRF, and SSLVRS parameters must be specified to correctly implement Encryption for Entire Net-Work.
The DRIVER statement parameters are read from a sequential file during system startup, and can be modified after startup using the ALTER operator command. Some parameters can be modified when the line driver is open or closed. Others can be modified only when the line driver is closed. Read about the ALTER and CLOSE commands in Operator Commands. The open/closed requirement for each parameter is included in the parameter descriptions.
This section describes all of the parameters that can be used for the SSL DRIVER statement.
This optional parameter determines whether the line driver will accept connections from systems that have not been previously defined with LINK statements. The ACCEPTUI parameter can be modified when the line driver is open or closed.
Valid values are "Y" (Yes) or "N" (No).
If "Y" is specified, Entire Net-Work will accept connection requests from an undefined system and the required control blocks are built dynamically. Normal handshaking procedures with the new connections are performed. This is the default.
If "N" is specified, Entire Net-Work will reject incoming requests from unknown source nodes.
This required parameter specifies the name of the TCP/IP application program interface being used. The API parameter can be modified only when the line driver is closed. Supported values are shown in the table below. There is no default.
| Value | Description | Valid for Platforms |
|---|---|---|
| OES | Loads the IBM OpenEdition sockets interface NWTCPOES. | z/OS |
Note:
At this time the API parameter must be set to
"OES" for z/OS systems (this is the default)
.
This optional parameter specifies debugging trace levels. It is a series of flags that are passed to the API routine, which then determines the events to be traced. The APITRACE specification must be enclosed in parentheses. For example:
APITRACE=(N,N,N,N,N,N,N,N,N,N)
Trace levels are positional within the parameter syntax-example and are set using "Y" (Yes) and "N" (No). It is recommended that all flags remain set to N, the default value. If your system is experiencing problems, contact your Software AG technical support representative for the settings that will produce the appropriate trace information. The APITRACE parameter can be modified when the line driver is open or closed.
This optional parameter specifies the number of connect queue entries. The value specified must accommodate the maximum number of simultaneous connection requests from remote nodes.
After the connection is accepted or rejected, connect queue entries are reused. If the value of this parameter is not high enough, the API routine is not able to process the incoming connection and the partner will eventually time out. Depending on the API being used, a message may be displayed indicating that an error has occurred. Values can range from 1 to 64; a value greater than 64 is reset to 64. The default value is 10. The CONNQUE parameter can be modified only when the line driver is closed.
This optional parameter specifies the special character used to designate that an operator command should be directed to this line driver rather than to a specific link. The DRVCHAR parameter can be modified only when the line driver is closed.
The default for this parameter is "#".
This optional parameter specifies the 4-byte driver name. The DRVNAME parameter can be modified only when the line driver is closed.
The default for this parameter is the "Driver name".
The DRVNAME parameter enables sites to make multiple TCP/IP API routines available at the same time. For example, the IBM APIs can be made available within the same Entire Net-Work address space. This parameter also allows two or more drivers to be defined so that Entire Net-Work can listen on multiple ports simultaneously.
This optional parameter allows you to maintain connections when there is no other traffic with the remote links. Valid values are "Y" or "N".
When this value is set to "Y", it causes internal TCP messages to be sent periodically to all remote links, thus maintaining the connections when there is no other traffic with the remote links. The amount of time between messages is determined by an initialization parameter in the TCP stack.
When this value is set to "N", internal TCP messages are no longer sent periodically and the connections are not maintained.
The default for this parameter is "N".
KEEPALIV can also be set for individual remote links. For more information, read about the KEEPALIV parameter associated with the SSL LINK statement.
This optional parameter determines whether a connect request from a host that has an active connection is treated as a new link. This parameter can be modified when the line driver is open or closed.
A value of "Y" indicates that the connect request is treated as a new link; a value of "N" indicates that the connect request is rejected. The default for this parameter is "Y".
This parameter specifies the estimated maximum number of concurrently active clients. For performance reasons, a table of individual client entries is preallocated based on this number. During the Entire Net-Work session, if the number of active clients is exceeded, the table is automatically expanded by 50% of the current value. The size of each entry in the table is 256 bytes. The minimum value is 10; the maximum is 32767. The default is 100.
This parameter can only be altered when the driver is closed.
This optional parameter determines whether statistics are printed. It does not affect the STATS command and can be modified when the driver is open or closed.
A value of "Y" indicates that statistics should be printed to DDPRINT when the statistics interval expires; a value of "N" indicates that the statistics should not be printed. The default for this parameter is "N".
This optional parameter specifies the retry interval in seconds (interval) and the number of retries (retries) that Entire Net-Work will attempt to reopen the access method with the API after a shutdown due to a failure. The RESTART parameter can be modified when the line driver is open or closed.
If RESTART is not specified, or interval is specified as zero, no retry is attempted. By specifying (retries) as zero, an infinite number of retries can be requested.
The RESTART parameter is particularly useful with Encryption for Entire Net-Work when Entire Net-Work is started at IPL and communication with the API is unsuccessful because TCP/IP is not yet fully initialized. Using this parameter, you can instruct Entire Net-Work to reopen the TCP/IP session, thereby giving TCP/IP sufficient time to become active.
The TIMER parameter on the NODE statement affects the RESTART parameter (read about the NODE statement in your Entire Net-Work reference documentation.) The retry interval should not be less than the TIMER parameter, and should be a multiple of this value. If a retry interval other than zero is specified that is less than the value of the TIMER parameter, the TIMER value is used instead.
This optional parameter determines whether statistics are reset. It can be modified when the line driver is open or closed.
A value of "Y" indicates that statistics should be reset when the statistics interval expires; a value of "N" indicates that the statistics should not be reset. The default for this parameter in "N".
This optional parameter specifies a well-known port number used by Entire Net-Work while awaiting connection requests from participating Entire Net-Work partners. Values may range from 1 to 65535. The SERVERID parameter can be modified only when the line driver is closed.
When specified in a DRIVER statement, the SERVERID parameter specifies the port number of the Entire Net-Work being initialized. If SERVERID is not specified for a link, the SERVERID specified for the driver is used as the default port for the link.
The default for this parameter is 1996. Only the DRIVER statement has a SERVERID parameter.
This optional parameter specifies the amount of time, in seconds, before statistics are automatically printed or reset. The default is "3600". The STATINT parameter can be modified when the line driver is open or closed.
Acceptable values range from 1 to 2147483647. Any value outside this range is in error.
This parameter specifies the name of the subsystem to be accessed by the API routines that use subsystem control blocks in interaddress space communications. The default value is "VMCF". The SUBSYS parameter can be modified only when the line driver is closed.
In a z/OS environment, the IBM API routines communicate to the system address space by locating the subsystem control table and retrieving the information required to perform cross-memory communication. If the subsystem is specified incorrectly, the driver is not able to perform its open processing and no connections are possible.
This parameter indicates whether tracing for this line driver should be active "Y" or not "N". When tracing is activated, trace information is placed in the trace table. The default is "N" (No). The TRACE parameter can be modified when the line driver is open or closed.
This is equivalent to specifying
TRACE=linedriver-code or
TRON=linedriver-code in the NODE
statement (for example, TRACE=SSL).
This optional parameter specifies the levels of tracing that the line driver will perform. It is a series of flags that determine which events are traced. The TRACELEV specification must be enclosed in parentheses. For example:
TRACELEV=(N,N,N,N,N,N,N,N,N,N)
Trace levels are positional within the parameter syntax and are set using "Y" (Yes) or "N" (No). It is recommended that all settings within the TRACELEV parameter be "N". If your system experiences problems, contact your Software AG technical support representative for the settings that produce the appropriate trace information. The TRACELEV parameter can be modified when the line driver is open or closed.
Note:
The tracing information provided is sent to the DDPRINT data
set. In addition to setting the TRACELEV flags, the trace must also be turned
on using either the DRIVER statement parameter TRACE=Y or the operator command
TRACE=linedriver-name. Tracing
dramatically affects the overall performance and throughput of Entire Net-Work.
This optional parameter specifies the size, in bytes, of the driver-specific trace table. It can be modified only when the line driver is closed.
This parameter is also used as the default size of the link specific trace table when the LINK statement does not include a TRACESIZ specification.
Valid values can range from 4096 to 4194304. A value less than 4096 is reset to 4096; a value greater than 4194304 is reset to 4194304. The default for this parameter is "4096".
This parameter's value can be modified only when the line driver is closed. It has two possible specifications:
For IBM APIs (i.e., the NWTCPIBM interface, the NWTCPHPS interface, the NWTCPOES interface, and the NWTCPCMS interface), the USERID parameter specifies the name of the started task, job, or virtual machine in which the IBM TCP/IP protocol stack is running. The value is 1-8 characters. The default value is "TCPIP".
For the CNS API (i.e., the NWTCPCNS interface), the USERID parameter is used to direct traffic to a particular TCP/IP stack. The value is a two-digit number that must match the ID= value in the PARM field of the TCP/IP stack. The default value is 00, which is also the default for the TCP/IP stack. The value of USERID is not validated; if its value does not match the ID= value of an active TCP/IP stack, the TCP/IP driver will fail to open and it will return messages similar to the following:
NETP571W TCP API ERROR ON OPEN - RC = 0008 NET0101I TCPI DRIVER OPEN FAILED - RC = 0004
To use multiple TCP/IP stacks, one DRIVER statement must be provided for each stack, and each link must specify the driver associated with the stack it will use. When defining multiple drivers, copy the module NETTCPI.phase and change the last four characters of the name to match the DRIVER name. For example, to define the following, NETTCPI would be copied (not renamed) to NETTCP2:
*Links using Driver TCPI use TCP/IP stack with ID=00 DRIVER TCPI API=CNS LINK PC01 TCPI,INETADDR=(x,x,x,x) *Links using Driver TCP2 use TCP/IP stack with ID=02 DRIVER TCP2 API=CNS,USERID=02,DRVNAME=TCP2 LINK PC02 TCP2,INETADDR=(x,x,x,x)
The LINK statement and its parameters are used to define the characteristics of the remote client. With Encryption for Entire Net-Work, links are not normally predefined; they are dynamically allocated as clients initiate communication. However, links may be predefined to override defaults or provide some control over clients.
The LINK statement parameters are read from a sequential file during system startup, and can be modified after startup using the ALTER operator command. Some parameters can be modified when the link is open or closed. Others can be modified only when the link is closed. Read about the ALTER and CLOSE commands in Operator Commands. The open/closed requirement for each parameter is included in the parameter descriptions.
The linkname part of this required specification provides the name by which this link is to be known. It is positional, and must be specified immediately after the LINK keyword and immediately before the driver name ("SSL"); the link name must be unique on the node. All operator commands affecting the link must specify this name.
If the link name begins with the characters "MODEL", the link is defined as a model link. See the section Model Links.
"SSL" is required and specifies the protocol name that defines the driver associated with this link. It must be the same as the value specified for the DRVNAME parameter in the SSL DRIVER statement and "SSLI" is required and specifies the protocol name that defines the driver associated with this link. It must be the same as the value specified for the DRVNAME parameter in the SSLI DRIVER statement.
This optional parameter specifies the Internet host name of a node with which a connection is to be established. Its value can be 1 - 255 characters. The ADJHOST parameter can be modified only when the link is closed.
The ADJHOST parameter uses Domain Name Services (DNS), as follows:
The GetHostByName function is used to determine the IP address of a host name specified with ADJHOST. IP address is used both for connecting to another node and for locating the link for an incoming connection.
The GetHostByAddr function is used to determine the host name of a node that is trying to connect to this node. This is necessary when the IP address of a host name specified with ADJHOST changes after the link has been opened.
Software AG recommends the use of the ADJHOST parameter for sites that assign IP addresses via the DHCP protocol. Entire Net-Work will use the GetHostByName function for every outgoing connection on nodes that have ADJHOST specified as long as INETADDR is not specified.
The following table lists the APIs that support Domain Name Services:
| API | GetHostByName | GetHostByAddr |
|---|---|---|
| BS2 | Yes | Yes |
| OES | Yes | Yes |
For performance reasons, Software AG recommends that all LINK statements containing an ADJHOST value be defined after the LINK statements containing an INETADDR specification. If neither of these parameters is specified, the link is not usable. If both are specified, the INETADDR parameter takes precedence.
This optional parameter specifies the IP (Internet Protocol) address of the remote host associated with this link. The INETADDR parameter can be modified only when the link is closed.
The IP address is used both for connecting to another node and for locating the link for an incoming connection. It is provided to Entire Net-Work in the form of INETADDR=(n1,n2,n3,n4) or INETADDR=(n1.n2.n3.n4) where each value represents 8 bits of the 32-bit IP address. Acceptable values are between 0 and 255 and may be separated by commas or periods.
For example:
INETADDR=(157,182,17,20)
or
INETADDR=(157.182.17.20)
On most UNIX-based machines, this address can be found in the /etc/hosts file. The following are examples of the information in the /etc/hosts file:
157.182.17.20 DALLAS dallas (VMS) 157.182.17.18 DENVER denver (UNIX)
Each host on the INTERNET is assigned a unique IP address, which is used by the internet protocol and higher level protocols to route packets through the network. The IP address is logically made up of two parts: the network number and the local address. This IP address is 32 bits in length and can take on different formats or classes. The class defines the length (number of bits) of each part. There are four classes (A, B, C, and D); the class is identified by the allocation of the initial bit.
For performance reasons, Software AG recommends that all LINK statements containing an INETADDR value be defined before the LINK statements containing an ADJHOST specification. If neither of these parameters is specified, the link is not usable. If both are specified, the INETADDR parameter takes precedence.
KEEPALIV=Y (Yes) causes internal TCP messages to be sent periodically to the remote node, thus maintaining the connection when there is no other traffic with the node. The amount of time between messages is determined by an initialization parameter in the TCP stack. If no KEEPALIV value is specified for the link, it defaults to the KEEPALIV value on the SSL DRIVER statement.
This optional parameter determines whether a connect request from a host that has an active connection will be treated as a new link "Y", or a reconnection of an existing link "N". The default value is the value specified for the MULTSESS parameter in the SSL DRIVER statement (N or Y, with Y as the default). The MULTSESS parameter can be modified when the link is open or closed.
This optional parameter determines whether (Y or N) statistics are printed to DDPRINT when the statistics interval expires. The default value is the value specified for the PSTATS parameter in the SSL DRIVER statement (for which the default is N). This parameter does not affect the STATS operator command. The PSTATS parameter can be modified when the link is open or closed.
This optional parameter determines whether (Y or N) statistics are automatically reset when the statistics interval expires. The default value is the value specified for the RSTATS parameter in the SSL DRIVER statement. The RSTATS parameter can be modified when the link is open or closed.
If SAF=Y or SAF=L is specified, Entire Net-Work will call the SAF Interface for all incoming requests on this link; failure to load the Interface is considered a security violation and Entire Net-Work will shut down. If SAF=L, the calls are traced and the output directed to DDPRINT. An error code is transmitted to the user if access to SAF is denied. The SAF parameter can be modified when the link is open or closed. The default value is "N" (No).
This optional parameter specifies the time (in seconds) that Encryption for Entire Net-Work allows for a send to complete. When this time is exceeded, a message is written to the operator console indicating a possible error condition on the remote node. The connection is considered severed and link disconnect processing is initiated. The default value is 90 seconds. The SENDTIME parameter can be modified when the link is open or closed.
This parameter specifies a well-known port number associated with a remote partner. Entire Net-Work will attempt to use this port number when connecting to the remote partner. If this parameter is not specified, or is set to zero (0), the value specified for the SERVERID parameter on the DRIVER statement is used. The SERVERID parameter can be modified only when the link is closed.
This optional parameter specifies the amount of time, in seconds, before statistics are automatically printed or reset. Acceptable values are 1 - 2147483647. Any value outside this range is in error. The default value is "3600". The STATINT parameter can be modified when the link is open or closed.
This optional parameter specifies the size of the TCP/IP link specific trace table. Value can be 4096 - 4194304. A value less than 4096 is reset to 4096. A value greater than 4194304 is reset to 4194304. The default value is the value specified for the TRACESIZ parameter in the SSL DRIVER statement. The TRACESIZ parameter can be modified only when the link is closed.
Encryption for Entire Net-Work can process operator commands that are directed to a specific link or directly to its driver. This section describes the operator commands you can use.
For information about entering operator commands under z/VSE, refer to the Entire Net-Work VSE installation instructions.
Under z/OS, the line driver operator commands have the following format:
The following table describes this syntax.
| Syntax Representation | Description |
|---|---|
| SSL | Informs Entire Net-Work that the command is destined for Encryption for Entire Net-Work. If more than one SSL DRIVER statement exists, use the name specified on the DRVNAME parameter of the SSL DRIVER statement instead of SSL. |
| target | A value that informs Entire Net-Work
what the target of the command is, as follows:
Specify the link name if the target is a specific link. |
| cmd | The operator commands to be carried out. Multiple commands can be specified in a single command statement. When the ALTER command is specified, it must be the last command in the statement, because everything following the ALTER command is treated as a DRIVER or LINK statement parameter. One or more DRIVER or LINK statement parameters must be specified. |
The following are examples of line driver operator commands:
F NETWORK,SSL * CLOSE SSL # STATS
The following table describes this syntax.
| Syntax Representation | Description |
|---|---|
| SSLI | Informs Entire Net-Work that the command is destined for Encryption for Entire Net-Work. If more than one SSLI DRIVER statement exists, use the name specified on the DRVNAME parameter of the SSLI DRIVER statement instead of SSLI. |
| target | A value that informs Entire Net-Work
what the target of the command is, as follows:
Specify the link name if the target is a specific link. |
| cmd | The operator commands to be carried out. Multiple commands can be specified in a single command statement. When the ALTER command is specified, it must be the last command in the statement, because everything following the ALTER command is treated as a DRIVER or LINK statement parameter. One or more DRIVER or LINK statement parameters must be specified. |
The following are examples of line driver operator commands:
F NETWORK,SSLI * CLOSE SSLI # STATS
Encryption for Entire Net-Work supports the commands listed in the following table when the target is the driver. The underlined portion of the command is the minimum abbreviation.
Note:
When the driver is closed, it does not recognize the commands
CLOSE, STATS, or RESET.
Encryption for Entire Net-Work supports the commands listed in the following table when the target is a link or all links. The underlined portion of the command is the minimum abbreviation.
Encryption for Entire Net-Work supports dynamically added links, thus reducing the time required to set up and maintain the SSL LINK statements. Model links can be coded and used to define new links as they are added.
Encryption for Entire Net-Work is permitted to add links dynamically if ACCEPTUI=Y is coded on the DRIVER statement. A new link block is created and is used to control all further communications on the link. The link block can be initialized with default values that will be applied to each new link. Alternatively, one or more model links can be defined to override the values contained in the link block.
The model link statement is identical to other LINK statements, except that the link name begins with the characters "MODEL". Most of the model link parameters, such as PSTATS and RSTATS, are copied into the dynamically-built link block. Some parameters, such as INETADDR, are not copied because they are truly link-specific.