s6-networking
Software
skarnet.org

The s6-tlsserver program

s6-tlsserver is an UCSPI server tool for TLS/SSL connections over INET domain sockets. It acts as a TCP super-server that listens to connections, accepts them, and for each connection, establishes a TLS transport over it, then executes into a program.

Interface

     s6-tlsserver [ options ] [ -- ] ip port prog...

prog is expected to read from its peer on its standard input and write to its peer on its standard output. Since there will be an s6-tlsd-io program between prog and the network to perform the SSL encryption/decryption, those descriptors will not be a network socket - they will be pipes.

Signals

s6-tlsserver reacts to the same signals as s6-tcpserver4d or s6-tcpserver6d, one of which is the long-lived process hanging around.

Environment variables

Read

The following variables should be set before invoking s6-tlsserver, because they will be used by every s6-tlsd invocation:

Setting both KEYFILE and CERTFILE is mandatory.

Written

prog... is run with the following variables added to, or removed from, its environment by s6-tcpserver4d or s6-tcpserver6d, and possibly by s6-tcpserver-access:

Depending on TCP access rules (if the -i or -x option has been given), it is possible that prog's environment undergoes more modifications. Also, since s6-tlsd is always run after s6-tcpserver-access, it is possible to set different TLS/SSL parameters (typically a different KEYFILE and CERTFILE) depending on the client connection, by writing the correct set of TCP access rules.

Unless the -Z option is given to s6-tlsserver, the CADIR, CAFILE, KEYFILE, CERTFILE, TLS_UID and TLS_GID variables will not appear in prog's environment.

Options

s6-tlsserver accepts a myriad of options, most of which are passed as is to the correct executable. Not giving any options will generally work, but unless you're running a very public server (such as a Web server) or base your access control on client certificates, you probably still want TCP access rules.

Options handled directly by s6-tlsserver

Options passed as is to s6-tcpserver

Options passed as is to s6-tcpserver-access

Options passed as is to s6-tlsd

Options passed to s6-applyuidgid

Example

As root:

env KEYFILE=/etc/ssl/private/mykey.der CERTFILE=/etc/ssl/public/mycert.pem \
TLS_UID=65534 TLS_UID=65534 \
s6-envuidgid www \
s6-tlsserver -U -- 1.2.3.4 443 httpd

This will start a server listening to 1.2.3.4 on TCP port 443, and for every connection, spawn the httpd program reading queries on stdin and replying on stdout, as user www, with a TLS layer protecting the connection, the TLS engine running as user nobody (65534:65534). The server is authenticated by the certificate in /etc/ssl/public/mycert.pem that it sends to the client, and the private key in /etc/ssl/private/mykey.der that it keeps to itself.