S6-UCSPITLSC(8)

NAME
s6-ucspitlsc - client-side program that establishes communication channels according to the UCSPI-TLS protocol, then execs into an application

SYNOPSIS
s6-ucspitlsc [-S | -s] [-J | -j] [-Y | -y] [-Z | -z] [-v verbosity] [-K -kimeout] [-k servername] [-6 rfd] [-7 wfd] [--] 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.

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 client itself.

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

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-ucspitlsc, following the UCSPI-TLS[1] protocol. Then the s6-ucspitlsc child will exec into an s6-tlsc-io(8) process that will initiate the TLS connection, perform the handshake (expecting a TLS server 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-ucspitlsc 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-tlsc(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.

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

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

-6 fdr
    Expect an open file descriptor numbered fdr to read network (ciphertext) data from. Make sure prog also reads its data from its own fd fdr. Default is 6.

-7  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-ucspitlsc does not expect to have any particular environment variables, but it spawns a 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, 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.

EXIT STATUS

100 Wrong usage.

111 System call failed.

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

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

[1] https://web.archive.org/web/20150311223933/http://www.suspectclass.com/sgifford/ucspi-tls/ucspi-tls.txt

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

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