sys/man/8/tlssrv

   1 .TH TLSSRV 8
   2 .SH NAME
   3 tlssrv, tlsclient, tlssrvtunnel, tlsclienttunnel \- TLS server and client
   4 .SH SYNOPSIS
   5 .PP
   6 .B tlssrv
   7 [
   8 .B -c
   9 .I cert.pem
  10 ]
  11 [
  12 .B -l
  13 .I
  14 logfile
  15 ]
  16 [
  17 .B -r
  18 .I remotesys
  19 ]
  20 .I cmd
  21 [
  22 .I args ...
  23 ]
  24 .PP
  25 .B tlsclient
  26 [
  27 .B -t
  28 .I trustedkeys
  29 ]
  30 [
  31 .B -x
  32 .I excludedkeys
  33 ]
  34 .I address
  35 .PP
  36 .B tlssrvtunnel
  37 .I plain-addr
  38 .I crypt-addr
  39 .I cert.pem
  40 .PP
  41 .B tlsclienttunnel
  42 .I crypt-addr
  43 .I plain-addr
  44 .I trustedkeys
  45 .SH DESCRIPTION
  46 .I Tlssrv
  47 is a helper program, typically exec'd in a
  48 .B /bin/service
  49 file to establish an SSL or TLS connection before launching
  50 .I cmd
  51 .IR args ;
  52 a typical command might start the IMAP or HTTP server.
  53 .I Cert.pem
  54 is the server certificate;
  55 .IR factotum (4)
  56 should hold the corresponding private key.
  57 The specified
  58 .I logfile
  59 is by convention the same as for the target server.
  60 .I Remotesys
  61 is mainly used for logging.
  62 .PP
  63 .I Tlsclient
  64 is the reverse of
  65 .IR tlssrv :
  66 it dials
  67 .IR address ,
  68 starts TLS,
  69 and then relays
  70 between the network connection
  71 and standard input and output.
  72 If the
  73 .B -t
  74 flag
  75 (and, optionally, the
  76 .B -x
  77 flag)
  78 is given, the remote server must present a key
  79 whose SHA1 hash is listed in
  80 the file
  81 .I trustedkeys
  82 but not in the file
  83 .IR excludedkeys .
  84 See
  85 .IR thumbprint (6)
  86 for more information.
  87 .PP
  88 .I Tlssrvtunnel
  89 and
  90 .I tlsclienttunnel
  91 use these tools and
  92 .I listen1
  93 (see
  94 .IR listen (8))
  95 to provide TLS network tunnels, allowing legacy
  96 application to take advantage of TLS encryption.
  97 .SH EXAMPLES
  98 Listen for TLS-encrypted IMAP by creating a server certificate
  99 .B /sys/lib/tls/imap.pem
 100 and a listener script
 101 .B /bin/service.auth/tcp993
 102 containing:
 103 .IP
 104 .EX
 105 #!/bin/rc
 106 exec tlssrv -c/sys/lib/tls/imap.pem -limap4d -r`{cat $3/remote} \e
 107     /bin/ip/imap4d -p -dyourdomain -r`{cat $3/remote} \e
 108     >[2]/sys/log/imap4d
 109 .EE
 110 .PP
 111 Interact with the server, putting the appropriate hash into
 112 .B /sys/lib/tls/mail
 113 and running:
 114 .IP
 115 .EX
 116 tlsclient -t /sys/lib/tls/mail tcp!server!imaps
 117 .EE
 118 .PP
 119 Create a TLS-encrypted VNC connection from a client on
 120 .B kremvax
 121 to a server on
 122 .BR moscvax :
 123 .IP
 124 .EX
 125 mosc% vncs -d :3
 126 mosc% tlssrvtunnel tcp!moscvax!5903 tcp!*!12345 \e
 127         /usr/you/lib/cert.pem
 128 krem% tlsclienttunnel tcp!moscvax!12345 tcp!*!5905 \e
 129         /usr/you/lib/cert.thumb
 130 krem% vncv kremvax:5
 131 .EE
 132 .LP
 133 (The port numbers passed to the VNC tools are offset by 5900 from the
 134 actual TCP port numbers.)
 135 .SH FILES
 136 .TP
 137 .B /sys/lib/tls
 138 .SH SOURCE
 139 .B /sys/src/cmd/tlssrv.c
 140 .br
 141 .B /sys/src/cmd/tlsclient.c
 142 .br
 143 .B /rc/bin/tlssrvtunnel
 144 .br
 145 .B /rc/bin/tlsclienttunnel
 146 .SH "SEE ALSO"
 147 .IR factotum (4),
 148 .IR listen (8),
 149 .IR rsa (8)
 150 .br
 151 Unix's
 152 .I stunnel