Improve documentation

README.md

@@ -17,7 +17,7 @@ network traffic as well.
 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 
+traffic is encrypted now, without SSLproxy it wouldn't be possible to deeply 
 inspect most of the network traffic passing through UTMFW.
 
 See [this presentation](https://drive.google.com/open?id=12YaGIGs0-xfpqMNAY3rzUbIyed-Tso8W) 
@@ -50,13 +50,13 @@ communication occurs over networking sockets.
 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 and 
-protocol validation. Also, note that the implementation of proxy core in 
-SSLproxy is different from the one in SSLsplit, for example the proxy core in 
-SSLproxy runs lockless, whereas SSLsplit implementation uses thread manager 
-level locks (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.
+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.
 
 SSLproxy does not automagically redirect any network traffic.  To actually
 implement a proxy, you also need to redirect the traffic to the system running 
@@ -108,8 +108,9 @@ connection options too:
 	    Divert (yes|no)
 
 	    # Connection options
-	    DenyOCSP (yes|no)
 	    Passthrough (yes|no)
+
+	    DenyOCSP (yes|no)
 	    CACert ca.crt
 	    CAKey ca.key
 	    ClientCert client.crt
@@ -126,15 +127,17 @@ connection options too:
 	    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
-	    RemoveHTTPAcceptEncoding (yes|no)
-	    RemoveHTTPReferer (yes|no)
 	    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
-	    ValidateProto (yes|no)
-	    MaxHTTPHeaderSize 8192
 
 	    # The DivertUsers, PassUsers, and PassSite options will be deprecated
 	    DivertUsers userlist
@@ -169,7 +172,7 @@ for the details of split style proxyspecs.
 
 #### SSLproxy line
 
-Given the example proxyspec above, a sample line SSLproxy inserts into the 
+Given the proxyspec example above, a sample line SSLproxy inserts into the 
 first packet in the connection may be the following:
 
 	SSLproxy: [127.0.0.1]:34649,[192.168.3.24]:47286,[192.168.111.130]:443,s
@@ -179,8 +182,8 @@ 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, e.g by asking the NAT engine, hence must 
-rely on the information in the SSLproxy line.
+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 
@@ -199,8 +202,7 @@ 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.
 
-Given the example proxyspec above, a listening program should be listening on 
-port 8080.
+Given the proxyspec example above, a program should be listening on port 8080.
 
 You can offload the system SSLproxy is running on by diverting packets to 
 remote listening programs too. For example, given the following proxy 
@@ -213,10 +215,12 @@ 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.
 
-Accordingly, the SSLproxy line now becomes:
+Accordingly, the SSLproxy line now becomes (notice the first IP address):
 
 	SSLproxy: [192.168.1.1]:34649,[192.168.3.24]:47286,[192.168.111.130]:443,s
 
+And a listening program should be running at address 192.168.0.1 on port 8080.
+
 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.
@@ -291,8 +295,9 @@ 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](https://insights.sei.cmu.edu/cert/2015/03/the-risks-of-ssl-inspection.html)
-for the reasons for this difference. You can disable this feature by the 
-VerifyPeer option.
+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.
 
 #### Client certificates
 
@@ -322,7 +327,7 @@ be created using the following SQL statement:
 	);
 
 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 the users table should 
+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 
@@ -336,8 +341,9 @@ 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 ethernet addresses do not match, the connection is 
-redirected to the login page.
+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 
@@ -370,11 +376,11 @@ only.
 SSLproxy can divert, split, pass, block, or match connections based on 
 filtering rules. Filtering rules can be defined globally and/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
+- `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
@@ -429,8 +435,9 @@ connection options too:
 	    ReconnectSSL (yes|no)
 
 	    # Connection options
-	    DenyOCSP (yes|no)
 	    Passthrough (yes|no)
+
+	    DenyOCSP (yes|no)
 	    CACert ca.crt
 	    CAKey ca.key
 	    ClientCert client.crt
@@ -447,19 +454,21 @@ connection options too:
 	    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
-	    RemoveHTTPAcceptEncoding (yes|no)
-	    RemoveHTTPReferer (yes|no)
 	    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
-	    ValidateProto (yes|no)
-	    MaxHTTPHeaderSize 8192
 	}
 
-The specification of which connections the filtering rule will be applied to 
-is achieved by the `from` and `to` parts of filtering rule and by the 
+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.
 
 - The `from` part of a rule defines source filter based on client IP address, 
@@ -481,14 +490,14 @@ If and how a connection should be logged is specified using the `log` or
 - `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 files
-- `mirror` enables mirroring packets to mirror interfaces or targets
+- `pcap` enables writing packets to pcap file
+- `mirror` enables mirroring packets to mirror interface or target
 
 You can add a negation prefix `!` to a log action to disable that logging.
 
-Structured filtering rules can also specify all possible connection options to 
-be selectively applied to matching connections, not just per-proxyspec or 
-globally. One line filtering rules cannot specify connection options.
+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.
 
 For example, if the following rules are defined in a structured HTTPS proxyspec,
 
@@ -496,16 +505,16 @@ For example, if the following rules are defined in a structured HTTPS proxyspec,
 	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 the description notebook to SSL 
-sites with the SNI of example.com. Also, the rule specifies that the packet 
+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.
 
-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.
+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.
 
 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 
@@ -539,6 +548,10 @@ 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.
 
+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.
+
 In terms of possible filter actions,
 
 - Dst Host filtering rules can take all of the filter and log actions.
@@ -554,22 +567,25 @@ 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.
 
+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.
+
 Connection options specified in a structured filtering rule can have any 
-effect only if the rule matches the connection before proxyspec or global 
-options are applied. Otherwise, the proxyspec or global connection options 
-already applied to a connection cannot be overriden by the connection options 
-specified in the matching structured filtering rule. For example, SSL/TLS 
-options of a connection cannot be changed after the SSL/TLS connection is 
-established. So, normally SSL type of rules cannot modify SSL/TLS options of a 
+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/TLS options in the SSL type of 
+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 connections and change 
-their SSL configuration.
+SNI and CN fields in stuctured filtering rules to match SSL connections and 
+change their SSL configuration.
 
 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 `$` char. 
-The macro name must be followed by words separated with spaces.
+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.
 
 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 
@@ -590,17 +606,17 @@ be written as Pass filtering rules. The PassSite option will be deprecated in
 favor of filtering 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 
-connection, that connection is passed through the proxy without being diverted 
+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.
+PassSite rules.
 
 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. PassSite rules do 
-not support macro expansion.
+PassSite rules can search for exact or substring matches, but do not support 
+macro expansion.
 
 #### User control lists
 
@@ -628,12 +644,12 @@ control lists do not support macro expansion.
 
 ### 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
-logged. Filtering rules can selectively modify connection 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.
 
-See the manual pages sslproxy(1) and sslproxy.conf(5) for details on using 
+See the manual pages `sslproxy(1)` and `sslproxy.conf(5)` for details on using 
 SSLproxy, setting up the various NAT engines, and for examples.
 
 
@@ -646,7 +662,7 @@ feature is omitted. The build depends on GNU make and a POSIX.2 environment
 in `PATH`. If available, pkg-config is used to locate and configure the 
 dependencies. The optional unit tests depend on the check library. The 
 optional end-to-end tests depend on the [TestProxy](https://github.com/sonertari/TestProxy) 
-tool, and are supported only on Linux.
+tool, and are supported on Linux only.
 
 SSLproxy currently supports the following operating systems and NAT mechanisms:
 

src/sslproxy.1

@@ -63,9 +63,9 @@ network traffic as well.
 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.
+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
@@ -88,13 +88,13 @@ communication occurs over networking sockets.
 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 and 
-protocol validation. Also, note that the implementation of proxy core in 
-SSLproxy is different from the one in SSLsplit, for example the proxy core in 
-SSLproxy runs lockless, whereas SSLsplit implementation uses thread manager 
-level locks (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.
+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 
@@ -144,8 +144,9 @@ ProxySpec {
     Divert (yes|no)
 
     # Connection options
-    DenyOCSP (yes|no)
     Passthrough (yes|no)
+
+    DenyOCSP (yes|no)
     CACert ca.crt
     CAKey ca.key
     ClientCert client.crt
@@ -162,15 +163,17 @@ ProxySpec {
     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
-    RemoveHTTPAcceptEncoding (yes|no)
-    RemoveHTTPReferer (yes|no)
     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
-    ValidateProto (yes|no)
-    MaxHTTPHeaderSize 8192
 
     # The DivertUsers, PassUsers, and PassSite options will be deprecated
     DivertUsers userlist
@@ -204,7 +207,7 @@ 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 example proxyspec above, a sample line SSLproxy inserts into the 
+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
@@ -214,8 +217,8 @@ 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, e.g by asking the NAT engine, hence must 
-rely on the information in the SSLproxy line.
+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 
@@ -232,8 +235,7 @@ 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 example proxyspec above, a listening program should be listening on 
-port 8080.
+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 
@@ -246,10 +248,12 @@ 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:
+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.
@@ -313,7 +317,8 @@ 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 disable this feature by the VerifyPeer option.
+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 
@@ -339,7 +344,7 @@ CREATE TABLE USERS(
 );
 .LP
 SSLproxy does not create this users table or the database file by itself, nor 
-does it log users in or out. So the database file and the users table should 
+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 
@@ -353,8 +358,9 @@ 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 ethernet addresses do not match, the connection is 
-redirected to the login page.
+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 
@@ -386,11 +392,11 @@ only.
 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 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
+ - 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
@@ -445,8 +451,9 @@ FilterRule {
     ReconnectSSL (yes|no)
 
     # Connection options
-    DenyOCSP (yes|no)
     Passthrough (yes|no)
+
+    DenyOCSP (yes|no)
     CACert ca.crt
     CAKey ca.key
     ClientCert client.crt
@@ -463,20 +470,22 @@ FilterRule {
     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
-    RemoveHTTPAcceptEncoding (yes|no)
-    RemoveHTTPReferer (yes|no)
     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
-    ValidateProto (yes|no)
-    MaxHTTPHeaderSize 8192
 .br
 }
 .LP
-The specification of which connections the filtering rule will be applied to 
-is achieved by the from and to parts of filtering rule and by the proxyspec 
+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, 
@@ -499,14 +508,14 @@ Log part of one line or structured filtering rules, respectively:
  - 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 files
- - mirror enables mirroring packets to mirror interfaces or targets
+ - 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 all possible connection options to 
-be selectively applied to matching connections, not just per-proxyspec or 
-globally. One line filtering rules cannot specify connection options.
+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
@@ -557,6 +566,10 @@ 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.
@@ -572,22 +585,25 @@ 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 proxyspec or global 
-options are applied. Otherwise, the proxyspec or global connection options 
-already applied to a connection cannot be overriden by the connection options 
-specified in the matching structured filtering rule. For example, SSL/TLS 
-options of a connection cannot be changed after the SSL/TLS connection is 
-established. So, normally SSL type of rules cannot modify SSL/TLS options of a 
+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/TLS options in the SSL type of 
+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 connections and change 
-their SSL configuration.
+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 $ char.
-The macro name must be followed by words separated with spaces.
+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 
@@ -606,17 +622,17 @@ 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 matches the SNI or common names in the SSL certificate of a 
-connection, that connection is passed through the proxy without being diverted 
+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.
+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. PassSite rules do 
-not support macro expansion.
+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 
@@ -640,10 +656,10 @@ are diverted to listening programs.
 These user control lists can be defined globally or per-proxyspec. User 
 control lists do not support macro expansion.
 .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
-logged. Filtering rules can selectively modify connection 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
@@ -907,8 +923,11 @@ Otherwise, connections matching no certificate will be dropped, or if
 .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.  This option is not available if SSLproxy was built without
-mirroring support.
+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,

src/sslproxy.conf.5

@@ -68,16 +68,20 @@ proxyspecs can only make use of the options defined earlier.
 Use CA cert (and key) to sign forged certs. Equivalent to -c command line option.
 .TP
 \fBCAKey STRING\fR
-Use CA key (and cert) to sign forged certs. Equivalent to -k command line option.
+Use CA key (and cert) to sign forged certs. Equivalent to -k command line 
+option.
 .TP 
 \fBClientCert STRING\fR
-Use cert from pemfile when destination requests client certs. Equivalent to -a command line option.
+Use cert from pemfile when destination requests client certs. Equivalent to -a 
+command line option.
 .TP
 \fBClientKey STRING\fR
-Use key from pemfile when destination requests client certs. Equivalent to -b command line option.
+Use key from pemfile when destination requests client certs. Equivalent to -b 
+command line option.
 .TP
 \fBCAChain STRING\fR
-Use CA chain from pemfile (intermediate and root CA certs). Equivalent to -C command line option.
+Use CA chain from pemfile (intermediate and root CA certs). Equivalent to -C 
+command line option.
 .TP
 \fBLeafKey STRING\fR
 Use key from pemfile for leaf certs. Equivalent to -K command line option.
@@ -85,19 +89,25 @@ Use key from pemfile for leaf certs. Equivalent to -K command line option.
 Default: generate
 .TP
 \fBLeafCRLURL STRING\fR
-Use URL as CRL distribution point for all forged certs. Equivalent to -q command line option.
+Use URL as CRL distribution point for all forged certs. Equivalent to -q 
+command line option.
 .TP
 \fBLeafCertDir STRING\fR
-Use cert+chain+key PEM files from certdir to target all sites matching the common names (non-matching: generate if CA). Equivalent to -t command line option.
+Use cert+chain+key PEM files from certdir to target all sites matching the 
+common names (non-matching: generate if CA). Equivalent to -t command line 
+option.
 .TP
 \fBDefaultLeafCert STRING\fR
-Use cert+chain+key from PEM file for leaf certificates if there is no match in \fBLeafCertDir\fR. Equivalent to -A command line option.
+Use cert+chain+key from PEM file for leaf certificates if there is no match in 
+\fBLeafCertDir\fR. Equivalent to -A command line option.
 .TP
 \fBWriteGenCertsDir STRING\fR
-Write leaf key and only generated certificates to gendir. Equivalent to -w command line option.
+Write leaf key and only generated certificates to gendir. Equivalent to -w 
+command line option.
 .TP
 \fBWriteAllCertsDir STRING\fR
-Write leaf key and all certificates to gendir. Equivalent to -W command line option.
+Write leaf key and all certificates to gendir. Equivalent to -W command line 
+option.
 .TP
 \fBDenyOCSP BOOL\fR
 Deny all OCSP requests on all proxyspecs. Equivalent to -O command line option.
@@ -119,7 +129,8 @@ Use ECDH named curve. Equivalent to -G command line option.
 Default: prime256v1
 .TP
 \fBSSLCompression BOOL\fR
-Enable/disable SSL/TLS compression on all connections. Equivalent to -Z command line option.
+Enable/disable SSL/TLS compression on all connections. Equivalent to -Z 
+command line option.
 .TP
 \fBForceSSLProto STRING\fR
 Force SSL/TLS protocol version only. Equivalent to -r command line option.
@@ -179,49 +190,63 @@ Drop privileges to group. Equivalent to -m command line option.
 Default: Primary group of user
 .TP 
 \fBChroot STRING\fR
-chroot() to jaildir (impacts sni proxyspecs, see sslproxy(1)). Equivalent to -j command line option.
+chroot() to jaildir (impacts sni proxyspecs, see sslproxy(1)). Equivalent to 
+-j command line option.
 .TP 
 \fBPidFile STRING\fR
 Write pid to file. Equivalent to -p command line option.
 .TP 
 \fBConnectLog STRING\fR
-Connect log: log one line summary per connection to logfile. Equivalent to -l command line option.
+Connect log: log one line summary per connection to logfile. Equivalent to -l 
+command line option.
 .TP 
 \fBContentLog STRING\fR
-Content log: full data to file or named pipe (excludes ContentLogDir/ContentLogPathSpec). Equivalent to -L command line option.
+Content log: full data to file or named pipe (excludes 
+ContentLogDir/ContentLogPathSpec). Equivalent to -L command line option.
 .TP 
 \fBContentLogDir STRING\fR
-Content log: full data to separate files in dir (excludes ContentLog/ContentLogPathSpec). Equivalent to -S command line option.
+Content log: full data to separate files in dir (excludes 
+ContentLog/ContentLogPathSpec). Equivalent to -S command line option.
 .TP 
 \fBContentLogPathSpec STRING\fR
-Content log: full data to sep files with % subst (excludes ContentLog/ContentLogDir). Equivalent to -F command line option.
+Content log: full data to sep files with % subst (excludes 
+ContentLog/ContentLogDir). Equivalent to -F command line option.
 .TP 
 \fBLogProcInfo BOOL\fR
-Look up local process owning each connection for logging. Equivalent to -i command line option.
+Look up local process owning each connection for logging. Equivalent to -i 
+command line option.
 .TP 
 \fBPcapLog STRING\fR
-Pcap log: packets to pcapfile (excludes PcapLogDir/PcapLogPathSpec). Equivalent to -X command line option.
+Pcap log: packets to pcapfile (excludes PcapLogDir/PcapLogPathSpec). 
+Equivalent to -X command line option.
 .TP 
 \fBPcapLogDir STRING\fR
-Pcap log: packets to separate files in dir (excludes PcapLog/PcapLogPathSpec). Equivalent to -Y command line option.
+Pcap log: packets to separate files in dir (excludes PcapLog/PcapLogPathSpec). 
+Equivalent to -Y command line option.
 .TP 
 \fBPcapLogPathSpec STRING\fR
-Pcap log: packets to sep files with % subst (excludes PcapLog/PcapLogDir). Equivalent to -y command line option.
+Pcap log: packets to sep files with % subst (excludes PcapLog/PcapLogDir). 
+Equivalent to -y command line option.
 .TP 
 \fBMirrorIf STRING\fR
 Mirror packets to interface. Equivalent to -I command line option.
 .TP 
 \fBMirrorTarget STRING\fR
-Mirror packets to target address (used with MirrorIf). Equivalent to -T command line option. Not used if the target is irrelevant (e.g. mirror to dummy device)
+Mirror packets to target address (used with MirrorIf). Not used if the target 
+is irrelevant (e.g. mirror to dummy device). Equivalent to -T command line 
+option.
 .TP 
 \fBMasterKeyLog STRING\fR
-Log master keys to logfile in SSLKEYLOGFILE format. Equivalent to -M command line option.
+Log master keys to logfile in SSLKEYLOGFILE format. Equivalent to -M command 
+line option.
 .TP 
 \fBDaemon BOOL\fR
-Daemon mode: run in background, log error messages to syslog. Equivalent to -d command line option.
+Daemon mode: run in background, log error messages to syslog. Equivalent to -d 
+command line option.
 .TP 
 \fBDebug BOOL\fR
-Debug mode: run in foreground, log debug messages on stderr. Equivalent to -D command line option.
+Debug mode: run in foreground, log debug messages on stderr. Equivalent to -D 
+command line option.
 .TP 
 \fBDebugLevel NUMBER\fR
 Verbose debug level, 2-4.
@@ -311,8 +336,8 @@ Set open files limit, use 50-10000.
 Default: System-wide limit.
 .TP
 \fBDivert BOOL\fR
-Set divert or split mode of operation, globally or per-proxyspec.
-The Divert option is not equivalent to the command line -n option.
+Set divert or split mode of operation, globally or per-proxyspec. The Divert 
+option is not equivalent to the command line -n option.
 .br
 Default: yes
 .TP
@@ -351,12 +376,12 @@ 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.
+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.
+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.
@@ -416,10 +441,10 @@ Log
 .br
 ReconnectSSL
 .br
-DenyOCSP
-.br
 Passthrough
 .br
+DenyOCSP
+.br
 CACert
 .br
 CAKey
@@ -436,7 +461,7 @@ DHGroupParams
 .br
 ECDHCurve
 .br
-SSLCompression (yes|no)
+SSLCompression
 .br
 ForceSSLProto
 .br
@@ -452,13 +477,17 @@ Ciphers
 .br
 CipherSuites
 .br
+VerifyPeer
+.br
+AllowWrongHost
+.br
 RemoveHTTPAcceptEncoding
 .br
 RemoveHTTPReferer
 .br
-VerifyPeer
+MaxHTTPHeaderSize
 .br
-AllowWrongHost
+ValidateProto
 .br
 UserAuth
 .br
@@ -466,15 +495,11 @@ UserTimeout
 .br
 UserAuthURL
 .br
-ValidateProto
-.br
-MaxHTTPHeaderSize
-.br
 \fB}\fR
 .br
-Structured filtering rules can specify all possible connection options to be 
-selectively applied to matching connections, not just per-proxyspec or 
-globally. One line filtering rules cannot specify connection options.
+Structured filtering rules can specify connection options to be selectively 
+applied to matching connections, not just per-proxyspec or globally. One line 
+filtering rules cannot specify connection options.
 
 See sslproxy(1) for the details.
 .TP
@@ -507,10 +532,10 @@ NatEngine
 .br
 Divert
 .br
-DenyOCSP
-.br
 Passthrough
 .br
+DenyOCSP
+.br
 CACert
 .br
 CAKey
@@ -543,13 +568,17 @@ Ciphers
 .br
 CipherSuites
 .br
+VerifyPeer
+.br
+AllowWrongHost
+.br
 RemoveHTTPAcceptEncoding
 .br
 RemoveHTTPReferer
 .br
-VerifyPeer
+MaxHTTPHeaderSize
 .br
-AllowWrongHost
+ValidateProto
 .br
 UserAuth
 .br
@@ -557,10 +586,6 @@ UserTimeout
 .br
 UserAuthURL
 .br
-ValidateProto
-.br
-MaxHTTPHeaderSize
-.br
 DivertUsers
 .br
 PassUsers
@@ -577,7 +602,7 @@ FilterRule {...} structured filtering rules
 .br
 
 Structured proxy specifications may consist of the options listed above. The 
-Addr and Port options are mandatory, and equivalent to listenaddr and port 
+Addr and Port options are mandatory, and equivalent to the listenaddr and port 
 options in one line proxyspecs, respectively. If an option is not specified, 
 the global default value is used.
 .SH "FILES"