This chapter describes the configuration and usage of the BS2000 porting of the Open Source TLS proxy stunnel, released under the GP license. The home page with further readings regarding the project led by Michal Trojnara can be found under https://www.stunnel.org/.
Basically stunnel is intended to link applications with TLS support with services without such or vice versa. As porting base version 5.73 has been used (at manual press date).
The target direction of the present porting is the usage in conjunction with an MT9750 terminal emulation supporting TLS secured connections. The stunnel instance on the respective target BS2000 system is then the other endpoint of the TLS connection. From this stunnel instance a second, unsecured, but local connection leads e.g. to the $DIALOG or OMNIS application. A transcending usage with other TCP based protocols is possible in principle, but is up to now neither tested nor guaranteed, The following description limits itself to topics important in conjunction with MT9750, for information beyond that see the further reading.
Stunnel is realized as a stand-alone program, which is contained in SYSLNK.TCP-IP-AP.nnn. There are several procedures for configuration and usage in SYSPRC.TCP-IP-AP.nnn, which are subsequently explained:
STUNNEL.INSTALL
This procedure creates an ENTER-JOB file SYSENT.TCP-IP-AP.nnn.STUNNEL, which is used later for starting stunnel, and an initial configuration file SYSDAT.TCP-IA-AP.nnn.STUNNEL.CONF. With the latter amongst others the log file and the file with the TSN of the stunnel task, needed for the further procedures, are configured. In addition a service for using with MT9750 is already configured; more details of the configuration file follow in a subsequent section.
For being able to try stunnel as quick and simple as possible also the file SYSDAT.TCP-IP-AP.nnn.STUNNEL.PEM is generated, which contains a self-signed X.509 certificate and the related private RSA key. As this file is not created individually, it is not good for fending off "Man in the Middle (MITM)" attacks and should therefore never be used in production, only for test purposes; the generation of a productively usable alternative is described further down.
STUNNEL.START
This procedure starts with the help of the SYSENT file created by STUNNEL.INSTALL an ENTER job, which executes the stunnel program.
STUNNEL.STOP
This procedure stops the stunnel program.
STUNNEL.SWITCH-LOGFILE
One can't view the current log file, while the stunnel program is running. This procedure allows it to switch to a new log file, whose name is the originally one (SYSLOG.TCP-IP-AP.nnn.STUNNEL) suffixed with date/time of the switch moment. With that the previous log file can be viewed.
STUNNEL.LOG-CONN
This procedure leads to dumping data regarding the currently existing connections into the log file, mainly for diagnostic purposes.
STUNNEL.RELOAD-CONFIG
This procedure causes stunnel to reload the (meanwhile modified) configuration file, e.g. for supporting additional services.
Installation and configuration
Because the operation works for different reasons only with TSOS privileges, the installation should also be done under TSOS. For this the procedure STUNNEL.INSTALL in the LMS library SYSPRC.TCP-IP-AP.nnn is called:
/CALL-PROCEDURE FROM-FILE=*LIBRARY-ELEMENT(LIBRARY=$TSOS.SYSPRC.TCP-IP-AP.nnn,ELEMENT=STUNNEL.INSTALL)
The thereby created initial stunnel configuration file SYSDAT.TCP-IP-AP.nnn.STUNNEL.CONF has the following content:
output = SYSLOG.TCP-IP-AP.nnn.STUNNEL
pid = SYSDAT.TCP-IP-AP.nnn.STUNNEL.TSN
sslVersionMin = TLSv1.2
; Uncomment the following line if you need more log information
;debug = debug
;stack = 100000
;
; Standard configuration for MT9750:
[MT9750]
accept = 994
connect = 127.0.0.1:102
cert = SYSDAT.TCP-IP-AP.nnn.STUNNEL.PEM
;
Empty lines and lines starting with a semicolon (;) are ignored. The file starts with the global, not service-specific, definitions. With [<service name>] service specific definitions are introduced; the service name helps to assign the log file entries to the respective service.
Global options
With output the log file is specified, with pid the file containing the TSN of the stunnel job (which is used by the procedures for addressing the stunnel program).
Because due to security shortcomings TLS versions older than 1.2 should not be used anymore, if possible (see also RFC 8996), these are globally deactivated with sslVersionMin = TLSv1.2, so that only TLS versions from TLS 1.2 upwards are used. sslVersionMin can also be used service-specific.
When experiencing problems the highest possible log level should be activated by removing the semicolon (;) before the debug option. The default of this option is notice, for other option values see the further reading.
The commented out stack option shows the default value for a run time system parameter, which should normally be sufficient. If with extensive usage against expectation problems occur, which indicate a too small stack area, one can increase this option tentatively.
Service specific options
With accept the port number for accepting TLS connections is configured, MT9750 uses as default port 994. With connect the target for the related unsecured connection is specified, where host name/IP address and port number are separated by a colon (:). As host one will typically specify localhost or the IP address 127.0.0.1 because otherwise the unsecured connection would leave the own host.
With cert one specifies a file, which contains the X.509 certificate chain needed for the establishment of a TLS connection, and which must also contain the related private RSA key, if, as here, for this no separate file is used.
stunnel quits normally idle connections after half a day, i.e. 43200 seconds. With the TIMEOUTidle option this period can be made shorter or longer, negative values lead to infinite idle periods, so add TIMEOUTidle = -1 to the service definition, when you don't want any quitting of idle connections.
If idle connections are e.g. terminated too early by firewalls, one can either activate the BCAM TCP-KEEP-ALIVE mechanism globally (see command MODIFY-BCAM-OPTIONS in the BCAM User Guide), or make per Sockets option a service specific setting. For this one adds a line with the content "socket = a:SO_KEEPALIVE=<120..32767>" to the service definition, where one can choose a timer interval between 120 and 32767 seconds. A value of 0 deactivates the Keep-Alive-Mechanism for the respective service. With the two above settings a service definition may look like:
[MT9750]
accept = 994
connect = 127.0.0.1:102
cert = SYSDAT.TCP-IP-AP.nnn.STUNNEL.PEM
TIMEOUTidle = -1
socket = a:SO_KEEPALIVE=120
;
Private key and certificate
As already mentioned, the SYSDAT.TCP-IP-AP.nnn.STUNNEL.PEM file created during installation is only good for testing the technical functionality, but not for fending off MITM attacks. For the latter an individual private key with a related X.509 certificate must be generated or obtained. Details depend on the authentication methods the respective client application uses, therefore consult the respective current MT9750 documentation please. The MT9750 version available at manual print date offers only a verification of the public key itself, which resembles SSH's approach, not the verification of an X.509 certificate chain. Therefore it suffices to put the public key, related to the private one, in form of a self-signed certificate into the same file. For the generation of a file with such a key pair exists the procedure MAKE.SELF-SIGNED-CERT, whose usage is described in the interNet Services User Guide. The file SYSDAT.TCP-IP-AP.nnn.SERVER.PEM generated by it can be used instead of the file created during the stunnel installation.
Operation
Starting stunnel
With the procedure STUNNEL.START an ENTER-JOB is started, which executes the stunnel program:
/CALL-PROCEDURE FROM-FILE=*LIBRARY-ELEMENT(LIBRARY=$TSOS.SYSPRC.TCP-IP-AP.nnn,ELEMENT=STUNNEL.START)
The SYSOUT/SYSLST output goes into the file SYSLST.TCP-IP-AP.nnn.STUNNEL.JOB. WIth the help of the SET-SYSLST-READ-MARK command one can look into the file without stopping stunnel if diagnostic purposes make this necessary. The procedure has an optional parameter JOB-CLASS, which allows changing the JOB-CLASS operand value of the ENTER-JOB command. The default is *STD.
Stopping stunnel
With the procedure STUNNEL.STOP the stunnel program is stopped:
/CALL-PROCEDURE FROM-FILE=*LIBRARY-ELEMENT(LIBRARY=$TSOS.SYSPRC.TCP-IP-AP.nnn,ELEMENT=STUNNEL.STOP)
Switch log file
With the procedure STUNNEL.SWITCH-LOGFILE the logging is switched to a new file, with the current timestamp appended to its original name, so that one can view the previous log file:
/CALL-PROCEDURE FROM-FILE=*LIBRARY-ELEMENT(LIBRARY=$TSOS.SYSPRC.TCP-IP-AP.nnn,ELEMENT=STUNNEL.SWITCH-LOGFILE)
Write data regarding current connections into a log file
With the procedure STUNNEL.LOG-CONN stunnel is caused to write data regarding the currently existing connections into the log file:
/CALL-PROCEDURE FROM-FILE=*LIBRARY-ELEMENT(LIBRARY=$TSOS.SYSPRC.TCP-IP-AP.nnn,ELEMENT=STUNNEL.LOG-CONN)
Load configuration anew
With the procedure STUNNEL.RELOAD-CONFIG stunnel is caused to read in and evaluate the configuration file anew:
/CALL-PROCEDURE FROM-FILE=*LIBRARY-ELEMENT(LIBRARY=$TSOS.SYSPRC.TCP-IP-AP.nnn,ELEMENT=STUNNEL.RELOAD-CONFIG)
Further reading
SYSDOC.TCP-IP-AP.nnn contains as X element STUNNEL-<stunnel version>.ZIP the stunnel man page, adapted to the BS2000 peculiarities and shortened by definitely not supported functionality. This ZIP file contains the man page in both HTML and PDF format. When transferring the ZIP file, pay attention to transporting it binary to the displaying system.