From bdb38fdeb4183371b8ad8669c2821526133c39c8 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sat, 3 Dec 2016 01:05:40 +0000 Subject: s6-tls*: small bugfixes. Add documentation. --- doc/s6-tlsc.html | 268 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 268 insertions(+) create mode 100644 doc/s6-tlsc.html (limited to 'doc/s6-tlsc.html') diff --git a/doc/s6-tlsc.html b/doc/s6-tlsc.html new file mode 100644 index 0000000..b44caf5 --- /dev/null +++ b/doc/s6-tlsc.html @@ -0,0 +1,268 @@ + + + + + + s6-networking: the s6-tlsc program + + + + + + +

+ +

The `s6-tlsc` program

+ +

+s6-tlsc is a program that establishes a TLS or SSL +client connection over an existing TCP connection, then spawns +an application. It 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-tlsc +is provided by the chosen SSL backend: +BearSSL or +LibreSSL, depending on +the options given when configuring s6-networking. +

+ +

Interface

+ +

+     s6-tlsc [ -S | -s ] [ -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 prog... as a child process, +interposing itself between it and the network.
It initiates a TLS/SSL handshake over the +network connection, expecting a TLS/SSL server on the other +side.
It manages the encryption/decryption of all the +messages between prog and the server. +prog speaks plaintext, but only ciphertext is sent +on the network.
When prog exits, s6-tlsc exits. +

+ +

Exit codes

+ +

96: error while configuring the TLS/SSL context - for instance, invalid trust anchor set.
97: error while setting up the TLS/SSL client engine.
98: TLS/SSL error while running the engine.
100: wrong usage.
111: system call failed.

+ +

+ If the TLS/SSL connection closes cleanly, s6-tlsc +waits for prog to exit, then exits with an +approximation +of prog's exit code. +

+ +

Protocol version and parameters

+ +

+ During the TLS/SSL handshake, s6-tlsc 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. The supported protocol versions are described +here.
For LibreSSL, this means use of the +tls_config_set_protocols(TLS_PROTOCOLS_ALL) +call.

+ +

+ As a client, it is better for s6-tlsc to adapt to as many servers +as possible, that's why it adopts a liberal approach to protocol +versions. +

+ +

Environment variables

+ +

Read

+ +

+ s6-tlsc 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 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. Please note that for now, support for client +certificates is experimental, and only works +with the LibreSSL +backend (BearSSL does not support client certificates yet). +

+ +

+ If s6-tlsc 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 +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 +program is a way of doing it. +

+ +

Written

+ +

+ Unless the -Z option has been given to +s6-tlsc, prog... is run with all the +TLS/SSL variables unset: CADIR, CAFILE, +KEYFILE, CERTFILE, TLS_UID and TLS_GID. The goal is +for s6-tlsc to be, by default, as invisible +as possible. +

+ +

Server name determination for SNI

+ +

+ The -k servername option is important to +s6-tlsc: it tells it to send servername +as the name to require a certificate for. +Not setting this option allows s6-tlsc to +proceed without SNI, +which may be a security risk. +

+ +

+ The s6-tlsclient program can +automatically craft a -k option for s6-tlsc +if the host argument that is given to it is a +host name. But if you're invoking s6-tlsc directly, +do not forget to give it this option. +

+ +

SSL close handling

+ +

+ If prog initiates the end of the session by sending +EOF, there are two ways for the TLS/SSL layer to handle it. +

+ +

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.
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 (2016), most protocols are auto-terminated, so +it is not dangerous anymore to use EOF tranmission, and that +is the default fo s6-tlsc. Nevertheless, by +using the -S option, you can +force it to use the close_notify method if your +application requires it to be secure. +

+ +

`s6-tlsc` 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 +s6-tlsc-related variables before spawning prog....
-z : clean the environment of +s6-tlsc-related variables before spawning 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.
-Y : Do not send a client certificate. This is the default.
-y : Send a client certificate. This is experimental and +for now unsupported by BearSSL.
-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 kimeout milliseconds elapse without any data being +received from either side. The default is 0, which means +infinite timeout (never kill the connection).
-6 rfd : expect an open file +descriptor numbered rfd to read network (ciphertext) +data from. Make sure prog also reads its data +from its own fd rfd. Default is 6.
-7 wfd : expect an open file +descriptor numbered wfd to write network (ciphertext) +data to. Make sure prog also writes its data to +its own fd wfd. 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.

+ + + -- cgit v1.2.3

The s6-tlsc program