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-tlsd-io.html | 212 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 doc/s6-tlsd-io.html (limited to 'doc/s6-tlsd-io.html') diff --git a/doc/s6-tlsd-io.html b/doc/s6-tlsd-io.html new file mode 100644 index 0000000..6aad7dc --- /dev/null +++ b/doc/s6-tlsd-io.html @@ -0,0 +1,212 @@ + + + + + + s6-networking: the s6-tlsc-io program + + + + + + +

+ +

The `s6-tlsc-io` program

+ +

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

+ +

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

+ +

Interface

+ +

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

+ +

s6-tlsd-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 expects a TLS client on the other side of the network connection +to initiate a TLS handshake, and it answers it.
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-tlsd-io exits.

+ +

Exit codes

+ +

0: the connection terminated normally. +
96: error while configuring the TLS context - for instance, invalid private key or server certificate files.
97: error while setting up the TLS server engine.
98: TLS error while running the engine.
100: wrong usage.
111: system call failed.

+ +

Protocol version and parameters

+ +

+ During the TLS/SSL handshake, s6-tlsd-io tries the +versions of the protocol that is supported by default by the +backend, with the default 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_server_init_full_rsa() or +br_ssl_server_init_full_ec() +function. The supported protocol versions are described +here.
For LibreSSL, this means use of the +tls_config_set_protocols(TLS_PROTOCOLS_DEFAULT) +call.

+ +

+ As a server, s6-tlsd-io can be conservative in its +choice of protocols. It is currently not very conservative +when using the BearSSL backend; it could become more so in +the future, by defining a custom server profile that supports +only TLS-1.2 but with several algorithms and cipher suites. +

+ +

Environment variables

+ +

+ s6-tlsd-io expects to have the following +environment variables set: +

+ +

KEYFILE: a path to the file +containing the server's private key, DER- or PEM-encoded.
CERTFILE: a path to the file +containing the server's certificate, DER- or PEM-encoded. +If PEM-encoded, the file can actually contain a chain +of certificates.

+ +

+ If one of those variables is unset, s6-tlsd-io +will refuse to run. +

+ +

+ If you are using client certificats, s6-tlsd-io +also requires either one of the following variables to be set: +

+ +

CADIR: a directory where trust anchors +(i.e. root or intermediate CA certificates) can be found, +one per file, DER- or PEM-encoded.
CAFILE: a file containing the whole set +of trust anchors, PEM-encoded.

+ +

+ If s6-tlsd-io is run as root, it can also read two +more environment variables, TLS_UID and TLS_GID, +which contain a numeric uid and a numeric gid; s6-tlsd-io +then drops its root privileges to this uid/gid after reading its +private key file. This ensures that the engine, including the +handshake, is run with as little privilege as possible. +

+ +

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

The s6-tlsc-io program