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

+ +

The `s6-tlsclient` program

+ +

+s6-tlsclient is an +UCSPI client tool for +TLS/SSL connections over INET domain sockets. It establishes a TCP +connection to a server and a TLS transport over it, +then executes into a program. +

+ +

Interface

+ +

+     s6-tlsclient [ options ] [ -- ] host port prog...
+

+ +

s6-tlsclient rewrites itself into a command line +involving: +
- s6-tcpclient, which +establishes a TCP connection to host host port port.
- s6-tlsc, which establishes +a TLS transport (client-side) over that connection.
- prog..., your client program, which is run as a +child of s6-tlsc.
It runs until the connection closes.
It exits either with a s6-tlsc +error code (and error message), or with an +approximation +of prog's exit code.

+ +

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

+ +

Server name determination for SNI

+ +

+ + If the -H option is not given to s6-tlsclient, +then host will be used as the server name to verify. +You can use the -k option to override this default. +Please note that if you use the -H option and do not +provide a server name via -k, SNI will not be +used, which may be a security risk. +

+ + +

Environment variables

+ +

Read

+ +

+ The following variables should be set before invoking +s6-tlsclient, because they will be used by +s6-tlsc: +

+ +

CADIR
CAFILE (alternative to CADIR)
KEYFILE (if you're using a client certificate)
CERTFILE (if you're using a client certificate)
TLS_UID and TLS_GID (if you run s6-tlsclient as root)

+ +

+ Setting either CADIR or CAFILE is mandatory. +

+ +

Written

+ +

+ prog... is run with the following variables added to, +or removed from, its environment by s6-tcpclient: +

+ +

PROTO
TCPREMOTEIP
TCPREMOTEPORT
TCPREMOTEHOST
TCPLOCALHOST
TCPREMOTEINFO

+ +

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

+ + +

Options

+ +

+ s6-tlsclient accepts a myriad of options, most of which are +passed as is to the correct executable. Not giving any options will +generally work: the defaults are sensible. +

+ +

Options passed as is to s6-tcpclient

+ +

-q, -Q, -v
-4, -6
-d, -D
-r, -R
-h, -H, -l localname
-n, -N
-t timeout
-i localip, -p localport
-T timeoutconn

+ +

Options passed as is to s6-tlsc

+ +

-Z, -z
-S, -s
-Y, -y
-k servername
-K kimeout

+ +

Example

+ +

+ CADIR=/etc/ssl/certs s6-tlsclient skarnet.org 443 s6-ioconnect +

+ +

+ This will open a connection to +the skarnet.org web server +over TLS and verify its certificate via the trust anchors +listed in the /etc/ssl/certs directory. It will then +branch your terminal to it: try typing +GET / HTTP/1.0 then hitting return twice. +

+ + + -- cgit v1.3.1

The s6-tlsclient program