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.html | 193 +++++++++++-------------------------------------------- 1 file changed, 37 insertions(+), 156 deletions(-) (limited to 'doc/s6-tlsd.html') diff --git a/doc/s6-tlsd.html b/doc/s6-tlsd.html index 36125d2..beeedda 100644 --- a/doc/s6-tlsd.html +++ b/doc/s6-tlsd.html @@ -20,8 +20,8 @@

s6-tlsd is a program that performs the server side of -a TLS or SSL connection over an existing TCP connection, then spawns -an application. It is meant to make network communications +a TLS or SSL 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.

@@ -45,69 +45,25 @@ 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 prog... as a child process, -interposing itself between it and the network. -In other words: prog still reads cleartext -on its stdin and writes cleartext on its stdout, but -those will actually be pipes to s6-tlsd, which -will read ciphertext from its own stdin (the network) -and write ciphertext to its own stdout (the network).
    • -
  • It initiates the server side of a TLS/SSL handshake -over the network connection, expecting a TLS/SSL client on -the other side.
    • -
  • It manages the encryption/decryption of all the -messages between prog and the client. -prog speaks plaintext, but only ciphertext is sent -on the network.
    • -
  • When prog exits, s6-tlsd exits. +
  • It spawns a s6-tlsd-io +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 +that the handshake has completed, s6-tlsd execs into +prog....

    • Exit codes

    - If the TLS/SSL connection closes cleanly, s6-tlsd -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-tlsd 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. -

    - - - -

    - As a server, s6-tlsd 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. + If everything goes smoothly, s6-tlsd does not exit, but execs +into prog... instead.

    Environment variables

    @@ -115,120 +71,44 @@ only TLS-1.2 but with several algorithms and cipher suites.

    Read

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

    - - - -

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

    - -

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

    - - - -

    - If s6-tlsd 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 -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. If the s6-tlsd -invocation actually comes from a -s6-tlsserver command line, -and privilege-dropping options (-G, -g, --u or -U) have been given to -s6-tlsserver, then -s6-applyuidgid -directly follows s6-tlsd on the command line, in order -to also drop the child's privileges before executing the application. -The point of that setup is: + s6-tlsd does not expect to have any particular +environment variables, but it spawns a +s6-tlsd-io program that does. +So it should pay attention to the following variables:

    Written

    - Unless the -Z option has been given to -s6-tlsd, prog... is run with all the -TLS/SSL variables unset: CADIR, CAFILE, -KEYFILE, CERTFILE, TLS_UID and TLS_GID. The goal is -for s6-tlsd to be, by default, as invisible -as possible. + 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-tlsd-io child but +not to prog.... +The -Z option prevents that behaviour.

    -

    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. + However, prog... is run with the following additional +environment variables:

    -

    - Nowadays (2017), most protocols are auto-terminated, so -it is not dangerous anymore to use EOF tranmission, and that -is the default for s6-tlsd. 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 options

    +

    Options