.\"- .\" 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-2024, Soner Tari . .\" 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" "18 Feb 2024" "v0.9.5" "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. But it can handle unencrypted network traffic as well. .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, without SSLproxy it wouldn't be possible 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, protocol validation, and filtering rules. Also, note that the implementation of the proxy core in SSLproxy is different from the one in SSLsplit; for example, the proxy core in SSLproxy runs lockless, whereas SSLsplit implementation uses a thread manager level lock (which does not necessarily make sslproxy run faster than sslsplit). In SSLproxy, split mode can be defined globally, per-proxyspec, or per-connection using filtering rules. .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 specifications SSLproxy supports three different types of proxy specifications, or proxyspecs for short, which can be in divert or split style. .LP - Command line proxyspecs passed on the command line - One line proxyspecs in configuration files - Structured proxyspecs in configuration files .LP The syntax of command line proxyspecs is as follows: .LP (tcp|ssl|http|https|pop3|pop3s|smtp|smtps|autossl) listenaddr listenport [up:divertport [ua:divertaddr ra:returnaddr]] [(targetaddr targetport|sni sniport|natengine)] .LP The syntax of one line proxyspecs is the same as the syntax of command line proxyspecs, except for the leading ProxySpec keyword: .LP ProxySpec (tcp|ssl|http|https|pop3|pop3s|smtp|smtps|autossl) listenaddr listenport [up:divertport [ua:divertaddr ra:returnaddr]] [(targetaddr targetport|sni sniport|natengine)] .LP The syntax of structured proxyspecs is as follows, and they can configure connection options too: .LP ProxySpec { Proto (tcp|ssl|http|https|pop3|pop3s|smtp|smtps|autossl) Addr listenaddr # inline Port listenport # comments DivertPort divertport # allowed DivertAddr divertaddr ReturnAddr returnaddr TargetAddr targetaddr TargetPort targetport SNIPort sniport NatEngine natengine # Divert or split Divert (yes|no) # Connection options Passthrough (yes|no) DenyOCSP (yes|no) CACert ca.crt CAKey ca.key ClientCert client.crt ClientKey client.key CAChain chain.crt LeafCRLURL http://example.com/example.crl DHGroupParams dh.pem ECDHCurve prime256v1 SSLCompression (yes|no) ForceSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13) DisableSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13) EnableSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13) MinSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13) MaxSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13) Ciphers MEDIUM:HIGH CipherSuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256 VerifyPeer (yes|no) AllowWrongHost (yes|no) RemoveHTTPAcceptEncoding (yes|no) RemoveHTTPReferer (yes|no) MaxHTTPHeaderSize 8192 ValidateProto (yes|no) UserAuth (yes|no) UserTimeout 300 UserAuthURL https://192.168.0.1/userdblogin.php # The DivertUsers, PassUsers, and PassSite options will be deprecated DivertUsers userlist PassUsers userlist PassSite rules Define $macro valuelist (Divert|Split|Pass|Block|Match) one line filtering rules FilterRule {...} structured filtering rules .br } .LP For example, given the following command line proxyspec: .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 Split style proxyspecs configure for split mode of operation similar to SSLsplit. See the SSLsplit documentation for the details of split style proxyspecs. .SH SSLproxy line Given the proxyspec example above, a sample line SSLproxy inserts into the first packet in the connection may be 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, for example 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 programs 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 their 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 Given the proxyspec example above, a program should be listening on port 8080. .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. - 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 (notice the first IP address): .LP SSLproxy: [192.168.1.1]:34649,[192.168.3.24]:47286,[192.168.111.130]:443,s .LP And a listening program should be running at address 192.168.0.1 on port 8080. .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. If a connection cannot pass protocol validation, it is terminated. To enable protocol validation, the ValidateProto option can be defined globally, per-proxyspec, or per-connection using filtering rules. This feature currently supports HTTP, POP3, and SMTP protocols. .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 for this difference. You can enable or disable this feature by the VerifyPeer option, which can be defined globally, per-proxyspec, or per-connection using filtering rules. .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, per-proxyspec, or per-connection using filtering rules. .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 with 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 client IP address is not in the arp cache, or 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, differently. .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 and/or per-proxyspec. .LP - Divert action diverts packets to the listening program, allowing SSL inspection by the listening program and content logging of packets - Split action splits the connection but does not divert packets to the listening program, effectively disabling SSL inspection by the 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 and/or connection options for the connection without changing its filter action .LP SSLproxy supports one line and structured filtering rules. .LP The syntax of one line filtering rules is as follows: .LP (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]|[!]*)] |*) [# comment] .LP The syntax of structured filtering rules is as follows, and they can configure connection options too: .LP FilterRule { Action (Divert|Split|Pass|Block|Match) # From User (username[*]|$macro|*) # inline Desc (desc[*]|$macro|*) # comments SrcIp (clientip[*]|$macro|*) # allowed # To SNI (servername[*]|$macro|*) CN (commonname[*]|$macro|*) Host (host[*]|$macro|*) URI (uri[*]|$macro|*) DstIp (serverip[*]|$macro|*) DstPort (serverport[*]|$macro|*) # Multiple Log lines allowed Log ([[!]connect] [[!]master] [[!]cert] [[!]content] [[!]pcap] [[!]mirror] [$macro]|[!]*) ReconnectSSL (yes|no) # Connection options Passthrough (yes|no) DenyOCSP (yes|no) CACert ca.crt CAKey ca.key ClientCert client.crt ClientKey client.key CAChain chain.crt LeafCRLURL http://example.com/example.crl DHGroupParams dh.pem ECDHCurve prime256v1 SSLCompression (yes|no) ForceSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13) DisableSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13) EnableSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13) MinSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13) MaxSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13) Ciphers MEDIUM:HIGH CipherSuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256 VerifyPeer (yes|no) AllowWrongHost (yes|no) RemoveHTTPAcceptEncoding (yes|no) RemoveHTTPReferer (yes|no) MaxHTTPHeaderSize 8192 ValidateProto (yes|no) UserAuth (yes|no) UserTimeout 300 UserAuthURL https://192.168.0.1/userdblogin.php .br } .LP The specification of which connections a filtering rule will be applied to is achieved by the from and to parts of the 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 and/or port, SNI or Common Names of SSL connections, Host or URI fields in HTTP Request headers, or * for all. + Dst Host type of rules use the ip site field + SSL type of rules use the sni or cn site field + HTTP type of rules use the host or uri site field + All rule types can use the port field .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 or Log part of one line or structured filtering rules, respectively: .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 file - mirror enables mirroring packets to mirror interface or target .LP You can add a negation prefix ! to a log action to disable that logging. .LP Structured filtering rules can also specify connection options to be selectively applied to matching connections, not just globally or per-proxyspec. One line filtering rules cannot specify connection options. .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 from behind sslproxy. .LP Filtering rules are applied based on certain precedence orders: .LP - More specific rules have higher precedence. Log actions increase rule precedence too. - 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 Pass and Block filter actions are deferred until the last moment they can be applied to a connection, so that Divert and Split filter actions can override them. .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 To increase rule reuse, one or more of SNI, CN, Host, URI, and DstIp site fields can be specified in the same structured filtering rule. .LP Connection options specified in a structured filtering rule can have any effect only if the rule matches the connection before global or proxyspec connection options are applied. Otherwise, the global or proxyspec connection options already applied to a connection cannot be overriden by the connection options specified in the matching structured filtering rule. For example, SSL options of a connection cannot be changed after the SSL connection is established. So, normally SSL type of rules cannot modify SSL options of a connection, but you can use the ReconnectSSL option to reconnect the server side of an SSL connection to enforce the SSL options in the SSL type of filtering rules. In other words, the ReconnectSSL option allows for using the SNI and CN fields in stuctured filtering rules to match SSL connections and change their SSL configuration. .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 $ sign. The macro name must be followed by words separated by 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 of one line filtering rules 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 rule matches the SNI or Common Names in the SSL certificate of a connection, the 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 rules. .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, but 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 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 \-B \fIproto\fP Enable the SSL/TLS protocol version \fIproto\fP on both client and server side by enabling the respective protocols in OpenSSL. To enable multiple protocol versions, \fB-B\fP can be given multiple times. This option can be used to enable any proto disabled before. Otherwise, all available protocols are enabled by default. See the \fB-R\fP option for further details. .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. Also, only targets with ethernet address assigned can be used with this option; for example, the loopback address 127.0.0.1 cannot be used as target address. Not used if the target is irrelevant (e.g. mirror to dummy device). 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 . SSLsplit is currently maintained by Daniel Roethlisberger and Soner Tari. .LP SSLproxy has been developed by Soner Tari . .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