S6-TLSC-IO(8)

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 the only client-side program in s6-networking that performs cryptography.

s6-networking does not include cryptographic software. All the crypto used in s6-tlsc-io is provided by the chosen SSL backend: BearSSL[1] or LibreSSL[2], depending on the options given when configuring s6-networking.

s6-tlsc-io expects to read cleartext data to stdin, and write cleartext data to stdout. It also expects descriptors fdr and fdw to be open ( typically connected to the network), to respectively read ciphertext from and write ciphertext to.

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.

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.

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, that's why it adopts a liberal approach to protocol versions.

  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 tranmission, 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.

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.

-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
s6-tls(7), s6-applyuidgid(8), s6-tlsc(8), s6-tlsclient(8), s6-tlsd(8), s6-tlsd-io(8), s6-tlsserver(8), s6-ucspitlsc(8), s6-ucspitlsd(8)

[1] https://bearssl.org/

[2] https://www.libressl.org/

[3] https://bearssl.org/apidoc/bearssl__ssl_8h.html#aa386dd0b03a0123760bf63df5a41c1e0

[4] https://bearssl.org/support.html#supported-versions

[5] https://man.openbsd.org/OpenBSD-current/man3/tls_config_set_protocols.3

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)