sys/man/2/pushtls

   1 .TH PUSHTLS 2
   2 .SH NAME
   3 pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert, readcertchain \- attach TLS1 or SSL3 encryption to a communication channel
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .PP
   9 .nf
  10 .B
  11 int     pushtls(int fd, char *hashalg, char *encalg,
  12 .B
  13                 int isclient, char *secret, char *dir)
  14 .PP
  15 .nf
  16 .B #include <mp.h>
  17 .B #include <libsec.h>
  18 .PP
  19 .B
  20 int     tlsClient(int fd, TLSconn *conn)
  21 .PP
  22 .B
  23 int     tlsServer(int fd, TLSconn *conn)
  24 .PP
  25 .B
  26 uchar *readcert(char *filename, int *pcertlen)
  27 .PP
  28 .B
  29 PEMchain *readcertchain(char *filename)
  30 .PP
  31 .B
  32 Thumbprint *initThumbprints(char *ok, char *crl)
  33 .PP
  34 .B
  35 void    freeThumbprints(Thumbprint *table)
  36 .PP
  37 .B
  38 int     okThumbprint(uchar *hash, Thumbprint *table)
  39 .SH DESCRIPTION
  40 Transport Layer Security (TLS) comprises a record layer protocol,
  41 doing message digesting and encrypting in the kernel,
  42 and a handshake protocol,
  43 doing initial authentication and secret creation at
  44 user level and then starting a data channel in the record protocol.
  45 TLS is nearly the same as SSL 3.0, and the software should interoperate
  46 with implementations of either standard.
  47 .PP
  48 To use just the record layer, as described in
  49 .IR tls (3),
  50 call
  51 .I pushtls
  52 to open the record layer device, connect to the communications channel
  53 .IR fd ,
  54 and start up encryption and message authentication as specified
  55 in
  56 .IR hashalg ,
  57 .IR encalg ,
  58 and
  59 .IR secret .
  60 These parameters must have been arranged at the two ends of the
  61 conversation by other means.
  62 For example,
  63 .I hashalg
  64 could be
  65 .BR sha1 ,
  66 .I encalg
  67 could be
  68 .BR rc4_128 ,
  69 and
  70 .I secret
  71 could be the base-64 encoding of two (client-to-server and server-to-client)
  72 20-byte digest keys and two corresponding 16-byte encryption keys.
  73 .I Pushtls
  74 returns a file descriptor for the TLS data channel.  Anything written to this
  75 descriptor will get encrypted and authenticated and then written to the
  76 file descriptor,
  77 .IR fd .
  78 If
  79 .I dir
  80 is non-zero, the path name of the connection directory is copied into
  81 .IR dir .
  82 This path name is guaranteed to be less than 40 bytes long.
  83 .SS Certificates
  84 .\" and other horseshit
  85 Alternatively, call
  86 .I tlsClient
  87 to speak the full handshake protocol,
  88 negotiate the algorithms and secrets,
  89 and return a new data file descriptor for the data channel.
  90 .I Conn
  91 points to a (caller-allocated) struct:
  92 .IP
  93 .EX
  94 typedef struct TLSconn {
  95         char    dir[40];                /* OUT    connection directory */
  96         uchar *cert;            /* IN/OUT certificate */
  97         uchar *sessionID;       /* IN/OUT session ID */
  98         int     certlen, sessionIDlen;
  99         void    (*trace)(char*fmt, ...);
 100         PEMChain *chain;
 101         char    *sessionType;   /* opt IN  session type */
 102         uchar *sessionKey;      /* opt IN/OUT session key */
 103         int     sessionKeylen;  /* opt IN  session key length */
 104         char    *sessionConst;  /* opt IN  session constant */
 105 } TLSconn;
 106 .EE
 107 .PP
 108 defined in
 109 .IR tls.h .
 110 On input, the caller can provide options such as
 111 .IR cert ,
 112 the local certificate, and
 113 .IR sessionID ,
 114 used by a client to resume a previously negotiated security association.
 115 On output, the connection directory is set, as with
 116 .B listen
 117 (see
 118 .IR dial (2)).
 119 The input
 120 .I cert
 121 is freed and a freshly allocated copy of the remote's certificate
 122 is returned in
 123 .IR conn ,
 124 to be checked by the caller
 125 according to its needs.
 126 One way to check the remote certificate is to use
 127 .I initThumbprints
 128 and
 129 .I freeThumbprints
 130 which allocate and free, respectively, a table of hashes
 131 from files of known trusted and revoked certificates.
 132 .I okThumbprint
 133 confirms that a particular hash is in the table.
 134 .PP
 135 .I TlsClient
 136 will optionally compute a session key for use
 137 by higher-level protocols.
 138 To compute a session key, the caller must set
 139 .I sessionType
 140 to a known session type;
 141 .I sessionKeylen
 142 to the desired key length;
 143 .I sessionKey
 144 to a buffer of length
 145 .IR sessionKeylen ;
 146 and
 147 .I sessionConst
 148 to the desired salting constant.
 149 The only supported session type is
 150 .BR ttls ,
 151 as used by 802.1x.
 152 .PP
 153 .I TlsServer
 154 executes the server side of the handshake.
 155 The caller must initialize
 156 .IB conn ->cert \fR,
 157 usually by calling
 158 .I readcert
 159 to read and decode the PEM-encoded certificate from
 160 .IR filename ,
 161 return a pointer to
 162 .IR malloc ed
 163 storage containing the certificate,
 164 and store its length through
 165 .IR pcertlen .
 166 The private key corresponding to
 167 .I cert.pem
 168 should have been previously loaded into factotum.
 169 (See
 170 .IR rsa (8)
 171 for more about key generation.)
 172 .PP
 173 .I Readcertchain
 174 will read a PEM-encoded chain of certificates from
 175 .I filename
 176 and return a pointer to a linked list of
 177 .IR malloc ed
 178 .B PEMChain
 179 structures, defined in
 180 .IR tls.h :
 181 .IP
 182 .EX
 183 typedef struct PEMChain PEMChain;
 184 struct PEMChain {
 185         PEMChain*next;
 186         uchar *pem;
 187         int     pemlen;
 188 };
 189 .EE
 190 .LP
 191 By setting
 192 .IP
 193 .EX
 194 conn->chain = readcertchain("intermediate-certs.pem");
 195 .EE
 196 .LP
 197 the server can present extra certificate evidence
 198 to establish the chain of trust to a root authority
 199 known to the client.
 200 .PP
 201 .I Conn
 202 is not required for the ongoing conversation and may
 203 be freed by the application whenever convenient.
 204 .SH EXAMPLES
 205 Start the client half of TLS and check the remote certificate:
 206 .IP
 207 .EX
 208 uchar hash[SHA1dlen];
 209
 210 conn = (TLSconn*)mallocz(sizeof *conn, 1);
 211 fd = tlsClient(fd, conn);
 212 sha1(conn->cert, conn->certlen, hash, nil);
 213 if(!okThumbprint(hash,table))
 214         exits("suspect server");
 215 \fI...application begins...\fP
 216 .EE
 217 .PP
 218 Run the server side:
 219 .IP
 220 .EX
 221 fd = accept(lcfd, ldir);
 222 conn = (TLSconn*)mallocz(sizeof *conn, 1);
 223 conn->cert = readcert("cert.pem", &conn->certlen);
 224 fd = tlsServer(fd, conn);
 225 \fI...application begins...\fP
 226 .EE
 227 .SH FILES
 228 .TF /sys/lib/tls
 229 .TP
 230 .B /sys/lib/tls
 231 thumbprints of trusted services
 232 .TP
 233 .B /sys/lib/ssl
 234 PEM certificate files
 235 .SH SOURCE
 236 .B /sys/src/libc/9sys/pushtls.c
 237 .br
 238 .B /sys/src/libsec/port
 239 .SH "SEE ALSO"
 240 .IR dial (2),
 241 .IR tls (3),
 242 .IR factotum (4),
 243 .IR thumbprint (6)
 244 .SH DIAGNOSTICS
 245 Return \-1 on failure.
 246 .SH BUGS
 247 Client certificates and client sessionIDs are not yet
 248 implemented.
 249 .PP
 250 Note that in the TLS protocol
 251 .I sessionID
 252 itself is public;  it is used as a pointer to
 253 secrets stored in
 254 .IR factotum .