S6-TLSD(8)

NAME
s6-tlsd - perform the server side of a TLS or SSL connection over an existing TCP connection, then exec into an application

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

DESCRIPTION
s6-tlsd is meant to make network communications secure even for applications that do not natively support TLS/SSL.

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

s6-tlsd expects to have an open TCP connection it can talk to on its stdin (for reading) and stdout (for writing).

It spawns an s6-tlsd-io(8) child process that will be the server-side of a TLS connection, perform the handshake (expecting a TLS client on the other side of the network) and maintain the TLS tunnel.

When notified by s6-tlsd-io(8) that the handshake has completed, s6-tlsd exec(3) s into prog....

The goal of the s6-tlsd interface ( and its client-side companion s6-tlsc(8)) 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.

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.

-Z  Do not clean the environment of the variables used by s6-tlsd-io(8) before exec(3)' ing prog....

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

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

ENVIRONMENT

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

•   KEYFILE and CERTFILE. 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. They're passed to the s6-tlsd-io(8) child but not to prog...; the -Z option keeps them accessible in prog... as well.

However, prog... is run with the following additional environment variables:

SSL_PROTOCOL
    Contains the protocol version: TLSv1, TLSv1.1, TLSv1.2...

SSL_CIPHER
    Contains the name of the cipher used.

SSL_TLS_SNI_SERVERNAME
    Contains the required SNI server name, if any. It is removed from the environment if no SNI has been sent by the client.

SSL_PEER_CERT_HASH
    Contains the hash of the peer's End Entity certificate, prefixed by the name of the hash and a colon ( typically ‘SHA256:’).

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.

EXIT STATUS

100 Wrong usage.

111 System call failed.

If everything goes smoothly, s6-tlsd does not exit, but exec(3) s into prog... instead.

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

[1] https://bearssl.org/

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

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

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