.TH PUSHTLS 2.SH NAMEpushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert, readcertchain \- attach TLS1 or SSL3 encryption to a communication channel.SH SYNOPSIS.B #include <u.h>.br.B #include <libc.h>.PP.nf.Bint	pushtls(int fd, char *hashalg, char *encalg,.B		int isclient, char *secret, char *dir).PP.nf.B #include <mp.h>.B #include <libsec.h>.PP.Bint	tlsClient(int fd, TLSconn *conn).PP.Bint	tlsServer(int fd, TLSconn *conn).PP.Buchar *readcert(char *filename, int *pcertlen).PP.BPEMchain *readcertchain(char *filename).PP.BThumbprint *initThumbprints(char *ok, char *crl).PP.Bvoid	freeThumbprints(Thumbprint *table).PP.Bint	okThumbprint(uchar *hash, Thumbprint *table).SH DESCRIPTIONTransport 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 atuser level and then starting a data channel in the record protocol.TLS is nearly the same as SSL 3.0, and the software should interoperatewith implementations of either standard..PPTo use just the record layer, as described in.IR tls (3),call.I pushtlsto open the record layer device, connect to the communications channel.IR fd ,and start up encryption and message authentication as specifiedin.IR hashalg ,.IR encalg ,and.IR secret .These parameters must have been arranged at the two ends of theconversation by other means.For example,.I hashalgcould be.BR sha1 ,.I encalgcould be.BR rc4_128 ,and.I secretcould 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 Pushtlsreturns a file descriptor for the TLS data channel.  Anything written to thisdescriptor will get encrypted and authenticated and then written to thefile descriptor,.IR fd .If.I diris 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..SS Certificates.\" and other horseshitAlternatively, call.I tlsClientto speak the full handshake protocol,negotiate the algorithms and secrets,and return a new data file descriptor for the data channel..I Connpoints to a (caller-allocated) struct:.IP.EXtypedef struct TLSconn {	char	dir[40];		/* OUT    connection directory */	uchar *cert;		/* IN/OUT certificate */	uchar *sessionID;	/* IN/OUT session ID */	int	certlen, sessionIDlen;	void	(*trace)(char*fmt, ...);	PEMChain *chain;	char	*sessionType;	/* opt IN  session type */	uchar *sessionKey;	/* opt IN/OUT session key */	int	sessionKeylen;	/* opt IN  session key length */	char	*sessionConst;	/* opt IN  session constant */} TLSconn;.EE.PPdefined 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 (2)).The input.I certis freed and a freshly allocated copy of the remote's certificateis returned in.IR conn ,to be checked by the calleraccording to its needs.One way to check the remote certificate is to use.I initThumbprintsand.I freeThumbprintswhich allocate and free, respectively, a table of hashesfrom files of known trusted and revoked certificates..I okThumbprintconfirms that a particular hash is in the table..PP.I TlsClientwill optionally compute a session key for useby higher-level protocols.To compute a session key, the caller must set.I sessionTypeto a known session type;.I sessionKeylento the desired key length;.I sessionKeyto a buffer of length.IR sessionKeylen ;and.I sessionConstto the desired salting constant.The only supported session type is.BR ttls ,as used by 802.1x..PP.I TlsServerexecutes the server side of the handshake.The caller must initialize.IB conn ->cert \fR,usually by calling.I readcertto read and decode the PEM-encoded certificate from.IR filename ,return a pointer to.IR malloc edstorage containing the certificate,and store its length through.IR pcertlen .The private key corresponding to.I cert.pemshould have been previously loaded into factotum.(See.IR rsa (8)for more about key generation.).PP.I Readcertchainwill read a PEM-encoded chain of certificates from.I filenameand return a pointer to a linked list of.IR malloc ed.B PEMChainstructures, defined in.IR tls.h :.IP.EXtypedef struct PEMChain PEMChain;struct PEMChain {	PEMChain*next;	uchar *pem;	int	pemlen;};.EE.LPBy setting.IP.EXconn->chain = readcertchain("intermediate-certs.pem");.EE.LPthe server can present extra certificate evidenceto establish the chain of trust to a root authorityknown to the client..PP.I Connis not required for the ongoing conversation and maybe freed by the application whenever convenient..SH EXAMPLESStart the client half of TLS and check the remote certificate:.IP.EXuchar 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");\fI...application begins...\fP.EE.PPRun the server side:.IP.EXfd = accept(lcfd, ldir);conn = (TLSconn*)mallocz(sizeof *conn, 1);conn->cert = readcert("cert.pem", &conn->certlen);fd = tlsServer(fd, conn);\fI...application begins...\fP.EE.SH FILES.TF /sys/lib/tls.TP .B /sys/lib/tlsthumbprints of trusted services.TP .B /sys/lib/sslPEM certificate files.SH SOURCE.B /sys/src/libc/9sys/pushtls.c.br.B /sys/src/libsec/port.SH "SEE ALSO".IR dial (2),.IR tls (3),.IR factotum (4),.IR thumbprint (6).SH DIAGNOSTICSReturn \-1 on failure..SH BUGSClient certificates and client sessionIDs are not yetimplemented..PPNote that in the TLS protocol.I sessionIDitself is public;  it is used as a pointer tosecrets stored in.IR factotum .