s6-networking
Software
skarnet.org

The s6-tlsd-io program

s6-tlsd-io is a program that establishes a TLS or SSL server connection over an existing TCP connection, then communicates with an existing local program over already established pipes. It is the only server-side program in s6-networking that performs cryptography.

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

Interface

     s6-tlsd-io [ -S | -s ] [ -J | -j ] [ -Y | -y ] [ -v verbosity ] [ -K kimeout ] [ -k snilevel ] [ -d notif ] [ -- ] fdr fdw

Exit codes

Protocol version and parameters

During the TLS/SSL handshake, s6-tlsd-io 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-io is conservative in its choice of protocols. It only supports TLS versions 1.2 and higher as supported by the backend, to avoid downgrade attacks.

Environment variables

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

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

Alternatively, if snilevel is nonzero, the private key for the server named x should be held in a file whose name is contained in the KEYFILE:x environment variable, and the corresponding certificate chain file should be named in the CERTFILE:x environment variable. If snilevel is 2 or more, the KEYFILE and CERTFILE variables will be entirely ignored.

You can wildcard the first level of a SNI domain: you can point to a valid certificate for foo.example.com for all values of foo via a variable called CERTFILE:*.example.com (and have the corresponding KEYFILE:*.example.com). Only the first level can be wildcarded, and this does not work for top-level domains (you cannot hold a certificate for *.com). Note: if you are using a shell to handle your environment variables, be careful to properly quote them so that it does not attempt to expand the asterisks.

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

If s6-tlsd-io 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-io then drops its root privileges to this uid/gid after reading its private key file. This ensures that the engine, including the handshake, is run with as little privilege as possible.

SSL close handling

If the local application initiates the end of the session by sending EOF to fdr, there are two ways for the TLS layer to handle it.

Nowadays (2020), most protocols are auto-terminated, so it is not dangerous anymore to use EOF tranmission, and that is the default for s6-tlsd-io. 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-io options