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.
1198 lines
54 KiB
Groff
1198 lines
54 KiB
Groff
.\"-
|
|
.\" SSLproxy - transparent SSL/TLS proxy for decrypting and diverting network
|
|
.\" traffic to other programs for deep SSL inspection
|
|
.\" https://github.com/sonertari/SSLproxy
|
|
.\"
|
|
.\" Copyright (c) 2009-2019, Daniel Roethlisberger <daniel@roe.ch>.
|
|
.\" Copyright (c) 2017-2021, Soner Tari <sonertari@gmail.com>.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" 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" "29 August 2021" "v0.8.7" "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, for deep SSL inspection.
|
|
.LP
|
|
The UTMFW project uses SSLproxy to decyrpt 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, it wouldn't be
|
|
possible without SSLproxy to deeply inspect most of the network traffic
|
|
passing through UTMFW.
|
|
.SH 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.
|
|
.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
|
|
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 non-existent in SSLsplit, such as user authentication and
|
|
protocol validation. Also, note that the implementation of proxy core in
|
|
SSLproxy is different from the one in SSLsplit, for example the proxy core in
|
|
SSLproxy runs lockless, whereas SSLsplit implementation uses thread manager
|
|
level locks (which does not necessarily make sslproxy run faster than
|
|
sslsplit). In SSLproxy, split mode can be defined globally or per-proxyspec.
|
|
.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.
|
|
.SH Proxy specification
|
|
For example, given the following proxy specification:
|
|
.LP
|
|
https 127.0.0.1 8443 up:8080
|
|
.LP
|
|
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.
|
|
.LP
|
|
The response from the Server follows the same path back to the Client in
|
|
reverse order.
|
|
.LP
|
|
See the SSLsplit documentation for split style and structured proxyspecs.
|
|
.SH SSLproxy line
|
|
A sample line SSLproxy inserts into the first packet in the connection is the
|
|
following:
|
|
.LP
|
|
SSLproxy: [127.0.0.1]:34649,[192.168.3.24]:47286,[192.168.111.130]:443,s
|
|
.LP
|
|
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, e.g
|
|
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.
|
|
.SH Listening program
|
|
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
|
|
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.
|
|
.LP
|
|
You can offload the system SSLproxy is running on by diverting packets to
|
|
remote listening programs too. For example, given the following proxy
|
|
specification:
|
|
.LP
|
|
https 127.0.0.1 8443 up:8080 ua:192.168.0.1 ra:192.168.1.1
|
|
.LP
|
|
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. Also, 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.
|
|
.LP
|
|
Accordingly, the SSLproxy line now becomes:
|
|
.LP
|
|
SSLproxy: [192.168.1.1]:34649,[192.168.3.24]:47286,[192.168.111.130]:443,s
|
|
.LP
|
|
So, the listening program can be running on a machine anywhere in the world.
|
|
Since the packets between SSLproxy and the listening program are always
|
|
unencrypted, you should be careful while using such a setup.
|
|
.SH Protocols
|
|
.SH Supported protocols
|
|
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. Depending on the version of OpenSSL,
|
|
SSLproxy supports SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2, and TLS 1.3, and
|
|
optionally SSL 2.0 as well. SSLproxy supports Server Name Indication (SNI),
|
|
but not Encrypted SNI in TLS 1.3. It is able to work with RSA, DSA and ECDSA
|
|
keys and DHE and ECDHE cipher suites.
|
|
.LP
|
|
The following features of SSLproxy are IPv4 only:
|
|
- Divert addresses for listening programs in proxyspecs
|
|
- SSLproxy return addresses dynamically assigned to connections
|
|
- IP addresses in the ua and ra options
|
|
- IP and ethernet addresses of clients in user authentication
|
|
- Target IP and ethernet addresses in mirror logging
|
|
.LP
|
|
.SH OCSP, HPKP, HSTS, Upgrade et al.
|
|
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 configured by
|
|
the ConnIdleTimeout option.
|
|
.SH Protocol validation
|
|
Protocol validation makes sure the traffic handled by a proxyspec is using the
|
|
protocol specified in that proxyspec. The ValidateProto option can be used to
|
|
enable global and/or per-proxyspec protocol validation. This feature currently
|
|
supports HTTP, POP3, and SMTP protocols. If a connection cannot pass protocol
|
|
validation, then it is terminated.
|
|
.LP
|
|
SSLproxy uses only client requests for protocol validation. However, it also
|
|
validates SMTP responses until it starts processing the packets from the
|
|
client. If there is no excessive fragmentation, the first couple of packets in
|
|
the connection should be enough for validating protocols.
|
|
.SH Certificates
|
|
.SH Certificate forging
|
|
For SSL and HTTPS 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.
|
|
.SH Certificate verification
|
|
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. See the risks of SSL inspection for the reasons of this difference. You
|
|
can disable this feature by the VerifyPeer option.
|
|
.SH Client certificates
|
|
SSLproxy uses the certificate and key from the pemfiles configured by the
|
|
ClientCert and ClientKey options when the destination requests client
|
|
certificates. These options can be defined globally and/or per-proxyspec.
|
|
.LP
|
|
Alternatively, you can use Pass filtering rules to pass through certain
|
|
destinations requesting client certificates.
|
|
.SH User authentication
|
|
If the UserAuth option is enabled, SSLproxy requires network users to log in
|
|
to the system to establish connections to the external network.
|
|
.LP
|
|
SSLproxy determines the user owner of a connection using a users table in an
|
|
SQLite3 database 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
|
|
SSLproxy does not create this users table or the database file by itself, nor
|
|
does it log users in or out. So the database file and the users table should
|
|
already exist at the location pointed to by the UserDBPath option. An external
|
|
program should log users in and out on the users table. The external program
|
|
should fill out all the fields in user records, except perhaps for the DESC
|
|
field, which can be left blank.
|
|
.LP
|
|
When SSLproxy accepts a connection,
|
|
.LP
|
|
- It searches the client IP address of the connection in the users table. If
|
|
the client IP address is not in the users table, the connection is redirected
|
|
to a login page configured by the UserAuthURL option.
|
|
- If SSLproxy finds a user record for the client IP address in the users
|
|
table, it obtains the ethernet address of the client IP address from the arp
|
|
cache of the system, and compares it with the value in the user record for
|
|
that IP address. If the ethernet addresses do not match, the connection is
|
|
redirected to the login page.
|
|
- If the ethernet addresses match, SSLproxy compares the atime value in the
|
|
user record with the current system time. If the difference is greater than
|
|
the value configured by the UserTimeout option, the connection is redirected
|
|
to the login page.
|
|
.LP
|
|
If the connection passes all these checks, SSLproxy proceeds with establishing
|
|
the connection.
|
|
.LP
|
|
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 executed
|
|
using a privsep command, it is expensive. So, to reduce the frequency of such
|
|
updates, it is deferred until after the user idle time is more than half of
|
|
the timeout period.
|
|
.LP
|
|
If a description text is provided in the DESC field, it can be used with
|
|
filtering rules to treat the user logged in from different locations, i.e.
|
|
from different client IP addresses, separately.
|
|
.LP
|
|
If the UserAuth option is enabled, the user owner of the connection is
|
|
appended at the end of the SSLproxy line, so that the listening program can
|
|
parse and use this information in its logic and/or logging:
|
|
.LP
|
|
SSLproxy: [127.0.0.1]:34649,[192.168.3.24]:47286,[192.168.111.130]:443,s,soner
|
|
.LP
|
|
The user authentication feature is currently available on OpenBSD and Linux
|
|
only.
|
|
.SH Filtering rules
|
|
.LP
|
|
SSLproxy can divert, split, pass, block, or match connections based on filtering
|
|
rules. Filtering rules can be defined globally or per-proxyspec.
|
|
.LP
|
|
- Divert action diverts packets to listening program, allowing SSL inspection
|
|
by listening program and content logging of packets
|
|
- Split action splits the connection but does not divert packets to listening
|
|
program, effectively disabling SSL inspection by listening program, but
|
|
allowing content logging of packets
|
|
- Pass action passes the connection through by engaging passthrough mode,
|
|
effectively disabling SSL inspection and content logging of packets
|
|
- Block action terminates the connection
|
|
- Match action specifies log actions for the connection without changing its
|
|
filter action
|
|
.LP
|
|
The syntax of filtering rules is as follows:
|
|
|
|
(Divert|Split|Pass|Block|Match)
|
|
([from (
|
|
user (username[*]|$macro|*) [desc (desc[*]|$macro|*)]|
|
|
desc (desc[*]|$macro|*)|
|
|
ip (clientip[*]|$macro|*)|
|
|
*)]
|
|
[to (
|
|
sni (servername[*]|$macro|*)|
|
|
cn (commonname[*]|$macro|*)|
|
|
host (host[*]|$macro|*)|
|
|
uri (uri[*]|$macro|*)|
|
|
ip (serverip[*]|$macro|*) [port (serverport[*]|$macro|*)]|
|
|
port (serverport[*]|$macro|*)|
|
|
*)]
|
|
[log ([[!]connect] [[!]master] [[!]cert]
|
|
[[!]content] [[!]pcap] [[!]mirror] [$macro]|[!]*)]
|
|
|*)
|
|
.LP
|
|
The definition of which connections the rule action will be applied to is
|
|
achieved by the from and to parts of a filtering rule and by the proxyspec
|
|
that the rule is defined for.
|
|
.LP
|
|
- The from part of a rule defines source filter based on client IP address,
|
|
user and/or description, or * for all.
|
|
- The to part defines destination filter based on server IP address, SNI or
|
|
Common Names of SSL connections, Host or URI fields in HTTP Request headers, or
|
|
* for all.
|
|
+ Dst Host type of rules use ip and port site fields
|
|
+ SSL type of rules use sni and cn site fields
|
|
+ HTTP type of rules use host and uri site fields
|
|
.br
|
|
- The proxyspec handling the connection defines the protocol filter for the
|
|
connection.
|
|
.LP
|
|
If and how a connection should be logged is specified using the log part of
|
|
filtering rules:
|
|
.LP
|
|
- connect enables logging connection information to connect log file
|
|
- master enables logging of master keys
|
|
- cert enables logging of generated certificates
|
|
- content enables logging packet contents to content log file
|
|
- pcap enables writing packets to pcap files
|
|
- mirror enables mirroring packets to mirror interfaces or targets
|
|
.LP
|
|
You can add a negation prefix ! to a log action to disable that logging.
|
|
.LP
|
|
For example, if the following rules are defined in a structured HTTPS proxyspec,
|
|
.LP
|
|
Split from user soner desc notebook to sni example.com log content
|
|
Pass from user soner desc android to cn .fbcdn.net*
|
|
.LP
|
|
The first filtering rule above splits but does not divert HTTPS connections
|
|
from the user soner who has logged in with the description notebook to SSL
|
|
sites with the SNI of example.com. Also, the rule specifies that the packet
|
|
contents of the matching connection be written to content log file configured
|
|
globally.
|
|
.LP
|
|
The second rule passes through HTTPS connections from the user soner who has
|
|
logged in with the description android to SSL sites with the Common Names
|
|
containing the substring .fbcdn.net anywhere in it (notice the asterisk at the
|
|
end). Since connection contents cannot be written to log files in passthrough
|
|
mode, the rule does not specify any content log action.
|
|
.LP
|
|
The default filter action is Divert. So, if those are the only filtering rules
|
|
in that proxyspec, the other connections are diverted to the listening program
|
|
specified in that proxyspec, without writing any logs.
|
|
.LP
|
|
If you want to enable, say, connect logging for the other connections handled
|
|
by that proxyspec, without changing their default Divert filter action, you
|
|
can add a third filtering rule to that proxyspec:
|
|
.LP
|
|
Match * log connect
|
|
.LP
|
|
Note that the second example above is a filtering rule you can use to resolve
|
|
one of the certificate issues preventing the Facebook application on Android
|
|
smartphones to connect to the Internet behind sslproxy.
|
|
.LP
|
|
Filtering rules are applied based on certain precedence orders:
|
|
.LP
|
|
- More specific rules have higher precedence.
|
|
- The precedence of filter types is as HTTP > SSL > Dst Host. Because, the
|
|
application order of filter types is as Dst Host > SSL > HTTP, and a filter
|
|
type can override the actions of a preceding filter type.
|
|
- The precedence of filter actions is as Divert > Split > Pass > Block. This is
|
|
only for the same type of filtering rules.
|
|
- The precedence of site fields is as sni > cn for SSL filter and host > uri
|
|
for HTTP filter.
|
|
.LP
|
|
For example, the pass action of a Dst Host filter rule is taken before the
|
|
split action of an SSL filter rule with the same from definition, due to the
|
|
precedence order of filter types. Or, the pass action of a rule with sni site
|
|
field is taken before the split action of the same rule with cn site field, due
|
|
to the precedence order of site fields.
|
|
.LP
|
|
In terms of possible filter actions,
|
|
.LP
|
|
- Dst Host filtering rules can take all of the filter and log actions.
|
|
- SSL filtering rules can take all of the filter and log actions.
|
|
- HTTP filtering rules can take match and block filter actions, can keep
|
|
enabled divert and split modes, but cannot take pass action. Also, HTTP
|
|
filtering rules can only disable logging.
|
|
.LP
|
|
Log actions do not configure any loggers. Global loggers for respective log
|
|
actions should have been configured for those log actions to have any effect.
|
|
.LP
|
|
If no filtering rules are defined for a proxyspec, all log actions for that
|
|
proxyspec are enabled. Otherwise, all log actions are disabled, and filtering
|
|
rules should enable them specifically.
|
|
.LP
|
|
Macro expansion is supported. The Define option can be used for defining
|
|
macros to be used in filtering rules. Macro names must start with a $ char.
|
|
The macro name must be followed by words separated with spaces.
|
|
.LP
|
|
You can append an asterisk * to the fields in filtering rules for substring
|
|
matching. Otherwise, the filter searches for an exact match with the field in
|
|
the rule. The filter uses B-trees for exact string matching and Aho-Corasick
|
|
machines for substring matching.
|
|
.LP
|
|
The ordering of filtering rules is important. The ordering of from, to, and
|
|
log parts is not important. The ordering of log actions is not important.
|
|
.LP
|
|
If the UserAuth option is disabled, only client IP addresses can be used in
|
|
the from part of filtering rules.
|
|
.SH Excluding sites from SSL inspection
|
|
PassSite option is a special form of Pass filtering rule. PassSite rules can
|
|
be written as Pass filtering rules. The PassSite option will be deprecated in
|
|
favor of filtering rules in the future.
|
|
.LP
|
|
PassSite option allows certain SSL sites to be excluded from SSL inspection.
|
|
If a PassSite matches the SNI or common names in the SSL certificate of a
|
|
connection, that connection is passed through the proxy without being diverted
|
|
to the listening program. SSLproxy engages the Passthrough mode for that
|
|
purpose. For example, sites requiring client authentication can be added as
|
|
PassSite.
|
|
.LP
|
|
Per-site filters can be defined using client IP addresses, users, and
|
|
description. If the UserAuth option is disabled, only client IP addresses can
|
|
be used in PassSite filters. Multiple sites can be defined, one on each line.
|
|
PassSite rules can search for exact or substring matches. PassSite rules do
|
|
not support macro expansion.
|
|
.SH User control lists
|
|
User control lists can be implemented using filtering rules. The DivertUsers
|
|
and PassUsers options will be deprecated in favor of filtering rules in the
|
|
future.
|
|
.LP
|
|
DivertUsers and PassUsers options can be used to divert, pass through, or
|
|
block users.
|
|
.LP
|
|
- If neither DivertUsers nor PassUsers is defined, all users are diverted to
|
|
listening programs.
|
|
- Connections from users in DivertUsers, if defined, are diverted to listening
|
|
programs.
|
|
- Connections from users in PassUsers, if defined, are simply passed through
|
|
to their original destinations. SSLproxy engages the Passthrough mode for that
|
|
purpose.
|
|
- If both DivertUsers and PassUsers are defined, users not listed in either of
|
|
the lists are blocked. SSLproxy simply terminates their connections.
|
|
- If *no* DivertUsers list is defined, only users *not* listed in PassUsers
|
|
are diverted to listening programs.
|
|
.LP
|
|
These user control lists can be defined globally or per-proxyspec. User
|
|
control lists do not support macro expansion.
|
|
.SH Logging
|
|
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. Filtering rules can selectively modify connection logging.
|
|
.SH OPTIONS
|
|
.TP
|
|
.B \-a \fIpemfile\fP
|
|
Use client certificate from \fIpemfile\fP when destination server requests a
|
|
client certificate.
|
|
.TP
|
|
.B \-A \fIpemfile\fP
|
|
Use private key, certificate and certificate chain from PEM file \fIpemfile\fP
|
|
as leaf certificate instead of generating a leaf certificate on the fly.
|
|
The 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-t\fP is also used and a connection matches any certificate in the
|
|
directory specified with the \fB-t\fP option, that matching certificate is used
|
|
instead, taking precedence over the certificate specified with \fB-A\fP.
|
|
.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. Configuration files can use the
|
|
Include option for loading configuration from an include file too. Note that
|
|
the ordering of options, rules, and proxyspecs in configuration files (and on
|
|
the command line) is important. For example, rules and proxyspecs can only
|
|
make use of the options defined earlier.
|
|
.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. If \fB-T\fP is omitted, the
|
|
packets are blindly pushed to \fIif\fP.
|
|
.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 2048-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
|
|
Quit after loading and testing configuration.
|
|
.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, \fBtls12\fP, and \fBtls13\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, \fBtls12\fP, and \fBtls13\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 \-n
|
|
Enable split mode of operation for all proxyspecs, effectively making sslproxy
|
|
behave like sslsplit.
|
|
.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"
|
|
SSLproxy supports two types of proxy specifications: one line and structured.
|
|
The structured proxy specifications provide more configuration options, but
|
|
can only be defined in configuration files. See sslproxy.conf(5) and the
|
|
sample configuration file in the sources for details.
|
|
.LP
|
|
One line proxy specifications (\fIproxyspecs\fP) consist of the connection
|
|
type, listen address and program port. You can also specify program and return
|
|
addresses, otherwise they default to the loopback address 127.0.0.1. The
|
|
program and return 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 "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 SIGNALS
|
|
A running \fBsslproxy\fP accepts SIGINT and SIGTERM for a clean shutdown 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 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 "EXIT STATUS"
|
|
The \fBsslproxy\fP process will exit with 0 on regular shutdown
|
|
(SIGINT, SIGTERM), and 128 + signal number on controlled shutdown based on
|
|
receiving a different signal such as SIGHUP. Exit status in the range 1..127
|
|
indicates error conditions.
|
|
.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
|