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 dial(3)).  The input cert is
       freed and a freshly allocated copy of the remote's certificate  is  re-
       turned  in  conn,  to  be checked by the	caller according to its	needs.
       One mechanism 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 partic-
       ular 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 rsa(3) for more about key generation.)  By
	  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


       dial(3),	thumbprint(7); 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