S6-TLSC-IO(8)

📦 version 2.8.0.1, in nixpkgs unstable

🦋 s6-tlsc-io — S6-TLSC-IO(8) 🦋

okay bestie, welcome to the S6-TLSC-IO(8) page from the System Manager's Manual. This is the TLS-client-meets-pipes era of the group chat, and it’s lowkey iconic once you know what every flag is doing. 💅

💖 NAME 💖

s6-tlsc-io — establish a TLS or SSL client connection over an existing TCP connection, then communicate with an existing local program over already established pipes.

🌸 SYNOPSIS 🌸

s6-tlsc-io [-S | -s] [-J | -j] [-Y | -y] [-v verbosity] [-K kimeout]
           [-k servername] [-d notif] [--] fdr fdw

✨ DESCRIPTION ✨

s6-tlsc-io is literally the only client-side program in s6-networking that performs cryptography. Main character energy, no cap. 👑

And no, s6-networking does not include cryptographic software by itself. All the crypto used in s6-tlsc-io comes from the chosen SSL backend: BearSSL[1] or LibreSSL[2], depending on the options given when configuring s6-networking. Pick your fighter at build time, bestie. 🧚

s6-tlsc-io expects to read cleartext data from stdin, and write cleartext data to stdout. It also expects descriptors fdr and fdw to already be open — typically connected to the network — so it can respectively read ciphertext from fdr and write ciphertext to fdw. Clear text in, clear text out; ciphertext over there. Slay. 💫

It initiates a TLS handshake over the network connection, expecting a TLS server on the other side.

Then it acts as a full duplex tunnel: encrypting and transmitting data from stdin to fdw, and decrypting and transmitting data from fdr to stdout. Full-duplex realness. 🦋

When it cannot transmit any more data from/to the local application because connections have closed, s6-tlsc-io exits.

🧸 Protocol version and parameters 🧸

During the TLS handshake, s6-tlsc-io tries every version of the protocol that is supported by the backend, with all supported algorithms and cipher suites. The backend normally ensures that the most secure combination is tried first, with slow degradation until the client and the server agree. Very diplomatic of them. 🕊️

For BearSSL, this means use of the br_ssl_client_init_full() function[3]. The supported protocol versions are described in [4].

For LibreSSL, this means use of the tls_config_set_protocols(TLS_PROTOCOLS_ALL) call[5].

As a client, it is better for s6-tlsc-io to adapt to as many servers as possible, which is why it adopts a liberal approach to protocol versions. Flexible queen. 💃

🎀 Server name determination for SNI 🎀

The -k servername option is important to s6-tlsc-io: it tells it to send servername as the name to require a certificate for. Not setting this option allows s6-tlsc-io to proceed without SNI, which may be a security risk. 🙈

🌈 SSL close handling 🌈

If the local application initiates the end of the session by sending EOF to fdr, there are two ways for the TLS layer to handle it.

  1. It can send a close_notify alert, and wait for an acknowledgement from the peer, at which point the connection is closed. The advantage of this setup is that it is secure even when the application protocol is not auto-terminated, i.e. when it does not know when its data stops. Old protocols such as HTTP-0.9 are in this case. The drawback of this setup is that it breaks full-duplex: once a peer has sent the close_notify, it must discard all the incoming records that are not a close_notify from the other peer. So if a client sends EOF while it is still receiving data from the server, the connection closes immediately and the data can be truncated. 😭
  2. It can simply transmit the EOF, shutting down half the TCP connection, and wait for the EOF back. The advantage of this setup is that it maintains full-duplex: a client can send EOF after its initial request, and still receive a complete answer from the server. The drawback is that it is insecure when the application protocol is not auto-terminated. 💀

Nowadays (2020), most protocols are auto-terminated, so it is not dangerous anymore to use EOF transmission, and that is the default for s6-tlsc-io. Nevertheless, by using the -S option, you can force it to use the close_notify method if your application requires it to 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. This option currently has no effect. (Iconic placeholder energy. 🎀)
  • -S — Send a close_notify alert and break the connection when receiving a local EOF.
  • -s — Transmit EOF by half-closing the TCP connection without using close_notify. This is the default.
  • -J — Treat EOF from the peer without a prior close_notify as an error: print a fatal error message and exit 98.
  • -j — Treat EOF from the peer without a prior close_notify as a normal exit condition. This is the default.
  • -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.
  • -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).
  • -d notif — Handshake notification. notif must be a file descriptor open for writing. When the TLS handshake has completed, some data (terminated by two null characters) will be sent to file descriptor notif. The data contains information about the TLS parameters of the connection; its exact contents are left unspecified, but there’s at least an SSL_PROTOCOL=protocol string and an SSL_CIPHER=cipher string, both null-terminated. Sending this data serves a dual purpose: telling the notif reader that the handshake has completed, and providing it with some basic information about the connection. If this option is not given, no such notification is performed.

🍓 ENVIRONMENT 🍓

s6-tlsc-io expects to have one of the CADIR or CAFILE environment variables set. It will refuse to run if both are unset. If both are set, CADIR has priority. 👑

The value of that variable is:

  • for CADIR: a directory where trust anchors (i.e. root or intermediate CA certificates) can be found, one per file, DER- or PEM-encoded.
  • for CAFILE: a file containing the whole set of trust anchors, PEM-encoded.

If you are using client certificates, s6-tlsc-io also reads two more environment variables: KEYFILE contains the path to a file containing the private key, DER- or PEM-encoded; and CERTFILE contains the path to a file containing the client certificate, DER- or PEM-encoded.

If s6-tlsc-io is run as root, it can also read two other environment variables, TLS_UID and TLS_GID, which contain a numeric uid and a numeric gid; s6-tlsc-io then drops its root privileges to this uid/gid after spawning prog.... This ensures that the TLS/engine and the application run with different privileges. Note that prog... should drop its own root privileges by its own means: the s6-applyuidgid(8) program is a chainloading way of doing it.

🔥 EXIT STATUS 🔥

  • 0 — The connection terminated normally.
  • 96 — Error while configuring the TLS context — for instance, invalid trust anchor set.
  • 97 — Error while setting up the TLS client engine.
  • 98 — TLS error while running the engine.
  • 100 — Wrong usage.
  • 111 — System call failed.

🦋 SEE ALSO 🦋

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

👑 AUTHORS 👑

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

mwah 💋 this baby is from Debian, dated November 20, 2023, and it’s the S6-TLSC-IO(8) page — stay encrypted and hydrated, bestie 🫶✨

📦 where this page comes from