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