S6-TLSC(8)

📦 version 2.8.0.1, in nixpkgs unstable

💅 s6-tlsc — the client-side TLS glow-up for your boring cleartext app ✨

okay so real talk: s6-tlsc is a page from the System Manager's Manual, and it's about establishing a TLS or SSL client connection over a TCP connection you already have open, then exec'ing into an application. it's giving "security blanket for apps that never learned to speak TLS" 🎀

🌸 SYNOPSIS 🌸

s6-tlsc [-S | -s] [-J | -j] [-Y | -y] [-Z | -z] [-v verbosity]
        [-K kimeout] [-k servername] [-6 rfd] [-7 wfd] [--] prog...

✨ DESCRIPTION ✨

so like, s6-tlsc exists to make network comms secure even for applications that do not natively support TLS/SSL. bestie, it's a whole vibe — your app doesn't need to know anything about certificates, the wrapper handles it 💖

s6-tlsc expects to already have an open TCP connection it can talk to on its descriptors — by default 6 (for reading) and 7 (for writing).

it spawns an s6-tlsc-io(8) child process, and that child is the one that initiates the TLS connection, performs the handshake (expecting a TLS server on the other side of the network) and maintains the TLS tunnel. main character energy fr 🫶

then, when s6-tlsc-io(8) notifies it that the handshake has completed, s6-tlsc exec(3)s into prog.... no cap, that's it, that's the whole trick.

the goal of the s6-tlsc interface (and its server-side companion s6-tlsd(8)) is genuinely iconic: if you have a client run by the command line client... that speaks a cleartext protocol to a server run by the command line server..., and the server has the proper private key and certificate, and the client has the proper list of trust anchors — then you can literally just change the client command line to s6-tlsc client... and the server command line to s6-tlsd server... without changing the client or the server themselves, and the communication between them will be secure. periodt. 👑

🔥 OPTIONS 🔥

  • -v verbosity — be more or less verbose. default for verbosity is 1. 0 is quiet, 2 is verbose, more than 2 is debug output. ⚠️ heads up: this option currently has no effect. (yes really, it's just sitting there being cute 🙈)
  • -Z — do not clean the environment of the variables used by s6-tlsc-io(8) before exec(3)'ing prog....
  • -z — clean the environment of the variables used by s6-tlsc-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.
  • -s — transmit EOF by half-closing the TCP connection without using close_notify. this is the default.
  • -J — make s6-tlsc-io(8) exit with a nonzero code if the peer sends EOF without a close_notify first.
  • -j — treat EOF from the peer as a normal exit condition.
  • -Y — do not send a client certificate. this is the default.
  • -y — send a client certificate.
  • -k servername — use Server Name Indication, and send servername. the default is not to use SNI, which may be a security risk 😬 (not me leaving that flag off…)
  • -K kimeout — if the handshake takes more than kimeout milliseconds to complete, close the connection. the default is 0, which means infinite timeout (never kill the connection).
  • -6 rfd — expect an open file descriptor numbered rfd to read network (ciphertext) data from. make sure prog also reads its data from its own fd rfd. default is 6.
  • -7 fdw — expect an open file descriptor numbered fdw to write network (ciphertext) data to. make sure prog also writes its data to its own fd fdw. default is 7.

🦋 ENVIRONMENT 🦋

🌈 Read

s6-tlsc does not expect to have any particular environment variables, but it spawns an s6-tlsc-io(8) program that does. so it should pay attention to the following variables:

  • CADIR or CAFILE
  • (if the -y option has been given) CERTFILE and KEYFILE
  • TLS_UID and TLS_GID

💜 Written

by default, prog... is run with all these variables unset: CADIR, CAFILE, KEYFILE, CERTFILE, TLS_UID and TLS_GID. they're passed to the s6-tlsc-io(8) child but not to prog.... the -Z option prevents that behaviour.

however, prog... is run with the following additional environment variables, and they're lowkey the good part:

  • 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 servername, if the -k option has been given; otherwise it is removed from the environment.
  • 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. what is traditionally called the “name” of the certificate is the CN field in that data. iykyk 🎀
more similar environment variables containing information about the connection may be added in the future. so like, stay tuned bestie ⭐

💀 EXIT STATUS 💀

  • 100 — wrong usage. (you did too much 🙈)
  • 111 — system call failed.

if everything goes smoothly, s6-tlsc does not exit, but exec(3)s into prog... instead. slay 💅

👑 SEE ALSO 👑

s6-tls(7), s6-tlsc-io(8), s6-tlsclient(8), s6-tlsd(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-tlsc.html

🍓 AUTHORS 🍓

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

and that's the whole thing, bestie 🧚💖 this one's from the Debian fam, dated November 20, 2023 — go forth and wrap literally everything in TLS, you absolute icon 🌸🦋✨

📦 where this page comes from