3 pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert, readcertchain \- attach TLS1 or SSL3 encryption to a communication channel
11 int pushtls(int fd, char *hashalg, char *encalg,
13 int isclient, char *secret, char *dir)
17 .B #include <libsec.h>
20 int tlsClient(int fd, TLSconn *conn)
23 int tlsServer(int fd, TLSconn *conn)
26 uchar *readcert(char *filename, int *pcertlen)
29 PEMchain *readcertchain(char *filename)
32 Thumbprint *initThumbprints(char *ok, char *crl)
35 void freeThumbprints(Thumbprint *table)
38 int okThumbprint(uchar *hash, Thumbprint *table)
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.
48 To use just the record layer, as described in
52 to open the record layer device, connect to the communications channel
54 and start up encryption and message authentication as specified
60 These parameters must have been arranged at the two ends of the
61 conversation by other means.
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.
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
82 close the original file descriptor on success.
85 is non-zero, the path name of the connection directory is copied into
87 This path name is guaranteed to be less than 40 bytes long.
89 .\" and other horseshit
92 to speak the full handshake protocol,
93 negotiate the algorithms and secrets,
94 and return a new data file descriptor for the data channel.
96 points to a (caller-allocated) struct:
99 typedef struct TLSconn {
100 char dir[40]; /* OUT connection directory */
101 uchar *cert; /* IN/OUT certificate */
102 uchar *sessionID; /* IN/OUT session ID */
103 int certlen, sessionIDlen;
104 void (*trace)(char*fmt, ...);
106 char *sessionType; /* opt IN session type */
107 uchar *sessionKey; /* opt IN/OUT session key */
108 int sessionKeylen; /* opt IN session key length */
109 char *sessionConst; /* opt IN session constant */
115 On input, the caller can provide options such as
117 the local certificate, and
119 used by a client to resume a previously negotiated security association.
120 On output, the connection directory is set, as with
126 is freed and a freshly allocated copy of the remote's certificate
129 to be checked by the caller
130 according to its needs.
131 One way to check the remote certificate is to use
135 which allocate and free, respectively, a table of hashes
136 from files of known trusted and revoked certificates.
138 confirms that a particular hash is in the table.
141 will optionally compute a session key for use
142 by higher-level protocols.
143 To compute a session key, the caller must set
145 to a known session type;
147 to the desired key length;
149 to a buffer of length
153 to the desired salting constant.
154 The only supported session type is
159 executes the server side of the handshake.
160 The caller must initialize
164 to read and decode the PEM-encoded certificate from
168 storage containing the certificate,
169 and store its length through
171 The private key corresponding to
173 should have been previously loaded into factotum.
176 for more about key generation.)
179 will read a PEM-encoded chain of certificates from
181 and return a pointer to a linked list of
184 structures, defined in
188 typedef struct PEMChain PEMChain;
199 conn->chain = readcertchain("intermediate-certs.pem");
202 the server can present extra certificate evidence
203 to establish the chain of trust to a root authority
207 is not required for the ongoing conversation and may
208 be freed by the application whenever convenient.
210 Start the client half of TLS and check the remote certificate:
213 uchar hash[SHA1dlen];
215 conn = (TLSconn*)mallocz(sizeof *conn, 1);
216 fd = tlsClient(fd, conn);
217 sha1(conn->cert, conn->certlen, hash, nil);
218 if(!okThumbprint(hash,table))
219 exits("suspect server");
220 \fI...application begins...\fP
226 fd = accept(lcfd, ldir);
227 conn = (TLSconn*)mallocz(sizeof *conn, 1);
228 conn->cert = readcert("cert.pem", &conn->certlen);
229 fd = tlsServer(fd, conn);
230 \fI...application begins...\fP
236 thumbprints of trusted services
239 PEM certificate files
241 .B /sys/src/libc/9sys/pushtls.c
243 .B /sys/src/libsec/port
250 Return \-1 on failure.
252 Client certificates and client sessionIDs are not yet
260 do not close the original file descriptor on failure,
269 structure have to be freed by the caller.
271 Note that in the TLS protocol
273 itself is public; it is used as a pointer to