OS4X SmartProxy

What is OS4X SmartProxy

OS4X SmartProxy is a software product which enables you to maintain OFTP2 Proxy activities in a very secure manner. This includes:

• Partner verification upon session initialization before OFTP2 takes place
• OFTP2 message syntax verification
• TLS termination in the DMZ
• configurable outgoing IP address
• No configuration values needed in DMZ
• Secure backend communication via https
• Support for both incoming and outgoing connections
• Manageable logging activities supporting intrusion detection systems
• Extended logging of all activities

Differences against OS4X Proxy

OS4X Proxy supports to forward any TCP/IP package from any source port to any destination via a combination of OS4X proxyserver and proxyclient. The protocol used on top of this connection is not under control of this OS4X proxy.

OS4X SmartProxy terminates the encrypted session of OFTP2 TLS sessions at its end-point (proxy server), verifies any traffic and forwards it securely to the inside proxy client, where it is being transported to the OS4X receive daemon. This enables the OS4X SmartProxy to analyze the complete traffic used in the communication stream, so invalid packages lead to session termination.

The design of the OS4X SmartProxy is that the proxy server and proxy client use as less information as needed for operation. Everything needed for operation is communicated to a secure backend via https.

Involved programs

The used components for the implementation of an OS4X SmartProxy are:

• OS4X SmartProxy server
• OS4X SmartProxy client
• OS4Xapi, accessed via https

Version requirements

OS4X SmartProxy required at least the same OS4X release (with the same or newer build date).

Licensing

OS4X Proxy is licensed via a license file at the OS4X Proxy (not client) side: only one license is needed to keep the system up and running. This license is based on an OS4X Proxy ID on the proxy server side, which can be easily obtained via a command line parameter:

dmz:~ # /opt/os4x/proxy/os4x_proxyserver2 -L
OS4X Proxy ID: c6bc8d9b37c5e36333a41acdda653aaef7fd4a00459eeb32a8a41059e23017c8px

This OS4X Proxy ID is needed for license generation, which can be done for test purposes on the product website at https://www.os4x.com/en/support/emergency-license/.

The valid license will be searched by default at

/etc/os4x_proxy.lic

but an alternative location can be given with the commandline option "-l":

dmz:~ # /opt/os4x/proxy/os4x_proxyserver2 -l /usr/licenses/os4x_proxy.lic

Since OS4X build 20220107, it is possible to extend license validity of the OS4X SmartProxy via GUI. Requirements are:

• writability of the license file on the DMZ server via proxy server process
• Internet access of the webbrowser which is using OS4Xadmin

For that the newest version must be up and running. The proxy server communicates its OS4X-ID and license expiration date to the internal proxy client, which sends it via API to the internal zone. The extending is done via web interface in "Configuration" -> "Proxy":

After clicking the icon for license extending, it is saved in the database and from there transported to the proxy server every 60 seconds:

Every time the proxy server receives the response, it checks the license file locally installed against the provided value. If it differs, it will be written and dynamically reloaded. No restart of proxy process is required. Licenses extended by this mechanism can be downloaded from the web interface.

Logging

The logging of all activities is important for the OS4X SmartProxy. It consists of the following parts:

OS4X SmartProxy server and client logging

The logging behaviour of the daemons is configured in the corresponding files in the same directory the binaries reside. They are:

• os4x_proxyserver.logrc
• os4x_proxyclient.logrc

The location must be in the binary directory, so you can start the binary from any position, it will search the configuration files in any case in its own directory.

Configure the logging behaviour to your needs according to log4c standard logging mechanism. The new logger layout "os4x_layout" and appender "os4x_appender" are OS4X's own implementations for daily logger: every process logs into the same file, the files itself are being appended by a datestamp. Rolling to another logfile is done automatically.

OS4Xapi logging

The OS4Xapi is being used for all backend communication, so you configure the logfile and path in "Configuration" -> "Logging" -> "Absolute path to logfile of OS4X API" and set the loglevel accordingly. The configuration takes place directly after saving.

OS4X API proxy system log event script

According to requests, the OS4Xapi starts an event script for every critical situation the OS4X SmartProxy arises. This event script is configurable at "Configuration" -> "Events" -> "OS4X API proxy system log event script"

Handling system logging

