SSLproxy - transparent SSL/TLS proxy for decrypting and diverting network traffic to other programs for deep SSL inspection

Copyright (C) 2017-2025, Soner Tari. https://github.com/sonertari/SSLproxy

Copyright (C) 2009-2019, Daniel Roethlisberger. https://www.roe.ch/SSLsplit

Overview

SSLproxy is a proxy for SSL/TLS encrypted network connections. It is intended to be used for decrypting and diverting network traffic to other programs, such as UTM services, for deep SSL inspection. But it can handle unencrypted network traffic as well.

The UTMFW project uses SSLproxy to decrypt and feed network traffic into its UTM services: Web Filter, POP3 Proxy, SMTP Proxy, and Inline IPS; and also indirectly into Virus Scanner and Spam Filter through those UTM software. Given that most of the Internet traffic is encrypted now, without SSLproxy it wouldn't be possible to deeply inspect most of the network traffic passing through UTMFW.

See this presentation for a summary of SSL interception and potential issues with middleboxes that support it.

Mode of operation

SSLproxy is designed to transparently terminate connections that are redirected to it using a network address translation engine. SSLproxy then terminates SSL/TLS and initiates a new SSL/TLS connection to the original destination address. Packets received on the client side are decrypted and sent to the program listening on a port given in the proxy specification. SSLproxy inserts in the first packet the address and port it is expecting to receive the packets back from the program. Upon receiving the packets back, SSLproxy re-encrypts and sends them to their original destination. The return traffic follows the same path back to the client in reverse order.

This is similar in principle to divert sockets, where the packet filter diverts the packets to a program listening on a divert socket, and after processing the packets the program reinjects them into the kernel. If there is no program listening on that divert socket or the program does not reinject the packets into the kernel, the connection is effectively blocked. In the case of SSLproxy, SSLproxy acts as both the packet filter and the kernel, and the communication occurs over networking sockets.

SSLproxy supports split mode of operation similar to SSLsplit as well. In split mode, packets are not diverted to listening programs, effectively making SSLproxy behave similar to SSLsplit, but not exactly like it, because SSLproxy has certain features nonexistent in SSLsplit, such as user authentication, protocol validation, and filtering rules. Also, note that the implementation of the proxy core in SSLproxy is different from the one in SSLsplit; for example, the proxy core in SSLproxy runs lockless, whereas SSLsplit implementation uses a thread manager level lock (which does not necessarily make sslproxy run faster than sslsplit). In SSLproxy, split mode can be defined globally, per-proxyspec, or per-connection using filtering rules.

SSLproxy does not automagically redirect any network traffic. To actually implement a proxy, you also need to redirect the traffic to the system running sslproxy. Your options include running sslproxy on a legitimate router, ARP spoofing, ND spoofing, DNS poisoning, deploying a rogue access point (e.g. using hostap mode), physical recabling, malicious VLAN reconfiguration or route injection, /etc/hosts modification and so on.

Proxy specifications

SSLproxy supports three different types of proxy specifications, or proxyspecs for short, which can be in divert or split style.

• Command line proxyspecs passed on the command line
• One line proxyspecs in configuration files
• Structured proxyspecs in configuration files

The syntax of command line proxyspecs is as follows:

(tcp|ssl|http|https|pop3|pop3s|smtp|smtps|autossl)
  listenaddr listenport
  [up:divertport [ua:divertaddr ra:returnaddr]]
  [(targetaddr targetport|sni sniport|natengine)]

The syntax of one line proxyspecs is the same as the syntax of command line proxyspecs, except for the leading ProxySpec keyword:

ProxySpec (tcp|ssl|http|https|pop3|pop3s|smtp|smtps|autossl)
  listenaddr listenport
  [up:divertport [ua:divertaddr ra:returnaddr]]
  [(targetaddr targetport|sni sniport|natengine)]

The syntax of structured proxyspecs is as follows, and they can configure connection options too:

