Improve documentation

pull/48/head
Soner Tari 3 years ago
parent 0bd1a414cb
commit 2b9cb937fd

@ -46,6 +46,13 @@ 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.
SSLproxy does not automagically redirect any network traffic. To actually
implement a proxy, you also need to redirect the traffic to the system running
sslproxy. Your options include running sslproxy on a legitimate router, ARP
spoofing, ND spoofing, DNS poisoning, deploying a rogue access point (e.g.
using hostap mode), physical recabling, malicious VLAN reconfiguration or
route injection, /etc/hosts modification and so on.
#### Proxy specification
For example, given the following proxy specification:
@ -258,7 +265,7 @@ 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
- 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.

@ -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

Loading…
Cancel
Save