Since situations can occur very often and and a high frequency, OS4X offers to ignore system logs. In the area "Configuration" -> "Proxy" -> "Log message ignore configuration" you can dynamically add and remove text message entries with a description, the matching text contained in the message (which must noch be exactly the text since the message will be searched for an occurance case-insensitively fro the given text) and a validity timeframe. The OS4X send queue daemon cleans old entries of this configuration and logs this into the system log. If a message is being matched by a configuration, the OS4Xapi logs this in INFO mode to the configured log file.

Possible problems

Known configuration problems are listed here:

• If the proxy client logs a message like

os4x_proxyclient- Cannot retrieve REST function 'getCrl' at URL http://<serverIP>/os4xapi/index.php!

then possibly the PHP memory limit is too small to process the list of CRLs in one step. Keep in mind that all active CRLs are calculated in-memory to a XML document in PHP, leading to a requirement of at least 2x the memory size of all CRLs.

PID files

Both the OS4X OFTP2 SmartProxy server and client create PID files containing the process ID of the process itself. The position of these PID files is the directory where the binary is located. If a PID file exists on startup, the daemon will fail to start stating the references process ID. You then have to check if this process really exists:

• If yes, send the process a SIGHUP (1) signal to terminate. The PID fill will be deleted, the logfile will contain a logging entry stating this situation in DEBUG level.
• If not, delete the stale PID file

Dynamic logging of daemons

The daemons can receive signals and will then change their logging behaviour on-the-fly. Since every active connections corresponds to an own process, you can send individual processes their own signals for problem analysis. The signal numbers and their loglevels are:

• 20: TRACE
• 21: DEBUG
• 22: INFO
• 23: ERROR
• 24: FATAL

Each change of loglevel will be logged in the logfile with the selected log level.

Example 1: change loglevel to INFO for running OS4X OFTP2 SmartProxy client with PID 82735

kill -22 82735

Example 2: change loglevel to FATAL for running OS4X OFTP2 SmartProxy server with PID 21521

kill -24 21521

OS4X SmartProxy server

The OS4X SmartProxy server is the part which connects to the outside world and which must be reachable via a defined port on the internet. The port on which the server listens to is configured in the OS4X administrative panel, "Configuration" -> "TCP/IP" -> "TCP/IP port of OFTP server (TLS)".

Command line parameters for the server are listed by calling the binary with the parameter "-h":

dmz:/opt/os4x/proxy os4x$ ./os4x_proxyserver2 -h
OS4X Proxy daemon build 20111115

usage:
-h: this help text
-v: display version
-i [<IP of device>]:<port>: accept from (optional) device on given port for internal connections.
                            defaults: IP of device: 0.0.0.0 (any)
                            --------- port: 2878
-L: print out OS4X Proxy ID (basis for license)
-l <license file>: point to readable license file (default: /etc/os4x_proxy.lic)
-V: print out license validity, if available and exit

After having started the server, it listens on an internal port for the OS4X SmartProxy client to connect. This port number can be changed by parameter "-i", in addition to a confiured IP address to listen on.

Only after a successful connect of a OS4X SmartProxy client, the OS4X SmartProxy server is able to retrieve its configuration from the backend and start listening on the configured TCP/IP port for incoming connections.

OS4X SmartProxy client

The OS4X SmartProxy client connects to the started OS4X SmartProxy server and communicates via https to the OS4Xapi, configured to via commandline parameters. The client also forwards internal sessions to a configured host (mostly "localhost") as configured in the configuration panel. The client needs a pre-rendered security token for the communication with the OS4Xapi.

Configuration

The OS4X SmartProxy client configuration is done via web interface in the OS4X administrative panel at "Configuration" -> "Proxy":

The configuration parameter are as follow:

• Hostname or IP address of host running OS4X receive daemon (mandatory for incoming connections): the host (resolvable hostname or IP address) of the host running OS4X receive daemon, to which all OFTP2 incoming communication will be forwarded.
• OS4X Proxy client security token: pre-rendered security token (mandatory): pre-shared token for communication to the OS4Xapi proxy services. All non-authentificated communication tries will be logged to the OS4Xapi log file.
• IP address of outgoing proxy connections (optional): If you want to use a defined outgoing IP address at the proxy server, you can define it here. If this IP address is not available at the OS4X SmartProxy server, an error will be logged to the OS4X system log and the server process will stop.

