From 058b0118a52061ad57694c01fc8763b22b789c4d Mon Sep 17 00:00:00 2001 From: rsc Date: Mon, 3 Jan 2005 06:40:20 +0000 Subject: Some man pages. --- man/man3/pushtls.3 | 196 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 man/man3/pushtls.3 (limited to 'man/man3/pushtls.3') diff --git a/man/man3/pushtls.3 b/man/man3/pushtls.3 new file mode 100644 index 00000000..b92dcb6e --- /dev/null +++ b/man/man3/pushtls.3 @@ -0,0 +1,196 @@ +.TH PUSHTLS 3 +.SH NAME +pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert, readcertchain \- attach TLS1 or SSL3 encryption to a communication channel +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int pushtls(int fd, char *hashalg, char *encalg, +.br +.B + int isclient, char *secret, char *dir) +.PP +.B #include +.br +.B #include +.PP +.B +int tlsClient(int fd, TLSconn *conn) +.PP +.B +int tlsServer(int fd, TLSconn *conn) +.PP +.B +uchar *readcert(char *filename, int *pcertlen) +.PP +.B +PEMchain *readcertchain(char *filename) +.PP +.B +Thumbprint* initThumbprints(char *ok, char *crl) +.PP +.B +void freeThumbprints(Thumbprint *table) +.PP +.B +int okThumbprint(uchar *hash, Thumbprint *table) +.SH DESCRIPTION +Transport Layer Security (TLS) comprises a record layer protocol, +doing message digesting and encrypting in the kernel, +and a handshake protocol, +doing initial authentication and secret creation at +user level and then starting a data channel in the record protocol. +TLS is nearly the same as SSL 3.0, and the software should interoperate +with implementations of either standard. +.PP +To use just the record layer, as described in Plan 9's +\fItls\fR(3), +call +.I pushtls +to open the record layer device, connect to the communications channel +.IR fd , +and start up encryption and message authentication as specified +in +.IR hashalg , +.IR encalg , +and +.IR secret . +These parameters must have been arranged at the two ends of the +conversation by other means. +For example, +.I hashalg +could be +.BR sha1 , +.I encalg +could be +.BR rc4_128 , +and +.I secret +could be the base-64 encoding of two (client-to-server and server-to-client) +20-byte digest keys and two corresponding 16-byte encryption keys. +.I Pushtls +returns a file descriptor for the TLS data channel. Anything written to this +descriptor will get encrypted and authenticated and then written to the +file descriptor, +.IR fd . +If +.I dir +is non-zero, the path name of the connection directory is copied into +.IR dir . +This path name is guaranteed to be less than 40 bytes long. +.PP +Alternatively, call +.I tlsClient +to speak the full handshake protocol, +negotiate the algorithms and secrets, +and return a new data file descriptor for the data channel. +.I Conn +points to a (caller-allocated) struct +.EX + typedef struct TLSconn{ + char dir[40]; // OUT connection directory + uchar *cert; // IN/OUT certificate + uchar *sessionID; // IN/OUT sessionID + int certlen, sessionIDlen; + void (*trace)(char*fmt, ...); + PEMChain *chain; + } TLSconn; +.EE +defined in +.IR tls.h . +On input, the caller can provide options such as +.IR cert , +the local certificate, and +.IR sessionID , +used by a client to resume a previously negotiated security association. +On output, the connection directory is set, as with +.B listen +(see +.IR dial (3)). +The input +.I cert +is freed and a freshly allocated copy of the remote's certificate +is returned in +.IR conn , +to be checked by the caller +according to its needs. One mechanism is supplied by +.I initThumbprints +and +.I freeThumbprints +which allocate and free, respectively, a table of hashes +from files of known trusted and revoked certificates. +.I okThumbprint +confirms that a particular hash is in the table, as computed by +.PP +.EX + uchar hash[SHA1dlen]; + conn = (TLSconn*)mallocz(sizeof *conn, 1); + fd = tlsClient(fd, conn); + sha1(conn->cert, conn->certlen, hash, nil); + if(!okThumbprint(hash,table)) + exits("suspect server"); + ...application begins... +.EE +.PP +Call +.I tlsServer +to perform the corresponding function on the server side: +.PP +.EX + fd = accept(lcfd, ldir); + conn = (TLSconn*)mallocz(sizeof *conn, 1); + conn->cert = readcert("cert.pem", &conn->certlen); + fd = tlsServer(fd, conn); + ...application begins... +.EE +The private key corresponding to +.I cert.pem +should have been previously loaded into factotum. +(See +.IR rsa (3) +.\" XXX should be rsa(8) +for more about key generation.) +By setting +.EX + conn->chain = readcertchain("intermediate-certs.pem"); +.EE +the server can present extra certificate evidence +to establish the chain of trust to a root authority +known to the client. +.PP +.I Conn +is not required for the ongoing conversation and may +be freed by the application whenever convenient. +.SH FILES +.TP +.B /sys/lib/tls +thumbprints of trusted services +.TP +.B /sys/lib/ssl +PEM certificate files +.SH SOURCE +.\" .B /sys/src/libc/9sys/pushtls.c +.\" .br +.B /usr/local/plan9/src/libsec/port +.SH "SEE ALSO" +.IR dial (3), +.IR thumbprint (7); +Plan 9's +\fIfactotum\fR(4) +and +\fItls\fR(3) +.SH DIAGNOSTICS +return \-1 on failure. +.SH BUGS +.I Pushtls +is not implemented. +.PP +Client certificates and client sessionIDs are not yet +implemented. +.PP +Note that in the TLS protocol +.I sessionID +itself is public; it is used as a pointer to +secrets stored in factotum. -- cgit v1.2.3