S6-UCSPITLSD(8)

📦 version 2.8.0.1, in nixpkgs unstable

💖 s6-ucspitlsd(8) 💖

okay bestie, this is the s6-ucspitlsd page from the System Manager's Manual (section 8), and it's literally the server-side bestie that sets up UCSPI-TLS channels then execs into your app. periodt.

🌸 NAME 🌸

s6-ucspitlsd — server-side program that establishes communication channels according to the UCSPI-TLS protocol, then execs into an application. slay.

✨ SYNOPSIS ✨

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

🦋 DESCRIPTION 🦋

If the application sends a command, a TLS tunnel will be started and the application will be able to use it instead of communicating with the network via cleartext. no cap, that's the whole vibe.

The point of this protocol, and this program, is to make it easy to implement commands like SMTP's STARTTLS without embedding a TLS stack in the server itself. iconic, honestly.

s6-ucspitlsd expects to have an open TCP connection it can talk to on its stdin and stdout.

It forks and establishes communication channels between the parent and the child. The parent executes into prog...; the child remains and waits for a command.

At any time, prog... can send a command to its control socket provided by s6-ucspitlsd, following the UCSPI-TLS[1] protocol. Then the s6-ucspitlsd child will exec into an s6-tlsd-io(8) process that will initialize the TLS connection, perform the handshake (expecting a TLS client on the other side of the network) and maintain a TLS tunnel. prog can use that TLS tunnel instead of talking directly to the network.

It only makes sense to run s6-ucspitlsd if its application program prog knows and understands the UCSPI-TLS[1] protocol for opportunistic TLS. If it does not, you will not be able to secure your connection, and what you need is a regular immediate TLS program instead, which means s6-tlsd(8).

💅 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. choose your fighter.
  • -Z — do not clean the environment of the variables used by s6-tlsc-io(8) before exec(3)'ing prog.... yep, that's s6-tlsc-io(8), bestie, keep it exact.
  • -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.
  • -s — transmit EOF by half-closing the TCP connection without using close_notify. this is the default.
  • -J — make s6-tlsd-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 — request an optional client certificate.
  • -y — request a mandatory client certificate. The default, with neither the -Y nor the -y option, is not to request a client certificate at all.
  • -K kimeout — close the connection if the handshake takes more than kimeout milliseconds to complete. The default is 0, which means infinite timeout: let the handshake complete at its own pace, no matter how slow. take your time, king.
  • -k snilevel — support alternative certificate chains for SNI. 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 that 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 is not given, which is the default, KEYFILE and CERTFILE are the only private key / certificate chain pair that are loaded, no other environment variable is read for keypairs. that's the whole SNI multiverse situation.

🌈 ENVIRONMENT 🌈

👀 Read

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

  • CERTFILE and KEYFILE. Also (or alternatively), if the -k option is given: a 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. The variables are passed to the s6-tlsd-io(8) child but not to prog.... The -Z option prevents that behaviour and keeps them accessible in the child.

However, prog... is run with the following additional environment variables, following the UCSPI-TLS protocol:

  • SSLCTLFD — contains the file descriptor number of the control socket.
  • SSLREADFD — contains the file descriptor number of the pipe used to read data from the TLS tunnel after it has been activated.
  • SSLWRITEFD — contains the file descriptor number of the pipe used to write data to the TLS tunnel after it has been activated.

Since prog is exec(3)'ed before the TLS handshake takes place, it cannot get information about the TLS connection via environment variables. However, if it starts the TLS connection via a Y command (as opposed to a y command), it will receive this information as a string sent over the control socket. iykyk.

💀 EXIT STATUS 💀

  • 100 — wrong usage.
  • 111 — system call failed.

Normally the parent s6-ucspitlsd process exec(3)s into prog... and the child process execs into s6-tlsd-io(8). If the parent dies or closes its control socket before sending a command to start TLS, the child exits 0.

🫶 SEE ALSO 🫶

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

👑 AUTHORS 👑

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

okay that's the whole s6-ucspitlsd(8) situation, bestie — Debian, November 20, 2023 — byeee 💅💖

📦 where this page comes from