s6-networking
Software
skarnet.org

The s6-tlsc-io program

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

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

Interface

     s6-tlsc-io [ -S | -s ] [ -Y | -y ] [ -v verbosity ] [ -K kimeout ] [ -k servername ] [ -d notif ] [ -- ] fdr fdw

Exit codes

Protocol version and parameters

During the TLS handshake, s6-tlsc-io tries every version of the protocol that is supported by the backend, with all supported 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 client, it is better for s6-tlsc-io to adapt to as many servers as possible, that's why it adopts a liberal approach to protocol versions.

Environment variables

s6-tlsc-io expects to have one of the CADIR or CAFILE environment variables set. It will refuse to run if both are unset. If both are set, CADIR has priority. The value of that variable is:

If you are using client certificates, s6-tlsc-io also reads two more environment variables: KEYFILE contains the path to a file containing the private key, DER- or PEM-encoded; and CERTFILE contains the path to a file containing the client certificate, DER- or PEM-encoded.

If s6-tlsc-io is run as root, it can also read two other environment variables, TLS_UID and TLS_GID, which contain a numeric uid and a numeric gid; s6-tlsc-io 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 chainloading way of doing it.

Server name determination for SNI

The -k servername option is important to s6-tlsc-io: it tells it to send servername as the name to require a certificate for. Not setting this option allows s6-tlsc-io to proceed without SNI, which may be a security risk.

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-tlsc-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-tlsc-io options