tls 6.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276
  1. .TH TLS 3
  2. .SH NAME
  3. tls \- TLS1 and SSL3 record layer
  4. .SH SYNOPSIS
  5. .nf
  6. .B bind -a #a /net
  7. .B /net/tls/clone
  8. .B /net/tls/encalgs
  9. .B /net/tls/hashalgs
  10. .BI /net/tls/ n
  11. .BI /net/tls/ n /ctl
  12. .BI /net/tls/ n /data
  13. .BI /net/tls/ n /hand
  14. .BI /net/tls/ n /stats
  15. .BI /net/tls/ n /status
  16. .fi
  17. .SH DESCRIPTION
  18. The TLS device implements the record layer protocols
  19. of Transport Layer Security version 1.0 and Secure Sockets Layer version 3.0.
  20. It does not implement the handshake protocols, which are responsible for
  21. mutual authentication and key exchange.
  22. The
  23. .I tls
  24. device can be thought of as filters providing optional encryption and anti-tampering.
  25. .PP
  26. The top level directory contains a
  27. .B clone
  28. file and subdirectories numbered from zero through at least the last active filter.
  29. Opening the
  30. .B clone
  31. file reserves a filter.
  32. The file descriptor returned from the
  33. .IR open (2)
  34. will point to the control file,
  35. .BR ctl ,
  36. of the newly allocated filter.
  37. Reading the
  38. .B ctl
  39. file returns a text string containing the number of the filter directory.
  40. .PP
  41. The filter initially cannot be used to pass messages
  42. and will not encrypt or digest messages.
  43. It is configured and controlled by writing commands to
  44. .BR ctl .
  45. .PP
  46. The following commands are supported:
  47. .TP
  48. .BI fd \ open-fd\ vers
  49. Pass record messages over the communications channel
  50. .IR open-fd .
  51. Initially, outgoing messages use version
  52. .I vers
  53. format records, but incoming messages of either version are accepted.
  54. Valid versions are
  55. .B 0x300
  56. for SSLv3.0 and
  57. .B 0x301
  58. for TLSv1.0 (which could be known as SSLv3.01.)
  59. This command must be issued before any other command
  60. and before reading or writing any messages;
  61. it may only be executed once.
  62. .TP
  63. .BI version \ vers
  64. Use
  65. .I vers
  66. format records for all future records,
  67. both outgoing and incoming.
  68. This command may only be executed once.
  69. .TP
  70. .BI secret \ hashalg\ encalg\ isclient\ secretdata
  71. Set up the digesting and encryption algorithms and secrets.
  72. .I Hashalg
  73. and
  74. .I encalg
  75. must be algorithm names returned by the corresponding files.
  76. .I Secretdata
  77. is the base-64 encoded (see
  78. .IR encode (2))
  79. secret data used for the algorithms.
  80. It must contain at least enough data to populate the
  81. secrets for digesting and encrypting.
  82. These secrets are divided into three categories: digest secrets, keys, and initialization vectors.
  83. The secrets are packed in this order, with no extra padding.
  84. Within each category, the secret for data traveling from the client to the server comes first.
  85. The incoming and outgoing secrets are automatically selected by devtls based on the
  86. .I isclient
  87. argument, which must be non-zero for the client of the TLS handshake,
  88. and zero for the server.
  89. .br
  90. This command must be issued after
  91. .BR version ,
  92. and may be issued more than once.
  93. At least one new
  94. .I secret
  95. command must be issued before each
  96. .I changecipher
  97. command; similarly, at least one new
  98. .I secret command
  99. must precede each incoming changecipher message.
  100. .TP
  101. .BI changecipher
  102. Enable outgoing encryption and digesting as configured by the previous
  103. .I secret
  104. command.
  105. This command sends a
  106. .I changecipher
  107. message.
  108. .TP
  109. .BI opened
  110. Enable data messages.
  111. This command may be issued any number of times,
  112. although only the first is significant.
  113. It must follow at least one successful
  114. .I changecipher
  115. command.
  116. .TP
  117. .BI alert \ alertno
  118. Send an alert message.
  119. .I Alertno
  120. may be a valid alert code for either SSLv3.0 or TLSv1.0,
  121. and is mapped to an appropriate code for the protocol in use.
  122. If it is a fatal alert, the filter is set into an error state.
  123. .PP
  124. Application messages and handshake messages are communicated using
  125. .I data
  126. and
  127. .IR hand ,
  128. respectively.
  129. Only one
  130. .IR open (2)
  131. of
  132. .I hand
  133. is allowed at a time.
  134. .PP
  135. Any record layer headers and trailers are inserted and
  136. stripped automatically, and are not visible from the outside.
  137. The device tries to synchronize record boundaries with reads and writes.
  138. Each read will return data from exactly one record,
  139. and will return all of the data from the record as long as
  140. the buffer is big enough.
  141. Each write will be converted into an integral number of records,
  142. with all but potentially the last being maximal size.
  143. The maximum record length supported is 16384 bytes.
  144. This behavior is not specified in the protocols,
  145. and may not be followed by other implementations.
  146. .PP
  147. If a fatal alert message is received, or a fatal
  148. .I alert
  149. command issued, the filter is set into an error state.
  150. All further correspondence is halted,
  151. although some pending operations may not be terminated.
  152. Operations on
  153. .I data
  154. will fail with a
  155. .BR "'tls error'" ,
  156. and operations on
  157. .I hand
  158. will fail with a textual decoding of the alert.
  159. The current non-fatal alert messages are
  160. .BR "'close notify'" ,
  161. .BR "'no renegotiation'" ,
  162. and
  163. .B "'handshake canceled by user'"
  164. (sic).
  165. Receipt of one of these alerts cause the next read on
  166. .I hand
  167. to terminate with an error.
  168. If the alert is
  169. .BR "'close notify'" ,
  170. all future reads will terminate with a
  171. .B "tls hungup"
  172. error.
  173. A
  174. .B "'close notify'"
  175. .I alert
  176. command will terminate all future writes or reads from
  177. .I data
  178. with a
  179. .B "'tls hungup'"
  180. error.
  181. .PP
  182. If an error is encountered while reading or writing
  183. the underlying communications channel, the error is returned
  184. to the offending operation.
  185. If the error is not
  186. .BR "'interrupted'" ,
  187. the filter is set into the error state.
  188. In this case, all future operations on
  189. .I hand
  190. will fail with a
  191. .BR "'channel error'" .
  192. .PP
  193. When all file descriptors for a filter have been closed,
  194. the session is terminated and the filter reclaimed for future use.
  195. A
  196. .B "'close notify'"
  197. alert will be sent on the underlying communications channel
  198. unless one has already been sent or the filter is in the error state.
  199. .PP
  200. Reading
  201. .I stats
  202. or
  203. .I status
  204. returns information about the filter.
  205. Each datum is returned on a single line of the form
  206. .IB tag ": " data .
  207. .I Stats
  208. returns the number of bytes communicated by the
  209. .B data
  210. and
  211. .B hand
  212. channels.
  213. The four lines returned are tagged by, in order,
  214. .BR DataIn ,
  215. .BR DataOut ,
  216. .BR HandIn ,
  217. and
  218. .BR HandOut .
  219. .I Status
  220. returns lines following tags:
  221. .BR State ,
  222. .BR Version ,
  223. .BR EncIn ,
  224. .BR HashIn ,
  225. .BR NewEncIn ,
  226. .BR NewHashIn ,
  227. .BR EncOut ,
  228. .BR HashOut ,
  229. .BR NewEncOut ,
  230. and
  231. .BR NewHashOut .
  232. .BR State 's
  233. value is a string describing the status of the connection,
  234. and is one of the following:
  235. .BR 'Handshaking' ,
  236. .BR 'Established' ,
  237. .BR 'RemoteClosed' ,
  238. .BR 'LocalClosed' ,
  239. .BR 'Alerting' ,
  240. .BR 'Errored' ,
  241. or
  242. .BR 'Closed' .
  243. .BR Version 's
  244. give the hexadecimal record layer version in use.
  245. The
  246. .B Enc
  247. and
  248. .B Hash
  249. fields return name of the current algorithms in use
  250. or ready to be used, if any.
  251. .PP
  252. Reading
  253. .I encalgs
  254. and
  255. .I hashalgs
  256. will give the space-separated list of algorithms implemented.
  257. This will always include
  258. .BR clear ,
  259. meaning no encryption or digesting.
  260. Currently implemented encryption algorithms are
  261. .BR 'rc4_128' ,
  262. .BR '3des_ede_cbc' ,
  263. .B 'aes_128_cbc'
  264. and
  265. .BR 'aes_256_cbc' .
  266. Currently implemented hashing algorithms are
  267. .B 'md5'
  268. and
  269. .BR 'sha1' .
  270. .SH "SEE ALSO"
  271. .IR listen (8),
  272. .IR dial (2),
  273. .IR pushtls (2)
  274. .SH SOURCE
  275. .B /sys/src/9/port/devtls.c