S6-TLSD(8)

📦 version 2.8.0.1, in nixpkgs unstable

💅 s6-tlsd(8) — ok bestie, let's talk TLS

So like, the manual name is s6-tlsd and it lives in the System Manager's Manual section, and honestly? It's giving "quiet little bodyguard for your cleartext apps." Let's get into it. 🫶

✨ NAME ✨

s6-tlsd — do the server side of a TLS or SSL connection over a TCP connection you already have, then exec into your app. That's it, that's the whole vibe. 🎀

🌸 SYNOPSIS 🌸

s6-tlsd [-S | -s] [-J | -j] [-Y | -y] [-Z | -z] [-v verbosity]
        [-K kimeout] [-k snilevel] [--] prog...

🦋 DESCRIPTION 🦋

So s6-tlsd exists to make network comms secure even for apps that, like... don't natively support TLS/SSL. No cap. It just wraps them up all cozy. 💜

Important thing first: s6-networking does not include cryptographic software. All the crypto happening in s6-tlsd is provided by whichever SSL backend you picked — that's BearSSL or LibreSSL, depending on the options you gave when configuring s6-networking. iykyk.

s6-tlsd expects to already have an open TCP connection it can talk to on its stdin (for reading) and its stdout (for writing). Like, the connection's already there, she's just here to secure it.

It spawns an s6-tlsd-io(8) child process — that's the actual server-side of the TLS connection, the one doing the handshake (expecting a TLS client on the other end of the network) and keeping the TLS tunnel alive and maintained. 🔥

When s6-tlsd-io(8) tells it "bestie, the handshake is done," s6-tlsd exec(3)s into prog.... And then it's just... your program. Living its life. Through a tunnel. ✨

The whole goal of the s6-tlsd interface — and its client-side partner in crime s6-tlsc(8) — is this: if you've got a client run by the command line client... that speaks a cleartext protocol to a server run by the command line server..., then as long as the server has the proper private key and certificate, and the client has the proper list of trust anchors, you can just change the client command line to s6-tlsc client... and the server command line to s6-tlsd server... — without touching the client or the server themselves — and boom 💥, the communication between them is secure.

Not me being obsessed with a drop-in wrapper. But like. It is iconic.

💅 OPTIONS 💅

  • -v verbosity — Be more or less verbose. Default verbosity is 1. 0 is quiet, 2 is verbose, more than 2 is debug output. And yeah — this option currently has no effect. 😭 Cute though.
  • -Z — Do not clean the environment of the variables used by s6-tlsd-io(8) before exec(3)'ing prog.... Keep the snackies around.
  • -z — Clean the environment of the variables used by s6-tlsd-io(8) before exec(3)'ing prog.... This is the default. 🧼
  • -S — Send a close_notify alert and break the connection when prog sends EOF. Polite goodbye energy.
  • -s — Transmit EOF by half-closing the TCP connection without using close_notify. This is the default. Lowkey rude but valid.
  • -J — Make s6-tlsd-io(8) exit with a nonzero code if the peer sends EOF without a close_notify first. Like, no goodbye? Rude. Flagged. 🚩
  • -j — Treat EOF from the peer as a normal exit condition. Chill vibes, no drama. 💀
  • -Y — Request an optional client certificate.
  • -y — Request a mandatory client certificate. And heads up: the default, when you give neither -Y nor -y, is to not request a client certificate at all. 🙈
  • -K kimeout — If the handshake takes more than kimeout milliseconds to complete, close the connection. The default is 0, which means infinite timeout — as in, never kill the connection. She'll wait forever. 🕰️
  • -k snilevel — Support alternative certificate chains for SNI. Okay this one's a mouthful, so listen up:
    • If snilevel is nonzero, private key file names are read from every environment variable of the form KEYFILE:x, where x is a server name the client may require, and a corresponding certificate chain for the name x should exist in the file named after the contents of the CERTFILE:x environment variable.
    • If snilevel is 2 or more, only those files are read, and the generic KEYFILE and CERTFILE variables are ignored.
    • If snilevel is 0, or if the option isn't given at all (which is the default), KEYFILE and CERTFILE are the only private key / certificate chain pair that gets loaded — no other environment variable is read for keypairs. periodt.

🌈 ENVIRONMENT 🌈

🍓 Read

s6-tlsd doesn't expect to have any particular environment variables itself, but it spawns an s6-tlsd-io(8) program that absolutely does. So it should pay attention to these bad boys:

  • KEYFILE and CERTFILE. Also (or alternatively), if the -k option is given: a whole series of KEYFILE:x and CERTFILE:x variables, for every x in the set of server names.
  • (If the -y or -Y option has been given) CADIR or CAFILE.
  • TLS_UID and TLS_GID.

🧚 Written

By default, prog... is run with all these variables unset: CADIR, CAFILE, KEYFILE, CERTFILE, KEYFILE:x and CERTFILE:x for every x, TLS_UID and TLS_GID. They're passed to the s6-tlsd-io(8) child but not to prog.... The -Z option keeps them accessible in prog... too, if that's your thing.

But wait, there's more — prog... is run with these additional environment variables:

  • SSL_PROTOCOL — Contains the protocol version: TLSv1, TLSv1.1, TLSv1.2... 💫
  • SSL_CIPHER — Contains the name of the cipher used.
  • SSL_TLS_SNI_SERVERNAME — Contains the required SNI server name, if any. It gets removed from the environment if no SNI has been sent by the client. ✂️
  • SSL_PEER_CERT_HASH — Contains the hash of the peer's End Entity certificate, prefixed by the name of the hash and a colon (typically SHA256:).
  • SSL_PEER_CERT_SUBJECT — Contains the decoded subjectDN of the peer's End Entity certificate, i.e. identifying information. The thing traditionally called the "name" of the certificate is the CN field in that data. 👑
More similar environment variables containing information about the connection may be added in the future. So like, stay tuned. 👀

💀 EXIT STATUS 💀

  • 100 — Wrong usage. (You held it wrong. 🙈)
  • 111 — System call failed.

And if everything goes smoothly? s6-tlsd doesn't exit at all — it exec(3)s into prog... instead. Main character behavior, honestly. 👑

⭐ SEE ALSO ⭐

s6-tls(7), s6-tlsc(8), s6-tlsc-io(8), s6-tlsclient(8), s6-tlsd-io(8), s6-tlsserver(8), s6-ucspitlsc(8), s6-ucspitlsd(8)

This man page is ported from the authoritative documentation at: https://skarnet.org/software/s6-networking/s6-tlsd.html — go read the source bestie, it's giving references. 🎀

👑 AUTHORS 👑

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

<div align="center">🌸</div>

okay that's the whole page!! written by Laurent Bercot with the man page port by Alexis <flexibeast@gmail.com>, shipped under the Debian banner, dated November 20, 2023 — and that's the tea, no cap. 💖✨🎀

📦 where this page comes from