SYNOPSIS
sslhandle [ opts ] host port prog
DESCRIPTION
opts is a series of getopt-style options, host is a host name or IP
address, port is a TCP port, and prog is one or more arguments
specifying a program to run for each accepted connection. The server
subroutine is called within a loop, with one iteration per request
listening to -c n 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 host and port.
BINDINGS
sslhandle will be attached to the primary IP address of host while the
host name is fed through qualification using dns_ip6_qualify. If host
is given as dotted decimal IPv4 or compactified IPv6 address, sslhandle
will bind uniquely to those. In order to bind sslhandle to a LLU IPv6
address (ie. fe80::a:b:c) additionally the interface name -Iifname has
to be provided.
Note: The kernel might use temporary changing SLAAC addresses.
sslhandle can be instructed to be multi-homing capable while binding to
all available IP addresses. Now host is given as 0.0.0.0 or ::.
Further, sslhandle can be forced to provide dual-stack capabilities,
thus allowing IPv4 and IPv6 clients to attach to the same instance once
host equals ':0' as pseudo IP address.
port may be a numeric port number or a port name. If port is 0,
sslhandle will choose a free port.
SERVING
sslhandle listens for connections from TCP clients. Typically, for
each connection, it runs prog, with file descriptor 0 reading from, and
file descriptor 1 writing to a child process ssl. The ssl process
attempts an SSL accept via the network. If it succeeds, it translates
data between prog and the network, performing any necessary SSL
encoding and decoding. Before running prog, sslhandle reads and sets
certain environment variables.
sslhandle exists, if the parent process receives a SIGTERM.
OPTIONS
General Options:
-q Quiet. Do not print error messages.
-6 Use IPv6 connections. This will set PROTO to TCP6 and put IPv6
addresses in TCP6LOCALIP and TCP6REMOTEIP.
-c n Do not handle more than n simultaneous connections. If there
are n simultaneous connections copies of prog running, defer
acceptance of a new connection until one copy finishes. n must
be a positive integer. The default value is 40.
-x cdb Follow the rules compiled into cdb by tcprules. These rules may
specify setting environment variables or rejecting connections
from bad sources. You can rerun tcprules to change the rules
while sslhandle is running.
-X With -x cdb, allow connections even if -I cdb does not exist.
Normally sslhandle will drop the connection if cdb does not
exist.
-B banner
Write banner to the network immediately after each SSL
connection is made. The banner is subject to SSL encryption.
-f lockfile
Additional filename given for locking. If lockfile is provided
and not exclusive readable sslhandle will not start. Utilize
this option if your accept system call suffers from the
thundering herd problem.
-g gid Switch group ID to gid after preparing to receive connections.
gid must be a positive integer.
-u uid Switch user ID to uid after preparing to receive connections.
uid must be a positive integer.
-U Same as -g $GID -u $UID. Typically, $GID and $UID are set by
envuidgid.
-I ifname
Bind to the network interface ifname ("eth0" on Linux, for
example). This is only defined and needed for IPv6 link-local
addresses.
-b n Allow a backlog of approximately n pending connections.
-o Leave IP options alone. If the client is sending packets along
an IP source route, send packets back along the same route.
-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.
-d Delay sending data for a fraction of a second whenever the
SSL and TLS connection options:
-s Store client and server certificate information in the
environment, a la mod_ssl.
-S (Default.) Do not store client and server certificate
information in the environment.
X509 certificate and encryption options:
-3 Read a null-terminated key password from file descriptor 3.
-m (Mail.) Require valid client certificates, but don't check for
matching FQDN.
-z (Host.) Require valid client certificates and match FQDN (if
given) against SAN/DN.
-Z (Default.) Do not require client certificates.
Data-gathering options:
-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 -z is set.
-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.
-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.
-P (Default.) Not paranoid.
-l localname
Do not look up the local host name in DNS; use localname for the
environment variable $SSLLOCALHOST. A common choice for
localname is 0. To avoid loops, you must use this option for
servers on TCP port 53.
DNS RESOLVER SETTINGS
Use $DNSCACHEIP to set the DNS resolver IP dynamically irrespectively
from the settings in /etc/resolv.conf. If the environment variable
$LOCALDOMAIN is populated, this name will be appended to unqualified
host names. Additional rewriting of local to public names is
facilitated in case the file /etc/dnswritefile exists and is populated,
or alternatively the environment variable $DNSREWRITEFILE points to a
differnent file.
SSL ENVIRONMENT VARIABLES READ
These variables define the run-time environment of sslhandle and are
used to specify X509 certificates and keyfile per connection.
$SSL_USER=name
The user, reading the certificates and keyfile.
$SSL_GROUP=group
The respective user group.
$SSL_UID=uid
The numerical UID of the $SSL_USER.
$SSL_CHROOT=path
Perform reading of certificates and keyfile in a $SSL_CHROOT
jail.
$CAFILE=path
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.
$CADIR=path
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.
$CERTFILE=path
If set, overrides the compiled-in certificate file name. The
server presents this certificate to clients.
$CERTCHAINFILE=path
If set, overrides the compiled-in certificate chainfile name.
The server presents this list of certificats to clients. 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.
$CIPHERS=string
If set, override the compiled-in SSL cipher list defining the
1.
$CCAFILE=path
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.
Note: Setting of $CCAFILE is required while using the option -z
or -m. However, declaring $CCAFILE="-" disables (on a per-
connection base) the client certificate request.
$CCAVERIFY
If set, sslhandle requests a valid client certificate on a per-
connection base, unlike the general option -z.
SSL ENVIRONMENT VARAIBLES SET
In case sslhandle is called with the option -e, the following mod_ssl
environment variables are provided:
SSL_PROTOCOL
The TLS protocol version (SSLv3, TLSv1, ...).
SSL_SESSION_ID
The hex-encoded SSL session id.
SSL_CIPHER
The cipher specification name.
SSL_CIPHER_USEKEYSIZE
Number of cipher bits (actually used).
SSL_CIPHER_ALGKEYSIZE
Number of cipher bits (possible).
SSL_VERSION_INTERFACE
The mod_ssl program version.
SSL_VERSION_LIBRARY
The OpenSSL program version.
SSL_CLIENT_M_VERSION
The version of the client certificate.
SSL_CLIENT_M_SERIAL
The serial of the client certificate.
SSL_CLIENT_S_DN
Subject DN in client's certificate.
SSL_CLIENT_S_DN_x509
Component of client's Subject DN.
SSL_CLIENT_I_DN
SSL_CLIENT_A_KEY
Algorithm used for the public key of client's certificate.
SSL_CLIENT_CERT
PEM-encoded client certificate.
SSL_CLIENT_CERT_CHAIN n
PEM-encoded certificates in client certificate chain.
SSL_CLIENT_VERIFY
NONE, SUCCESS, GENEROUS or FAILED:reason.
SSL_SERVER_M_SERIAL
The serial of the server certificate.
SSL_SERVER_S_DN
Subject DN in server's certificate.
SSL_SERVER_S_DN_x509
Component of server's Subject DN.
SSL_SERVER_I_DN
Issuer DN of server's certificate.
SSL_SERVER_I_DN_x509
Component of server's Issuer DN.
SSL_SERVER_V_START
Validity of server's certificate (start time).
SSL_SERVER_V_END
Validity of server's certificate (end time).
SSL_SERVER_A_SIG
Algorithm used for the signature of server's certificate.
SSL_SERVER_A_KEY
Algorithm used for the public key of server's certificate.
SSL_SERVER_CERT
PEM-encoded server certificate.
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.
Other SSL environment variables set:
PROTO, SSLLOCALHOST, SSLLOCALIP, SSLLOCALPORT, SSLREMOTEHOST,
SSLREMOTEINFO, SSLREMOTEIP, SSLREMOTEPORT.
TCP environment variables set:
TCPLOCALHOST, TCPLOCALIP, TCPLOCALPORT, TCPREMOTEHOST, TCPREMOTEINFO,
TCPREMOTEIP, TCPREMOTEPORT.
TCP6 environment variables set:
TCP6INTERFACE, TCP6LOCALHOST, TCP6LOCALIP, TCP6LOCALPORT, TCP6REMOTEHOST,
TCP6REMOTEIP, TCP6REMOTEPORT.
LOGGING AND ERROR MESSAGES
sslserver prints particular IP information for individual connections in case -v
is specified as argument:
sslserver status 1/40
sslserver pid xxxx from 127.0.0.1
sslserver [ok|deny] xxxx localhost:127.0.0.1::port remotehost:a.b.c.d::port
sslsever ended by xxyy status nnnn
where the resolved host names depends on the usage of l, -h and -p. If
-V is instead given as argument, the line:
sslserver: tls xxxx accept TLSv1.2:ECDH-RSA-AES256-GCM-SHA384
additionally shows the negotiated cipher suite.
Error and particular messages
TLS error messages are provided, if possible:
unable to speak TLS for pid: ... DH lib
TLS handshake failure.
unable to accept TLS for pid: ...
The remote socket was prematurely closed.
info: valid client cert received for: <pid>
A client X.509 cert has been accepted for mutual authentication.
SEE ALSO
sslserver(1), sslclient(1), sslconnect(1), sslcat(1), https@(1), ucspi-
tls(2), tcprules(1), tcprulescheck(1), tcpserver(1), tcp-environ(5)
REFERENCE
http://httpd.apache.org/docs/2.4/mod/mod_ssl.html
http://www.superscript.com/ucspi-ssl/prefork.html
sslhandle(1)
Man(1) output converted with
man2html