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