SSLproxy/sslproxy.1

.\"-
.\" 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" "07 Mar 2019" "v0.5.10" "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
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