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