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

Exit codes

If the TLS/SSL connection closes cleanly, s6-tlsd waits for prog to exit, then exits with an approximation of prog's exit code.

Protocol version and parameters

During the TLS/SSL handshake, s6-tlsd tries the versions of the protocol that is supported by default by the backend, with the default algorithms and cipher suites; the backend normally ensures that the most secure combination is tried first, with slow degradation until the client and the server agree.

As a server, s6-tlsd can be conservative in its choice of protocols. It is currently not very conservative when using the BearSSL backend; it could become more so in the future, by defining a custom server profile that supports only TLS-1.2 but with several algorithms and cipher suites.

Environment variables

Read

s6-tlsd expects to have the following environment variables set:

If one of those variables is unset, s6-tlsd will refuse to run.

If you are using client certificats, s6-tlsd also requires either one of the following variables to be set:

If s6-tlsd is run as root, it can also read two more environment variables, TLS_UID and TLS_GID, which contain a numeric uid and a numeric gid; s6-tlsd then drops its root privileges to this uid/gid after spawning prog.... This ensures that the TLS/engine and the application run with different privileges.

Note that prog... should drop its own root privileges by its own means: the s6-applyuidgid program is a way of doing it. If the s6-tlsd invocation actually comes from a s6-tlsserver command line, and privilege-dropping options (-G, -g, -u or -U) have been given to s6-tlsserver, then s6-applyuidgid directly follows s6-tlsd on the command line, in order to also drop the child's privileges before executing the application. The point of that setup is:

Written

Unless the -Z option has been given to s6-tlsd, prog... is run with all the TLS/SSL variables unset: CADIR, CAFILE, KEYFILE, CERTFILE, TLS_UID and TLS_GID. The goal is for s6-tlsd to be, by default, as invisible as possible.

SSL close handling

If prog initiates the end of the session by sending EOF, there are two ways for the TLS/SSL layer to handle it.

Nowadays (2017), most protocols are auto-terminated, so it is not dangerous anymore to use EOF tranmission, and that is the default for s6-tlsd. Nevertheless, by using the -S option, you can force it to use the close_notify method if your application requires it to be secure.

s6-tlsd options

Notes