SSLproxy/sslproxy.conf.5

.\"-
.\" SSLproxy - transparent SSL/TLS proxy for diverting packets to programs
.\" https://github.com/sonertari/SSLproxy
.\"
.\" Copyright (c) 2009-2018, Daniel Roethlisberger <daniel@roe.ch>.
.\" Copyright (c) 2017-2019, 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" "22 Jul 2019" "v0.7.0" "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.
.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
\fBLeafCerts STRING\fR
Use key from pemfile for leaf certs. Equivalent to -K command line option.
.br
Default: generate
.TP
\fBCRL STRING\fR
Use URL as CRL distribution point for all forged certs. Equivalent to -q command line option.
.TP
\fBTargetCertDir 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
\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
\fBPassSite STRING\fR
Passthrough site: site [(clientaddr|(user|*) [description keyword])]. If the 
site matches SNI or common names in the SSL certificate, the connection is 
passed through the proxy. Per site filters can be defined using client IP 
addresses, users, and description keywords. '*' matches all users. User auth 
should be enabled for user and description keyword filtering to work. 
Case is ignored while matching description keywords. Multiple sites are 
allowed, one on each line.
.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
\fBCiphers STRING\fR
Use the given OpenSSL cipher suite spec. Equivalent to -s command line option.
.br 
Default: ALL:-aNULL
.TP
\fBLeafKeyRSABits NUMBER\fR
Leaf key RSA keysize in bits, use 1024|2048|3072|4096.
.br 
Default: 1024
.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). 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 
\fBSSLShutdownRetryDelay NUMBER\fR
Retry to shut ssl conns down after this many micro seconds. Increasing this 
delay may avoid dirty shutdowns on slow connections, but increases resource 
usage, such as file descriptors and memory.
.br 
Default: 100
.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
\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
\fBProxySpec STRING\fR
One line proxy specification: type listenaddr+port up:port ua:addr ra:addr. 
The other options of one line proxyspecs are set to the global defaults. 
Multiple specs are allowed, one on each line.
.TP
\fBProxySpec {\fR
.br
Proto
.br
Addr
.br
Port
.br
DivertAddr
.br
DivertPort
.br
ReturnAddr
.br
NatEngine
.br
SNIPort
.br
TargetAddr
.br
TargetPort
.br
DenyOCSP
.br
Passthrough
.br
CACert
.br
CAKey
.br
ClientCert
.br
ClientKey
.br
CAChain
.br
DHGroupParams
.br
ECDHCurve
.br
SSLCompression
.br
ForceSSLProto
.br
DisableSSLProto
.br
Ciphers
.br
RemoveHTTPAcceptEncoding
.br
RemoveHTTPReferer
.br
VerifyPeer
.br
UserAuth
.br
UserTimeout
.br
UserAuthURL
.br
ValidateProto
.br
PassSite
.br
\fB}\fR
.br
Structured proxy specifications may consist of the options listed above. The 
Proto, Addr, Port, and DivertPort options are mandatory, and equivalent to 
type, listenaddr, port, and up options in one line proxyspecs, respectively. 
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)