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 .I Pushtls ,
  79 .IR tlsClient
  80 and
  81 .IR tlsServer
  82 close the original file descriptor on success.
  83 If
  84 .I dir
  85 is non-zero, the path name of the connection directory is copied into
  86 .IR dir .
  87 This path name is guaranteed to be less than 40 bytes long.
  88 .SS Certificates
  89 .\" and other horseshit
  90 Alternatively, call
  91 .I tlsClient
  92 to speak the full handshake protocol,
  93 negotiate the algorithms and secrets,
  94 and return a new data file descriptor for the data channel.
  95 .I Conn
  96 points to a (caller-allocated) struct:
  97 .IP
  98 .EX
  99 typedef struct TLSconn {
 100         char    dir[40];                /* OUT    connection directory */
 101         uchar *cert;            /* IN/OUT certificate */
 102         uchar *sessionID;       /* IN/OUT session ID */
 103         uchar *psk;             /* opt IN pre-shared key */
 104         int     certlen, sessionIDlen, psklen;
 105         int     (*trace)(char*fmt, ...);
 106         PEMChain *chain;
 107         char    *sessionType;   /* opt IN  session type */
 108         uchar *sessionKey;      /* opt IN/OUT session key */
 109         int     sessionKeylen;  /* opt IN  session key length */
 110         char    *sessionConst;  /* opt IN  session constant */
 111         char    *serverName;    /* opt IN  server name */
 112         char    *pskID;         /* opt IN  pre-shared key ID */
 113 } TLSconn;
 114 .EE
 115 .PP
 116 defined in
 117 .IR libsec.h .
 118 On input, the caller can provide options such as
 119 .IR cert ,
 120 the local certificate, and
 121 .IR sessionID ,
 122 used by a client to resume a previously negotiated security association.
 123 On output, the connection directory is set, as with
 124 .B listen
 125 (see
 126 .IR dial (2)).
 127 The input
 128 .I cert
 129 is freed and a freshly allocated copy of the remote's certificate
 130 is returned in
 131 .IR conn ,
 132 to be checked by the caller
 133 according to its needs.
 134 One way to check the remote certificate is to use
 135 .I initThumbprints
 136 and
 137 .I freeThumbprints
 138 which allocate and free, respectively, a table of hashes
 139 from files of known trusted and revoked certificates.
 140 .I okThumbprint
 141 confirms that a particular hash is in the table.
 142 .PP
 143 .I TlsClient
 144 will optionally compute a session key for use
 145 by higher-level protocols.
 146 To compute a session key, the caller must set
 147 .I sessionType
 148 to a known session type;
 149 .I sessionKeylen
 150 to the desired key length;
 151 .I sessionKey
 152 to a buffer of length
 153 .IR sessionKeylen ;
 154 and
 155 .I sessionConst
 156 to the desired salting constant.
 157 The only supported session type is
 158 .BR ttls ,
 159 as used by 802.1x.
 160 .PP
 161 .I TlsServer
 162 executes the server side of the handshake.
 163 The caller must initialize
 164 .IB conn ->cert \fR,
 165 usually by calling
 166 .I readcert
 167 to read and decode the PEM-encoded certificate from
 168 .IR filename ,
 169 return a pointer to
 170 .IR malloc ed
 171 storage containing the certificate,
 172 and store its length through
 173 .IR pcertlen .
 174 The private key corresponding to
 175 .I cert.pem
 176 should have been previously loaded into factotum.
 177 (See
 178 .IR rsa (8)
 179 for more about key generation.)
 180 .PP
 181 .I Readcertchain
 182 will read a PEM-encoded chain of certificates from
 183 .I filename
 184 and return a pointer to a linked list of
 185 .IR malloc ed
 186 .B PEMChain
 187 structures, defined in
 188 .IR libsec.h :
 189 .IP
 190 .EX
 191 typedef struct PEMChain PEMChain;
 192 struct PEMChain {
 193         PEMChain*next;
 194         uchar *pem;
 195         int     pemlen;
 196 };
 197 .EE
 198 .LP
 199 By setting
 200 .IP
 201 .EX
 202 conn->chain = readcertchain("intermediate-certs.pem");
 203 .EE
 204 .LP
 205 the server can present extra certificate evidence
 206 to establish the chain of trust to a root authority
 207 known to the client.
 208 .PP
 209 .I Conn
 210 is not required for the ongoing conversation and may
 211 be freed by the application whenever convenient.
 212 .SH EXAMPLES
 213 Start the client half of TLS and check the remote certificate:
 214 .IP
 215 .EX
 216 uchar hash[SHA1dlen];
 217
 218 conn = (TLSconn*)mallocz(sizeof *conn, 1);
 219 fd = tlsClient(fd, conn);
 220 sha1(conn->cert, conn->certlen, hash, nil);
 221 if(!okThumbprint(hash,table))
 222         exits("suspect server");
 223 \fI...application begins...\fP
 224 .EE
 225 .PP
 226 Run the server side:
 227 .IP
 228 .EX
 229 fd = accept(lcfd, ldir);
 230 conn = (TLSconn*)mallocz(sizeof *conn, 1);
 231 conn->cert = readcert("cert.pem", &conn->certlen);
 232 fd = tlsServer(fd, conn);
 233 \fI...application begins...\fP
 234 .EE
 235 .SH FILES
 236 .TF /sys/lib/tls
 237 .TP
 238 .B /sys/lib/tls
 239 thumbprints of trusted services
 240 .TP
 241 .B /sys/lib/ssl
 242 PEM certificate files
 243 .SH SOURCE
 244 .B /sys/src/libc/9sys/pushtls.c
 245 .br
 246 .B /sys/src/libsec/port
 247 .SH "SEE ALSO"
 248 .IR dial (2),
 249 .IR tls (3),
 250 .IR factotum (4),
 251 .IR thumbprint (6)
 252 .SH DIAGNOSTICS
 253 Return \-1 on failure.
 254 .SH BUGS
 255 Client certificates and client sessionIDs are not yet
 256 implemented.
 257 .PP
 258 Note that
 259 .IR pushtls ,
 260 .IR tlsClient
 261 and
 262 .IR tlsServer
 263 do not close the original file descriptor on failure,
 264 only on success.
 265 .PP
 266 The
 267 .IR sessionID
 268 and
 269 .IR cert
 270 pointers in the
 271 .IR TLSconn
 272 structure have to be freed by the caller.
 273 .PP
 274 Note that in the TLS protocol
 275 .I sessionID
 276 itself is public;  it is used as a pointer to
 277 secrets stored in
 278 .IR factotum .