mirror of https://github.com/sonertari/SSLproxy
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
868 lines
38 KiB
Groff
868 lines
38 KiB
Groff
.\"-
|
|
.\" SSLproxy - transparent SSL/TLS proxy for diverting packets to programs
|
|
.\" https://github.com/sonertari/SSLproxy
|
|
.\"
|
|
.\" Copyright (c) 2009-2018, Daniel Roethlisberger <daniel@roe.ch>.
|
|
.\" Copyright (c) 2017-2019, Soner Tari <sonertari@gmail.com>.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" The modifications for SSLproxy are licensed under the same terms as
|
|
.\" SSLsplit.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright notice,
|
|
.\" this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright notice,
|
|
.\" this list of conditions and the following disclaimer in the documentation
|
|
.\" and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ``AS IS''
|
|
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
|
|
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.TH "sslproxy" "1" "27 Mar 2019" "v0.6.0" "SSLproxy"
|
|
.SH NAME
|
|
sslproxy \-\- transparent SSL/TLS proxy for decrypting and diverting network
|
|
traffic to other programs for deep SSL inspection
|
|
.SH SYNOPSIS
|
|
.na
|
|
.B sslproxy
|
|
[\fB-kCKqwWOPZdDgGsrRxeumjplLSFXYyTIMiab\fP] \fB-c\fP \fIpem\fP
|
|
\fIproxyspecs\fP [...]
|
|
.br
|
|
.B sslproxy
|
|
[\fB-kCKqwWOPZdDgGsrRxeumjplLSFXYyTIMiab\fP] \fB-c\fP \fIpem\fP \fB-t\fP \fIdir\fP
|
|
\fIproxyspecs\fP [...]
|
|
.br
|
|
.B sslproxy
|
|
[\fB-OPZwWdDgGsrRxeumjplLSFXYyTIMiab\fP] \fB-t\fP \fIdir\fP
|
|
\fIproxyspecs\fP [...]
|
|
.br
|
|
.B sslproxy [\fB-kCKwWOPZdDgGsrRxeumjplLSFXYyTIMi\fP] -f \fIconffile\fP
|
|
.br
|
|
.B sslproxy -E
|
|
.br
|
|
.B sslproxy -V
|
|
.br
|
|
.B sslproxy -h
|
|
.br
|
|
.ad
|
|
.SH DESCRIPTION
|
|
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.
|
|
.LP
|
|
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 a
|
|
program listening on the 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.
|
|
.LP
|
|
This is similar in principle to divert sockets, 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.
|
|
.LP
|
|
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 the original destination as it
|
|
normally would.
|
|
.LP
|
|
SSLproxy supports plain TCP, plain SSL, HTTP, HTTPS, POP3, POP3S, SMTP, and
|
|
SMTPS connections over both IPv4 and IPv6. It also has the ability to
|
|
dynamically upgrade plain TCP to SSL in order to generically support SMTP
|
|
STARTTLS and similar upgrade mechanisms. 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.
|
|
.LP
|
|
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.
|
|
.LP
|
|
SSLproxy implements a number of defences 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 mangles headers to
|
|
prevent server-instructed public key pinning (HPKP),
|
|
avoid strict transport security restrictions (HSTS),
|
|
avoid Certificate Transparency enforcement (Expect-CT) and
|
|
prevent switching to QUIC/SPDY, HTTP/2 or WebSockets (Upgrade,
|
|
Alternate Protocols).
|
|
HTTP compression, encodings and keep-alive are disabled to make the logs more
|
|
readable.
|
|
.LP
|
|
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.
|
|
.LP
|
|
SSLproxy verifies upstream certificates by default. If the verification fails,
|
|
the connection is terminated immediately. This is in contrast to SSLsplit,
|
|
because in order to maximize the chances that a connection can be successfully
|
|
split, SSLsplit accepts all certificates by default, including self-signed
|
|
ones.
|
|
.LP
|
|
If enabled, the UserAuth option requires network users to log in to the system
|
|
to use SSLproxy (this feature is currently available on OpenBSD and Linux
|
|
only). When users are logged in, they should be recorded on the users table in
|
|
an SQLite3 database. SSLproxy does not create this users table by itself, so
|
|
it should already exist in the SQLite3 database file configured by the
|
|
UserDBPath option. The users table should be created using the following SQL
|
|
statement:
|
|
.LP
|
|
CREATE TABLE USERS(
|
|
IP CHAR(45) PRIMARY KEY NOT NULL,
|
|
USER CHAR(31) NOT NULL,
|
|
ETHER CHAR(17) NOT NULL,
|
|
ATIME INT NOT NULL,
|
|
DESC CHAR(50)
|
|
);
|
|
.LP
|
|
When SSLproxy accepts a connection, it obtains the ethernet address of the
|
|
client IP address from the arp cache of the system, then compares it with
|
|
the value in the users table. If the ethernet addresses do not match, the
|
|
connection is redirected to the login page. SSLproxy also compares the atime
|
|
value in the users table with the current system time. If the difference is
|
|
larger than the configured value of the user timeout option, then the
|
|
connection is redirected to the login page. The atime of the IP address in the
|
|
users table is updated with the system time while the connection is being
|
|
terminated. Since this atime update is run using a privsep command, it is
|
|
expensive. So, to reduce the frequency of such updates, it is deferred until
|
|
the user idle time is more than half of the timeout period.
|
|
.LP
|
|
If enabled, the ValidateProto option validates protocols in proxy
|
|
specifications. If a connection cannot pass protocol validation, then it is
|
|
terminated. This feature currently supports HTTP, POP3, and SMTP protocols.
|
|
.LP
|
|
PassSite option allows certain SSL sites to be excluded from SSL inspection.
|
|
If a PassSite matches SNI or common names in the SSL certificate, the
|
|
connection is passed through the proxy without being diverted to the listening
|
|
program. For example, sites requiring client authentication can be added as
|
|
PassSite. Per site filters can be defined using client IP addresses, users,
|
|
and description keywords. Multiple sites can be defined, one on each line.
|
|
.LP
|
|
Logging options include traditional SSLproxy connect and content log files as
|
|
well as PCAP files and mirroring decrypted traffic to a network interface.
|
|
Additionally, certificates, master secrets and local process information can be
|
|
logged.
|
|
.LP
|
|
SSLproxy does not automagically redirect any network traffic. To actually
|
|
implement a proxy, you also need to redirect the traffic to the system
|
|
running \fBsslproxy\fP. Your options include running \fBsslproxy\fP 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.
|
|
.LP
|
|
As SSLproxy is based on SSLsplit, this is a modified SSLsplit man page.
|
|
.SH OPTIONS
|
|
.TP
|
|
.B \-a \fIpemfile\fP
|
|
Use client certificate from \fIpemfile\fP when destination server requests a
|
|
client certificate.
|
|
.TP
|
|
.B \-b \fIpemfile\fP
|
|
Use client private key from \fIpemfile\fP when destination server requests a
|
|
client certificate.
|
|
.TP
|
|
.B \-c \fIpemfile\fP
|
|
Use CA certificate from \fIpemfile\fP to sign certificates forged on-the-fly.
|
|
If \fIpemfile\fP also contains the matching CA private key, it is also loaded,
|
|
otherwise it must be provided with \fB-k\fP.
|
|
If \fIpemfile\fP also contains Diffie-Hellman group parameters, they are also
|
|
loaded, otherwise they can be provided with \fB-g\fP.
|
|
If \fB-t\fP is also given, SSLproxy will only forge a certificate if there is
|
|
no matching certificate in the provided certificate directory.
|
|
.TP
|
|
.B \-C \fIpemfile\fP
|
|
Use CA certificates from \fIpemfile\fP as extra certificates in the certificate
|
|
chain. This is needed if the CA given with \fB-k\fP and \fB-c\fP is a sub-CA,
|
|
in which case any intermediate CA certificates and the root CA certificate must
|
|
be included in the certificate chain.
|
|
.TP
|
|
.B \-d
|
|
Detach from TTY and run as a daemon, logging error messages to syslog instead
|
|
of standard error.
|
|
.TP
|
|
.B \-D \fIlevel\fP
|
|
Run in debug mode, log lots of debugging information to standard error. This
|
|
also forces foreground mode and cannot be used with \fB-d\fP. Debug \fIlevel\fP
|
|
can be a number from 1 to 4, a higher number meaning more verbosity.
|
|
|
|
.TP
|
|
.B \-e \fIengine\fP
|
|
Use \fIengine\fP as the default NAT engine for \fIproxyspecs\fP without
|
|
explicit NAT engine, static destination address or SNI mode.
|
|
\fIengine\fP can be any of the NAT engines supported by the system, as
|
|
returned by \fB-E\fP.
|
|
.TP
|
|
.B \-E
|
|
List all supported NAT engines available on the system and exit. See
|
|
NAT ENGINES for a list of NAT engines currently supported by SSLproxy.
|
|
.TP
|
|
.B \-f \fIconffile\fP
|
|
Read configuration from \fIconffile\fP.
|
|
.TP
|
|
.B \-F \fIlogspec\fP
|
|
Log connection content to separate log files with the given path specification
|
|
(see LOG SPECIFICATIONS below). For each connection, a log file will be
|
|
written, which will contain both directions of data as transmitted.
|
|
Information about the connection will be contained in the filename only.
|
|
Only one of \fB-F\fP, \fB-L\fP and \fB-S\fP may be used (last one wins).
|
|
.TP
|
|
.B \-g \fIpemfile\fP
|
|
Use Diffie-Hellman group parameters from \fIpemfile\fP for Ephemereal
|
|
Diffie-Hellman (EDH/DHE) cipher suites. If \fB-g\fP is not given, SSLproxy
|
|
first tries to load DH parameters from the PEM files given by \fB-K\fP,
|
|
\fB-k\fP or \fB-c\fP. If no DH parameters are found in the key files, built-in
|
|
group parameters are automatically used.
|
|
The \fB-g\fP option is only available if SSLproxy was built against a version
|
|
of OpenSSL which supports Diffie-Hellman cipher suites.
|
|
.TP
|
|
.B \-G \fIcurve\fP
|
|
Use the named \fIcurve\fP for Ephemereal Elliptic Curve Diffie-Hellman (ECDHE)
|
|
cipher suites. If \fB-G\fP is not given, a default curve (\fBprime256v1\fP) is
|
|
used automatically.
|
|
The \fB-G\fP option is only available if SSLproxy was built against a version
|
|
of OpenSSL which supports Elliptic Curve Diffie-Hellman cipher suites.
|
|
.TP
|
|
.B \-h
|
|
Display help on usage and exit.
|
|
.TP
|
|
.B \-i
|
|
For each connection, find the local process owning the connection. This makes
|
|
process information such as pid, owner:group and executable path for
|
|
connections originating on the same system as SSLproxy available to the
|
|
connect log and enables the respective \fB-F\fP path specification directives.
|
|
\fB-i\fP is available on Mac OS X and FreeBSD; support for other platforms has
|
|
not been implemented yet.
|
|
.TP
|
|
.B \-I \fIif\fP
|
|
Mirror connection content as emulated packets to interface \fIif\fP with
|
|
destination address given by \fB-T\fP. This option is not available if
|
|
SSLproxy was built without mirroring support.
|
|
.TP
|
|
.B \-j \fIjaildir\fP
|
|
Change the root directory to \fIjaildir\fP using chroot(2) after opening files.
|
|
Note that this has implications for \fBsni\fP \fIproxyspecs\fP.
|
|
Depending on your operating system, you will need to copy files such as
|
|
\fB/etc/resolv.conf\fP to \fIjaildir\fP in order for name resolution to work.
|
|
Using \fBsni\fP proxyspecs depends on name resolution.
|
|
Some operating systems require special device nodes such as \fB/dev/null\fP
|
|
to be present within the jail. Check your system's documentation for details.
|
|
.TP
|
|
.B \-J
|
|
Enable connection statistics logging.
|
|
.TP
|
|
.B \-k \fIpemfile\fP
|
|
Use CA private key from \fIpemfile\fP to sign certificates forged on-the-fly.
|
|
If \fIpemfile\fP also contains the matching CA certificate, it is also loaded,
|
|
otherwise it must be provided with \fB-c\fP.
|
|
If \fIpemfile\fP also contains Diffie-Hellman group parameters, they are also
|
|
loaded, otherwise they can be provided with \fB-g\fP.
|
|
If \fB-t\fP is also given, SSLproxy will only forge a certificate if there is
|
|
no matching certificate in the provided certificate directory.
|
|
.TP
|
|
.B \-K \fIpemfile\fP
|
|
Use private key from \fIpemfile\fP for the leaf certificates forged on-the-fly.
|
|
If \fB-K\fP is not given, SSLproxy will generate a random 1024-bit RSA key.
|
|
.TP
|
|
.B \-l \fIlogfile\fP
|
|
Log connections to \fIlogfile\fP in a single line per connection format,
|
|
including addresses and ports and some HTTP and SSL information, if available.
|
|
SIGHUP or SIGUSR1 will cause \fIlogfile\fP to be re-opened.
|
|
.TP
|
|
.B \-L \fIlogfile\fP
|
|
Log connection content to \fIlogfile\fP. The content log will contain a
|
|
parsable log format with transmitted data, prepended with headers identifying
|
|
the connection and the data length of each logged segment.
|
|
SIGHUP or SIGUSR1 will cause \fIlogfile\fP to be re-opened.
|
|
Only one of \fB-F\fP, \fB-L\fP and \fB-S\fP may be used (last one wins).
|
|
.TP
|
|
.B \-m
|
|
When dropping privileges using \fB-u\fP, override the target primary group
|
|
to be set to \fIgroup\fP.
|
|
.TP
|
|
.B \-M \fIlogfile\fP
|
|
Log master keys to \fIlogfile\fP in SSLKEYLOGFILE format as defined by Mozilla.
|
|
Logging master keys in this format allows for decryption of SSL/TLS traffic
|
|
using Wireshark.
|
|
Note that unlike browsers implementing this feature, setting the SSLKEYLOGFILE
|
|
environment variable has no effect on SSLproxy.
|
|
SIGHUP or SIGUSR1 will cause \fIlogfile\fP to be re-opened.
|
|
.TP
|
|
.B \-O
|
|
Deny all Online Certificate Status Protocol (OCSP) requests on all
|
|
\fIproxyspecs\fP and for all OCSP servers with an OCSP response of
|
|
\fBtryLater\fP, causing OCSP clients to temporarily accept even revoked
|
|
certificates.
|
|
HTTP requests are being treated as OCSP requests if the method is \fBGET\fP
|
|
and the URI contains a syntactically valid OCSPRequest ASN.1 structure
|
|
parsable by OpenSSL, or if the method is \fBPOST\fP and the \fBContent-Type\fP
|
|
is \fBapplication/ocsp-request\fP.
|
|
For this to be effective, SSLproxy must be handling traffic destined to the
|
|
port used by the OCSP server. In particular, SSLproxy must be configured to
|
|
receive traffic to all ports used by OCSP servers of targeted certificates
|
|
within the \fIcertdir\fP specified by \fB-t\fP.
|
|
.TP
|
|
.B \-p \fIpidfile\fP
|
|
Write the process ID to \fIpidfile\fP and refuse to run if the \fIpidfile\fP
|
|
is already in use by another process.
|
|
.TP
|
|
.B \-P
|
|
Passthrough SSL/TLS connections which cannot be split instead of dropping them.
|
|
Connections cannot be split if \fB-c\fP and \fB-k\fP are not given and the
|
|
site does not match any certificate loaded using \fB-t\fP, or if the connection
|
|
to the original server gives SSL/TLS errors. Specifically, this happens if the
|
|
site requests a client certificate.
|
|
In these situations, passthrough with \fB-P\fP results in uninterrupted service
|
|
for the clients, while dropping is the more secure alternative if unmonitored
|
|
connections must be prevented.
|
|
Passthrough mode currently does not apply to SSL/TLS errors in the connection
|
|
from the client, since the connection from the client cannot easily be retried.
|
|
Specifically, \fB-P\fP does not currently work for clients that do not accept
|
|
forged certificates.
|
|
.TP
|
|
.B \-q \fIcrlurl\fP
|
|
Set CRL distribution point (CDP) \fIcrlurl\fP on forged leaf certificates.
|
|
Some clients, such as some .NET applications, reject certificates that do not
|
|
carry a CDP. When using \fB-q\fP, you will need to generate an empty CRL
|
|
signed by the CA certificate and key provided with \fB-c\fP and \fB-k\fP, and
|
|
make it available at \fIcrlurl\fP.
|
|
.TP
|
|
.B \-r \fIproto\fP
|
|
Force SSL/TLS protocol version on both client and server side to \fIproto\fP
|
|
by selecting the respective OpenSSL method constructor instead of the default
|
|
SSLv23_method() which supports all protocol versions.
|
|
This is useful when analyzing traffic to a server that only supports a specific
|
|
version of SSL/TLS and does not implement proper protocol negotiation.
|
|
Depending on build options and the version of OpenSSL that is used, the
|
|
following values for \fIproto\fP are accepted: \fBssl2\fP, \fBssl3\fP,
|
|
\fBtls10\fP, \fBtls11\fP and \fBtls12\fP.
|
|
Note that SSL 2.0 support is not built in by default because some servers
|
|
don't handle SSL 2.0 Client Hello messages gracefully.
|
|
.TP
|
|
.B \-R \fIproto\fP
|
|
Disable the SSL/TLS protocol version \fIproto\fP on both client and server
|
|
side by disabling the respective protocols in OpenSSL. To disable multiple
|
|
protocol versions, \fB-R\fP can be given multiple times. If \fI-r\fP is also
|
|
given, there will be no effect in disabling other protocol versions.
|
|
Disabling protocol versions is useful when analyzing traffic to a server that
|
|
does not handle some protocol versions well, or to test behaviour with
|
|
different protocol versions.
|
|
Depending on build options and the version of OpenSSL that is used, the
|
|
following values for \fIproto\fP are accepted: \fBssl2\fP, \fBssl3\fP,
|
|
\fBtls10\fP, \fBtls11\fP and \fBtls12\fP.
|
|
Note that SSL 2.0 support is not built in by default because some servers
|
|
don't handle SSL 2.0 Client Hello messages gracefully.
|
|
.TP
|
|
.B \-s \fIciphers\fP
|
|
Use OpenSSL \fIciphers\fP specification for both server and client SSL/TLS
|
|
connections. If \fB-s\fP is not given, a cipher list of \fBALL:-aNULL\fP is
|
|
used.
|
|
Normally, SSL/TLS implementations choose the most secure cipher suites, not the
|
|
fastest ones. By specifying an appropriate OpenSSL cipher list, the set of
|
|
cipher suites can be limited to fast algorithms, or \fBeNULL\fP cipher suites
|
|
can be added. Note that for connections to be successful, the SSLproxy cipher
|
|
suites must include at least one cipher suite supported by both the client and
|
|
the server of each connection.
|
|
See ciphers(1) for details on how to construct OpenSSL cipher lists.
|
|
.TP
|
|
.B \-S \fIlogdir\fP
|
|
Log connection content to separate log files under \fIlogdir\fP. For each
|
|
connection, a log file will be written, which will contain both directions of
|
|
data as transmitted. Information about the connection will be contained in
|
|
the filename only.
|
|
Only one of \fB-F\fP, \fB-L\fP and \fB-S\fP may be used (last one wins).
|
|
.TP
|
|
.B \-t \fIcertdir\fP
|
|
Use private key, certificate and certificate chain from PEM files in
|
|
\fIcertdir\fP for connections to hostnames matching the respective
|
|
certificates, instead of using certificates forged on-the-fly.
|
|
A single PEM file must contain a single private key, a single certificate and
|
|
optionally intermediate and root CA certificates to use as certificate chain.
|
|
When using \fB-t\fP, SSLproxy will first attempt to use a matching certificate
|
|
loaded from \fIcertdir\fP.
|
|
If \fB-c\fP and \fB-k\fP are also given, certificates will be forged
|
|
on-the-fly for sites matching none of the common names in the certificates
|
|
loaded from \fIcertdir\fP.
|
|
Otherwise, connections matching no certificate will be dropped, or if
|
|
\fB-P\fP is given, passed through without splitting SSL/TLS.
|
|
.TP
|
|
.B \-T \fIaddr\fP
|
|
Mirror connection content as emulated packets to destination address \fIaddr\fP
|
|
on the interface given by \fB-I\fP. Only IPv4 target addresses are currently
|
|
supported. This option is not available if SSLproxy was built without
|
|
mirroring support.
|
|
.TP
|
|
.B \-u \fIuser\fP
|
|
Drop privileges after opening sockets and files by setting the real,
|
|
effective and stored user IDs to \fIuser\fP and loading the appropriate
|
|
primary and ancillary groups. If \fB-u\fP is not given, SSLproxy will drop
|
|
privileges to the stored UID if EUID != UID (setuid bit scenario), or to
|
|
\fBnobody\fP if running with full \fBroot\fP privileges (EUID == UID == 0).
|
|
User \fIuser\fP needs to be allowed to make outbound TCP connections, and in
|
|
some configurations, to also perform DNS resolution.
|
|
Dropping privileges enables privilege separation, which incurs latency for
|
|
certain options, such as separate per-connection log files. By using
|
|
\fB-u root\fP, SSLproxy can be run as root without dropping privileges.
|
|
Due to an Apple bug, \fB-u\fP cannot be used with \fBpf\fP proxyspecs on
|
|
Mac OS X.
|
|
.TP
|
|
.B \-x \fIengine\fP
|
|
Use the OpenSSL engine with identifier \fIengine\fP as a default engine. The
|
|
engine must be available within the OpenSSL ecosystem under the specified
|
|
identifier, that is, they must be loaded from the global OpenSSL configuration.
|
|
If \fIengine\fP is an absolute path, it will be interpreted as path to an
|
|
engine dynamically linked library and loaded by path, regardless of global
|
|
OpenSSL configuration.
|
|
This option is only available if built against a version of OpenSSL with engine
|
|
support.
|
|
.TP
|
|
.B \-X \fIpcapfile\fP
|
|
Log connection content to \fIpcapfile\fP in PCAP format, with emulated TCP, IP
|
|
and Ethernet headers.
|
|
SIGHUP or SIGUSR1 will cause \fIpcapfile\fP to be re-opened.
|
|
Only one of \fB-X\fP, \fB-Y\fP and \fB-y\fP may be used (last one wins).
|
|
.TP
|
|
.B \-Y \fIpcapdir\fP
|
|
Log connection content to separate PCAP files under \fIpcapdir\fP. For each
|
|
connection, a separate PCAP file will be written.
|
|
Only one of \fB-X\fP, \fB-Y\fP and \fB-y\fP may be used (last one wins).
|
|
.TP
|
|
.B \-y \fIpcapspec\fP
|
|
Log connection content to separate PCAP files with the given path specification
|
|
(see LOG SPECIFICATIONS below). For each connection, a separate PCAP file will
|
|
be written.
|
|
Only one of \fB-X\fP, \fB-Y\fP and \fB-y\fP may be used (last one wins).
|
|
.TP
|
|
.B \-V
|
|
Display version and compiled features information and exit.
|
|
.TP
|
|
.B \-w \fIgendir\fP
|
|
Write generated keys and certificates to individual files in \fIgendir\fP.
|
|
For keys, the key identifier is used as filename, which consists of the SHA-1
|
|
hash of the ASN.1 bit string of the public key, as referenced by the
|
|
subjectKeyIdentifier extension in certificates.
|
|
For certificates, the SHA-1 fingerprints of the original and the used (forged)
|
|
certificate are combined to form the filename.
|
|
Note that only newly generated certificates are written to disk.
|
|
.TP
|
|
.B \-W \fIgendir\fP
|
|
Same as \fB-w\fP, but also write original certificates and certificates not
|
|
newly generated, such as those loaded from \fB-t\fP.
|
|
.TP
|
|
.B \-Z
|
|
Disable SSL/TLS compression on all connections. This is useful if your
|
|
limiting factor is CPU, not network bandwidth.
|
|
The \fB-Z\fP option is only available if SSLproxy was built against a version
|
|
of OpenSSL which supports disabling compression.
|
|
.SH "PROXY SPECIFICATIONS"
|
|
Proxy specifications (\fIproxyspecs\fP) consist of the connection type, listen
|
|
address and program port. You can also specify program and return address,
|
|
otherwise they default to the loopback address 127.0.0.1. The program and
|
|
remote address options help you divert packets to remote locations. However,
|
|
beware that the diverted traffic is always unencrypted:
|
|
.LP
|
|
.na
|
|
\fBhttps\fP \fIlistenaddr port\fP \fIup:port\fP
|
|
.br
|
|
\fBhttps\fP \fIlistenaddr port\fP \fIup:port\fP \fIua:addr\fP \fIra:addr\fP
|
|
.br
|
|
\fBpop3s\fP \fIlistenaddr port\fP \fIup:port\fP
|
|
.br
|
|
\fBsmtps\fP \fIlistenaddr port\fP \fIup:port\fP
|
|
.br
|
|
\fBssl\fP \fIlistenaddr port\fP \fIup:port\fP
|
|
.br
|
|
\fBhttp\fP \fIlistenaddr port\fP \fIup:port\fP
|
|
.br
|
|
\fBpop3\fP \fIlistenaddr port\fP \fIup:port\fP
|
|
.br
|
|
\fBsmtp\fP \fIlistenaddr port\fP \fIup:port\fP
|
|
.br
|
|
\fBtcp\fP \fIlistenaddr port\fP \fIup:port\fP
|
|
.ad
|
|
.TP
|
|
\fBhttps\fP
|
|
SSL/TLS interception with HTTP protocol decoding, including the removal of
|
|
HPKP, HSTS, Upgrade and Alternate Protocol response headers.
|
|
This mode currently suppresses WebSockets and HTTP/2.
|
|
.TP
|
|
\fBpop3s\fP
|
|
SSL/TLS interception with POP3 protocol decoding.
|
|
.TP
|
|
\fBsmtps\fP
|
|
SSL/TLS interception with SMTP protocol decoding.
|
|
.TP
|
|
\fBssl\fP
|
|
SSL/TLS interception without any lower level protocol decoding; decrypted
|
|
connection content is treated as opaque stream of bytes and not modified.
|
|
.TP
|
|
\fBhttp\fP
|
|
Plain TCP connection without SSL/TLS, with HTTP protocol decoding, including
|
|
the removal of HPKP, HSTS, Upgrade and Alternate Protocol response headers.
|
|
This mode currently suppresses WebSockets and HTTP/2.
|
|
.TP
|
|
\fBpop3\fP
|
|
Plain POP3 connection without SSL/TLS and with POP3 protocol
|
|
decoding.
|
|
.TP
|
|
\fBsmtp\fP
|
|
Plain SMTP connection without SSL/TLS and with SMTP protocol
|
|
decoding.
|
|
.TP
|
|
\fBtcp\fP
|
|
Plain TCP connection without SSL/TLS and without any lower level protocol
|
|
decoding; decrypted connection content is treated as opaque stream of bytes
|
|
and not modified.
|
|
.TP
|
|
\fBautossl\fP
|
|
Plain TCP connection until a Client Hello SSL/TLS message appears in the byte
|
|
stream, then automatic upgrade to SSL/TLS interception.
|
|
This is generic, protocol-independent STARTTLS support, that may erroneously
|
|
trigger on byte sequences that look like Client Hello messages even though
|
|
there was no actual STARTTLS command issued.
|
|
.TP
|
|
.I listenaddr port
|
|
IPv4 or IPv6 address and port or service name to listen on. This is the
|
|
address and port where the NAT engine should redirect connections to.
|
|
.TP
|
|
.I up:port
|
|
Port or service name that the program is listening for connections. This is the
|
|
port where the traffic should be diverted to.
|
|
.TP
|
|
.I ua:addr
|
|
Address that the program is listening for connections. This is the address
|
|
where the traffic should be diverted to. If not specified, defaults to
|
|
127.0.0.1.
|
|
.TP
|
|
.I ra:addr
|
|
Address that the program should return packets to. This is the address where
|
|
SSLproxy is listening for returned packets from the program. This address is
|
|
inserted into the SSLproxy header line along with the dynamically assigned port
|
|
number. If not specified, defaults to 127.0.0.1.
|
|
.SH SIGNALS
|
|
A running \fBsslproxy\fP accepts SIGINT and SIGQUIT for a clean shutdown, and
|
|
SIGHUP and SIGUSR1 to re-open the single-file log files (such as \fB-l\fP,
|
|
\fB-L\fP and \fB-X\fP). The canonical way to rotate or post-process logs is to
|
|
rename the active log file, send SIGHUP or SIGUSR1 to the PID in the PID file
|
|
given by \fB-p\fP, give SSLproxy some time to flush buffers after closing the
|
|
old file, and then post-process the renamed log file.
|
|
Per-connection log files (such as \fB-S\fP and \fB-F\fP) are not re-opened
|
|
because their filename is specific to the connection.
|
|
.SH "LOG SPECIFICATIONS"
|
|
Log specifications are composed of zero or more printf-style directives;
|
|
ordinary characters are included directly in the output path.
|
|
SSLproxy current supports the following directives:
|
|
.TP
|
|
.I %T
|
|
The initial connection time as an ISO 8601 UTC timestamp.
|
|
.TP
|
|
.I %d
|
|
The destination host and port, separated by a comma, IPv6 addresses using
|
|
underscore instead of colon.
|
|
.TP
|
|
.I %D
|
|
The destination host, IPv6 addresses using underscore instead of colon.
|
|
.TP
|
|
.I %p
|
|
The destination port.
|
|
.TP
|
|
.I %s
|
|
The source host and port, separated by a comma, IPv6 addresses using
|
|
underscore instead of colon.
|
|
.TP
|
|
.I %S
|
|
The source host, IPv6 addresses using underscore instead of colon.
|
|
.TP
|
|
.I %q
|
|
The source port.
|
|
.TP
|
|
.I %x
|
|
The name of the local process.
|
|
Requires \fB-i\fP to be used.
|
|
If process information is unavailable,
|
|
this directive will be omitted from the output path.
|
|
.TP
|
|
.I %X
|
|
The full path of the local process.
|
|
Requires \fB-i\fP to be used.
|
|
If process information is unavailable,
|
|
this directive will be omitted from the output path.
|
|
.TP
|
|
.I %u
|
|
The username or numeric uid of the local process.
|
|
Requires \fB-i\fP to be used.
|
|
If process information is unavailable,
|
|
this directive will be omitted from the output path.
|
|
.TP
|
|
.I %g
|
|
The group name or numeric gid of the local process.
|
|
Requires \fB-i\fP to be used.
|
|
If process information is unavailable,
|
|
this directive will be omitted from the output path.
|
|
.TP
|
|
.I %%
|
|
A literal '%' character.
|
|
.LP
|
|
.SH "NAT ENGINES"
|
|
SSLproxy currently supports the following NAT engines:
|
|
.TP
|
|
.B pf
|
|
OpenBSD packet filter (pf) \fBrdr\fP/\fBrdr-to\fP NAT redirects, also available
|
|
on FreeBSD, NetBSD and Mac OS X.
|
|
Fully supported, including IPv6.
|
|
Note that SSLproxy needs permission to open \fB/dev/pf\fP for reading, which by
|
|
default means that it needs to run under \fBroot\fP privileges.
|
|
Assuming inbound interface \fBem0\fP, first in old (FreeBSD, Mac OS X),
|
|
then in new (OpenBSD 4.7+) syntax:
|
|
.LP
|
|
.RS
|
|
.nf
|
|
\fBrdr pass on em0 proto tcp from 2001:db8::/64 to any port 80 \\
|
|
-> ::1 port 10080\fP
|
|
\fBrdr pass on em0 proto tcp from 2001:db8::/64 to any port 443 \\
|
|
-> ::1 port 10443\fP
|
|
\fBrdr pass on em0 proto tcp from 192.0.2.0/24 to any port 80 \\
|
|
-> 127.0.0.1 port 10080\fP
|
|
\fBrdr pass on em0 proto tcp from 192.0.2.0/24 to any port 443 \\
|
|
-> 127.0.0.1 port 10443\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
.RS
|
|
.nf
|
|
\fBpass in quick on em0 proto tcp from 2001:db8::/64 to any \\
|
|
port 80 rdr-to ::1 port 10080\fP
|
|
\fBpass in quick on em0 proto tcp from 2001:db8::/64 to any \\
|
|
port 443 rdr-to ::1 port 10443\fP
|
|
\fBpass in quick on em0 proto tcp from 192.0.2.0/24 to any \\
|
|
port 80 rdr-to 127.0.0.1 port 10080\fP
|
|
\fBpass in quick on em0 proto tcp from 192.0.2.0/24 to any \\
|
|
port 443 rdr-to 127.0.0.1 port 10443\fP
|
|
.fi
|
|
.RE
|
|
.TP
|
|
.B ipfw
|
|
FreeBSD IP firewall (IPFW) divert sockets, also available on Mac OS X.
|
|
Available on FreeBSD and OpenBSD using pf \fBdivert-to\fP.
|
|
Fully supported on FreeBSD and OpenBSD, including IPv6.
|
|
Only supports IPv4 on Mac OS X due to the ancient version of IPFW included.
|
|
First in IPFW, then in pf \fBdivert-to\fP syntax:
|
|
.LP
|
|
.RS
|
|
.nf
|
|
\fBipfw add fwd ::1,10080 tcp from 2001:db8::/64 to any 80\fP
|
|
\fBipfw add fwd ::1,10443 tcp from 2001:db8::/64 to any 443\fP
|
|
\fBipfw add fwd 127.0.0.1,10080 tcp from 192.0.2.0/24 to any 80\fP
|
|
\fBipfw add fwd 127.0.0.1,10443 tcp from 192.0.2.0/24 to any 443\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
.RS
|
|
.nf
|
|
\fBpass in quick on em0 proto tcp from 2001:db8::/64 to any \\
|
|
port 80 divert-to ::1 port 10080\fP
|
|
\fBpass in quick on em0 proto tcp from 2001:db8::/64 to any \\
|
|
port 443 divert-to ::1 port 10443\fP
|
|
\fBpass in quick on em0 proto tcp from 192.0.2.0/24 to any \\
|
|
port 80 divert-to 127.0.0.1 port 10080\fP
|
|
\fBpass in quick on em0 proto tcp from 192.0.2.0/24 to any \\
|
|
port 443 divert-to 127.0.0.1 port 10443\fP
|
|
.fi
|
|
.RE
|
|
.TP
|
|
.B ipfilter
|
|
IPFilter (ipfilter, ipf), available on many systems, including FreeBSD, NetBSD,
|
|
Linux and Solaris.
|
|
Note that SSLproxy needs permission to open \fB/dev/ipnat\fP for reading, which
|
|
by default means that it needs to run under \fBroot\fP privileges.
|
|
Only supports IPv4 due to limitations in the SIOCGNATL ioctl(2) interface.
|
|
Assuming inbound interface \fBbge0\fP:
|
|
.LP
|
|
.RS
|
|
.nf
|
|
\fBrdr bge0 0.0.0.0/0 port 80 -> 127.0.0.1 port 10080\fP
|
|
\fBrdr bge0 0.0.0.0/0 port 443 -> 127.0.0.1 port 10443\fP
|
|
.fi
|
|
.RE
|
|
.TP
|
|
.B netfilter
|
|
Linux netfilter using the iptables REDIRECT target.
|
|
Fully supported including IPv6 since Linux v3.8-rc1; on older kernels only
|
|
supports IPv4 due to limitations in the SO_ORIGINAL_DST getsockopt(2)
|
|
interface.
|
|
.LP
|
|
.RS
|
|
.nf
|
|
\fBiptables -t nat -A PREROUTING -s 192.0.2.0/24 \\
|
|
-p tcp --dport 80 \\
|
|
-j REDIRECT --to-ports 10080\fP
|
|
\fBiptables -t nat -A PREROUTING -s 192.0.2.0/24 \\
|
|
-p tcp --dport 443 \\
|
|
-j REDIRECT --to-ports 10443\fP
|
|
\fB# please contribute a tested ip6tables config\fP
|
|
.fi
|
|
.LP
|
|
Note that SSLproxy is only able to accept incoming connections if it binds
|
|
to the correct IP address (e.g. 192.0.2.1) or on all interfaces (0.0.0.0).
|
|
REDIRECT uses the local interface address of the incoming interface as
|
|
target IP address, or 127.0.0.1 for locally generated packets.
|
|
.RE
|
|
.TP
|
|
.B tproxy
|
|
Linux netfilter using the iptables TPROXY target together with routing
|
|
table magic to allow non-local traffic to originate on local sockets.
|
|
Fully supported, including IPv6.
|
|
.LP
|
|
.RS
|
|
.nf
|
|
\fBip -f inet6 rule add fwmark 1 lookup 100\fP
|
|
\fBip -f inet6 route add local default dev lo table 100\fP
|
|
\fBip6tables -t mangle -N DIVERT\fP
|
|
\fBip6tables -t mangle -A DIVERT -j MARK --set-mark 1\fP
|
|
\fBip6tables -t mangle -A DIVERT -j ACCEPT\fP
|
|
\fBip6tables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT\fP
|
|
\fBip6tables -t mangle -A PREROUTING -s 2001:db8::/64 \\
|
|
-p tcp --dport 80 \\
|
|
-j TPROXY --tproxy-mark 0x1/0x1 --on-port 10080\fP
|
|
\fBip6tables -t mangle -A PREROUTING -s 2001:db8::/64 \\
|
|
-p tcp --dport 443 \\
|
|
-j TPROXY --tproxy-mark 0x1/0x1 --on-port 10443\fP
|
|
\fBip -f inet rule add fwmark 1 lookup 100\fP
|
|
\fBip -f inet route add local default dev lo table 100\fP
|
|
\fBiptables -t mangle -N DIVERT\fP
|
|
\fBiptables -t mangle -A DIVERT -j MARK --set-mark 1\fP
|
|
\fBiptables -t mangle -A DIVERT -j ACCEPT\fP
|
|
\fBiptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT\fP
|
|
\fBiptables -t mangle -A PREROUTING -s 192.0.2.0/24 \\
|
|
-p tcp --dport 80 \\
|
|
-j TPROXY --tproxy-mark 0x1/0x1 --on-port 10080\fP
|
|
\fBiptables -t mangle -A PREROUTING -s 192.0.2.0/24 \\
|
|
-p tcp --dport 443 \\
|
|
-j TPROXY --tproxy-mark 0x1/0x1 --on-port 10443\fP
|
|
.fi
|
|
.LP
|
|
Note that return path filtering (rp_filter) also needs to be disabled on
|
|
interfaces which handle TPROXY redirected traffic.
|
|
.RE
|
|
.SH EXAMPLES
|
|
With configuration similar to the above NAT engine samples, intercept HTTPS and
|
|
POP3S over IPv4 using forged certificates with CA private key \fBca.key\fP and
|
|
certificate \fBca.crt\fP, logging connections to \fBconnect.log\fP and
|
|
connection data into separate files under \fB/tmp\fP (add \fB-e\fP
|
|
\fInat-engine\fP to select the appropriate engine if multiple engines are
|
|
available on your system) and diverting packets to a program running on address
|
|
127.0.0.1 and port 8080 for HTTPS and to another program running on address
|
|
127.0.0.1 and port 8110 for POP3S:
|
|
.LP
|
|
.nf
|
|
\fBsslproxy -k ca.key -c ca.crt -l connect.log -L /tmp \\
|
|
https 127.0.0.1 8443 up:8080 \\
|
|
pop3s 127.0.0.1 8995 up:8110\fP
|
|
.fi
|
|
.LP
|
|
To generate a CA private key \fBca.key\fP and certificate \fBca.crt\fP using
|
|
OpenSSL:
|
|
.LP
|
|
.nf
|
|
\fBcat >x509v3ca.cnf <<'EOF'\fP
|
|
[ req ]
|
|
distinguished_name = reqdn
|
|
|
|
[ reqdn ]
|
|
|
|
[ v3_ca ]
|
|
basicConstraints = CA:TRUE
|
|
subjectKeyIdentifier = hash
|
|
authorityKeyIdentifier = keyid:always,issuer:always
|
|
\fBEOF\fP
|
|
|
|
\fBopenssl genrsa -out ca.key 2048\fP
|
|
\fBopenssl req -new -nodes -x509 -sha256 -out ca.crt -key ca.key \\
|
|
-config x509v3ca.cnf -extensions v3_ca \\
|
|
-subj '/O=SSLproxy Root CA/CN=SSLproxy Root CA/' \\
|
|
-set_serial 0 -days 3650\fP
|
|
.fi
|
|
.SH NOTES
|
|
SSLproxy is able to handle a relatively high number of listeners and
|
|
connections due to a multithreaded, event based architecture based on libevent,
|
|
taking advantage of platform specific select() replacements such as kqueue.
|
|
The main thread handles the listeners and signaling, while a number of worker
|
|
threads equal to twice the number of CPU cores is used for handling the actual
|
|
connections in separate event bases, including the CPU-intensive SSL/TLS
|
|
handling.
|
|
.LP
|
|
Care has been taken to choose well-performing data structures for caching
|
|
certificates and SSL sessions. Logging is implemented in separate disk writer
|
|
threads to ensure that socket event handling threads don't have to block on
|
|
disk I/O.
|
|
DNS lookups are performed asynchronously.
|
|
SSLproxy uses SSL session caching on both ends to minimize the amount of full
|
|
SSL handshakes, but even then, the limiting factor in handling SSL connections
|
|
are the actual bignum computations.
|
|
.LP
|
|
For high performance and low latency and when running SSLproxy as root or
|
|
otherwise in a privilege separation mode, avoid using options which require a
|
|
privileged operation to be invoked through privilege separation for each
|
|
connection. These are currently all per-connection log types:
|
|
content log to per-stream file in dir or filespec (\fB-F\fP, \fB-S\fP),
|
|
content log to per-stream PCAP in dir or filespec (\fB-Y\fP, \fB-y\fP), and
|
|
generated or all certificates to files in directory (\fB-w\fP, \fB-W\fP).
|
|
Instead, use the respective single-file variants where available.
|
|
It is possible, albeit not recommended, to bypass the default privilege
|
|
separation when run as root by using \fB-u root\fP, thereby bypassing
|
|
privilege separation entirely.
|
|
.SH "SEE ALSO"
|
|
sslproxy.conf(5), openssl(1), ciphers(1), speed(1),
|
|
pf(4), ipfw(8), iptables(8), ip6tables(8), ip(8),
|
|
hostapd(8), arpspoof(8), parasite6(8), yersinia(8),
|
|
.I https://www.roe.ch/SSLsplit,
|
|
.I https://github.com/sonertari/SSLproxy
|
|
.SH AUTHORS
|
|
SSLsplit was written by Daniel Roethlisberger <daniel@roe.ch>.
|
|
SSLsplit is currently maintained by Daniel Roethlisberger and Soner Tari.
|
|
.LP
|
|
SSLproxy has been developed by Soner Tari <sonertari@gmail.com>.
|
|
.LP
|
|
|
|
The following individuals have contributed code or documentation, in
|
|
chronological order of their first contribution:
|
|
Steve Wills, Landon Fuller, Wayne Jensen, Rory McNamara, Alexander Neumann,
|
|
Adam Jacob Muller, Richard Poole, Maciej Kotowicz, Eun Soo Park, Christian
|
|
Groschupp, Alexander Savchenkov, Soner Tari, Petr Vanek, Hilko Bengen,
|
|
Philip Duldig, Levente Polyak, Nick French and Cihan Komecoglu.
|
|
|
|
SSLsplit contains work sponsored by HackerOne.
|
|
.SH BUGS
|
|
Use Github for submission of bug reports or patches:
|
|
.LP
|
|
.RS
|
|
.I https://github.com/droe/sslsplit
|
|
.LP
|
|
.I https://github.com/sonertari/sslproxy
|
|
.RE
|
|
.LP
|