MAN.9FRONT.ORG RTFM


     TLSSRV(8)                                               TLSSRV(8)

     NAME
          tlssrv, tlsclient, tlssrvtunnel, tlsclienttunnel - TLS
          server and client

     SYNOPSIS
          tlssrv [ -D ] [ -[aA] [ -k keyspec ] ] [ -c cert.pem ] [ -l
          logfile ] [ -r remotesys ] cmd [ args ... ]

          tlsclient [ -D ] [ -a [ -k keyspec ] ] [ -c clientcert.pem ]
          [ -d servercert ] [ -t trustedkeys ] [ -x excludedkeys ] [
          -n servername ] [ -o ] address [ cmd [ args ... ] ]

          tlssrvtunnel plain-addr crypt-addr cert.pem

          tlsclienttunnel crypt-addr plain-addr trustedkeys

     DESCRIPTION
          Tlssrv is a helper program, typically exec'd in a
          /bin/service file to establish an SSL or TLS connection
          before launching cmd args; a typical command might start the
          IMAP or HTTP server.  Cert.pem is the server certificate;
          factotum(4) should hold the corresponding private key.  The
          specified logfile is by convention the same as for the tar-
          get server.  Remotesys is mainly used for logging.  If the
          -a or -A flag is specified, p9any authentication is run
          before the TLS handshake and the resulting plan9 session
          secret is used as a pre-shared key for TLS encryption.  This
          enables the use of TLS without certificates and also runs
          the server command as the authorized user when the -a flag
          was specified.

          Tlsclient is the reverse of tlssrv: it connects to address,
          starts TLS, and then relays between the network connection
          and standard input and output or executes cmd args with
          standard input and output redirected to the connection.  The
          -D flag enables some debug output.  Specifying a certificate
          in pem(8) format with the -c flag, causes the client to sub-
          mit this certificate upon server's request. A corresponding
          key has to be present in factotum(4). The -d flag writes the
          server's certificate to the file servercert in binary ASN.1
          encoding.  If the server doesnt provide a certificate, an
          empty file is created.  If the -t flag (and, optionally, the
          -x flag) is given, the remote server must present a public
          key whose SHA1 or SHA256 hash is listed in the file
          trustedkeys but not in the file excludedkeys. See
          thumbprint(6) for more information. The -n option passes the
          string servername in the TLS hello message (Server Name
          Idenfitication) which is usefull when talking to webservers.
          When the -o option was specified, address is interpreted as
          a filename to be opend read-write instead of a dial string.

     TLSSRV(8)                                               TLSSRV(8)

          Tlssrvtunnel and tlsclienttunnel use these tools and listen1
          (see listen(8)) to provide TLS network tunnels, allowing
          legacy application to take advantage of TLS encryption.

     EXAMPLES
          Listen for TLS-encrypted IMAP by creating a server certifi-
          cate /sys/lib/tls/imap.pem and a listener script
          /bin/service.auth/tcp993 containing:

               #!/bin/rc
               exec tlssrv -c/sys/lib/tls/imap.pem -limap4d -r`{cat $3/remote} \
                   /bin/upas/imap4d -p -dyourdomain -r`{cat $3/remote} \
                   >[2]/sys/log/imap4d

          Interact with the server, putting the appropriate hash into
          /sys/lib/tls/mail and running:

               tlsclient -t /sys/lib/tls/mail tcp!server!imaps

          Create a TLS-encrypted VNC connection from a client on
          kremvax to a server on moscvax:

               mosc% vncs -d :3
               mosc% tlssrvtunnel tcp!moscvax!5903 tcp!*!12345 \
                       /usr/you/lib/cert.pem
               krem% tlsclienttunnel tcp!moscvax!12345 tcp!*!5905 \
                       /usr/you/lib/cert.thumb
               krem% vncv kremvax:5

          (The port numbers passed to the VNC tools are offset by 5900
          from the actual TCP port numbers.)

     FILES
          /sys/lib/tls

     SOURCE
          /sys/src/cmd/tlssrv.c
          /sys/src/cmd/tlsclient.c
          /rc/bin/tlssrvtunnel
          /rc/bin/tlsclienttunnel

     SEE ALSO
          factotum(4), listen(8), rsa(8)
          Unix's stunnel