s6-networking: the s6-tlsc program
Keywords: s6-networking s6-tlsc tlsc tls ssl ucspi tcp inet network tcp/ip client

s6-networking
Software
skarnet.org

# 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 TLS/SSL.

## Interface

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

## Exit codes

- 100: wrong usage.
- 111: system call failed.

If everything goes smoothly, s6-tlsc does not exit, but execs into prog... instead.

## Environment variables

### Read

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`

### 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 child but not to prog.... The `-Z` option prevents that behaviour.

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

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

## Notes

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