pushtls 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254
  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. conn = (TLSconn*)mallocz(sizeof *conn, 1);
  210. fd = tlsClient(fd, conn);
  211. sha1(conn->cert, conn->certlen, hash, nil);
  212. if(!okThumbprint(hash,table))
  213. exits("suspect server");
  214. \fI...application begins...\fP
  215. .EE
  216. .PP
  217. Run the server side:
  218. .IP
  219. .EX
  220. fd = accept(lcfd, ldir);
  221. conn = (TLSconn*)mallocz(sizeof *conn, 1);
  222. conn->cert = readcert("cert.pem", &conn->certlen);
  223. fd = tlsServer(fd, conn);
  224. \fI...application begins...\fP
  225. .EE
  226. .SH FILES
  227. .TF /sys/lib/tls
  228. .TP
  229. .B /sys/lib/tls
  230. thumbprints of trusted services
  231. .TP
  232. .B /sys/lib/ssl
  233. PEM certificate files
  234. .SH SOURCE
  235. .B /sys/src/libc/9sys/pushtls.c
  236. .br
  237. .B /sys/src/libsec/port
  238. .SH "SEE ALSO"
  239. .IR dial (2),
  240. .IR tls (3),
  241. .IR factotum (4),
  242. .IR thumbprint (6)
  243. .SH DIAGNOSTICS
  244. Return \-1 on failure.
  245. .SH BUGS
  246. Client certificates and client sessionIDs are not yet
  247. implemented.
  248. .PP
  249. Note that in the TLS protocol
  250. .I sessionID
  251. itself is public; it is used as a pointer to
  252. secrets stored in
  253. .IR factotum .