sys/man/2/pushtls

   1 .TH PUSHTLS 2
   2 .SH NAME
   3 pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, okCertificate, 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, char *tag)
  33 .PP
  34 .B
  35 void    freeThumbprints(Thumbprint *table)
  36 .PP
  37 .B
  38 int     okThumbprint(uchar *hash, int len, Thumbprint *table)
  39 .PP
  40 .B
  41 int     okCertificate(uchar *cert, int len, Thumbprint *table)
  42 .SH DESCRIPTION
  43 Transport Layer Security (TLS) comprises a record layer protocol,
  44 doing message digesting and encrypting in the kernel,
  45 and a handshake protocol,
  46 doing initial authentication and secret creation at
  47 user level and then starting a data channel in the record protocol.
  48 TLS is nearly the same as SSL 3.0, and the software should interoperate
  49 with implementations of either standard.
  50 .PP
  51 To use just the record layer, as described in
  52 .IR tls (3),
  53 call
  54 .I pushtls
  55 to open the record layer device, connect to the communications channel
  56 .IR fd ,
  57 and start up encryption and message authentication as specified
  58 in
  59 .IR hashalg ,
  60 .IR encalg ,
  61 and
  62 .IR secret .
  63 These parameters must have been arranged at the two ends of the
  64 conversation by other means.
  65 For example,
  66 .I hashalg
  67 could be
  68 .BR sha1 ,
  69 .I encalg
  70 could be
  71 .BR rc4_128 ,
  72 and
  73 .I secret
  74 could be the base-64 encoding of two (client-to-server and server-to-client)
  75 20-byte digest keys and two corresponding 16-byte encryption keys.
  76 .I Pushtls
  77 returns a file descriptor for the TLS data channel.  Anything written to this
  78 descriptor will get encrypted and authenticated and then written to the
  79 file descriptor,
  80 .IR fd .
  81 .I Pushtls ,
  82 .IR tlsClient
  83 and
  84 .IR tlsServer
  85 close the original file descriptor on success.
  86 If
  87 .I dir
  88 is non-zero, the path name of the connection directory is copied into
  89 .IR dir .
  90 This path name is guaranteed to be less than 40 bytes long.
  91 .SS Certificates
  92 .\" and other horseshit
  93 Alternatively, call
  94 .I tlsClient
  95 to speak the full handshake protocol,
  96 negotiate the algorithms and secrets,
  97 and return a new data file descriptor for the data channel.
  98 .I Conn
  99 points to a (caller-allocated) struct:
 100 .IP
 101 .EX
 102 typedef struct TLSconn {
 103         char    dir[40];                /* OUT    connection directory */
 104         uchar *cert;            /* IN/OUT certificate */
 105         uchar *sessionID;       /* IN/OUT session ID */
 106         uchar *psk;             /* opt IN pre-shared key */
 107         int     certlen, sessionIDlen, psklen;
 108         int     (*trace)(char*fmt, ...);
 109         PEMChain *chain;
 110         char    *sessionType;   /* opt IN  session type */
 111         uchar *sessionKey;      /* opt IN/OUT session key */
 112         int     sessionKeylen;  /* opt IN  session key length */
 113         char    *sessionConst;  /* opt IN  session constant */
 114         char    *serverName;    /* opt IN  server name */
 115         char    *pskID;         /* opt IN  pre-shared key ID */
 116 } TLSconn;
 117 .EE
 118 .PP
 119 defined in
 120 .IR libsec.h .
 121 On input, the caller can provide options such as
 122 .IR cert ,
 123 the local certificate, and
 124 .IR sessionID ,
 125 used by a client to resume a previously negotiated security association.
 126 On output, the connection directory is set, as with
 127 .B listen
 128 (see
 129 .IR dial (2)).
 130 The input
 131 .I cert
 132 is freed and a freshly allocated copy of the remote's certificate
 133 is returned in
 134 .IR conn ,
 135 to be checked by the caller
 136 according to its needs.
 137 One way to check the remote certificate is to use
 138 .I initThumbprints
 139 and
 140 .I freeThumbprints
 141 which allocate and free, respectively, a table of hashes
 142 from files of known trusted and revoked certificates.
 143 .I okThumbprint
 144 confirms that a particular hash is in the table.
 145 .PP
 146 .I TlsClient
 147 will optionally compute a session key for use
 148 by higher-level protocols.
 149 To compute a session key, the caller must set
 150 .I sessionType
 151 to a known session type;
 152 .I sessionKeylen
 153 to the desired key length;
 154 .I sessionKey
 155 to a buffer of length
 156 .IR sessionKeylen ;
 157 and
 158 .I sessionConst
 159 to the desired salting constant.
 160 The only supported session type is
 161 .BR ttls ,
 162 as used by 802.1x.
 163 .PP
 164 .I TlsServer
 165 executes the server side of the handshake.
 166 The caller must initialize
 167 .IB conn ->cert \fR,
 168 usually by calling
 169 .I readcert
 170 to read and decode the PEM-encoded certificate from
 171 .IR filename ,
 172 return a pointer to
 173 .IR malloc ed
 174 storage containing the certificate,
 175 and store its length through
 176 .IR pcertlen .
 177 The private key corresponding to
 178 .I cert.pem
 179 should have been previously loaded into factotum.
 180 (See
 181 .IR rsa (8)
 182 for more about key generation.)
 183 .PP
 184 .I Readcertchain
 185 will read a PEM-encoded chain of certificates from
 186 .I filename
 187 and return a pointer to a linked list of
 188 .IR malloc ed
 189 .B PEMChain
 190 structures, defined in
 191 .IR libsec.h :
 192 .IP
 193 .EX
 194 typedef struct PEMChain PEMChain;
 195 struct PEMChain {
 196         PEMChain*next;
 197         uchar *pem;
 198         int     pemlen;
 199 };
 200 .EE
 201 .LP
 202 By setting
 203 .IP
 204 .EX
 205 conn->chain = readcertchain("intermediate-certs.pem");
 206 .EE
 207 .LP
 208 the server can present extra certificate evidence
 209 to establish the chain of trust to a root authority
 210 known to the client.
 211 .PP
 212 .I Conn
 213 is not required for the ongoing conversation and may
 214 be freed by the application whenever convenient.
 215 .SH EXAMPLES
 216 Start the client half of TLS and check the remote certificate:
 217 .IP
 218 .EX
 219 conn = (TLSconn*)mallocz(sizeof *conn, 1);
 220 fd = tlsClient(fd, conn);
 221 if(!okCertificate(conn->cert, conn->certlen, table))
 222         sysfatal("suspect server: %r");
 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 .