|
|
|
@ -83,6 +83,13 @@ 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 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
|
|
|
|
@ -90,12 +97,14 @@ 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. After processing the packets, the Program gives
|
|
|
|
|
them back to SSLproxy listening on a dynamically assigned address, which the
|
|
|
|
|
Program obtains from the SSLproxy line in the first packet in the connection.
|
|
|
|
|
Then SSLproxy re-encrypts and sends the packets to the Server. The response
|
|
|
|
|
from the Server follows the same path to the Client in reverse
|
|
|
|
|
order.
|
|
|
|
|
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.
|
|
|
|
|
.SH SSLproxy line
|
|
|
|
|
A sample line SSLproxy inserts into the first packet in the connection is the
|
|
|
|
|
following:
|
|
|
|
@ -106,12 +115,12 @@ 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, hence
|
|
|
|
|
must rely on the information in this SSLproxy line. The last letter is either
|
|
|
|
|
s or p, for SSL/TLS encrypted or plain traffic respectively. This information
|
|
|
|
|
is also important for the program, because it cannot reliably determine if the
|
|
|
|
|
actual network traffic it is processing was encrypted or not
|
|
|
|
|
before being diverted to it.
|
|
|
|
|
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
|
|
|
|
@ -131,10 +140,11 @@ specification:
|
|
|
|
|
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 example. Also, the ra option
|
|
|
|
|
instructs SSLproxy to listen for returned packets from the program on
|
|
|
|
|
192.168.1.1. Accordingly, the line SSLproxy inserts into the first packet in
|
|
|
|
|
the connection now becomes:
|
|
|
|
|
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
|
|
|
|
@ -151,6 +161,14 @@ 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
|
|
|
|
@ -190,7 +208,8 @@ 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.
|
|
|
|
|
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
|
|
|
|
@ -215,7 +234,7 @@ CREATE TABLE USERS(
|
|
|
|
|
);
|
|
|
|
|
.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 this table should
|
|
|
|
|
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
|
|
|
|
@ -256,17 +275,20 @@ 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.
|
|
|
|
|
- Users not listed in DivertUsers or PassUsers are blocked.
|
|
|
|
|
- If no DivertUsers list is defined, only users *not* listed in PassUsers are
|
|
|
|
|
diverted to listening programs.
|
|
|
|
|
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.
|
|
|
|
|
.SH Servers Excluded from SSL Inspection
|
|
|
|
|
.SH Excluding sites from SSL inspection
|
|
|
|
|
PassSite option allows certain SSL sites to be excluded from SSL inspection.
|
|
|
|
|
If a PassSite matches SNI or common names in the SSL certificate, the
|
|
|
|
|
connection is passed through the proxy without being diverted to the listening
|
|
|
|
|
program. For example, sites requiring client authentication can be added as
|
|
|
|
|
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
|
|
|
|
@ -278,13 +300,6 @@ 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.
|
|
|
|
|
.SH OPTIONS
|
|
|
|
|
.TP
|
|
|
|
|
.B \-a \fIpemfile\fP
|
|
|
|
|