path: root/man/sslserver.1

.TH sslserver 1
.SH NAME
sslserver \- accept TLS connections and setup SSL CTX
.SH SYNOPSIS
.B sslserver 
[
.I opts 
]
.I host 
.I port 
.I prog 
.SH DESCRIPTION
.I opts 
is a series of getopt-style options, 
.I host 
is a host name or IP address, 
.I port 
is a TCP port, and 
.I prog 
is one or more arguments specifying a program 
to run for each accepted connection. 

The server's address is given by
.I host
and
.IR port .
.SH BINDINGS
.B sslserver
will be attached to the primary IP address of
.I host
while the host name is fed through qualification using 
.IR dns_ip6_qualify .
If 
.I host
is given as dotted decimal IPv4 or compactified IPv6
address,
.B sslserver 
will bind uniquely to those.  In order to bind
.B sslserver
to a LLU IPv6 address (ie. fe80::a:b:c) additionally the interface name
.B \-I\fIifname
has to be provided.

\fINote\fR: The kernel might use temporary changing SLAAC addresses.

.B sslserver
can be instructed to be multi-homing capable while binding 
to all available IP addresses. Now
.I host 
is given as 
.I 0.0.0.0 
or 
.IR :: .

Further,
.B sslserver
can be forced to provide dual-stack capabilities, thus allowing
IPv4 and IPv6 clients to attach to the same instance once 
.I host 
equals ':0' as pseudo IP address.

.I port
may be a numeric port number
or a port name.  If
.I port
is 0,
.B sslserver
will choose a free port.
.SH SERVING
.B sslserver 
listens for connections from TCP clients. 
Typically, for each connection, it runs 
.IR prog , 
with file descriptor 0 reading from, 
and file descriptor 1 writing to a child process
.IR ssl .
If however
.B sslserver
is called with the option
.IR \-n ,
it communcates with 
.I prog
on mutually chosen, arbitrary file descriptors.
.I prog
needs to support the UCSPI-TLS API.
The
.I ssl 
process attempts an SSL accept via the network. 
If it succeeds, it translates data between
.I prog 
and the network, performing any necessary SSL encoding and decoding. 
Before running
.IR prog , 
.B sslserver 
reads and sets certain environment variables. 

.B sslserver 
exits when it receives SIGTERM. 
.SH OPTIONS
.B General Options: 
.TP
.B \-q 
Quiet. Do not print error messages. 
.TP
.B \-Q 
(Default.) Print error messages. 
.TP
.B \-v 
Verbose. Print error and status messages.
.TP
.B \-V 
Print additional verbose SSL connection informations (protocol and cipher).

.P
.B Connection options: 
.TP
.B \-1 
After preparing to receive connections, 
print the local port number to standard output. 
.TP
.B \-4
Use IPv4 sockets for connections. 
.TP
.B \-6
Use IPv6 connections. This will set \fIPROTO\fR to \fBTCP6\fR and put 
IPv6 addresses in \fITCP6LOCALIP\fR and \fITCP6REMOTEIP\fR.
.TP
.B \-c \fIn
Do not handle more than 
.I n 
simultaneous connections. 
If there are 
.I n 
simultaneous connections copies of 
.I prog 
running, defer acceptance of a new connection until one copy finishes. 
.I n 
must be a positive integer. The default value is 40. 
.TP
.B \-x \fIcdb 
Follow the rules compiled into 
.I cdb 
by 
.BR tcprules . 
These rules may specify setting environment variables 
or rejecting connections from bad sources. 
You can rerun 
.B tcprules 
to change the rules while 
.B sslserver 
is running. 
.TP 
.B \-X
With 
.B \-x \fIcdb, 
allow connections even if 
.I cdb 
does not exist. Normally 
.B sslserver 
will drop the connection if
.I cdb 
does not exist. 
.TP 
.B \-y \fIcdb
Evaluate and follow IP rules compiled into
.I cdb
prior of doing a \fIDNS\fR or \fIIDENT\fR lookup.
A shared \fIcdb\fR is possible.
.TP
.B \-B \fIbanner
Write 
.I banner 
to the network immediately after each SSL connection is made. The 
.I banner 
is subject to SSL encryption. 
.TP
.B \-g \fIgid
Switch group ID to 
.I gid 
after preparing to receive connections. 
.I gid 
must be a positive integer. 
.TP
.B \-u \fIuid
Switch user ID to 
.I uid 
after preparing to receive connections.
.I uid 
must be a positive integer. 
.TP
.B \-U 
Same as
.B \-g 
$GID
.B \-u 
$UID. Typically, $GID and $UID are set by 
.BR envuidgid . 
.TP
.B \-I \fIifname
Bind to the network interface
.I ifname
("eth0" on Linux, for example).  This is only defined and needed for
IPv6 link-local addresses.
.TP
.B \-b \fIn
Allow a backlog of approximately 
.I n 
pending connections. 
.TP
.B \-o 
Leave IP options alone. If the client is sending packets 
along an IP source route, send packets back along the same route. 
.TP
.B \-O 
(Default.) Kill IP options. 
A client can still use source routing to connect and to send data, 
but packets will be sent back along the default route. 
.TP
.B \-d 
Delay sending data for a fraction of a second whenever the 
remote host is responding slowly. This is currently the default, 
but it may not be in the future; if you want it, set it explicitly. 
.TP
.B \-D 
Never delay sending data; enable TCP_NODELAY. 
.TP
.B \-t \fIn 
Give up on the $SSLREMOTEINFO connection attempt after 
.I n 
seconds. The default value is: 26. 
.TP
.B \-T \fIn 
Give up on the SSL connection attempt after
.I n 
seconds. The default value is: 26. 
.TP
.B \-w \fIn 
Give up on a connection or program after waiting 
.I n 
seconds for read or write. The default value is: 3600. 