ProxySpec {
    Proto (tcp|ssl|http|https|pop3|pop3s|smtp|smtps|autossl)
    Addr listenaddr       # inline
    Port listenport       # comments
    DivertPort divertport # allowed
    DivertAddr divertaddr
    ReturnAddr returnaddr
    TargetAddr targetaddr
    TargetPort targetport
    SNIPort sniport
    NatEngine natengine

    # Divert or split
    Divert (yes|no)

    # Connection options
    Passthrough (yes|no)

    DenyOCSP (yes|no)
    CACert ca.crt
    CAKey ca.key
    ClientCert client.crt
    ClientKey client.key
    CAChain chain.crt
    LeafCRLURL http://example.com/example.crl
    DHGroupParams dh.pem
    ECDHCurve prime256v1
    SSLCompression (yes|no)
    ForceSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13)
    DisableSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13)
    EnableSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13)
    MinSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13)
    MaxSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13)
    Ciphers MEDIUM:HIGH
    CipherSuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
    VerifyPeer (yes|no)
    AllowWrongHost (yes|no)

    RemoveHTTPAcceptEncoding (yes|no)
    RemoveHTTPReferer (yes|no)
    MaxHTTPHeaderSize 8192
    ValidateProto (yes|no)

    UserAuth (yes|no)
    UserTimeout 300
    UserAuthURL https://192.168.0.1/userdblogin.php

    # The DivertUsers, PassUsers, and PassSite options will be deprecated
    DivertUsers userlist
    PassUsers userlist
    PassSite rules

    Define $macro valuelist

    (Divert|Split|Pass|Block|Match) one line filtering rules
    FilterRule {...} structured filtering rules
}

For example, given the following command line proxyspec:

https 127.0.0.1 8443 up:8080

• SSLproxy listens for HTTPS connections on 127.0.0.1:8443.
• Upon receiving a connection from the Client, it decrypts and diverts the packets to a Program listening on 127.0.0.1:8080. The default divert address is 127.0.0.1, which can be configured by the ua option.
• After processing the packets, the Program gives them back to SSLproxy listening on a dynamically assigned address, which the Program obtains from the SSLproxy line in the first packet in the connection.
• Then SSLproxy re-encrypts and sends the packets to the Server.

The response from the Server follows the same path back to the Client in reverse order.

Split style proxyspecs configure for split mode of operation similar to SSLsplit. See the SSLsplit documentation for the details of split style proxyspecs.

SSLproxy line

Given the proxyspec example above, a sample line SSLproxy inserts into the first packet in the connection may be the following:

SSLproxy: [127.0.0.1]:34649,[192.168.3.24]:47286,[192.168.111.130]:443,s

• The first IP:port pair is a dynamically assigned address that SSLproxy expects the program send the packets back to it.
• The second and third IP:port pairs are the actual source and destination addresses of the connection, respectively. Since the program receives the packets from SSLproxy, it cannot determine the source and destination addresses of the packets by itself, for example by asking the NAT engine, hence must rely on the information in the SSLproxy line.
• The last letter is either s or p, for SSL/TLS encrypted or plain traffic, respectively. This information is also important for the program, because it cannot reliably determine if the actual network traffic it is processing was encrypted or not before being diverted to it.

Listening programs

The program that packets are diverted to should support this mode of operation. Specifically, it should be able to recognize the SSLproxy address in the first packet, and give the first and subsequent packets back to SSLproxy listening on that address, instead of sending them to their original destination as it normally would.

You can use any software as a listening program as long as it supports this mode of operation. So existing or new software developed in any programming language can be modified to be used with SSLproxy to inspect and/or modify any or all parts of the packets diverted to it.

Given the proxyspec example above, a program should be listening on port 8080.

You can offload the system SSLproxy is running on by diverting packets to remote listening programs too. For example, given the following proxy specification:

https 127.0.0.1 8443 up:8080 ua:192.168.0.1 ra:192.168.1.1

• The ua option instructs SSLproxy to divert packets to 192.168.0.1:8080, instead of 127.0.0.1:8080 as in the previous proxyspec example.
• The ra option instructs SSLproxy to listen for returned packets from the program on 192.168.1.1, instead of 127.0.0.1 as in the previous SSLproxy line.

Accordingly, the SSLproxy line now becomes (notice the first IP address):

SSLproxy: [192.168.1.1]:34649,[192.168.3.24]:47286,[192.168.111.130]:443,s

And a listening program should be running at address 192.168.0.1 on port 8080.

So, the listening program can be running on a machine anywhere in the world. Since the packets