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
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
<head>
<title>pushtls(3) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>PUSHTLS(3)</b><td align=right><b>PUSHTLS(3)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints,
okThumbprint, readcert, readcertchain – attach TLS1 or SSL3 encryption
to a communication channel<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>#include <u.h><br>
#include <libc.h>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int pushtls(int fd, char *hashalg, char *encalg,<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
int isclient, char *secret, char *dir)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</table>
</table>
</font></tt>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
</table>
</table>
<tt><font size=+1>#include <mp.h><br>
#include <libsec.h>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int tlsClient(int fd, TLSconn *conn)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int tlsServer(int fd, TLSconn *conn)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>uchar *readcert(char *filename, int *pcertlen)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>PEMchain *readcertchain(char *filename)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>Thumbprint* initThumbprints(char *ok, char *crl)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void freeThumbprints(Thumbprint *table)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int okThumbprint(uchar *hash, Thumbprint *table)<br>
</font></tt>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
Transport Layer Security (TLS) comprises a record layer protocol,
doing message digesting and encrypting in the kernel, and a handshake
protocol, doing initial authentication and secret creation at
user level and then starting a data channel in the record protocol.
TLS is nearly the same as SSL 3.0, and the software
should interoperate with implementations of either standard.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
To use just the record layer, as described in Plan 9’s <i>tls</i>(3),
call <i>pushtls</i> to open the record layer device, connect to the communications
channel <i>fd</i>, and start up encryption and message authentication
as specified in <i>hashalg</i>, <i>encalg</i>, and <i>secret</i>. These parameters
must have been arranged at the two ends of the
conversation by other means. For example, <i>hashalg</i> could be <tt><font size=+1>sha1</font></tt>,
<i>encalg</i> could be <tt><font size=+1>rc4_128</font></tt>, and <i>secret</i> could be the base-64 encoding
of two (client-to-server and server-to-client) 20-byte digest
keys and two corresponding 16-byte encryption keys. <i>Pushtls</i> returns
a file descriptor for the TLS data channel.
Anything written to this descriptor will get encrypted and authenticated
and then written to the file descriptor, <i>fd</i>. If <i>dir</i> is non-zero,
the path name of the connection directory is copied into <i>dir</i>.
This path name is guaranteed to be less than 40 bytes long.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Alternatively, call <i>tlsClient</i> to speak the full handshake protocol,
negotiate the algorithms and secrets, and return a new data file
descriptor for the data channel. <i>Conn</i> points to a (caller-allocated)
struct<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>typedef struct TLSconn{<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
char dir[40]; // OUT connection directory<br>
uchar *cert; // IN/OUT certificate<br>
uchar *sessionID; // IN/OUT sessionID<br>
int certlen, sessionIDlen;<br>
void (*trace)(char*fmt, ...);<br>
PEMChain *chain;<br>
</table>
} TLSconn;<br>
</font></tt>
</table>
defined in <i>tls.h</i>. On input, the caller can provide options such
as <i>cert</i>, the local certificate, and <i>sessionID</i>, used by a client
to resume a previously negotiated security association. On output,
the connection directory is set, as with <tt><font size=+1>listen</font></tt> (see <a href="../man3/dial.html"><i>dial</i>(3)</a>).
The input <i>cert</i> is freed and a freshly allocated copy of the remote’s
certificate is returned in <i>conn</i>, to be checked by the caller according
to its needs. One mechanism is supplied by <i>initThumbprints</i> and
<i>freeThumbprints</i> which allocate and free, respectively, a table
of hashes from files of known trusted and revoked certificates.
<i>okThumbprint</i> confirms that a particular hash is in the
table, as computed by
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>uchar hash[SHA1dlen];<br>
conn = (TLSconn*)mallocz(sizeof *conn, 1);<br>
fd = tlsClient(fd, conn);<br>
sha1(conn−>cert, conn−>certlen, hash, nil);<br>
if(!okThumbprint(hash,table))<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
exits("suspect server");<br>
</table>
...application begins...<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
</table>
Call <i>tlsServer</i> to perform the corresponding function on the server
side:
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>fd = accept(lcfd, ldir);<br>
conn = (TLSconn*)mallocz(sizeof *conn, 1);<br>
conn−>cert = readcert("cert.pem", &conn−>certlen);<br>
fd = tlsServer(fd, conn);<br>
...application begins...<br>
</font></tt>
</table>
The private key corresponding to <i>cert.pem</i> should have been previously
loaded into factotum. (See <a href="../man3/rsa.html"><i>rsa</i>(3)</a> for more about key generation.)
By setting<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>conn−>chain = readcertchain("intermediate−certs.pem");<br>
</font></tt>
</table>
the server can present extra certificate evidence to establish
the chain of trust to a root authority known to the client.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Conn</i> is not required for the ongoing conversation and may be freed
by the application whenever convenient.<br>
</table>
<p><font size=+1><b>FILES </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>/sys/lib/tls<br>
</font></tt>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
thumbprints of trusted services<br>
</table>
<tt><font size=+1>/sys/lib/ssl<br>
</font></tt>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
PEM certificate files<br>
</table>
</table>
<p><font size=+1><b>SOURCE </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>/usr/local/plan9/src/libsec/port<br>
</font></tt>
</table>
<p><font size=+1><b>SEE ALSO </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<a href="../man3/dial.html"><i>dial</i>(3)</a>, <a href="../man7/thumbprint.html"><i>thumbprint</i>(7)</a>; Plan 9’s <i>factotum</i>(4) and <i>tls</i>(3)<br>
</table>
<p><font size=+1><b>DIAGNOSTICS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
return –1 on failure.<br>
</table>
<p><font size=+1><b>BUGS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>Pushtls</i> is not implemented.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Client certificates and client sessionIDs are not yet implemented.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Note that in the TLS protocol <i>sessionID</i> itself is public; it is
used as a pointer to secrets stored in factotum.<br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>
|