.P
.B SSL and TLS connection options:
.TP
.B \-n 
Delay setup of SSL environment until a STARTTLS/STLS command
has been issued by the client.
.TP
.B \-N 
(Default.) Setup the SSL environment immediately.
.TP
.B \-s 
Store client and server certificate information in the environment, a la 
.IR mod_ssl .
.TP
.B \-S 
(Default.) Do not store client and server certificate information in the environment. 

.P
.B X509 certificate and encryption options:
.TP
.B \-3
Read a null-terminated
.I key password
from file descriptor
.IR 3 .
.TP
.B \-m
(Mail.) Require valid client certificates, but don't check for matching FQDN.
.TP
.B \-z
(Host.) Require valid client certificates and match FQDN (if given) against SAN/DN.
.TP
.B \-Z
(Default.) Do not require client certificates.

.P
.B Data-gathering options: 
.TP
.B \-h 
(Default.) Look up the remote host name in DNS to set the 
environment variable $SSLREMOTEHOST. 
In this case, additionally the CN/SAN in the X509 certificate can be
checked, provided, the option
.B \-z
is set. 
.TP
.B \-H 
Do not look up the remote host name in DNS; 
remove the environment variable $SSLREMOTEHOST. 
To avoid loops, you must use this option for servers on TCP port 53. 
.TP
.B \-p 
Paranoid. After looking up the remote host name in DNS, 
look up the IP addresses in DNS for that host name, 
and remove the environment variable  $SSLREMOTEHOST 
if none of the addresses match the client's IP address. 
.TP
.B \-P
(Default.) Not paranoid. 
.TP
.B \-l \fIlocalname 
Do not look up the local host name in DNS; use 
.I localname 
for the environment variable $SSLLOCALHOST. 
A common choice for 
.I localname 
is 0. To avoid loops, you must use this option for servers on TCP port 53. 
.TP
.B \-r 
Attempt to obtain $SSLREMOTEINFO from the remote host. 
.TP
.B \-R
(Default.) Do not attempt to obtain $SSLREMOTEINFO from the remote host.
To avoid loops, you must use this option for servers on TCP ports 53 and 113. 
.TP
.B \-e 
Set protocol environment a la
.B tcpserver . 
Set $TCPLOCALIP, $TCPLOCALPORT, $TCPLOCALHOST, $TCPREMOTEIP, 
$TCPREMOTEPORT, $TCPREMOTEHOST, and $TCPREMOTEINFO as well as for IPv6
connections additionally $TCP6LOCALIP, $TCP6LOCALPORT, $TCP6LOCALHOST
together with $TCP6REMOTEIP, $TCP6REMOTEPORT, $TCP6RMEOTEHOST and
$TCP6INTERFACE from the current $SSL environment (see below). 
.TP
.B \-E
(Default.) Do not set any 
.B tcpserver 
environment variables.
.SH "DNS RESOLVER SETTINGS"
Use \fI$DNSCACHEIP\fR to set the DNS resolver IP dynamically
irrespectively from the settings in 
.IR /etc/resolv.conf .
If the environment variable \fI$LOCALDOMAIN\fR is populated,
this name will be appended to unqualified host names.
Additional rewriting of local to public names is facilitated
in case the file
.I /etc/dnswritefile
exists and is populated, or alternatively the environment
variable \fI$DNSREWRITEFILE\fR points to a differnent file.
.SH "ENVIRONMENT VARIABLES READ"
.B sslserver
acknowledges the environment variable
.I MAXCONIP="n"
where
.I n
is the number of
.B sslserver
children spawned for a particular remote IP address.
.I n
is restricted to the general connection limit
.I c
provided as call argument.
.I MAXCONIP
is typically defined in
.BR sslserver 's
cdb for a given condition and thus only active meeting those.
.I MAXCONIP
defaults
.I 0
meaning no restriction.
.SH "SSL ENVIRONMENT VARIABLES READ"
These variables define the run-time environment of
.B sslserver
and are used to specify X509 certificates and keyfile per connection.
.TP
.B $SSL_USER=\fIname
The user, reading the certificates and keyfile.
.TP
.B $SSL_GROUP=\fIgroup
The respective user group.
.TP
.B $SSL_UID=\fIuid
The numerical UID of the $SSL_USER.
.TP
.B $SSL_CHROOT=\fIpath
Perform reading of certificates and keyfile in a $SSL_CHROOT jail.
.TP
.B $CAFILE=\fIpath 
If set, overrides the compiled-in CA file name. 
The CA file contains the list of CAs used to verify the client certificate. 
Certificates in $CAFILE are processed when the server starts. 
.TP
.B $CADIR=\fIpath
If set, overrides the compiled-in CA directory name. 
The CA directory contains certificates files used to verify the client certificate. 
This list augments the list from $CAFILE. 
Certificates in $CADIR are processed during certificate verification. 
.TP
.B $CERTFILE=\fIpath
If set, overrides the compiled-in certificate file name. 
The server presents this certificate to clients. 
.TP
.B $CERTCHAINFILE=\fIpath
If set, overrides the compiled-in certificate chainfile name. 
The server presents this list of certificats to clients. 
.I Note: 
Providing $CERTCHAINFILE has precedence over $CERTFILE. 
Certificates in this file needs to be 'ordered' starting from the
uppermost root certificates and placing your host's certificate at the end.
.TP
.B $CIPHERS=\fIstring
If set, override the compiled-in SSL cipher list
defining the security level for the connection.
A typical choice would be 'TLSv1+HIGH:!SSLv2:!MD5'.
.TP
.B $DHFILE=\fIpath
If set, overrides the compiled-in DH parameter file name. 
.TP
.B $KEYFILE=\fIpath 
If set, overrides the compiled-in key file name. 
The key is used when loading the server certificate. 
Setting $KEYFILE to the empty instructs the server 
not to use a 
.I keyfile 
when loading it's certificate. 
.TP
.B $VERIFYDEPTH=\fIn
If set, overrides the compiled-in verification depth. Default: 1.
.TP
.B $CCAFILE=\fIpath
If set, overrides the compiled-in client CA file name for client certificate request. 
The client CA file contains the list of CAs sent to the client 
when requesting a client certificate. 
.I Note:
Setting of $CCAFILE is required while using the option 
.IR \-z
or
.IR \-m.
However, declaring
.B $CCAFILE="-"
disables (on a per-connection base) the client certificate request.
.TP
.B $CCAVERIFY
If set, 
.B sslserver
requests a valid client certificate on a per-connection base, unlike the general 
option
.IR \-z . 
.SH "SSL ENVIRONMENT VARAIBLES SET"
In case 
.B sslserver
is called with the option
.BR \-e ,
the following
.I mod_ssl
environment variables are provided:
.TP 
.B SSL_PROTOCOL
The TLS protocol version (SSLv3, TLSv1, ...).
.TP 
.B SSL_SESSION_ID
The hex-encoded SSL session id.
.TP 
.B SSL_CIPHER
The cipher specification name.
.TP 
.B SSL_CIPHER_USEKEYSIZE
Number of cipher bits (actually used).
.TP 
.B SSL_CIPHER_ALGKEYSIZE
Number of cipher bits (possible).
.TP 
.B SSL_VERSION_INTERFACE
The mod_ssl program version.
.TP 
.B SSL_VERSION_LIBRARY	
The OpenSSL program version.
.TP 
.B SSL_CLIENT_M_VERSION	
The version of the client certificate.
.TP
.B SSL_CLIENT_M_SERIAL	
The serial of the client certificate.
.TP 
.B SSL_CLIENT_S_DN	
Subject DN in client's certificate.
.TP 
.B SSL_CLIENT_S_DN_x509	
Component of client's Subject DN.
.TP 
.B SSL_CLIENT_I_DN	
Issuer DN of client's certificate.
.TP 
.B SSL_CLIENT_I_DN_x509	
Component of client's Issuer DN.
.TP 
.B SSL_CLIENT_V_START	
Validity of client's certificate (start time).
.TP 
.B SSL_CLIENT_V_END	
Validity of client's certificate (end time).
.TP 
.B SSL_CLIENT_A_SIG	
Algorithm used for the signature of client's certificate.
.TP 
.B SSL_CLIENT_A_KEY	
Algorithm used for the public key of client's certificate.
.TP 
.B SSL_CLIENT_CERT	
PEM-encoded client certificate.
.TP 
.B SSL_CLIENT_CERT_CHAIN \fIn	
PEM-encoded certificates in client certificate chain.
.TP 
.B SSL_CLIENT_VERIFY	
NONE, SUCCESS, GENEROUS or FAILED:reason.
.TP 
.B SSL_SERVER_M_SERIAL	
The serial of the server certificate.
.TP 
.B SSL_SERVER_S_DN	
Subject DN in server's certificate.
.TP 
.B SSL_SERVER_S_DN_x509	
Component of server's Subject DN.
.TP 
.B SSL_SERVER_I_DN	
Issuer DN of server's certificate.
.TP 
.B SSL_SERVER_I_DN_x509	
Component of server's Issuer DN.
.TP 
.B SSL_SERVER_V_START	
Validity of server's certificate (start time).
.TP 
.B SSL_SERVER_V_END	
Validity of server's certificate (end time).
.TP 
.B SSL_SERVER_A_SIG	
Algorithm used for the signature of server's certificate.
.TP 
.B SSL_SERVER_A_KEY	
Algorithm used for the public key of server's certificate.
.TP 
.B SSL_SERVER_CERT	
PEM-encoded server certificate.
.P 
For \fBSSL_CLIENT_x_DN_x509\fR and \fBSSL_SERVER_x_DN_x509\fR, 
x509 denotes a component of the DN: 
C, ST, L, O, OU, CN, T, I, G, S, D, UID, Email.