The block "Proxy client configuration" defines all available OS4X OFTP2 SmartProxy clients. The OS4X SmartProxy client retrieves his configuration of his listening port dynamically from this configuration, so be sure to configure your client with his IP address correctly here!

The block "Log message ignore configuration" is configured in the section "Handling system logging" above.

Starting the process

The OS4X SmartProxy client needs some command line parameter to start up. All available parameters are displayed when starting the binary without any or with the parameter "-h":

appzone:/opt/os4x/proxy os4x$ ./os4x_proxyclient2 -h
OS4X Proxy client build 20160602

usage:
-U <URL>: URL of OS4X API (i.e. https://localhost/os4xapi/index.php)
-S <proxyserver[:<port>]: name or IP of the OS4X OFTP2 proxy server, optionally with port (default: 2878)
-T <security token>: token configured in OS4X admin web GUI ('Configuration' -> 'Proxy' -> 'OS4X Proxy client security token')
[-h: this help text]
[-v: display version]
[-d: enable debug mode]
[-o <IP>: set IP address of all outgoing connections from proxy client to proxy server]

The mandatory parameters are:

• -U: URL of the OS4Xapi service. When using password protected URLs, use a schema of "https://username:password@server/os4x/os4xapi/index.php"
• -S: OS4X SmartProxy server hostname/IP address (and optionally its port)
• -T: Security token configured in the OS4X Proxy configurartion section above

The switch "-d" starts the daemon in foreground mode, so you can easily cancel it by pressing "Ctrl-C", no other output will be displayed (as someone may assume).

Process behaviour

If the OS4X SmartProxy server terminates, the connected client terminates, too.

If the OS4X SmartProxy client terminates, the server switches back to "listen for internal connection".

Each incoming connection which has been verified leads to a new OS4X SmartProxy server process and a new OS4X SmartProxy client process. The OS4X SmartProxy client process opens a new connection to the configured OS4X receive daemon host.

The OS4X SmartProxy server process checks every 60 seconds for an updated security configuration if a client process is connected. This ongoing traffic generates calls at the OS4Xapi. This 60 second latency must be taken into account when administrating trusted certificates and CRLs.

The OS4X SmartProxy server process analyzes incoming connections upon their client certificate and adds non-existing CRL URLs to the OS4X database backend by calls via the client connection. A latency for download is defined by the OS4X send queue time slice and the above mentioned 60 second latency for configuration update of the server process.

HTTP connections from local hosts may result into a configured IPv6 behaviour, where the local hosts has the IP adddress "::1". This special IP address is resolved internally to "127.0.0.1", so if you have problems in configuring a listener, use the IP address "127.0.0.1" for the resolvable hostname or IP address.

Verifying process status

In order to verify a normal state of the daemons, you may want to check the following situations (after successful setup of a connection from the proxy client to the proxy server):

• Proxy server:
  • The process has an established TCP connection on the internal TCP/IP listener port (defined by parameter "-i", default 2878; see above)
  • The process has a TCP listener on the defined TCP/IP port for TLS connections (default: 6619)
  • The process writes a PID file in the same directory where the binary resides with the name "os4x_proxyserver.pid". The contained process ID must exist with the name of the binary.
• Proxy client:
  • The process has a TCP listener on the defined TCP/IP port for the configurable proxy client (default 65433; see above)
  • The process writes a PID file in the same directory where the binary resides with the name "os4x_proxyclient.pid". The contained process ID must exist with the name of the binary.

The tool "lsof" is quite handy for checking the situation of a process.

Example for a running proxy client:

root@os4xvirtual:/opt/os4x/proxy# lsof -p `cat os4x_proxyclient.pid` | grep IPv4
os4x_prox 9134 root    5u  IPv4  23735        0t0     TCP 192.168.10.20:34952->192.168.10.198:2878 (ESTABLISHED)
os4x_prox 9134 root    6u  IPv4  23738        0t0     TCP *:65433 (LISTEN)

Example for a running proxy server:

root@os4xvirtual:/opt/os4x/proxy# lsof -p `cat os4x_proxyserver.pid` | grep IPv4
os4x_prox 9195 root    5u  IPv4  24036        0t0     TCP *:6619 (LISTEN)
os4x_prox 9195 root    6u  IPv4  23783        0t0     TCP 192.168.10.198:2878->192.168.10.20:34952 (ESTABLISHED)