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.
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.
s6-tlsserver reacts to the same signals as s6-tcpserver4d or s6-tcpserver6d, one of which is the long-lived process hanging around.
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.
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.
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.
KEYFILE=/etc/ssl/private/mykey.der CERTFILE=/etc/ssl/public/mycert.pem \
TLS_UID=65534 TLS_UID=65536 \
s6-tlsserver -U -- 126.96.36.199 443 httpd
This will start a server listening to 188.8.131.52 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.