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
|
.TH PUSHTLS 3
.SH NAME
pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert, readcertchain \- attach TLS1 or SSL3 encryption to a communication channel
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
int pushtls(int fd, char *hashalg, char *encalg,
.br
.B
int isclient, char *secret, char *dir)
.PP
.B #include <mp.h>
.br
.B #include <libsec.h>
.PP
.B
int tlsClient(int fd, TLSconn *conn)
.PP
.B
int tlsServer(int fd, TLSconn *conn)
.PP
.B
uchar *readcert(char *filename, int *pcertlen)
.PP
.B
PEMchain *readcertchain(char *filename)
.PP
.B
Thumbprint* initThumbprints(char *ok, char *crl)
.PP
.B
void freeThumbprints(Thumbprint *table)
.PP
.B
int okThumbprint(uchar *hash, Thumbprint *table)
.SH DESCRIPTION
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.
.PP
To use just the record layer, as described in Plan 9's
\fItls\fR(3),
call
.I pushtls
to open the record layer device, connect to the communications channel
.IR fd ,
and start up encryption and message authentication as specified
in
.IR hashalg ,
.IR encalg ,
and
.IR secret .
These parameters must have been arranged at the two ends of the
conversation by other means.
For example,
.I hashalg
could be
.BR sha1 ,
.I encalg
could be
.BR rc4_128 ,
and
.I secret
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
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,
.IR fd .
If
.I dir
is non-zero, the path name of the connection directory is copied into
.IR dir .
This path name is guaranteed to be less than 40 bytes long.
.PP
Alternatively, call
.I tlsClient
to speak the full handshake protocol,
negotiate the algorithms and secrets,
and return a new data file descriptor for the data channel.
.I Conn
points to a (caller-allocated) struct
.EX
typedef struct TLSconn{
char dir[40]; // OUT connection directory
uchar *cert; // IN/OUT certificate
uchar *sessionID; // IN/OUT sessionID
int certlen, sessionIDlen;
void (*trace)(char*fmt, ...);
PEMChain *chain;
} TLSconn;
.EE
defined in
.IR tls.h .
On input, the caller can provide options such as
.IR cert ,
the local certificate, and
.IR sessionID ,
used by a client to resume a previously negotiated security association.
On output, the connection directory is set, as with
.B listen
(see
.IR dial (3)).
The input
.I cert
is freed and a freshly allocated copy of the remote's certificate
is returned in
.IR conn ,
to be checked by the caller
according to its needs. One mechanism is supplied by
.I initThumbprints
and
.I freeThumbprints
which allocate and free, respectively, a table of hashes
from files of known trusted and revoked certificates.
.I okThumbprint
confirms that a particular hash is in the table, as computed by
.PP
.EX
uchar hash[SHA1dlen];
conn = (TLSconn*)mallocz(sizeof *conn, 1);
fd = tlsClient(fd, conn);
sha1(conn->cert, conn->certlen, hash, nil);
if(!okThumbprint(hash,table))
exits("suspect server");
...application begins...
.EE
.PP
Call
.I tlsServer
to perform the corresponding function on the server side:
.PP
.EX
fd = accept(lcfd, ldir);
conn = (TLSconn*)mallocz(sizeof *conn, 1);
conn->cert = readcert("cert.pem", &conn->certlen);
fd = tlsServer(fd, conn);
...application begins...
.EE
The private key corresponding to
.I cert.pem
should have been previously loaded into factotum.
(See
.IR rsa (3)
.\" XXX should be rsa(8)
for more about key generation.)
By setting
.EX
conn->chain = readcertchain("intermediate-certs.pem");
.EE
the server can present extra certificate evidence
to establish the chain of trust to a root authority
known to the client.
.PP
.I Conn
is not required for the ongoing conversation and may
be freed by the application whenever convenient.
.SH FILES
.TP
.B /sys/lib/tls
thumbprints of trusted services
.TP
.B /sys/lib/ssl
PEM certificate files
.SH SOURCE
.\" .B /sys/src/libc/9sys/pushtls.c
.\" .br
.B \*9/src/libsec/port
.SH "SEE ALSO"
.IR dial (3),
.IR thumbprint (7);
Plan 9's
\fIfactotum\fR(4)
and
\fItls\fR(3)
.SH DIAGNOSTICS
return \-1 on failure.
.SH BUGS
.I Pushtls
is not implemented.
.PP
Client certificates and client sessionIDs are not yet
implemented.
.PP
Note that in the TLS protocol
.I sessionID
itself is public; it is used as a pointer to
secrets stored in factotum.
|