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 -D
   9 ]
  10 [
  11 .BR - [ aA ]
  12 [
  13 .B -k
  14 .I keyspec
  15 ]
  16 ]
  17 [
  18 .B -c
  19 .I cert.pem
  20 ]
  21 [
  22 .B -l
  23 .I
  24 logfile
  25 ]
  26 [
  27 .B -r
  28 .I remotesys
  29 ]
  30 .I cmd
  31 [
  32 .I args ...
  33 ]
  34 .PP
  35 .B tlsclient
  36 [
  37 .B -D
  38 ]
  39 [
  40 .B -a
  41 [
  42 .B -k
  43 .I keyspec
  44 ]
  45 ]
  46 [
  47 .B -c
  48 .I cert.pem
  49 ]
  50 [
  51 .B -t
  52 .I trustedkeys
  53 ]
  54 [
  55 .B -x
  56 .I excludedkeys
  57 ]
  58 [
  59 .B -n
  60 .I servername
  61 ]
  62 [
  63 .B -o
  64 ]
  65 .I address
  66 [
  67 .I cmd
  68 [
  69 .I args ...
  70 ]
  71 ]
  72 .PP
  73 .B tlssrvtunnel
  74 .I plain-addr
  75 .I crypt-addr
  76 .I cert.pem
  77 .PP
  78 .B tlsclienttunnel
  79 .I crypt-addr
  80 .I plain-addr
  81 .I trustedkeys
  82 .SH DESCRIPTION
  83 .I Tlssrv
  84 is a helper program, typically exec'd in a
  85 .B /bin/service
  86 file to establish an SSL or TLS connection before launching
  87 .I cmd
  88 .IR args ;
  89 a typical command might start the IMAP or HTTP server.
  90 .I Cert.pem
  91 is the server certificate;
  92 .IR factotum (4)
  93 should hold the corresponding private key.
  94 The specified
  95 .I logfile
  96 is by convention the same as for the target server.
  97 .I Remotesys
  98 is mainly used for logging.
  99 If the
 100 .B -a
 101 or
 102 .B -A
 103 flag is specified,
 104 .B p9any
 105 authentication is run before the TLS handshake and the resulting
 106 plan9 session secret is used as a pre-shared key for TLS encryption.
 107 This enables the use of TLS without certificates and also runs
 108 the server command as the authorized user when the
 109 .B -a
 110 flag was specified.
 111 .PP
 112 .I Tlsclient
 113 is the reverse of
 114 .IR tlssrv :
 115 it connects to
 116 .IR address ,
 117 starts TLS,
 118 and then relays
 119 between the network connection
 120 and standard input and output or executes
 121 .I cmd args
 122 with standard input and output redirected to the connection.
 123 The
 124 .B -D
 125 flag enables some debug output.
 126 Specifying a certificate in pem(8) format with the
 127 .B -c
 128 flag, causes the client to submit this certificate upon
 129 server's request. A corresponding key has to be present in
 130 .IR factotum (4).
 131 If the
 132 .B -t
 133 flag
 134 (and, optionally, the
 135 .B -x
 136 flag)
 137 is given, the remote server must present a key
 138 whose SHA1 hash is listed in
 139 the file
 140 .I trustedkeys
 141 but not in the file
 142 .IR excludedkeys .
 143 See
 144 .IR thumbprint (6)
 145 for more information. The
 146 .B -n
 147 option passes the string
 148 .I servername
 149 in the TLS hello message (Server Name Idenfitication)
 150 which is usefull when talking to webservers.
 151 When the
 152 .B -o
 153 option was specified,
 154 .I address
 155 is interpreted as a filename to be opend read-write instead of
 156 a dial string.
 157 .PP
 158 .I Tlssrvtunnel
 159 and
 160 .I tlsclienttunnel
 161 use these tools and
 162 .I listen1
 163 (see
 164 .IR listen (8))
 165 to provide TLS network tunnels, allowing legacy
 166 application to take advantage of TLS encryption.
 167 .SH EXAMPLES
 168 Listen for TLS-encrypted IMAP by creating a server certificate
 169 .B /sys/lib/tls/imap.pem
 170 and a listener script
 171 .B /bin/service.auth/tcp993
 172 containing:
 173 .IP
 174 .EX
 175 #!/bin/rc
 176 exec tlssrv -c/sys/lib/tls/imap.pem -limap4d -r`{cat $3/remote} \e
 177     /bin/ip/imap4d -p -dyourdomain -r`{cat $3/remote} \e
 178     >[2]/sys/log/imap4d
 179 .EE
 180 .PP
 181 Interact with the server, putting the appropriate hash into
 182 .B /sys/lib/tls/mail
 183 and running:
 184 .IP
 185 .EX
 186 tlsclient -t /sys/lib/tls/mail tcp!server!imaps
 187 .EE
 188 .PP
 189 Create a TLS-encrypted VNC connection from a client on
 190 .B kremvax
 191 to a server on
 192 .BR moscvax :
 193 .IP
 194 .EX
 195 mosc% vncs -d :3
 196 mosc% tlssrvtunnel tcp!moscvax!5903 tcp!*!12345 \e
 197         /usr/you/lib/cert.pem
 198 krem% tlsclienttunnel tcp!moscvax!12345 tcp!*!5905 \e
 199         /usr/you/lib/cert.thumb
 200 krem% vncv kremvax:5
 201 .EE
 202 .LP
 203 (The port numbers passed to the VNC tools are offset by 5900 from the
 204 actual TCP port numbers.)
 205 .SH FILES
 206 .TP
 207 .B /sys/lib/tls
 208 .SH SOURCE
 209 .B /sys/src/cmd/tlssrv.c
 210 .br
 211 .B /sys/src/cmd/tlsclient.c
 212 .br
 213 .B /rc/bin/tlssrvtunnel
 214 .br
 215 .B /rc/bin/tlsclienttunnel
 216 .SH "SEE ALSO"
 217 .IR factotum (4),
 218 .IR listen (8),
 219 .IR rsa (8)
 220 .br
 221 Unix's
 222 .I stunnel