261 lines
11 KiB
HTML
261 lines
11 KiB
HTML
<head>
|
|
<title>pushtls(3) - Plan 9 from User Space</title>
|
|
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
|
|
</head>
|
|
<body bgcolor=#ffffff>
|
|
<table border=0 cellpadding=0 cellspacing=0 width=100%>
|
|
<tr height=10><td>
|
|
<tr><td width=20><td>
|
|
<tr><td width=20><td><b>PUSHTLS(3)</b><td align=right><b>PUSHTLS(3)</b>
|
|
<tr><td width=20><td colspan=2>
|
|
<br>
|
|
<p><font size=+1><b>NAME </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints,
|
|
okThumbprint, readcert, readcertchain – attach TLS1 or SSL3 encryption
|
|
to a communication channel<br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>SYNOPSIS </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>#include <u.h><br>
|
|
#include <libc.h>
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>int pushtls(int fd, char *hashalg, char *encalg,<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
int isclient, char *secret, char *dir)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
</table>
|
|
|
|
</table>
|
|
</font></tt>
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
|
|
|
|
</table>
|
|
|
|
</table>
|
|
<tt><font size=+1>#include <mp.h><br>
|
|
#include <libsec.h>
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>int tlsClient(int fd, TLSconn *conn)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>int tlsServer(int fd, TLSconn *conn)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>uchar *readcert(char *filename, int *pcertlen)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>PEMchain *readcertchain(char *filename)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>Thumbprint* initThumbprints(char *ok, char *crl)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>void freeThumbprints(Thumbprint *table)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>int okThumbprint(uchar *hash, Thumbprint *table)<br>
|
|
</font></tt>
|
|
</table>
|
|
<p><font size=+1><b>DESCRIPTION </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
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.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
To use just the record layer, as described in Plan 9’s <i>tls</i>(3),
|
|
call <i>pushtls</i> to open the record layer device, connect to the communications
|
|
channel <i>fd</i>, and start up encryption and message authentication
|
|
as specified in <i>hashalg</i>, <i>encalg</i>, and <i>secret</i>. These parameters
|
|
must have been arranged at the two ends of the
|
|
conversation by other means. For example, <i>hashalg</i> could be <tt><font size=+1>sha1</font></tt>,
|
|
<i>encalg</i> could be <tt><font size=+1>rc4_128</font></tt>, and <i>secret</i> 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. <i>Pushtls</i> 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, <i>fd</i>. If <i>dir</i> is non-zero,
|
|
the path name of the connection directory is copied into <i>dir</i>.
|
|
This path name is guaranteed to be less than 40 bytes long.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
Alternatively, call <i>tlsClient</i> to speak the full handshake protocol,
|
|
negotiate the algorithms and secrets, and return a new data file
|
|
descriptor for the data channel. <i>Conn</i> points to a (caller-allocated)
|
|
struct<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>typedef struct TLSconn{<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
char dir[40]; // OUT connection directory<br>
|
|
uchar *cert; // IN/OUT certificate<br>
|
|
uchar *sessionID; // IN/OUT sessionID<br>
|
|
int certlen, sessionIDlen;<br>
|
|
void (*trace)(char*fmt, ...);<br>
|
|
PEMChain *chain;<br>
|
|
|
|
</table>
|
|
} TLSconn;<br>
|
|
</font></tt>
|
|
</table>
|
|
defined in <i>tls.h</i>. On input, the caller can provide options such
|
|
as <i>cert</i>, the local certificate, and <i>sessionID</i>, used by a client
|
|
to resume a previously negotiated security association. On output,
|
|
the connection directory is set, as with <tt><font size=+1>listen</font></tt> (see <a href="../man3/dial.html"><i>dial</i>(3)</a>).
|
|
The input <i>cert</i> is freed and a freshly allocated copy of the remote’s
|
|
certificate is returned in <i>conn</i>, to be checked by the caller according
|
|
to its needs. One mechanism is supplied by <i>initThumbprints</i> and
|
|
<i>freeThumbprints</i> which allocate and free, respectively, a table
|
|
of hashes from files of known trusted and revoked certificates.
|
|
<i>okThumbprint</i> confirms that a particular hash is in the
|
|
table, as computed by
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>uchar hash[SHA1dlen];<br>
|
|
conn = (TLSconn*)mallocz(sizeof *conn, 1);<br>
|
|
fd = tlsClient(fd, conn);<br>
|
|
sha1(conn−>cert, conn−>certlen, hash, nil);<br>
|
|
if(!okThumbprint(hash,table))<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
exits("suspect server");<br>
|
|
|
|
</table>
|
|
...application begins...<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
|
|
</table>
|
|
Call <i>tlsServer</i> to perform the corresponding function on the server
|
|
side:
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>fd = accept(lcfd, ldir);<br>
|
|
conn = (TLSconn*)mallocz(sizeof *conn, 1);<br>
|
|
conn−>cert = readcert("cert.pem", &conn−>certlen);<br>
|
|
fd = tlsServer(fd, conn);<br>
|
|
...application begins...<br>
|
|
</font></tt>
|
|
</table>
|
|
The private key corresponding to <i>cert.pem</i> should have been previously
|
|
loaded into factotum. (See <a href="../man3/rsa.html"><i>rsa</i>(3)</a> for more about key generation.)
|
|
By setting<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>conn−>chain = readcertchain("intermediate−certs.pem");<br>
|
|
</font></tt>
|
|
</table>
|
|
the server can present extra certificate evidence to establish
|
|
the chain of trust to a root authority known to the client.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Conn</i> is not required for the ongoing conversation and may be freed
|
|
by the application whenever convenient.<br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>FILES </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>/sys/lib/tls<br>
|
|
</font></tt>
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
thumbprints of trusted services<br>
|
|
|
|
</table>
|
|
<tt><font size=+1>/sys/lib/ssl<br>
|
|
</font></tt>
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
PEM certificate files<br>
|
|
|
|
</table>
|
|
|
|
</table>
|
|
<p><font size=+1><b>SOURCE </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>/usr/local/plan9/src/libsec/port<br>
|
|
</font></tt>
|
|
</table>
|
|
<p><font size=+1><b>SEE ALSO </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<a href="../man3/dial.html"><i>dial</i>(3)</a>, <a href="../man7/thumbprint.html"><i>thumbprint</i>(7)</a>; Plan 9’s <i>factotum</i>(4) and <i>tls</i>(3)<br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>DIAGNOSTICS </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
return –1 on failure.<br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>BUGS </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<i>Pushtls</i> is not implemented.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
Client certificates and client sessionIDs are not yet implemented.
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
Note that in the TLS protocol <i>sessionID</i> itself is public; it is
|
|
used as a pointer to secrets stored in factotum.<br>
|
|
|
|
</table>
|
|
|
|
<td width=20>
|
|
<tr height=20><td>
|
|
</table>
|
|
<!-- TRAILER -->
|
|
<table border=0 cellpadding=0 cellspacing=0 width=100%>
|
|
<tr height=15><td width=10><td><td width=10>
|
|
<tr><td><td>
|
|
<center>
|
|
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
|
|
</center>
|
|
</table>
|
|
<!-- TRAILER -->
|
|
</body></html>
|