diff options
Diffstat (limited to 'man/sslhandle.1')
| -rw-r--r-- | man/sslhandle.1 | 578 |
1 files changed, 578 insertions, 0 deletions
diff --git a/man/sslhandle.1 b/man/sslhandle.1 new file mode 100644 index 0000000..8ca1b1f --- /dev/null +++ b/man/sslhandle.1 @@ -0,0 +1,578 @@ +.TH sslhandle 1 +.SH NAME +sslhandle \- preforking TLS server +.SH SYNOPSIS +.B sslhandle +[ +.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 +.I server +subroutine is called within a loop, with one iteration per request +listening to +.I \-c \fIn +incoming connections simultanously. +It must release any resources allocated to handle a particular request before returning to its caller. + +The server's address is given by +.I host +and +.IR port . + +.SH BINDINGS +.B sslhandle +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 sslhandle +will bind uniquely to those. In order to bind +.B sslhandle +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 sslhandle +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 sslhandle +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 sslhandle +will choose a free port. + +.SH SERVING +.B sslhandle +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 . +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 sslhandle +reads and sets certain environment variables. + +.B sslhandle +exists, if the parent process receives a 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 messages 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 sslhandle +is running. +.TP +.B \-X +With +.B \-x \fIcdb, +allow connections even if +.B \-I cdb +does not exist. Normally +.B sslhandle +will drop the connection if +.I cdb +does not exist. +.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 \-f \fIlockfile +Additional filename given for locking. If +.I lockfile +is provided and not exclusive readable +.B sslhandle +will not start. +Utilize this option if your accept system call suffers from the thundering herd problem. +.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 \-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 $TCP6REMOTEIP, $TCP6RMEOTEHOST, and $TCP6REMOTEINFO +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 "SSL ENVIRONMENT VARIABLES READ" +These variables define the run-time environment of +.B sslhandle +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 sslhandle +requests a valid client certificate on a per-connection base, unlike the general +option +.IR \-z . +.SH "SSL ENVIRONMENT VARAIBLES SET" +In case +.B sslhandle +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 $SSL_CLIENT_x_DN_x509 and $SSL_SERVER_x_DN_x509, +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 sslhandle +prints information about individual connections +in case +.I -v +or +.I -V +is specified as argument. +TLS error messages are provided if possible: +.TP +.B unable to speak TLS for pid: ... DH lib +TLS handshake failure. +.TP +.B unable to accept TLS for pid: ... +The remote socket was prematurely closed. +.P +.SH "SEE ALSO" +sslserver(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 +http://www.superscript.com/ucspi-ssl/prefork.html |