diff --git a/README.md b/README.md index d069ce0..3d85b19 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ For example, given the following proxy specification: https 127.0.0.1 8443 up:8080 -The SSLproxy listens for HTTPS connections on 127.0.0.1:8443. Upon receiving a +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 @@ -313,7 +313,8 @@ With the requirements above available, run: Dependencies are autoconfigured using pkg-config. If dependencies are not picked up and fixing `PKG_CONFIG_PATH` does not help, you can specify their respective locations manually by setting `OPENSSL_BASE`, `LIBEVENT_BASE`, -`LIBPCAP_BASE`, `LIBNET_BASE` and/or `CHECK_BASE` to the respective prefixes. +`LIBPCAP_BASE`, `LIBNET_BASE`, `SQLITE_BASE` and/or `CHECK_BASE` to the +respective prefixes. You can override the default install prefix (`/usr/local`) by setting `PREFIX`. For more build options and build-time defaults see [`GNUmakefile`](GNUmakefile) diff --git a/src/sslproxy.1 b/src/sslproxy.1 index 4c8df97..48ea83e 100644 --- a/src/sslproxy.1 +++ b/src/sslproxy.1 @@ -1,14 +1,12 @@ .\"- -.\" SSLproxy - transparent SSL/TLS proxy for diverting packets to programs +.\" 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 . .\" Copyright (c) 2017-2020, Soner Tari . .\" 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, @@ -57,19 +55,26 @@ traffic to other programs for deep SSL inspection .br .ad .SH DESCRIPTION -SSLproxy is a proxy for SSL/TLS encrypted network connections. It is intended +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. +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 @@ -78,61 +83,128 @@ 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. For an example, see the lp program under the extra folder in -the sources. -.LP +.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. 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. +.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, 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. +.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 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: +.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 +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, TLS 1.2, and TLS 1.3, 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. +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. +.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 changed in -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 +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. +.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 the PassSite option 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 -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: +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, @@ -142,39 +214,66 @@ CREATE TABLE USERS( 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 this 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, 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 -greater 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. +connection is redirected to a login page configured by the UserAuthURL option. .LP -DivertUsers and PassUsers options can be used to divert, pass through, or -block users. 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. 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. These user lists can be defined globally or -per-proxyspec. -.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. +SSLproxy also compares the atime value in the users table with the current +system time. If the difference is greater than the value configured by the +UserTimeout option, then the connection is redirected to the login page. +.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 the +PassSite option 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 User control lists +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. + - 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. +.LP +These user control lists can be defined globally or per-proxyspec. +.SH Servers Excluded 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 -PassSite. Per site filters can be defined using client IP addresses, users, -and description keywords. Multiple sites can be defined, one on each line. +PassSite. .LP +Per-site filters can be defined using client IP addresses, users, and +description keywords. 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. +.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 @@ -186,8 +285,6 @@ 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