s6-networking
Software
skarnet.org

The s6-tlsd program

s6-tlsd is a program that performs the server side of a TLS or SSL connection over an existing TCP connection, then execs into an application. It is meant to make network communications secure even for applications that do not natively support TLS/SSL.

s6-networking does not include cryptographic software. All the crypto used in s6-tlsd is provided by the chosen SSL backend: BearSSL or LibreSSL, depending on the options given when configuring s6-networking.

Interface

     s6-tlsd [ -S | -s ] [ -Y | -y ] [ -Z | -z ] [ -v verbosity ] [ -K kimeout ] [ -- ] prog...

• s6-tlsd expects to have an open TCP connection it can talk to on its stdin (for reading) and stdout (for writing).
• It spawns a s6-tlsd-io child process that will be the server-side of a TLS connection, perform the handshake (expecting a TLS client on the other side of the network) and maintain the TLS tunnel.
• When notified by s6-tlsd-io that the handshake has completed, s6-tlsd execs into prog....

Exit codes

• 100: wrong usage.
• 111: system call failed.

If everything goes smoothly, s6-tlsd does not exit, but execs into prog... instead.

Environment variables

Read

s6-tlsd does not expect to have any particular environment variables, but it spawns a s6-tlsd-io program that does. So it should pay attention to the following variables:

• KEYFILE and CERTFILE
• (if the -y or -Y option has been given) CADIR or CAFILE
• TLS_UID and TLS_GID

Written

By default, prog... is run with all these variables unset: CADIR, CAFILE, KEYFILE, CERTFILE, TLS_UID and TLS_GID. They're passed to the s6-tlsd-io child but not to prog.... The -Z option prevents that behaviour.

However, prog... is run with the following additional environment variables:

• SSL_PROTOCOL contains the protocol version: TLSv1, TLSv1.1, TLSv1.2...
• SSL_CIPHER contains the name of the cipher used.
• SSL_TLS_SNI_SERVERNAME contains the required SNI server name, if any. It is removed from the environment if no SNI has been sent by the client.
• More similar environment variables containing information about the connection may be added in the future.

Options

• -v verbosity : Be more or less verbose. Default for verbosity is 1. 0 is quiet, 2 is verbose, more than 2 is debug output. This option currently has no effect.
• -Z : do not clean the environment of the variables used by s6-tlsd-io before execing prog....
• -z : clean the environment of the variables used by s6-tlsd-io before execing prog.... This is the default.
• -S : send a close_notify alert and break the connection when prog sends EOF.
• -s : transmit EOF by half-closing the TCP connection without using close_notify. This is the default.
• -Y : Require an optional client certificate.
• -y : Require a mandatory client certificate. The default, with neither the -Y nor the -y option, is not to require a client certificate at all.
• -K kimeout : if the peer fails to send data for kimeout milliseconds during the handshake, close the connection. The default is 0, which means infinite timeout (never kill the connection). This option is ignored by the libtls backend, which does not have a way to interrupt the handshake after a timeout.

Notes

• The goal of the s6-tlsd interface (and its client-side companion s6-tlsc) is to make it so that if you have a client, run by the command line client... that speaks a cleartext protocol to a server run by the command line server..., then if the server has the proper private key and certificate, and the client has the proper list of trust anchors, you can just change the client command line to s6-tlsc client... and the server command line to s6-tlsd server... without changing the client or the server themselves, and the communication between them will be secure.