From adc93f6097615f16d57e8a24a256302f2144ec4e Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 17:37:50 +0000 Subject: cut out the html - they're going to cause diffing problems. --- man/man3/pushtls.html | 261 -------------------------------------------------- 1 file changed, 261 deletions(-) delete mode 100644 man/man3/pushtls.html (limited to 'man/man3/pushtls.html') diff --git a/man/man3/pushtls.html b/man/man3/pushtls.html deleted file mode 100644 index ee806701..00000000 --- a/man/man3/pushtls.html +++ /dev/null @@ -1,261 +0,0 @@ - -pushtls(3) - Plan 9 from User Space - - - - -
-
-
PUSHTLS(3)PUSHTLS(3) -
-
-

NAME
- -
- - pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, - okThumbprint, readcert, readcertchain – attach TLS1 or SSL3 encryption - to a communication channel
- -
-

SYNOPSIS
- -
- - #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)
- -
-

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. -
- - 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 specified in hashalg, encalg, and secret. These parameters - must have been arranged at the two ends of the - conversation by other means. For example, 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, - negotiate the algorithms and secrets, and return a new data file - descriptor 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 connection 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 returned 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 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);
- if(!okThumbprint(hash,table))
- -
- - exits("suspect server");
- -
- ...application begins...
- -
- - -
- Call tlsServer to perform the corresponding function on the server - side: -
- - -
- - 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 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.
- -
-

FILES
- -
- - /sys/lib/tls
- -
- - thumbprints of trusted services
- -
- /sys/lib/ssl
- -
- - PEM certificate files
- -
- -
-

SOURCE
- -
- - /usr/local/plan9/src/libsec/port
- -
-

SEE ALSO
- -
- - dial(3), thumbprint(7); Plan 9’s factotum(4) and tls(3)
- -
-

DIAGNOSTICS
- -
- - return –1 on failure.
- -
-

BUGS
- -
- - 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.
- -
- -

 -
-
- - -
-
-
-Space Glenda -
-
- - -- cgit v1.2.3