From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man3/pushtls.html | 261 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 261 insertions(+) create mode 100644 man/man3/pushtls.html (limited to 'man/man3/pushtls.html') diff --git a/man/man3/pushtls.html b/man/man3/pushtls.html new file mode 100644 index 00000000..ee806701 --- /dev/null +++ b/man/man3/pushtls.html @@ -0,0 +1,261 @@ + +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