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,
#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 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. Certificates
TlsClient will optionally compute a session key for use by higher–level protocols. To compute a session key, the caller must set sessionType to a known session type; sessionKeylen to the desired key length; sessionKey to a buffer of length sessionKeylen; and sessionConst to the desired salting constant. The only supported session type is ttls, as used by 802.1x. TlsServer executes the server side of the handshake. The caller must initialize conn–>cert, usually by calling readcert to read and decode the PEM–encoded certificate from filename, return a pointer to malloced storage containing the certificate, and store its length through pcertlen. The private key corresponding to cert.pem should have been previously loaded into factotum. (See rsa(8) for more about key generation.)
Readcertchain will read a PEM–encoded chain of certificates from
filename and return a pointer to a linked list of malloced PEMChain
structures, defined in tls.h:
Conn is not required for the ongoing conversation and may be freed
by the application whenever convenient. |
EXAMPLES
Start the client half of TLS and check the remote certificate:
|
FILES
/sys/lib/tls thumbprints of trusted services /sys/lib/ssl PEM certificate files |
SOURCE
/sys/src/libc/9sys/pushtls.c /sys/src/libsec/port |
SEE ALSO
dial(2), tls(3), factotum(4), thumbprint(6) |
DIAGNOSTICS
Return –1 on failure. |
BUGS
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. |