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

+s6-networking
+Software
+skarnet.org +

+ +

The s6-tlsserver program

+ +

+s6-tlsserver is an +UCSPI server tool for +TLS/SSL connections over INET domain sockets. It acts as a TCP superserver +that listens to connections, accepts them, and for each connection, +establishes a TLS transport over it, then executes into a program. +

+ +

Interface

+ +
+     s6-tlsserver [ options ] [ -- ] ip port prog...
+
+ + + +

+ prog is expected to read from its peer on its +standard input and write to its peer on its standard output. +Since there will be a s6-tlsd +program between prog and the network to perform +the SSL encryption/decryption, those descriptors will not +be a network socket - they will be pipes. +

+ +

Signals

+ +

+ s6-tlsserver reacts to the same signals as +s6-tcpserver4d or +s6-tcpserver6d, +one of which is the long-lived process hanging around. +

+ +

Environment variables

+ +

Read

+ +

+ The following variables should be set before invoking +s6-tlsserver, because they will be used by +every s6-tlsd invocation: +

+ + + +

+ Setting both KEYFILE and CERTFILE is mandatory. +

+ +

Written

+ +

+ prog... is run with the following variables added to, +or removed from, its environment by s6-tcpserver4d +or s6-tcpserver6d, and possibly +by s6-tcpserver-access: +

+ + + +

+ Depending on TCP access rules (if the -i or -x +option has been given), it is possible that prog's +environment undergoes more modifications. Also, since +s6-tlsd is always run +after s6-tcpserver-access, +it is possible to set different TLS/SSL parameters (typically +a different KEYFILE and CERTFILE) depending on the client +connection, by writing the correct set of TCP access rules. +

+ +

+ Unless the -Z option is given to s6-tlsserver, +the CADIR, CAFILE, KEYFILE, CERTFILE, TLS_UID and TLS_GID +variables will not appear in prog's environment. +

+ + +

Options

+ +

+ s6-tlsserver accepts a myriad of options, most of which are +passed as is to the correct executable. Not giving any options will +generally work, but unless you're running a very public server +(such as a Web server) or base your access control on client +certificates, you probably still want TCP access rules. +

+ +

Options passed as is to s6-tcpserver

+ + + +

Options passed as is to s6-tcpserver-access

+ + + +

Options passed as is to s6-tlsd

+ + + +

Options passed to s6-applyuidgid

+ + + +

Example

+ + +

+ As root: + KEYFILE=/etc/ssl/private/mykey.der CERTFILE=/etc/ssl/public/mycert.pem \ + TLS_UID=65534 TLS_UID=65536 \ + s6-envuidgid www + s6-tlsserver -U -- 1.2.3.4 443 httpd +

+ +

+This will start a server listening to 1.2.3.4 on TCP port 443, + and for every connection, spawn the httpd program +reading queries on stdin and replying on stdout, as user www, +with a TLS layer protecting the connection, the TLS engine running +as user nobody (65534:65534). The server is +authentified by the certificate in /etc/ssl/public/mycert.pem +that it sends to the client, and the private key in +/etc/ssl/private/mykey.der that it keeps to itself. +

+ + + -- cgit v1.2.3