mirror of https://github.com/sonertari/SSLproxy
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
617 lines
16 KiB
Groff
617 lines
16 KiB
Groff
.\"-
|
|
.\" SSLproxy - transparent SSL/TLS proxy for diverting packets to programs
|
|
.\" https://github.com/sonertari/SSLproxy
|
|
.\"
|
|
.\" Copyright (c) 2009-2019, Daniel Roethlisberger <daniel@roe.ch>.
|
|
.\" Copyright (c) 2017-2024, Soner Tari <sonertari@gmail.com>.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright notice,
|
|
.\" this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright notice,
|
|
.\" this list of conditions and the following disclaimer in the documentation
|
|
.\" and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ``AS IS''
|
|
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
|
|
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.TH "sslproxy.conf" "5" "18 Feb 2024" "v0.9.5" "SSLproxy"
|
|
.SH "NAME"
|
|
.LP
|
|
\fBsslproxy.conf\fR \- Configuration file for SSLproxy
|
|
.SH "DESCRIPTION"
|
|
.LP
|
|
The file sslproxy.conf configures SSLproxy, sslproxy(1).
|
|
.SH "FILE FORMAT"
|
|
The file consists of comments and options with arguments. Each line which
|
|
starts with a hash (\fB#\fR) symbol is ignored by the parser. Options and
|
|
arguments are of the form \fBOption Argument\fR.
|
|
.LP
|
|
Structured proxyspecs are defined between curly braces. The opening curly
|
|
brace should be on the same line as the ProxySpec keyword. The closing curly
|
|
brace and option-argument pairs should be on a line of their own.
|
|
.LP
|
|
The arguments are of the following types:
|
|
.TP
|
|
\fBBOOL\fR
|
|
Boolean value (yes/no).
|
|
.TP
|
|
\fBSTRING\fR
|
|
String.
|
|
.TP
|
|
\fBNUMBER\fR
|
|
Unsigned integer.
|
|
.SH "DIRECTIVES"
|
|
.LP
|
|
When an option is not used (hashed or doesn't exist in the configuration file)
|
|
sslproxy takes a default action. If an option is defined outside any
|
|
structured proxyspec, then it is used as a global default. If an option does
|
|
not have a command line equivalent, -o opt=val option can be used to override
|
|
it on the command line.
|
|
.LP
|
|
Note that the ordering of options, rules, and proxyspecs in configuration
|
|
files (and on the command line) is important. For example, rules and
|
|
proxyspecs can only make use of the options defined earlier.
|
|
.TP
|
|
\fBCACert STRING\fR
|
|
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.
|
|
.TP
|
|
\fBClientCert STRING\fR
|
|
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.
|
|
.TP
|
|
\fBCAChain STRING\fR
|
|
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.
|
|
.br
|
|
Default: generate
|
|
.TP
|
|
\fBLeafCRLURL STRING\fR
|
|
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.
|
|
.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.
|
|
.TP
|
|
\fBWriteGenCertsDir STRING\fR
|
|
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.
|
|
.TP
|
|
\fBDenyOCSP BOOL\fR
|
|
Deny all OCSP requests on all proxyspecs. Equivalent to -O command line option.
|
|
.TP
|
|
\fBPassthrough BOOL\fR
|
|
Passthrough SSL connections if they cannot be split because of client cert
|
|
auth or no matching cert and no CA. Equivalent to -P command line option.
|
|
.br
|
|
Default: drop
|
|
.TP
|
|
\fBDHGroupParams STRING\fR
|
|
Use DH group params from pemfile. Equivalent to -g command line option.
|
|
.br
|
|
Default: keyfiles or auto
|
|
.TP
|
|
\fBECDHCurve STRING\fR
|
|
Use ECDH named curve. Equivalent to -G command line option.
|
|
.br
|
|
Default: prime256v1
|
|
.TP
|
|
\fBSSLCompression BOOL\fR
|
|
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.
|
|
.br
|
|
Default: all
|
|
.TP
|
|
\fBDisableSSLProto STRING\fR
|
|
Disable SSL/TLS protocol version. Equivalent to -R command line option.
|
|
.br
|
|
Default: none
|
|
.TP
|
|
\fBEnableSSLProto STRING\fR
|
|
Enable SSL/TLS protocol version. Equivalent to -B command line option.
|
|
.br
|
|
Default: all
|
|
.TP
|
|
\fBMinSSLProto STRING\fR
|
|
Min SSL/TLS protocol version.
|
|
.br
|
|
Default: tls10
|
|
.TP
|
|
\fBMaxSSLProto STRING\fR
|
|
Max SSL/TLS protocol version.
|
|
.br
|
|
Default: tls13
|
|
.TP
|
|
\fBCiphers STRING\fR
|
|
Use the given OpenSSL ciphers spec. Equivalent to -s command line option.
|
|
.br
|
|
Default: ALL:-aNULL
|
|
.TP
|
|
\fBCipherSuites STRING\fR
|
|
Use the given OpenSSL ciphersuites spec. The ciphersuites spec is for TLS 1.3.
|
|
Equivalent to -U command line option.
|
|
.br
|
|
Default: TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
|
|
.TP
|
|
\fBLeafKeyRSABits NUMBER\fR
|
|
Leaf key RSA keysize in bits, use 1024|2048|3072|4096.
|
|
.br
|
|
Default: 2048
|
|
.TP
|
|
\fBOpenSSLEngine STRING\fR
|
|
The OpenSSL engine to activate. Equivalent to -x command line option.
|
|
.TP
|
|
\fBNATEngine STRING\fR
|
|
Specify default NAT engine to use. Equivalent to -e command line option.
|
|
.TP
|
|
\fBUser STRING\fR
|
|
Drop privileges to user. Equivalent to -u command line option.
|
|
.br
|
|
Default: nobody, if run as root
|
|
.TP
|
|
\fBGroup STRING\fR
|
|
Drop privileges to group. Equivalent to -m command line option.
|
|
.br
|
|
Default: Primary group of user
|
|
.TP
|
|
\fBChroot STRING\fR
|
|
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.
|
|
.TP
|
|
\fBContentLog STRING\fR
|
|
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.
|
|
.TP
|
|
\fBContentLogPathSpec STRING\fR
|
|
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.
|
|
.TP
|
|
\fBPcapLog STRING\fR
|
|
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.
|
|
.TP
|
|
\fBPcapLogPathSpec STRING\fR
|
|
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). 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.
|
|
.TP
|
|
\fBDaemon BOOL\fR
|
|
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.
|
|
.TP
|
|
\fBDebugLevel NUMBER\fR
|
|
Verbose debug level, 2-4.
|
|
.TP
|
|
\fBConnIdleTimeout NUMBER\fR
|
|
Close connections after this many seconds of idle time.
|
|
.br
|
|
Default: 120
|
|
.TP
|
|
\fBExpiredConnCheckPeriod NUMBER\fR
|
|
Check for expired connections every this many seconds.
|
|
.br
|
|
Default: 10.
|
|
.TP
|
|
\fBLogStats BOOL\fR
|
|
Log statistics to syslog. Equivalent to -J command line option.
|
|
.br
|
|
Default: yes
|
|
.TP
|
|
\fBStatsPeriod NUMBER\fR
|
|
Log statistics every this many ExpiredConnCheckPeriod periods.
|
|
.br
|
|
Default: 1
|
|
.TP
|
|
\fBRemoveHTTPAcceptEncoding BOOL\fR
|
|
Remove HTTP header line for Accept-Encoding.
|
|
.br
|
|
Default: yes
|
|
.TP
|
|
\fBRemoveHTTPReferer BOOL\fR
|
|
Remove HTTP header line for Referer.
|
|
.br
|
|
Default: yes
|
|
.TP
|
|
\fBVerifyPeer BOOL\fR
|
|
Verify peer using default certificates.
|
|
.br
|
|
Default: yes
|
|
.TP
|
|
\fBAllowWrongHost BOOL\fR
|
|
When disabled, never add the SNI to forged certificates, even if the SNI
|
|
provided by the client does not match the server certificate's CN/SAN. Helps
|
|
pass the wrong.host test at https://badssl.com.
|
|
.br
|
|
Default: no
|
|
.TP
|
|
\fBUserAuth BOOL\fR
|
|
Require authentication for users to use SSLproxy.
|
|
.br
|
|
Default: no
|
|
.TP
|
|
\fBDivertUsers STRING\fR
|
|
Comma separated list of users. Connections from these users are diverted to
|
|
listening programs. Users not listed in DivertUsers or PassUsers are blocked.
|
|
Max of 50 users can be listed.
|
|
.TP
|
|
\fBPassUsers STRING\fR
|
|
Comma separated list of users. Connections from these users are simply passed
|
|
through to their original destinations, not diverted to listening programs.
|
|
Users not listed in DivertUsers or PassUsers are blocked.
|
|
Max of 50 users can be listed.
|
|
.TP
|
|
\fBUserDBPath STRING\fR
|
|
Path to user db file.
|
|
.TP
|
|
\fBUserTimeout NUMBER\fR
|
|
Time users out after this many seconds of idle time.
|
|
.br
|
|
Default: 300.
|
|
.TP
|
|
\fBUserAuthURL STRING\fR
|
|
Redirect URL for users to log in to the system.
|
|
.TP
|
|
\fBValidateProto BOOL\fR
|
|
Validate proxy spec protocols.
|
|
.br
|
|
Default: no
|
|
.TP
|
|
\fBMaxHTTPHeaderSize NUMBER\fR
|
|
Max HTTP header size in bytes for protocol validation.
|
|
.br
|
|
Default: 8192.
|
|
.TP
|
|
\fBOpenFilesLimit NUMBER\fR
|
|
Set open files limit, use 50-10000.
|
|
.br
|
|
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.
|
|
.br
|
|
Default: yes
|
|
.TP
|
|
\fBPassSite STRING\fR
|
|
Passthrough site: site[*] [(clientaddr|user|*) [description desc]].
|
|
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. '*'
|
|
matches all client IP addresses or users. User auth should be enabled for user
|
|
and description filtering to work. Case is ignored while matching description.
|
|
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
|
|
\fBInclude STRING\fR
|
|
Load configuration from an include file.
|
|
|
|
Recursive include files are not allowed. The Include option cannot be used in
|
|
include files.
|
|
.TP
|
|
\fBDefine STRING\fR
|
|
Define macro to be used in filtering rules. Macro names must start with a $
|
|
char. The macro name must be followed by words separated with spaces. For
|
|
example,
|
|
|
|
Define $macro value1 value2
|
|
|
|
Recursive macro definitions are not allowed.
|
|
.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.
|
|
.TP
|
|
\fBMatch STRING\fR
|
|
Match filtering rule specifies log actions for the connection without changing
|
|
its filter action.
|
|
.br
|
|
|
|
The syntax of one line filtering rules is as follows:
|
|
.br
|
|
|
|
(Divert|Split|Pass|Block|Match)
|
|
([from (
|
|
user (username[*]|$macro|*) [desc (desc[*]|$macro|*)]|
|
|
desc (desc[*]|$macro|*)|
|
|
ip (clientip[*]|$macro|*)|
|
|
*)]
|
|
[to (
|
|
(sni (servername[*]|$macro|*)|
|
|
cn (commonname[*]|$macro|*)|
|
|
host (host[*]|$macro|*)|
|
|
uri (uri[*]|$macro|*)|
|
|
ip (serverip[*]|$macro|*)) [port (serverport[*]|$macro|*)]|
|
|
port (serverport[*]|$macro|*)|
|
|
*)]
|
|
[log ([[!]connect] [[!]master] [[!]cert]
|
|
[[!]content] [[!]pcap] [[!]mirror] [$macro]|[!]*)]
|
|
|*) [# comment]
|
|
.br
|
|
|
|
See sslproxy(1) for the details.
|
|
.TP
|
|
\fBFilterRule {\fR
|
|
.br
|
|
Action
|
|
.br
|
|
User
|
|
.br
|
|
Desc
|
|
.br
|
|
SrcIp
|
|
.br
|
|
SNI
|
|
.br
|
|
CN
|
|
.br
|
|
Host
|
|
.br
|
|
URI
|
|
.br
|
|
DstIp
|
|
.br
|
|
DstPort
|
|
.br
|
|
Log
|
|
.br
|
|
ReconnectSSL
|
|
.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
|
|
\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
|
|
.br
|
|
PassSite
|
|
.br
|
|
Define
|
|
.br
|
|
(Divert|Split|Pass|Block|Match) one line filtering rules
|
|
.br
|
|
FilterRule {...} structured filtering rules
|
|
.br
|
|
\fB}\fR
|
|
.br
|
|
|
|
Structured proxy specifications may consist of the options listed above. The
|
|
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"
|
|
.LP
|
|
/etc/sslproxy/sslproxy.conf
|
|
.SH "AUTHOR"
|
|
.LP
|
|
The config file facility was added by Soner Tari <sonertari@gmail.com>.
|
|
.SH "SEE ALSO"
|
|
.LP
|
|
sslproxy(1)
|