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