.P
Other SSL environment variables set:
.P
.BR PROTO,
.BR SSLLOCALHOST,
.BR SSLLOCALIP,
.BR SSLLOCALPORT,
.BR SSLREMOTEHOST,
.BR SSLREMOTEINFO,
.BR SSLREMOTEIP,
.BR SSLREMOTEPORT.

.P
TCP environment variables set:
.P
.BR TCPLOCALHOST,
.BR TCPLOCALIP,
.BR TCPLOCALPORT,
.BR TCPREMOTEHOST,
.BR TCPREMOTEINFO,
.BR TCPREMOTEIP,
.BR TCPREMOTEPORT.

.P
TCP6 environment variables set:
.P
.BR TCP6INTERFACE,
.BR TCP6LOCALHOST,
.BR TCP6LOCALIP,
.BR TCP6LOCALPORT,
.BR TCP6REMOTEHOST,
.BR TCP6REMOTEIP,
.BR TCP6REMOTEPORT.
.SH "LOGGING AND ERROR MESSAGES"
.B sslserver
prints particular state information for individual connections in case 
.I -v
is specified. Here, the
local and remote IP addresses and port together
with the number of used/available/ip connection limited children:

.EX 
  sslserver: status 1/40/0
  sslserver: pid xxxx from <ip>
  sslserver: [ok|deny] xxxx <local>:<localip>:<localport> <remotehost>:<remoteip>:<remoteport> 
  sslserver: ended by xyz status nnnn
