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
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.
84 .\" and other horseshit
87 to speak the full handshake protocol,
88 negotiate the algorithms and secrets,
89 and return a new data file descriptor for the data channel.
91 points to a (caller-allocated) struct:
94 typedef struct TLSconn {
95 char dir[40]; /* OUT connection directory */
96 uchar *cert; /* IN/OUT certificate */
97 uchar *sessionID; /* IN/OUT session ID */
98 int certlen, sessionIDlen;
99 void (*trace)(char*fmt, ...);
101 char *sessionType; /* opt IN session type */
102 uchar *sessionKey; /* opt IN/OUT session key */
103 int sessionKeylen; /* opt IN session key length */
104 char *sessionConst; /* opt IN session constant */
110 On input, the caller can provide options such as
112 the local certificate, and
114 used by a client to resume a previously negotiated security association.
115 On output, the connection directory is set, as with
121 is freed and a freshly allocated copy of the remote's certificate
124 to be checked by the caller
125 according to its needs.
126 One way to check the remote certificate is to use
130 which allocate and free, respectively, a table of hashes
131 from files of known trusted and revoked certificates.
133 confirms that a particular hash is in the table.
136 will optionally compute a session key for use
137 by higher-level protocols.
138 To compute a session key, the caller must set
140 to a known session type;
142 to the desired key length;
144 to a buffer of length
148 to the desired salting constant.
149 The only supported session type is
154 executes the server side of the handshake.
155 The caller must initialize
159 to read and decode the PEM-encoded certificate from
163 storage containing the certificate,
164 and store its length through
166 The private key corresponding to
168 should have been previously loaded into factotum.
171 for more about key generation.)
174 will read a PEM-encoded chain of certificates from
176 and return a pointer to a linked list of
179 structures, defined in
183 typedef struct PEMChain PEMChain;
194 conn->chain = readcertchain("intermediate-certs.pem");
197 the server can present extra certificate evidence
198 to establish the chain of trust to a root authority
202 is not required for the ongoing conversation and may
203 be freed by the application whenever convenient.
205 Start the client half of TLS and check the remote certificate:
208 uchar hash[SHA1dlen];
210 conn = (TLSconn*)mallocz(sizeof *conn, 1);
211 fd = tlsClient(fd, conn);
212 sha1(conn->cert, conn->certlen, hash, nil);
213 if(!okThumbprint(hash,table))
214 exits("suspect server");
215 \fI...application begins...\fP
221 fd = accept(lcfd, ldir);
222 conn = (TLSconn*)mallocz(sizeof *conn, 1);
223 conn->cert = readcert("cert.pem", &conn->certlen);
224 fd = tlsServer(fd, conn);
225 \fI...application begins...\fP
231 thumbprints of trusted services
234 PEM certificate files
236 .B /sys/src/libc/9sys/pushtls.c
238 .B /sys/src/libsec/port
245 Return \-1 on failure.
247 Client certificates and client sessionIDs are not yet
250 Note that in the TLS protocol
252 itself is public; it is used as a pointer to