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