pushtls 5.5 KB

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