S6-TLS(7)

NAME
s6-tls - overview of the s6 TLS-related programs

DESCRIPTION
The ‘s6-tls*’ programs are organized in a way that minimizes the amount of code, and in particular that keeps the crypto code as encapsulated as possible.

They are divided in two sets: client programs, which have ‘client’ or ‘c’ in their name, and server programs, which have ‘server’ or ‘d’ in their name. The sets are symmetrical: the same functionality is available whether you're interested in using a client or a server.

Of course, they do not have to be used together. You can run a TLS-enabled super-server via s6-tlsserver(8) and it will work with any client speaking the correct TLS-enabled protocol, not only s6-tlsclient(8).

  The core TLS engine: s6-tlsc-io and s6-tlsd-io
s6-tlsc-io(8) and s6-tlsd-io(8) are the only programs that actually perform TLS operations; the only ones that are linked against the BearSSL or LibreSSL libraries.

They:

•   read TLS-related information (where to find my trust anchor list? where to find my server certificate and private key?) from their environment.

•   assume that their stdin/stdout is talking to the network; they also take two other fds on the command line that they assume are open and talking to the local application - one for reading, one for writing.

•   establish a TLS tunnel over the network.

•   maintain full-duplex communication: what they read from the local application is sent to stdout as ciphertext; what they read from stdin is sent to the local application as cleartext.

•   exit when they cannot transmit any more data.

Other programs in the ‘s6-tls*’ set perform various operations such as Unix file descriptor plumbing in order to provide a specific interface, but they always end up spawning an s6-tlsc-io(8) or s6-tlsd-io(8) child that will handle the actual TLS management for them.

  Regular TLSification of a service: s6-tlsc and s6-tlsd
The s6-tlsc(8) and s6-tlsd(8) programs are “immediate encryption” -type programs. They assume that the rest of their command line is a UCSPI client or server application, i.e. reads from the network on fd (6 for clients, 0 for servers) and writes to the network on fd (7 for clients, 1 for servers); their goal is to provide this application with transparent encryption.

They first spawn an s6-tlsc-io(8) or s6-tlsd-io(8) child to initialize the TLS connection.

When the TLS handshake has completed, they exec into the rest of their command line, interposing the ‘s6-tls[cd]-io’ program in between this application and the network.

The application still communicates via cleartext, but the data is transparently encrypted before it goes to the network.

The application is only started after the handshake succeeds; the TLS tunnel stays up for the whole lifetime of the application, or until the application closes the fds it uses to communicate with (what it thinks is) the network.

  Opportunistic TLS: s6-ucspitlsc and s6-ucspitlsd
The s6-ucspitlsc(8) and s6-ucspitlsd(8) programs are “delayed encryption” -type programs. They assume that the rest of their command line is an application that follows the UCSPI-TLS[1] protocol. This is a bit of a misnomer: the aim of this protocol is just to provide an application with a means to ask for TLS encryption at any time.

They prepare the necessary communication channels, then fork. The parent execs into the rest of its command line, with the appropriate ucspi-tls environment variables set. The child stays and waits for a command.

When the application sends a command to start TLS, the child execs into s6-tlsc-io(8) or s6-tlsd-io(8), which initializes a TLS connection and performs a handshake.

The application then communicates via the fds that have been provided to it via the ucspi-tls protocol. Those fds go through the TLS engine.

  High-level client connections and super-servers: s6-tlsclient and s6-tlsserver
The s6-tlsclient(8) and s6-tlsserver(8) programs are high-level wrappers around TCP client and server functionality, followed by the establishment of a TLS tunnel, followed by the execution of an application.

They're meant to provide simpler interfaces over long, complex command lines.

s6-tlsclient(8) rewrites itself into a command line involving s6-tcpclient(8) and s6-tlsc(8).

s6-tlsserver(8) rewrites itself into a command line involving (depending on the given options) s6-tcpserver(8), s6-tcpserver-access(8), s6-tlsd(8), and s6-applyuidgid(8).

SEE ALSO
s6-applyuidgid(8), s6-tcpclient(8), s6-tcpserver(8), s6-tcpserver-access(8), s6-tlsc(8), s6-tlsc-io(8), s6-tlsclient(8), s6-tlsd(8), s6-tlsd-io(8), s6-tlsserver(8), s6-ucspitlsc(8), s6-ucspitlsd(8)

[1] https://web.archive.org/web/20150311223933/http://www.suspectclass.com/sgifford/ucspi-tls/ucspi-tls.txt

This man page is ported from the authoritative documentation at: https://skarnet.org/software/s6-networking/tls-overview.html

AUTHORS
Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)