diff options
Diffstat (limited to 'man/sslserver.1')
| -rw-r--r-- | man/sslserver.1 | 657 |
1 files changed, 657 insertions, 0 deletions
diff --git a/man/sslserver.1 b/man/sslserver.1 new file mode 100644 index 0000000..2d31845 --- /dev/null +++ b/man/sslserver.1 @@ -0,0 +1,657 @@ +.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 |