Archives/SSLproxy
2
0
Fork 0
mirror of https://github.com/sonertari/SSLproxy synced 2024-10-31 21:20:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve documentation

Browse Source
This commit is contained in:
Soner Tari 2021-12-28 16:10:36 +03:00
parent 59c28f6ad9
commit 3dea854173
3 changed files with 318 additions and 258 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

156
README.md
View File

@ -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:

147
src/sslproxy.1
View File

@ -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,

273
src/sslproxy.conf.5
View File

@ -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,101 +441,10 @@ Log
.br
ReconnectSSL
.br
DenyOCSP
.br
Passthrough
.br
CACert
.br
CAKey
.br
ClientCert
.br
ClientKey
.br
CAChain
.br
LeafCRLURL
.br
DHGroupParams
.br
ECDHCurve
.br
SSLCompression (yes|no)
.br
ForceSSLProto
.br
DisableSSLProto
.br
EnableSSLProto
.br
MinSSLProto
.br
MaxSSLProto
.br
Ciphers
.br
CipherSuites
.br
RemoveHTTPAcceptEncoding
.br
RemoveHTTPReferer
.br
VerifyPeer
.br
AllowWrongHost
.br
UserAuth
.br
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.
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 configuration
preceding them. Multiple specs are allowed, one on each line.
.TP
\fBProxySpec {\fR
.br
Proto
.br
Addr
.br
Port
.br
DivertPort
.br
DivertAddr
.br
ReturnAddr
.br
TargetAddr
.br
TargetPort
.br
SNIPort
.br
NatEngine
.br
Divert
.br
DenyOCSP
.br
Passthrough
.br
CACert
.br
CAKey
@ -543,13 +477,17 @@ Ciphers
.br
CipherSuites
.br
VerifyPeer
.br
AllowWrongHost
.br
RemoveHTTPAcceptEncoding
.br
RemoveHTTPReferer
.br
VerifyPeer
MaxHTTPHeaderSize
.br
AllowWrongHost
ValidateProto
.br
UserAuth
.br
@ -557,10 +495,97 @@ UserTimeout
.br
UserAuthURL
.br
ValidateProto
\fB}\fR
.br
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
\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 configuration
preceding them. Multiple specs are allowed, one on each line.
.TP
\fBProxySpec {\fR
.br
Proto
.br
Addr
.br
Port
.br
DivertPort
.br
DivertAddr
.br
ReturnAddr
.br
TargetAddr
.br
TargetPort
.br
SNIPort
.br
NatEngine
.br
Divert
.br
Passthrough
.br
DenyOCSP
.br
CACert
.br
CAKey
.br
ClientCert
.br
ClientKey
.br
CAChain
.br
LeafCRLURL
.br
DHGroupParams
.br
ECDHCurve
.br
SSLCompression
.br
ForceSSLProto
.br
DisableSSLProto
.br
EnableSSLProto
.br
MinSSLProto
.br
MaxSSLProto
.br
Ciphers
.br
CipherSuites
.br
VerifyPeer
.br
AllowWrongHost
.br
RemoveHTTPAcceptEncoding
.br
RemoveHTTPReferer
.br
MaxHTTPHeaderSize
.br
ValidateProto
.br
UserAuth
.br
UserTimeout
.br
UserAuthURL
.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"