pushtls.3 (4867B)
1 .TH PUSHTLS 3 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 .B 10 int pushtls(int fd, char *hashalg, char *encalg, 11 .br 12 .B 13 int isclient, char *secret, char *dir) 14 .PP 15 .B #include <mp.h> 16 .br 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 Plan 9's 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 .PP 84 Alternatively, call 85 .I tlsClient 86 to speak the full handshake protocol, 87 negotiate the algorithms and secrets, 88 and return a new data file descriptor for the data channel. 89 .I Conn 90 points to a (caller-allocated) struct 91 .EX 92 typedef struct TLSconn{ 93 char dir[40]; // OUT connection directory 94 uchar *cert; // IN/OUT certificate 95 uchar *sessionID; // IN/OUT sessionID 96 int certlen, sessionIDlen; 97 void (*trace)(char*fmt, ...); 98 PEMChain *chain; 99 } TLSconn; 100 .EE 101 defined in 102 .IR tls.h . 103 On input, the caller can provide options such as 104 .IR cert , 105 the local certificate, and 106 .IR sessionID , 107 used by a client to resume a previously negotiated security association. 108 On output, the connection directory is set, as with 109 .B listen 110 (see 111 .MR dial (3) ). 112 The input 113 .I cert 114 is freed and a freshly allocated copy of the remote's certificate 115 is returned in 116 .IR conn , 117 to be checked by the caller 118 according to its needs. One mechanism is supplied by 119 .I initThumbprints 120 and 121 .I freeThumbprints 122 which allocate and free, respectively, a table of hashes 123 from files of known trusted and revoked certificates. 124 .I okThumbprint 125 confirms that a particular hash is in the table, as computed by 126 .PP 127 .EX 128 uchar hash[SHA1dlen]; 129 conn = (TLSconn*)mallocz(sizeof *conn, 1); 130 fd = tlsClient(fd, conn); 131 sha1(conn->cert, conn->certlen, hash, nil); 132 if(!okThumbprint(hash,table)) 133 exits("suspect server"); 134 ...application begins... 135 .EE 136 .PP 137 Call 138 .I tlsServer 139 to perform the corresponding function on the server side: 140 .PP 141 .EX 142 fd = accept(lcfd, ldir); 143 conn = (TLSconn*)mallocz(sizeof *conn, 1); 144 conn->cert = readcert("cert.pem", &conn->certlen); 145 fd = tlsServer(fd, conn); 146 ...application begins... 147 .EE 148 The private key corresponding to 149 .I cert.pem 150 should have been previously loaded into factotum. 151 (See 152 .MR rsa (3) 153 .\" XXX should be rsa(8) 154 for more about key generation.) 155 By setting 156 .EX 157 conn->chain = readcertchain("intermediate-certs.pem"); 158 .EE 159 the server can present extra certificate evidence 160 to establish the chain of trust to a root authority 161 known to the client. 162 .PP 163 .I Conn 164 is not required for the ongoing conversation and may 165 be freed by the application whenever convenient. 166 .SH FILES 167 .TP 168 .B /sys/lib/tls 169 thumbprints of trusted services 170 .TP 171 .B /sys/lib/ssl 172 PEM certificate files 173 .SH SOURCE 174 .\" .B /sys/src/libc/9sys/pushtls.c 175 .\" .br 176 .B \*9/src/libsec/port 177 .SH "SEE ALSO" 178 .MR dial (3) , 179 .MR thumbprint (7) ; 180 Plan 9's 181 .IR factotum (4) 182 and 183 .IR tls (3) 184 .SH DIAGNOSTICS 185 return \-1 on failure. 186 .SH BUGS 187 .I Pushtls 188 is not implemented. 189 .PP 190 Client certificates and client sessionIDs are not yet 191 implemented. 192 .PP 193 Note that in the TLS protocol 194 .I sessionID 195 itself is public; it is used as a pointer to 196 secrets stored in factotum.