|
|
|
# SSLproxy - transparent SSL/TLS proxy for diverting packets to other programs
|
|
|
|
|
|
|
|
Copyright (C) 2017, [Soner Tari](http://comixwall.org).
|
|
|
|
https://github.com/sonertari/SSLproxy
|
|
|
|
|
|
|
|
Copyright (C) 2009-2016, [Daniel Roethlisberger](//daniel.roe.ch/).
|
|
|
|
http://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.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
This is similar in principle to [divert
|
|
|
|
sockets](https://man.openbsd.org/divert.4), 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.
|
|
|
|
|
|
|
|
For example, given the following proxy specification:
|
|
|
|
|
|
|
|
https 127.0.0.1 8443 up:8080
|
|
|
|
|
|
|
|
The 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. After processing the packets, the Program gives
|
|
|
|
them back to the SSLproxy listening on a dynamically assigned address, which
|
|
|
|
the Program obtains from the first packet in the connection. Then the SSLproxy
|
|
|
|
re-encrypts and sends the packets to the Server. The response from the Server
|
|
|
|
follows the same path to the Client in reverse order.
|
|
|
|
|
|
|
|
Program
|
|
|
|
^^
|
|
|
|
/ \
|
|
|
|
v v
|
|
|
|
Client <-> SSLproxy <-> Server
|
|
|
|
|
|
|
|
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 the SSLproxy
|
|
|
|
listening on that address, instead of sending them to the original destination
|
|
|
|
as it normally would.
|
|
|
|
|
|
|
|
A sample line SSLproxy inserts into the first packet in the connection is 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 the 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. Since
|
|
|
|
the program receives the packets from the SSLproxy, it cannot determine the
|
|
|
|
source and destination addresses of the packets by itself, hence must rely on
|
|
|
|
the information in this 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.
|
|
|
|
|
|
|
|
SSLproxy supports plain TCP, plain SSL, HTTP, HTTPS, POP3, POP3S, SMTP, and
|
|
|
|
SMTPS connections over both IPv4 and IPv6. SSLproxy fully supports Server Name
|
|
|
|
Indication (SNI) and is able to work with RSA, DSA and ECDSA keys and DHE and
|
|
|
|
ECDHE cipher suites. Depending on the version of OpenSSL, SSLproxy supports
|
|
|
|
SSL 3.0, TLS 1.0, TLS 1.1 and TLS 1.2, and optionally SSL 2.0 as well.
|
|
|
|
|
|
|
|
For SSL/TLS connections, SSLproxy generates and signs forged X509v3
|
|
|
|
certificates on-the-fly, mimicking the original server certificate's subject
|
|
|
|
DN, subjectAltName extension and other characteristics. SSLproxy has the
|
|
|
|
ability to use existing certificates of which the private key is available,
|
|
|
|
instead of generating forged ones. SSLproxy supports NULL-prefix CN
|
|
|
|
certificates but otherwise does not implement exploits against specific
|
|
|
|
certificate verification vulnerabilities in SSL/TLS stacks.
|
|
|
|
|
|
|
|
SSLproxy implements a number of defenses against mechanisms which would
|
|
|
|
normally prevent MitM attacks or make them more difficult. SSLproxy can deny
|
|
|
|
OCSP requests in a generic way. For HTTP and HTTPS connections, SSLproxy
|
|
|
|
removes response headers for HPKP in order to prevent server-instructed public
|
|
|
|
key pinning, for HSTS to avoid the strict transport security restrictions, and
|
|
|
|
Alternate Protocols to prevent switching to QUIC/SPDY. HTTP compression,
|
|
|
|
encodings and keep-alive are disabled to make the logs more readable.
|
|
|
|
|
|
|
|
Another reason to disable persistent connections is to reduce file descriptor
|
|
|
|
usage. Accordingly, connections are closed if they remain idle for a certain
|
|
|
|
period of time. The default timeout is 120 seconds, which can be changed in a
|
|
|
|
configuration file.
|
|
|
|
|
|
|
|
In order to maximize the chances that a connection can be successfully split,
|
|
|
|
SSLproxy does not verify upstream server certificates. Instead, all
|
|
|
|
certificates including self-signed are accepted and if the expected hostname
|
|
|
|
signaled in SNI is missing from the server certificate, it will be added to
|
|
|
|
dynamically forged certificates.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
As SSLproxy is based on SSLsplit, this is a modified SSLsplit README file.
|
|
|
|
See the manual page sslproxy(1) for details on using SSLproxy and setting up
|
|
|
|
the various NAT engines.
|
|
|
|
|
|
|
|
|
|
|
|
## Requirements
|
|
|
|
|
|
|
|
SSLproxy depends on the OpenSSL and libevent 2.x libraries.
|
|
|
|
The build depends on GNU make and a POSIX.2 environment in `PATH`.
|
|
|
|
If available, pkg-config is used to locate and configure the dependencies.
|
|
|
|
The optional unit tests depend on the check library.
|
|
|
|
|
|
|
|
SSLproxy currently supports the following operating systems and NAT mechanisms:
|
|
|
|
|
|
|
|
- FreeBSD: pf rdr and divert-to, ipfw fwd, ipfilter rdr
|
|
|
|
- OpenBSD: pf rdr-to and divert-to
|
|
|
|
- Linux: netfilter REDIRECT and TPROXY
|
|
|
|
- Mac OS X: pf rdr and ipfw fwd
|
|
|
|
|
|
|
|
Support for local process information (`-i`) is currently available on Mac OS X
|
|
|
|
and FreeBSD.
|
|
|
|
|
|
|
|
SSL/TLS features and compatibility greatly depend on the version of OpenSSL
|
|
|
|
linked against; for optimal results, use a recent release of OpenSSL proper.
|
|
|
|
OpenSSL forks like BoringSSL may or may not work.
|
|
|
|
|
|
|
|
|
|
|
|
## Installation
|
|
|
|
|
|
|
|
With OpenSSL, libevent 2.x, pkg-config and check available, run:
|
|
|
|
|
|
|
|
make
|
|
|
|
make test # optional unit tests
|
|
|
|
make install # optional install
|
|
|
|
|
|
|
|
Dependencies are autoconfigured using pkg-config. If dependencies are not
|
|
|
|
picked up and fixing `PKG_CONFIG_PATH` does not help, you can specify their
|
|
|
|
respective locations manually by setting `OPENSSL_BASE`, `LIBEVENT_BASE` and/or
|
|
|
|
`CHECK_BASE` to the respective prefixes.
|
|
|
|
|
|
|
|
You can override the default install prefix (`/usr/local`) by setting `PREFIX`.
|
|
|
|
For more build options see `GNUmakefile`.
|
|
|
|
|
|
|
|
|
|
|
|
## Documentation
|
|
|
|
|
|
|
|
See `NEWS.md` for release notes listing significant changes between releases.
|
|
|
|
See `HACKING.md` for information on development and how to submit bug reports.
|
|
|
|
See `AUTHORS.md` for the list of contributors.
|
|
|
|
|
|
|
|
|
|
|
|
## License
|
|
|
|
|
|
|
|
SSLsplit is provided under a 2-clause BSD license.
|
|
|
|
SSLsplit contains components licensed under the MIT and APSL licenses.
|
|
|
|
See `LICENSE.md` and the respective source file headers for details.
|
|
|
|
The modifications for SSLproxy are licensed under the same terms as SSLsplit.
|
|
|
|
|