S6-TLSCLIENT(8)

NAME
s6-tlsclient - UCSPI client tool[1] for TLS/SSL connections over INET domain sockets

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

DESCRIPTION
s6-tlsclient establishes a TCP connection to a server and a TLS transport over it, then executes into a program.

s6-tlsclient rewrites itself into a command line involving:

•   s6-tcpclient(8), which establishes a TCP connection to host host port port.

•   s6-tlsc(8), which establishes a TLS transport (client-side) over that connection.

•   prog..., your client program, which is executed into by s6-tlsc(8) once the s6-tlsc-io(8) child it has spawned has set up the TLS connection and performed the handshake.

prog... is run with the same pid as s6-tlsclient.

prog is expected to read from its peer on descriptor 6 and write to its peer on descriptor 7. Since there will be an s6-tlsc-io(8) program between prog and the network to perform the TLS 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.

OPTIONS
s6-tlsclient accepts a myriad of options, all 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 1

-q, -Q, -v
    Be quiet, normally verbose, or verbose.

-4, -6
    Stick to IPv4 or IPv6 addresses.

-d, -D
    Enable or disable Nagle's algorithm.

-r, -R
    Enable or disable IDENT lookup.

-H  Disable DNS lookups.

-h  Consult /etc/hosts before DNS.

-l localname
    Get the local name from the command line, don't look it up.

-n, -N
    Qualify the host or not when resolving it.

-t timeout
    Global timeout on the connection attempt.

-i localip, -p localport
    Force local socket parameters.

-T timeoutconn
    Configurable connection timeouts.

  Options passed as-is to s6-tlsc 1

-Z, -z
    Keep or remove the s6-tlsc-io(8) -specific variables from the application's environment.

-S, -s
    Use ‘close_notify’ or EOF to signal the end of a TLS connection.

-J, -j
    Exit nonzero with an error message when the peer fails to ‘close_notify’, or ignore it.

-Y, -y
    Don't send, or send, a client certificate.

-k servername
    Use SNI and provide a server name.

-K kimeout
    Set a timeout for the TLS handshake.

ENVIRONMENT

  Read
The following variables should be set before invoking s6-tlsclient, because they will be used by s6-tlsc-io(8):

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(8):

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.

EXAMPLES
    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.

SEE ALSO
s6-tls(7), s6-tlsc(8), s6-tlsc-io(8), s6-tlsd(8), s6-tlsd-io(8), s6-tlsserver(8), s6-ucspitlsc(8), s6-ucspitlsd(8)

[1] https://cr.yp.to/proto/ucspi.txt

This man page is ported from the authoritative documentation at: https://skarnet.org/software/s6-networking/s6-tlsclient.html

AUTHORS
Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)