.EE

If 
.I MAXCONIP
is given as global environment variable, one may encounter:

.EX 
  sslserver: status z/40/<maxconip>
  sslserver: WARNING ip connection limit of <maxconip> exceeded for: <remoteip>
.EE

Rather, if 
.I MAXCONIP 
is read from the cdb, the following message might appear:

.EX 
  sslserver: status 1/40/0
  sslserver: pid xxxx from <ip>
  sslserver: deny xxxx ... ip connection limit:<maxconip> exceeded
  sslserver: ended by xyz status nnnn
.EE

In all cases, the resolved host names depends on the usage of
.IR l ,
.I -h
and 
.IR -p .
If
.I -V 
is instead given as argument, lines like

.EX 
  sslserver: tls xxxx accept TLSv1.2:ECDH-RSA-AES256-GCM-SHA384
  sslserver: tls xxxx accept TLSv1.3:TLS_CHACHA20_POLY1305_SHA256
.EE

show additionally the negotiated cipher suite.
.P
.B Error and particular messages
.P
TLS error messages are provided, if possible:
.TP
.I sslerver: error: (111) unable to speak TLS from: ... for pid: ... DH lib
.P 
TLS handshake failure.
.TP 
.I sslserver: error: (111) unable to accept TLS from: ... for pid: ... system lib
.P 
The remote socket was prematurely closed; usually because 
the X.509 cert was not accepted by the client.
.TP 
.I sslserver: info: valid client cert received for pid: <pid>
.P 
A client X.509 cert has been accepted for
mutual authentication.
.P
.SH "SEE ALSO"
sslhandle(1),
sslclient(1),
sslconnect(1),
sslcat(1),
https@(1),
ucspi-tls(2),
tcprules(1),
tcprulescheck(1),
tcpserver(1),
tcp-environ(5)
.SH REFERENCE
http://httpd.apache.org/docs/2.4/mod/mod_ssl.html