3 tls \- TLS and SSL3 record layer
15 .BI /net/tls/ n /stats
16 .BI /net/tls/ n /status
19 The TLS device implements the record layer protocols
20 of Transport Layer Security version 1.0-1.2 and Secure Sockets Layer version 3.0.
21 It does not implement the handshake protocols, which are responsible for
22 mutual authentication and key exchange.
25 device can be thought of as filters providing optional encryption and anti-tampering.
27 The top level directory contains a
29 file and subdirectories numbered from zero through at least the last active filter.
32 file reserves a filter.
33 The file descriptor returned from the
35 will point to the control file,
37 of the newly allocated filter.
40 file returns a text string containing the number of the filter directory.
42 The filter initially cannot be used to pass messages
43 and will not encrypt or digest messages.
44 It is configured and controlled by writing commands to
47 The following commands are supported:
49 .BI fd \ open-fd\ vers
50 Pass record messages over the communications channel
52 Initially, outgoing messages use version
54 format records, but incoming messages of either version are accepted.
62 for TLSv1.0 (which could be known as SSLv3.01), TLSv1.1 and TLSv1.2.
63 This command must be issued before any other command
64 and before reading or writing any messages;
65 it may only be executed once.
70 format records for all future records,
71 both outgoing and incoming.
72 This command may only be executed once.
74 .BI secret \ hashalg\ encalg\ isclient\ secretdata
75 Set up the digesting and encryption algorithms and secrets.
79 must be algorithm names returned by the corresponding files.
81 is the base-64 encoded (see
83 secret data used for the algorithms.
84 It must contain at least enough data to populate the
85 secrets for digesting and encrypting.
86 These secrets are divided into three categories: digest secrets, keys, and initialization vectors.
87 The secrets are packed in this order, with no extra padding.
88 Within each category, the secret for data traveling from the client to the server comes first.
89 The incoming and outgoing secrets are automatically selected by devtls based on the
91 argument, which must be non-zero for the client of the TLS handshake,
92 and zero for the server.
94 This command must be issued after
96 and may be issued more than once.
99 command must be issued before each
101 command; similarly, at least one new
103 must precede each incoming changecipher message.
106 Enable outgoing encryption and digesting as configured by the previous
114 Enable data messages.
115 This command may be issued any number of times,
116 although only the first is significant.
117 It must follow at least one successful
122 Send an alert message.
124 may be a valid alert code for either SSLv3.0 or TLS,
125 and is mapped to an appropriate code for the protocol in use.
126 If it is a fatal alert, the filter is set into an error state.
128 Application messages and handshake messages are communicated using
137 is allowed at a time.
139 Any record layer headers and trailers are inserted and
140 stripped automatically, and are not visible from the outside.
141 The device tries to synchronize record boundaries with reads and writes.
142 Each read will return data from exactly one record,
143 and will return all of the data from the record as long as
144 the buffer is big enough.
145 Each write will be converted into an integral number of records,
146 with all but potentially the last being maximal size.
147 The maximum record length supported is 16384 bytes.
148 This behavior is not specified in the protocols,
149 and may not be followed by other implementations.
151 If a fatal alert message is received, or a fatal
153 command issued, the filter is set into an error state.
154 All further correspondence is halted,
155 although some pending operations may not be terminated.
162 will fail with a textual decoding of the alert.
163 The current non-fatal alert messages are
164 .BR "'close notify'" ,
165 .BR "'no renegotiation'" ,
167 .BR "'handshake canceled by user'" .
168 Receipt of one of these alerts cause the next read on
170 to terminate with an error.
172 .BR "'close notify'",
173 all future reads will terminate with a
179 command will terminate all future writes or reads from
185 If an error is encountered while reading or writing
186 the underlying communications channel, the error is returned
187 to the offending operation.
189 .BR "'interrupted'" ,
190 the filter is set into the error state.
191 In this case, all future operations on
194 .BR "'channel error'" .
196 When all file descriptors for a filter have been closed,
197 the session is terminated and the filter reclaimed for future use.
200 alert will be sent on the underlying communications channel
201 unless one has already been sent or the filter is in the error state.
207 returns information about the filter.
208 Each datum is returned on a single line of the form
211 returns the number of bytes communicated by the
216 The four lines returned are tagged by, in order,
223 returns lines following tags:
236 value is a string describing the status of the connection,
237 and is one of the following:
247 give the hexadecimal record layer version in use.
252 fields return name of the current algorithms in use
253 or ready to be used, if any.
259 will give the space-separated list of algorithms implemented.
260 This will always include
262 meaning no encryption or digesting.
263 Currently implemented encryption algorithms for use with TLSv1.0 and TLSv1.1 are:
269 For TLSv1.2, which adds support for authenticated encryption with
270 associated data (AEAD), the following ciphers are supported:
275 .BR aes_256_gcm_aead .
276 Currently implemented hashing algorithms are:
281 For an AEAD cipher, the hashing algorithm should be set to
288 .B /sys/src/9/port/devtls.c