The s6-tlsc program
s6-tlsc is a program that establishes a TLS or SSL
client connection over an existing TCP connection, then execs
into an application. It is meant to make network communications
secure even for applications that do not natively support
s6-tlsc [ -S | -s ] [ -J | -j ] [ -Y | -y ] [ -Z | -z ] [ -v verbosity ] [ -K kimeout ] [ -k servername ] [ -6 rfd ] [ -7 wfd ] [ -- ] prog...
- s6-tlsc expects to have an open TCP connection it
can talk to on its (by default) descriptors 6 (for reading)
and 7 (for writing).
- It spawns an s6-tlsc-io
child process that will initiate the TLS connection, perform the
handshake (expecting a TLS server on the other side of the
network) and maintain the TLS tunnel.
- When notified by s6-tlsc-io
that the handshake has completed, s6-tlsc execs into
- 100: wrong usage.
- 111: system call failed.
If everything goes smoothly, s6-tlsc does not exit, but execs
into prog... instead.
s6-tlsc does not expect to have any particular
environment variables, but it spawns an
s6-tlsc-io 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
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 child but
not to prog....
The -Z option prevents that behaviour.
However, prog... is run with the following additional
- SSL_PROTOCOL contains the protocol version:
TLSv1, TLSv1.1, TLSv1.2...
- SSL_CIPHER contains the name of the cipher
- 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
- 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.
- More similar environment variables containing information
about the connection may be added in the future.
- -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
- -Z : do not clean the environment of
the variables used by s6-tlsc-io
before execing prog....
- -z : clean the environment of
the variables used by s6-tlsc-io
before execing 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
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 : 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 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 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.
- The goal of the s6-tlsc interface (and its
server-side companion s6-tlsd) is to
make it so that 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..., then if the server
has the proper private key and certificate, and the client has
the proper list of trust anchors, you can 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.