Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PUSHTLS(3)		   Library Functions Manual		    PUSHTLS(3)

       pushtls,	 tlsClient,  tlsServer,	 initThumbprints, freeThumbprints, ok-
       Thumbprint, readcert, readcertchain - attach TLS1 or SSL3 encryption to
       a communication channel

       #include	<u.h>
       #include	<libc.h>

       int	      pushtls(int fd, char *hashalg, char *encalg,
			   int isclient, char *secret, char *dir)

       #include	<mp.h>
       #include	<libsec.h>

       int	      tlsClient(int fd,	TLSconn	*conn)

       int	      tlsServer(int fd,	TLSconn	*conn)

       uchar	      *readcert(char *filename,	int *pcertlen)

       PEMchain	      *readcertchain(char *filename)

       Thumbprint*    initThumbprints(char *ok,	char *crl)

       void	      freeThumbprints(Thumbprint *table)

       int	      okThumbprint(uchar *hash,	Thumbprint *table)

       Transport Layer Security	(TLS) comprises	a record layer protocol, doing
       message digesting and encrypting	in the kernel, and a handshake	proto-
       col, 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 implementa-
       tions of	either standard.

       To use just the record layer, as	described in  Plan  9's	 tls(3),  call
       pushtls	to open	the record layer device, connect to the	communications
       channel fd, and start up	encryption and message authentication as spec-
       ified  in hashalg, encalg, and secret.  These parameters	must have been
       arranged	at the two ends	of the conversation by other means.  For exam-
       ple,  hashalg  could be sha1, encalg could be rc4_128, and 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.
       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, fd.	 If dir	is non-zero, the  path
       name of the connection directory	is copied into dir.  This path name is
       guaranteed to be	less than 40 bytes long.

       Alternatively, call tlsClient to	speak the full handshake protocol, ne-
       gotiate the algorithms and secrets, and return a	new data file descrip-
       tor for the data	channel.  Conn points to a (caller-allocated) struct
	  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;
       defined in tls.h.  On input, the	caller can  provide  options  such  as
       cert,  the local	certificate, and sessionID, used by a client to	resume
       a previously negotiated security	association.  On output,  the  connec-
       tion  directory is set, as with listen (see The input cert is freed and
       a freshly allocated copy	of the remote's	 certificate  is  returned  in
       conn,  to  be checked by	the caller according to	its needs.  One	mecha-
       nism is supplied	by initThumbprints and freeThumbprints which  allocate
       and  free,  respectively, a table of hashes from	files of known trusted
       and revoked certificates.  okThumbprint confirms	that a particular hash
       is in the table,	as computed by

	  uchar	hash[SHA1dlen];
	  conn = (TLSconn*)mallocz(sizeof *conn, 1);
	  fd = tlsClient(fd, conn);
	  sha1(conn->cert, conn->certlen, hash,	nil);
	     exits("suspect server");
	  ...application begins...

       Call  tlsServer	to  perform  the  corresponding	function on the	server

	  fd = accept(lcfd, ldir);
	  conn = (TLSconn*)mallocz(sizeof *conn, 1);
	  conn->cert = readcert("cert.pem", &conn->certlen);
	  fd = tlsServer(fd, conn);
	  ...application begins...
       The private key corresponding to	cert.pem should	have  been  previously
       loaded into factotum.  (See for more about key generation.)  By setting
	  conn->chain =	readcertchain("intermediate-certs.pem");
       the  server  can	 present  extra	 certificate evidence to establish the
       chain of	trust to a root	authority known	to the client.

       Conn is not required for	the ongoing conversation and may be  freed  by
       the application whenever	convenient.

	      thumbprints of trusted services

	      PEM certificate files


       Plan 9's	factotum(4) and	tls(3)

       return -1 on failure.

       Pushtls is not implemented.

       Client certificates and client sessionIDs are not yet implemented.

       Note  that  in the TLS protocol sessionID itself	is public;  it is used
       as a pointer to secrets stored in factotum.



Want to link to this manual page? Use this URL:

home | help