tpushtls.3 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tpushtls.3 (4867B)
---
1 .TH PUSHTLS 3
2 .SH NAME
3 pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert, readcertchain \- attach TLS1 or SSL3 encryption to a communication channel
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .PP
9 .B
10 int pushtls(int fd, char *hashalg, char *encalg,
11 .br
12 .B
13 int isclient, char *secret, char *dir)
14 .PP
15 .B #include <mp.h>
16 .br
17 .B #include <libsec.h>
18 .PP
19 .B
20 int tlsClient(int fd, TLSconn *conn)
21 .PP
22 .B
23 int tlsServer(int fd, TLSconn *conn)
24 .PP
25 .B
26 uchar *readcert(char *filename, int *pcertlen)
27 .PP
28 .B
29 PEMchain *readcertchain(char *filename)
30 .PP
31 .B
32 Thumbprint* initThumbprints(char *ok, char *crl)
33 .PP
34 .B
35 void freeThumbprints(Thumbprint *table)
36 .PP
37 .B
38 int okThumbprint(uchar *hash, Thumbprint *table)
39 .SH DESCRIPTION
40 Transport Layer Security (TLS) comprises a record layer protocol,
41 doing message digesting and encrypting in the kernel,
42 and a handshake protocol,
43 doing initial authentication and secret creation at
44 user level and then starting a data channel in the record protocol.
45 TLS is nearly the same as SSL 3.0, and the software should interoperate
46 with implementations of either standard.
47 .PP
48 To use just the record layer, as described in Plan 9's
49 .IR tls (3),
50 call
51 .I pushtls
52 to open the record layer device, connect to the communications channel
53 .IR fd ,
54 and start up encryption and message authentication as specified
55 in
56 .IR hashalg ,
57 .IR encalg ,
58 and
59 .IR secret .
60 These parameters must have been arranged at the two ends of the
61 conversation by other means.
62 For example,
63 .I hashalg
64 could be
65 .BR sha1 ,
66 .I encalg
67 could be
68 .BR rc4_128 ,
69 and
70 .I secret
71 could be the base-64 encoding of two (client-to-server and server-to-client)
72 20-byte digest keys and two corresponding 16-byte encryption keys.
73 .I Pushtls
74 returns a file descriptor for the TLS data channel. Anything written to this
75 descriptor will get encrypted and authenticated and then written to the
76 file descriptor,
77 .IR fd .
78 If
79 .I dir
80 is non-zero, the path name of the connection directory is copied into
81 .IR dir .
82 This path name is guaranteed to be less than 40 bytes long.
83 .PP
84 Alternatively, call
85 .I tlsClient
86 to speak the full handshake protocol,
87 negotiate the algorithms and secrets,
88 and return a new data file descriptor for the data channel.
89 .I Conn
90 points to a (caller-allocated) struct
91 .EX
92 typedef struct TLSconn{
93 char dir[40]; // OUT connection directory
94 uchar *cert; // IN/OUT certificate
95 uchar *sessionID; // IN/OUT sessionID
96 int certlen, sessionIDlen;
97 void (*trace)(char*fmt, ...);
98 PEMChain *chain;
99 } TLSconn;
100 .EE
101 defined in
102 .IR tls.h .
103 On input, the caller can provide options such as
104 .IR cert ,
105 the local certificate, and
106 .IR sessionID ,
107 used by a client to resume a previously negotiated security association.
108 On output, the connection directory is set, as with
109 .B listen
110 (see
111 .MR dial (3) ).
112 The input
113 .I cert
114 is freed and a freshly allocated copy of the remote's certificate
115 is returned in
116 .IR conn ,
117 to be checked by the caller
118 according to its needs. One mechanism is supplied by
119 .I initThumbprints
120 and
121 .I freeThumbprints
122 which allocate and free, respectively, a table of hashes
123 from files of known trusted and revoked certificates.
124 .I okThumbprint
125 confirms that a particular hash is in the table, as computed by
126 .PP
127 .EX
128 uchar hash[SHA1dlen];
129 conn = (TLSconn*)mallocz(sizeof *conn, 1);
130 fd = tlsClient(fd, conn);
131 sha1(conn->cert, conn->certlen, hash, nil);
132 if(!okThumbprint(hash,table))
133 exits("suspect server");
134 ...application begins...
135 .EE
136 .PP
137 Call
138 .I tlsServer
139 to perform the corresponding function on the server side:
140 .PP
141 .EX
142 fd = accept(lcfd, ldir);
143 conn = (TLSconn*)mallocz(sizeof *conn, 1);
144 conn->cert = readcert("cert.pem", &conn->certlen);
145 fd = tlsServer(fd, conn);
146 ...application begins...
147 .EE
148 The private key corresponding to
149 .I cert.pem
150 should have been previously loaded into factotum.
151 (See
152 .MR rsa (3)
153 .\" XXX should be rsa(8)
154 for more about key generation.)
155 By setting
156 .EX
157 conn->chain = readcertchain("intermediate-certs.pem");
158 .EE
159 the server can present extra certificate evidence
160 to establish the chain of trust to a root authority
161 known to the client.
162 .PP
163 .I Conn
164 is not required for the ongoing conversation and may
165 be freed by the application whenever convenient.
166 .SH FILES
167 .TP
168 .B /sys/lib/tls
169 thumbprints of trusted services
170 .TP
171 .B /sys/lib/ssl
172 PEM certificate files
173 .SH SOURCE
174 .\" .B /sys/src/libc/9sys/pushtls.c
175 .\" .br
176 .B \*9/src/libsec/port
177 .SH "SEE ALSO"
178 .MR dial (3) ,
179 .MR thumbprint (7) ;
180 Plan 9's
181 .IR factotum (4)
182 and
183 .IR tls (3)
184 .SH DIAGNOSTICS
185 return \-1 on failure.
186 .SH BUGS
187 .I Pushtls
188 is not implemented.
189 .PP
190 Client certificates and client sessionIDs are not yet
191 implemented.
192 .PP
193 Note that in the TLS protocol
194 .I sessionID
195 itself is public; it is used as a pointer to
196 secrets stored in factotum.