From 2b9cb937fd4046f80cd8d498948eac990d1922ad Mon Sep 17 00:00:00 2001 From: Soner Tari Date: Sat, 8 May 2021 11:17:27 +0300 Subject: [PATCH] Improve documentation --- README.md | 9 +++++- src/sslproxy.1 | 81 ++++++++++++++++++++++++++++++-------------------- 2 files changed, 56 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index ea9ccc4..57a1849 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/src/sslproxy.1 b/src/sslproxy.1 index ca9454b..9ed4780 100644 --- a/src/sslproxy.1 +++ b/src/sslproxy.1 @@ -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