pushtls 4.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180
  1. .TH PUSHTLS 2
  2. .SH NAME
  3. pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert \- 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. Thumbprint* initThumbprints(char *ok, char *crl)
  30. .PP
  31. .B
  32. void freeThumbprints(Thumbprint *table)
  33. .PP
  34. .B
  35. int okThumbprint(uchar *hash, Thumbprint *table)
  36. .SH DESCRIPTION
  37. Transport Layer Security (TLS) comprises a record layer protocol,
  38. doing message digesting and encrypting in the kernel,
  39. and a handshake protocol,
  40. doing initial authentication and secret creation at
  41. user level and then starting a data channel in the record protocol.
  42. TLS is nearly the same as SSL 3.0, and the software should interoperate
  43. with implementations of either standard.
  44. .PP
  45. To use just the record layer, as described in
  46. .IR tls (3),
  47. call
  48. .I pushtls
  49. to open the record layer device, connect to the communications channel
  50. .IR fd ,
  51. and start up encryption and message authentication as specified
  52. in
  53. .IR hashalg ,
  54. .IR encalg ,
  55. and
  56. .IR secret .
  57. These parameters must have been arranged at the two ends of the
  58. conversation by other means.
  59. For example,
  60. .I hashalg
  61. could be
  62. .BR sha1 ,
  63. .I encalg
  64. could be
  65. .BR rc4_128 ,
  66. and
  67. .I secret
  68. could be the base-64 encoding of two (client-to-server and server-to-client)
  69. 20-byte digest keys and two corresponding 16-byte encryption keys.
  70. .I Pushtls
  71. returns a file descriptor for the TLS data channel. Anything written to this
  72. descriptor will get encrypted and authenticated and then written to the
  73. file descriptor,
  74. .IR fd .
  75. If
  76. .I dir
  77. is non-zero, the path name of the connection directory is copied into
  78. .IR dir .
  79. This path name is guaranteed to be less than 40 bytes long.
  80. .PP
  81. Alternatively, call
  82. .I tlsClient
  83. to speak the full handshake protocol,
  84. negotiate the algorithms and secrets,
  85. and return a new data file descriptor for the data channel.
  86. .I Conn
  87. points to a (caller-allocated) struct
  88. .EX
  89. typedef struct TLSconn{
  90. char dir[40]; // OUT connection directory
  91. uchar *cert; // IN/OUT certificate
  92. uchar *sessionID; // IN/OUT sessionID
  93. int certlen, sessionIDlen;
  94. void (*trace)(char*fmt, ...);
  95. } TLSconn;
  96. .EE
  97. defined in
  98. .IR tls.h .
  99. On input, the caller can provide options such as
  100. .IR cert ,
  101. the local certificate, and
  102. .IR sessionID ,
  103. used by a client to resume a previously negotiated security association.
  104. On output, the connection directory is set, as with
  105. .B listen
  106. (see
  107. .IR dial (2)).
  108. The input
  109. .I cert
  110. is freed and a freshly allocated copy of the remote's certificate
  111. is returned in
  112. .IR conn ,
  113. to be checked by the caller
  114. according to its needs. One mechanism is supplied by
  115. .I initThumbprints
  116. and
  117. .I freeThumbprints
  118. which allocate and free, respectively, a table of hashes
  119. from files of known trusted and revoked certificates.
  120. .I okThumbprint
  121. confirms that a particular hash is in the table, as computed by
  122. .PP
  123. .EX
  124. uchar hash[SHA1dlen];
  125. conn = (TLSconn*)mallocz(sizeof *conn, 1);
  126. fd = tlsClient(fd, conn);
  127. sha1(conn->cert, conn->certlen, hash, nil);
  128. if(!okThumbprint(hash,table))
  129. exits("suspect server");
  130. ...application begins...
  131. .EE
  132. .PP
  133. Call
  134. .I tlsServer
  135. to perform the corresponding function on the server side:
  136. .PP
  137. .EX
  138. fd = accept(lcfd, ldir);
  139. conn = (TLSconn*)mallocz(sizeof *conn, 1);
  140. conn->cert = readcert("cert.pem", &conn->certlen);
  141. fd = tlsServer(fd, conn);
  142. ...application begins...
  143. .EE
  144. The private key corresponding to
  145. .I cert.pem
  146. should have been previously loaded into factotum.
  147. (See
  148. .IR rsa (8)
  149. for more about key generation.)
  150. .PP
  151. .I Conn
  152. is not required for the ongoing conversation and may
  153. be freed by the application whenever convenient.
  154. .SH FILES
  155. .TP
  156. .B /sys/lib/tls
  157. thumbprints of trusted services
  158. .TP
  159. .B /sys/lib/ssl
  160. PEM certificate files
  161. .SH SOURCE
  162. .B /sys/src/libc/9sys/pushtls.c
  163. .br
  164. .B /sys/src/libsec/port
  165. .SH "SEE ALSO"
  166. .IR dial (2),
  167. .IR tls (3),
  168. .IR factotum (4),
  169. .IR thumbprint (6)
  170. .SH DIAGNOSTICS
  171. return \-1 on failure.
  172. .SH BUGS
  173. .PP
  174. Client certificates and client sessionIDs are not yet
  175. implemented.
  176. .PP
  177. Note that in the TLS protocol
  178. .I sessionID
  179. itself is public; it is used as a pointer to
  180. secrets stored in factotum.