S6-TLS(7)

📦 version 2.8.0.1, in nixpkgs unstable

💅 S6-TLS(7) 💅

ok so this is the miscellaneous information manual page for s6-tls — the whole overview of the s6 TLS-related programs. welcome to the group chat, bestie, let's get you fluent ✨

🌸 NAME 🌸

<pink>s6-tls</pink> — an overview of the s6 TLS-related programs 🎀

🦋 DESCRIPTION 🦋

ok so the whole <purple>s6-tls*</purple> family is organized in a way that minimizes the amount of code, and in particular that keeps the crypto code as encapsulated as possible. like, crypto stays in its own little lane, no cap 💅

They're divided in two sets:

  • client programs — these have <cyan>client</cyan> or <cyan>c</cyan> in their name 🫶
  • server programs — these have <cyan>server</cyan> or <cyan>d</cyan> in their name 👑

and the sets are symmetrical: the exact same functionality is available whether you're interested in using a client or a server. it's giving mirrored slay ✨

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). it's giving "we're not codependent, we just vibe" 😌

🔥 The core TLS engine: s6-tlsc-io and s6-tlsd-io 🔥

<purple>s6-tlsc-io(8)</purple> and <purple>s6-tlsd-io(8)</purple> are the only programs that actually perform TLS operations — the only ones that are linked against the BearSSL or LibreSSL libraries. everyone else is just plumbing, and honestly? iconic division of labor 👑

They:

  • read TLS-related information from their environment (where to find my trust anchor list? where to find my server certificate and private key? 🕵️‍♀️)
  • 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 <purple>s6-tls*</purple> set perform various operations such as Unix file descriptor plumbing in order to provide a specific interface, but they always end up spawning an <purple>s6-tlsc-io(8)</purple> or <purple>s6-tlsd-io(8)</purple> child that will handle the actual TLS management for them. main character energy, the parent just does the vibes 🧚

🎀 Regular TLSification of a service: s6-tlsc and s6-tlsd 🎀

The <purple>s6-tlsc(8)</purple> and <purple>s6-tlsd(8)</purple> programs are “immediate encryption”-type programs. they assume that the rest of their command line is a UCSPI client or server application — i.e. it 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 whole goal is to provide this application with transparent encryption.

So here's the choreography bestie:

  1. They first spawn an <purple>s6-tlsc-io(8)</purple> or <purple>s6-tlsd-io(8)</purple> child to initialize the TLS connection 🔐
  2. When the TLS handshake has completed, they exec into the rest of their command line, interposing the <purple>s6-tls[cd]-io</purple> program in between this application and the network 🪄
  3. 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 <purple>s6-ucspitlsc(8)</purple> and <purple>s6-ucspitlsd(8)</purple> 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. and ok, 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 🙈

How the drama unfolds:

  • 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 <purple>s6-tlsc-io(8)</purple> or <purple>s6-tlsd-io(8)</purple>, 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 🔥

it's giving "encrypt on your own schedule, queen" 💅

👑 High-level client connections and super-servers: s6-tlsclient and s6-tlsserver 👑

The <purple>s6-tlsclient(8)</purple> and <purple>s6-tlsserver(8)</purple> 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. like, you don't have to type the whole essay, they'll do it for you 🫶

⭐ SEE ALSO ⭐

ok so go read these next, fr fr:

and the link, bestie (iykyk, it's the ucspi-tls protocol spec):

[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) 🎀
ok that's the whole page bestie, you're officially TLS-literate, periodt 💅✨

sign-off time: this one's from the Debian fam, dated September 29, 2021 — mwah, go encrypt something cute 🍓🧚‍♀️

📦 where this page comes from