sslhandle(1)                General Commands Manual               sslhandle(1)



NAME
       sslhandle - preforking TLS server

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 specify‐
       ing  a program to run for each accepted connection.  The server subrou‐
       tine 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, ssl‐
       handle 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  encod‐
       ing  and  decoding.  Before running prog, sslhandle reads and sets cer‐
       tain environment variables.

       sslhandle exists, if the parent process receives a SIGTERM.

OPTIONS
       General Options:

       -q     Quiet. Do not print error messages.

       -Q     (Default.) Print error messages.

       -v     Verbose. Print error messages and status messages.

       -V     Print additional verbose SSL connection  informations  (protocol
              and cipher).


       Connection options:

       -1     After  preparing  to  receive  connections, print the local port
              number to standard output.

       -4     Use IPv4 sockets for connections.

       -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 connec‐
              tion 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 thunder‐
              ing 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 exam‐
              ple).   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 rout‐
              ing 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
              remote host is responding slowly. This is currently the default,
              but  it may not be in the future; if you want it, set it explic‐
              itly.

       -D     Never delay sending data; enable TCP_NODELAY.

       -t n   Give up on the $SSLREMOTEINFO connection attempt  after  n  sec‐
              onds. The default value is: 26.

       -T n   Give  up  on  the  SSL  connection  attempt after n seconds. The
              default value is: 26.

       -w n   Give up on a connection or program after waiting n  seconds  for
              read or write. The default value is: 3600.


       SSL and TLS connection options:

       -s     Store  client and server certificate information in the environ‐
              ment, a la mod_ssl.

       -S     (Default.) Do not store client and server  certificate  informa‐
              tion 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 envi‐
              ronment 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  environ‐
              ment 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 envi‐
              ronment 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  local‐
              name  is 0. To avoid loops, you must use this option for servers
              on TCP port 53.

       -r     Attempt to obtain $SSLREMOTEINFO from the remote host.

       -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.

       -e     Set protocol environment a  la  tcpserver  .   Set  $TCPLOCALIP,
              $TCPLOCALPORT,   $TCPLOCALHOST,   $TCPREMOTEIP,  $TCPREMOTEPORT,
              $TCPREMOTEHOST, and $TCPREMOTEINFO as well as for  IPv6  connec‐
              tions    additionally    $TCP6REMOTEIP,   $TCP6RMEOTEHOST,   and
              $TCP6REMOTEINFO from the current $SSL environment (see below).

       -E     (Default.) Do not set any tcpserver environment variables.

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 facili‐
       tated in case the file /etc/dnswritefile exists and  is  populated,  or
       alternatively the environment variable $DNSREWRITEFILE points to a dif‐
       fernent 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.   Cer‐
              tificates  in  $CADIR are processed during certificate verifica‐
              tion.

       $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.  Cer‐
              tificates 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
              security  level  for  the connection.  A typical choice would be
              'TLSv1+HIGH:!SSLv2:!MD5'.

       $DHFILE=path
              If set, overrides the compiled-in DH parameter file name.

       $KEYFILE=path
              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 keyfile when loading
              it's certificate.

       $VERIFYDEPTH=n
              If  set,  overrides the compiled-in verification depth. Default:
              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-con‐
              nection 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
              Issuer DN of client's certificate.

       SSL_CLIENT_I_DN_x509
              Component of client's Issuer DN.

       SSL_CLIENT_V_START
              Validity of client's certificate (start time).

       SSL_CLIENT_V_END
              Validity of client's certificate (end time).

       SSL_CLIENT_A_SIG
              Algorithm used for the signature of client's certificate.

       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,  SSLRE‐
       MOTEINFO, SSLREMOTEIP, SSLREMOTEPORT.


       TCP environment variables set:

       TCPLOCALHOST,  TCPLOCALIP,  TCPLOCALPORT, TCPREMOTEHOST, TCPREMOTEINFO,
       TCPREMOTEIP, TCPREMOTEPORT.


       TCP6 environment variables set:

       TCP6INTERFACE, TCP6LOCALHOST, TCP6LOCALIP,  TCP6LOCALPORT,  TCP6REMOTE‐
       HOST, TCP6REMOTEIP, TCP6REMOTEPORT.

LOGGING AND ERROR MESSAGES
       sslhandle prints information about individual connections in case -v or
       -V is specified as argument.  TLS error messages are provided if possi‐
       ble:

       unable to speak TLS for pid: ... DH lib
              TLS handshake failure.

       unable to accept TLS for pid: ...
              The remote socket was prematurely closed.

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.super‐
       script.com/ucspi-ssl/prefork.html



                                                                  sslhandle(1)