From 8d752b4d31d5e837d696a154ae9b3ec127348016 Mon Sep 17 00:00:00 2001 From: Soner Tari Date: Mon, 13 Sep 2021 22:36:25 +0300 Subject: [PATCH] Add documentation for filtering rules Also bump version to 0.8.7 --- README.md | 101 ++++++++++++++++++++++-- src/sslproxy.1 | 104 +++++++++++++++++++++++-- src/sslproxy.conf | 43 ++++++++-- src/sslproxy.conf.5 | 75 ++++++++++++++---- tests/testproxy/sslproxy.conf | 2 +- tests/testproxy/sslproxy_no_tls11.conf | 2 +- tests/testproxy/sslproxy_no_tls13.conf | 2 +- 7 files changed, 295 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 7cef6c6..bcaf781 100644 --- a/README.md +++ b/README.md @@ -211,7 +211,7 @@ 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. -Alternatively, you can use the PassSite option to pass through certain +Alternatively, you can use Pass filter rules to pass through certain destinations requesting client certificates. ### User authentication @@ -262,8 +262,8 @@ 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. -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. +If a description text is provided in the DESC field, it can be used with +filter rules to treat the user logged in from different locations, i.e. from different client IP addresses, separately. If the UserAuth option is enabled, the user owner of the connection is @@ -272,7 +272,8 @@ parse and use this information in its logic and/or logging: SSLproxy: [127.0.0.1]:34649,[192.168.3.24]:47286,[192.168.111.130]:443,s,soner -The user authentication feature is currently available on OpenBSD and Linux only. +The user authentication feature is currently available on OpenBSD and Linux +only. #### User control lists @@ -293,7 +294,97 @@ are diverted to listening programs. These user control lists can be defined globally or per-proxyspec. -### Excluding sites from SSL inspection +### Filtering rules + +SSLproxy can divert, split, pass, or block connections based on filtering +rules. Filtering rules can be defined globally or per-proxyspec. + +- Divert action diverts packets to listening program, allowing SSL inspection +by listening program and content logging of packets +- Split action splits the connection but does not divert packets to listening +program, effectively disabling SSL inspection by 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 + +The syntax of filtering rules is as follows: + + (Divert|Split|Pass|Block) + ([from ( + user (username|*) [desc keyword]| + ip (clientaddr|*)| + *)] + [to ( + sni (servername[*]|*)| + cn (commonname[*]|*)| + host (host[*]|*)| + uri (uri[*]|*)| + ip (serveraddr|*)| + *)] + |*) + +The definition of which connections the rule action will be applied to is +achieved by the `from` and `to` parts of a filtering rule and by the proxyspec +that the rule is defined for. + +- The `from` part of a rule defines source filter based on client IP address, +user or description keyword, or `*` for all. +- The `to` part defines destination filter based on server IP address, SNI or +Common Names of SSL connections, Host or URI fields in HTTP Request headers, or +`*` for all. Dst Host type of rules use `ip`, SSL type of rules use `sni` and +`cn`, and HTTP type of rules use `host` and `uri` site fields. +- The proxyspec handling the connection defines the protocol filter for the +connection. + +For example, if the following rules are defined in a structured HTTPS proxyspec, + + Split from user soner desc notebook to sni example.com + Pass from user soner desc android to cn .fbcdn.net* + +The first filtering rule above splits but does not divert HTTPS connections +from the user soner who has logged in with a description containing the keyword +notebook to SSL sites with the SNI of example.com. The second rule passes +through HTTPS connections from the user soner who has logged in with a +description containing the keyword android to SSL sites with the Common Names +containing the substring .fbcdn.net anywhere in it (notice the asterisk at the +end). Note that the second example 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 behind sslproxy. + +Filtering rules are applied based on certain precedence orders: + +- The precedence of filter types is as Dst Host > SSL > HTTP. +- The precedence of filter actions is as Divert > Split > Pass > Block. This is +only for the same type of filter rules. +- The precedence of site fields is as sni > cn for ssl filter and host > uri +for http filter. + +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. + +In terms of possible filter actions, + +- Dst Host filter rules can take all of the actions. +- SSL filter rules can take all of the actions. +- HTTP filter rules can take the block action, but not divert, split, or pass +actions. + +You can append an asterisk `*` to site field of filtering rules for substring +matching. Otherwise, the filter searches for an exact match with the site field +in the rule. + +If the UserAuth option is disabled, only client IP addresses can be used in +the from part of filtering rules. + +#### Excluding sites from SSL inspection + +PassSite option is a special form of Pass filtering rule. All PassSite rules +can be written as Pass filter rules. The PassSite option will be deprecated in +favor of filter rules in the future. PassSite option allows certain SSL sites to be excluded from SSL inspection. If a PassSite matches the SNI or common names in the SSL certificate of a diff --git a/src/sslproxy.1 b/src/sslproxy.1 index 9f1edbe..a1be4b5 100644 --- a/src/sslproxy.1 +++ b/src/sslproxy.1 @@ -27,7 +27,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.TH "sslproxy" "1" "29 August 2021" "v0.8.4" "SSLproxy" +.TH "sslproxy" "1" "29 August 2021" "v0.8.7" "SSLproxy" .SH NAME sslproxy \-\- transparent SSL/TLS proxy for decrypting and diverting network traffic to other programs for deep SSL inspection @@ -65,7 +65,7 @@ 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 +.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 @@ -227,7 +227,7 @@ 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 +Alternatively, you can use Pass filter 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 @@ -276,8 +276,8 @@ 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. +If a description text is provided in the DESC field, it can be used with +filter rules 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 @@ -286,7 +286,8 @@ 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. +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. @@ -304,7 +305,96 @@ the lists are blocked. SSLproxy simply terminates their connections. are diverted to listening programs. .LP These user control lists can be defined globally or per-proxyspec. -.SH Excluding sites from SSL inspection +.SH Filtering rules +.LP +SSLproxy can divert, split, pass, or block connections based on filtering +rules. Filtering rules can be defined globally or per-proxyspec. +.LP + - Divert action diverts packets to listening program, allowing SSL inspection +by listening program and content logging of packets + - Split action splits the connection but does not divert packets to listening +program, effectively disabling SSL inspection by 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 +.LP +The syntax of filtering rules is as follows: + +(Divert|Split|Pass|Block) + ([from ( + user (username|*) [desc keyword]| + ip (clientaddr|*)| + *)] + [to ( + sni (servername[*]|*)| + cn (commonname[*]|*)| + host (host[*]|*)| + uri (uri[*]|*)| + ip (serveraddr|*)| + *)] + |*) +.LP +The definition of which connections the rule action will be applied to is +achieved by the from and to parts of a 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 or description keyword, or * for all. + - The to part defines destination filter based on server IP address, SNI or +Common Names of SSL connections, Host or URI fields in HTTP Request headers, or +* for all. Dst Host type of rules use ip, SSL type of rules use sni and +cn, and HTTP type of rules use host and uri site fields. + - The proxyspec handling the connection defines the protocol filter for the +connection. +.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 +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 a description containing the keyword +notebook to SSL sites with the SNI of example.com. The second rule passes +through HTTPS connections from the user soner who has logged in with a +description containing the keyword android to SSL sites with the Common Names +containing the substring .fbcdn.net anywhere in it (notice the asterisk at the +end). Note that the second example 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 behind sslproxy. +.LP +Filtering rules are applied based on certain precedence orders: +.LP + - The precedence of filter types is as Dst Host > SSL > HTTP. + - The precedence of filter actions is as Divert > Split > Pass > Block. This is +only for the same type of filter 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 +In terms of possible filter actions, +.LP + - Dst Host filter rules can take all of the actions. + - SSL filter rules can take all of the actions. + - HTTP filter rules can take the block action, but not divert, split, or pass +actions. +.LP +You can append an asterisk * to site field of filtering rules for substring +matching. Otherwise, the filter searches for an exact match with the site field +in the rule. +.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. All PassSite rules +can be written as Pass filter rules. The PassSite option will be deprecated in +favor of filter rules in the future. +.LP PassSite option allows certain SSL sites to be excluded from SSL inspection. 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 diff --git a/src/sslproxy.conf b/src/sslproxy.conf index 25650bf..592e683 100644 --- a/src/sslproxy.conf +++ b/src/sslproxy.conf @@ -1,4 +1,4 @@ -# Sample configuration for sslproxy v0.8.4 +# Sample configuration for sslproxy v0.8.7 # # Use the -f command line option to start sslproxy with a config file. # See sslproxy.conf(5) and sslproxy(1) for documentation. @@ -254,7 +254,17 @@ PassUsers admin # Set open files limit, use 50-10000 #OpenFilesLimit 1024 +# Set divert or split mode of operation +# If set to no, equivalent to -n command line option for split mode. +# Overrides the divert mode of all proxyspecs, but not the split mode. +# Note that if the arg is not yes|no, this is assumed to be a Divert filter rule +# (default: yes) +#Divert yes + # Passthrough sites +# The PassSite option is a special form of Pass filter rule +# PassSite rules can be written as Pass filter rules, see filter rule examples +# PassSite rules will be deprecated in favor of filter rules in the future # site[*] [(clientaddr|user|*) [description keyword]] #PassSite example.com #PassSite example.com 192.168.0.1 @@ -262,11 +272,32 @@ PassUsers admin #PassSite *.google.com * android #PassSite .fbcdn.net* soner android -# Set divert or split mode of operation -# If set to no, equivalent to -n command line option for split mode. -# Overrides the divert mode of all proxyspecs, but not the split mode. -# (default: yes) -#Divert yes +# Filter rules +# +# (Divert|Split|Pass|Block) +# ([from ( +# user (username|*) [desc keyword]| +# ip (clientaddr|*)| +# *)] +# [to ( +# sni (servername[*]|*)| +# cn (commonname[*]|*)| +# host (host[*]|*)| +# uri (uri[*]|*)| +# ip (serveraddr|*)| +# *)] +# |*) +# +# Filter rules using host or uri can only take block action, +# the other actions are ignored by issuing a warning. +# PassSite example.com is equivalent to the following two Pass rules: +# Pass to sni example.com +# Pass to cn example.com +# +#Divert from ip 192.168.0.1 to sni example.com +#Split from user soner to sni example.com +#Pass from user * desc android to sni *.google.com +#Block from user soner desc android to cn .fbcdn.net* # One line proxy specifications # type listenaddr+port up:utmport [ua:utmaddr ra:returnaddr] diff --git a/src/sslproxy.conf.5 b/src/sslproxy.conf.5 index fdf2f4a..be837ea 100644 --- a/src/sslproxy.conf.5 +++ b/src/sslproxy.conf.5 @@ -26,7 +26,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.TH "sslproxy.conf" "5" "29 August 2021" "v0.8.4" "SSLproxy" +.TH "sslproxy.conf" "5" "29 August 2021" "v0.8.7" "SSLproxy" .SH "NAME" .LP \fBsslproxy.conf\fR \- Configuration file for SSLproxy @@ -104,18 +104,6 @@ auth or no matching cert and no CA. Equivalent to -P command line option. .br Default: drop .TP -\fBPassSite STRING\fR -Passthrough site: site[*] [(clientaddr|user|*) [description keyword]]. If -the site matches SNI or common names in the SSL certificate, the connection is -passed through the proxy. Per site filters can be defined using client IP -addresses, users, and description keywords. '*' matches all client IP -addresses or users. User auth should be enabled for user and description -keyword filtering to work. Case is ignored while matching description -keywords. Multiple sites are allowed, one on each line. PassSite rules can -search for exact or substring matches. Append an asterisk to the site field to -search for substring match. Note that the substring search is not a regex or -wildcard search, and that the asterisk at the end is removed before search. -.TP \fBDHGroupParams STRING\fR Use DH group params from pemfile. Equivalent to -g command line option. .br @@ -308,6 +296,58 @@ Set divert or split mode of operation, globally or per-proxyspec. .br Default: yes .TP +\fBPassSite STRING\fR +Passthrough site: site[*] [(clientaddr|user|*) [description keyword]]. +PassSite option is a special form of Pass filtering rule. All PassSite rules +can be written as Pass filter rules. The PassSite option will be deprecated in +favor of filter rules in the future. If the site matches SNI or common names +in the SSL certificate, the connection is passed through the proxy. Per site +filters can be defined using client IP addresses, users, and description +keywords. '*' matches all client IP addresses or users. User auth should be +enabled for user and description keyword filtering to work. Case is ignored +while matching description keywords. Multiple sites are allowed, one on each +line. PassSite rules can search for exact or substring matches. Append an +asterisk to the site field to search for substring match. Note that the +substring search is not a regex or wildcard search, and that the asterisk at +the end is removed before search. +.TP +\fBDivert STRING\fR +Divert filtering rule diverts packets to listening program, allowing SSL +inspection by listening program and content logging of packets. +.TP +\fBSplit STRING\fR +Split filtering rule splits the connection but does not divert packets to +listening program, effectively disabling SSL inspection by listening program, but +allowing content logging of packets. +.TP +\fBPass STRING\fR +Pass filtering rule passes the connection through by engaging passthrough mode, +effectively disabling SSL inspection and content logging of packets. +.TP +\fBBlock STRING\fR +Block filtering rule terminates the connection. +.br + +The syntax of filtering rules is as follows: +.br + +(Divert|Split|Pass|Block) + ([from ( + user (username|*) [desc keyword]| + ip (clientaddr|*)| + *)] + [to ( + sni (servername[*]|*)| + cn (commonname[*]|*)| + host (host[*]|*)| + uri (uri[*]|*)| + ip (serveraddr|*)| + *)] + |*) +.br + +See sslproxy(1) for the details. +.TP \fBProxySpec STRING\fR One line proxy specification: type listenaddr+port up:port ua:addr ra:addr. The other options of one line proxyspecs are set to the global defaults. @@ -385,8 +425,17 @@ ValidateProto .br PassSite .br +Divert filtering rules +.br +Split filtering rules +.br +Pass filtering rules +.br +Block filtering rules +.br \fB}\fR .br + Structured proxy specifications may consist of the options listed above. The Proto, Addr, Port, and DivertPort options are mandatory, and equivalent to type, listenaddr, port, and up options in one line proxyspecs, respectively. diff --git a/tests/testproxy/sslproxy.conf b/tests/testproxy/sslproxy.conf index 3b1c1f8..cb404e6 100644 --- a/tests/testproxy/sslproxy.conf +++ b/tests/testproxy/sslproxy.conf @@ -1,4 +1,4 @@ -# TestProxy test configuration for sslproxy v0.8.4 +# TestProxy test configuration for sslproxy v0.8.7 # Global options #User _sslproxy diff --git a/tests/testproxy/sslproxy_no_tls11.conf b/tests/testproxy/sslproxy_no_tls11.conf index e8238ec..c95d9b8 100644 --- a/tests/testproxy/sslproxy_no_tls11.conf +++ b/tests/testproxy/sslproxy_no_tls11.conf @@ -1,4 +1,4 @@ -# TestProxy test configuration for sslproxy v0.8.4 +# TestProxy test configuration for sslproxy v0.8.7 # Global options #User _sslproxy diff --git a/tests/testproxy/sslproxy_no_tls13.conf b/tests/testproxy/sslproxy_no_tls13.conf index 1dce755..30e7c58 100644 --- a/tests/testproxy/sslproxy_no_tls13.conf +++ b/tests/testproxy/sslproxy_no_tls13.conf @@ -1,4 +1,4 @@ -# TestProxy test configuration for sslproxy v0.8.4 +# TestProxy test configuration for sslproxy v0.8.7 # Global options #User _sslproxy