From 47cbbb1619ace4013856843ef8f7d68279c74faa Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sun, 22 Nov 2020 00:16:06 +0000 Subject: Add documentation, fix tiny privdrop bug --- doc/s6-tlsc-io.html | 217 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 doc/s6-tlsc-io.html (limited to 'doc/s6-tlsc-io.html') diff --git a/doc/s6-tlsc-io.html b/doc/s6-tlsc-io.html new file mode 100644 index 0000000..2f02841 --- /dev/null +++ b/doc/s6-tlsc-io.html @@ -0,0 +1,217 @@ + + + + + + s6-networking: the s6-tlsc-io program + + + + + + +

+ +

The `s6-tlsc-io` program

+ +

+s6-tlsc-io is a program that establishes a TLS or SSL +client connection over an existing TCP connection, then +communicates with an existing local program over already +established pipes. It is the only client-side program in +s6-networking that performs cryptography. +

+ +

+ s6-networking does not include +cryptographic software. All the crypto used in s6-tlsc-io +is provided by the chosen SSL backend: +BearSSL or +LibreSSL, depending on +the options given when configuring s6-networking. +

+ +

Interface

+ +

+     s6-tlsc-io [ -S | -s ] [ -Y | -y ] [ -v verbosity ] [ -K kimeout ] [ -k servername ] [ -d notif ] [ -- ] fdr fdw
+

+ +

s6-tlsc-io expects to have an open connection it +can talk to on its standard input and output. It also expects to read +cleartext data from file descriptor fdr and write cleartext +data to file descriptor fdw.
It initiates a TLS handshake over the network connection, +expecting a TLS server on the other side.
Then it acts as a full duplex tunnel, decrypting and transmitting +data from stdin to fdw, and encrypting and transmitting data +from fdr to stdout.
When it cannot transmit any more data from/to the local application +because connections have closed, s6-tlsc-io exits.

+ +

Exit codes

+ +

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

+ +

Protocol version and parameters

+ +

+ During the TLS handshake, s6-tlsc-io 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-io to adapt to as many servers +as possible, that's why it adopts a liberal approach to protocol +versions. +

+ +

Environment variables

+ +

+ s6-tlsc-io 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-io 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. +

+ +

+ If s6-tlsc-io 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-io +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 chainloading way of doing it. +

+ +

Server name determination for SNI

+ +

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

+ +

SSL close handling

+ +

+ If the local application initiates the end of the session by sending +EOF to fdr, there are two ways for the TLS 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 (2020), most protocols are auto-terminated, so +it is not dangerous anymore to use EOF tranmission, and that +is the default for s6-tlsc-io. 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-io` 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.
-S : send a close_notify alert +and break the connection when receiving a local 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.
-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).
-d notif : handshake notification. +notif must be a file descriptor open for writing. When the +TLS handshake has completed, some data (terminated by two null +characters) will be sent to file descriptor notif. The +data contains information about the TLS parameters of the connection; +its exact contents are left unspecified, but there's at least +a SSL_PROTOCOL=protocol string +and a SSL_CIPHER=cipher string, both null-terminated. +Sending this data serves a dual purpose: telling the notif +reader that the handshake has completed, and providing it with some +basic information about the connection. If this option is not given, +no such notification is performed.

+ + + -- cgit v1.2.3

The s6-tlsc-io program