3 pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert, readcertchain \- attach TLS1 or SSL3 encryption to a communication channel
10 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 Plan 9's
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
80 is non-zero, the path name of the connection directory is copied into
82 This path name is guaranteed to be less than 40 bytes long.
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.
90 points to a (caller-allocated) struct
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, ...);
103 On input, the caller can provide options such as
105 the local certificate, and
107 used by a client to resume a previously negotiated security association.
108 On output, the connection directory is set, as with
114 is freed and a freshly allocated copy of the remote's certificate
117 to be checked by the caller
118 according to its needs. One mechanism is supplied by
122 which allocate and free, respectively, a table of hashes
123 from files of known trusted and revoked certificates.
125 confirms that a particular hash is in the table, as computed by
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...
139 to perform the corresponding function on the server side:
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...
148 The private key corresponding to
150 should have been previously loaded into factotum.
153 .\" XXX should be rsa(8)
154 for more about key generation.)
157 conn->chain = readcertchain("intermediate-certs.pem");
159 the server can present extra certificate evidence
160 to establish the chain of trust to a root authority
164 is not required for the ongoing conversation and may
165 be freed by the application whenever convenient.
169 thumbprints of trusted services
172 PEM certificate files
174 .\" .B /sys/src/libc/9sys/pushtls.c
176 .B \*9/src/libsec/port
185 return \-1 on failure.
190 Client certificates and client sessionIDs are not yet
193 Note that in the TLS protocol
195 itself is public; it is used as a pointer to
196 secrets stored in factotum.
