TLS(3) TLS(3)
NAME
tls - TLS and SSL3 record layer
SYNOPSIS
bind -a #a /net
/net/tls/clone
/net/tls/encalgs
/net/tls/hashalgs
/net/tls/n
/net/tls/n/ctl
/net/tls/n/data
/net/tls/n/hand
/net/tls/n/stats
/net/tls/n/status
DESCRIPTION
The TLS device implements the record layer protocols of
Transport Layer Security version 1.0-1.2 and Secure Sockets
Layer version 3.0. It does not implement the handshake pro-
tocols, which are responsible for mutual authentication and
key exchange. The tls device can be thought of as filters
providing optional encryption and anti-tampering.
The top level directory contains a clone file and subdirec-
tories numbered from zero through at least the last active
filter. Opening the clone file reserves a filter. The file
descriptor returned from the open(2) will point to the con-
trol file, ctl, of the newly allocated filter. Reading the
ctl file returns a text string containing the number of the
filter directory.
The filter initially cannot be used to pass messages and
will not encrypt or digest messages. It is configured and
controlled by writing commands to ctl.
The following commands are supported:
fd open-fd vers
Pass record messages over the communications channel
open-fd. Initially, outgoing messages use version vers
format records, but incoming messages of either version
are accepted. Valid versions are 0x300 for SSLv3.0 and
0x301, 0x302 and 0x303 for TLSv1.0 (which could be
known as SSLv3.01), TLSv1.1 and TLSv1.2. This command
must be issued before any other command and before
reading or writing any messages; it may only be exe-
cuted once.
version vers
Page 1 Plan 9 (printed 11/21/24)
TLS(3) TLS(3)
Use vers format records for all future records, both
outgoing and incoming. This command may only be exe-
cuted once.
secret hashalg encalg isclient secretdata
Set up the digesting and encryption algorithms and
secrets. Hashalg and encalg must be algorithm names
returned by the corresponding files. Secretdata is the
base-64 encoded (see encode(2)) secret data used for
the algorithms. It must contain at least enough data
to populate the secrets for digesting and encrypting.
These secrets are divided into three categories: digest
secrets, keys, and initialization vectors. The secrets
are packed in this order, with no extra padding.
Within each category, the secret for data traveling
from the client to the server comes first. The incom-
ing and outgoing secrets are automatically selected by
devtls based on the isclient argument, which must be
non-zero for the client of the TLS handshake, and zero
for the server.
This command must be issued after version, and may be
issued more than once. At least one new secret command
must be issued before each changecipher command; simi-
larly, at least one new secret command must precede
each incoming changecipher message.
changecipher
Enable outgoing encryption and digesting as configured
by the previous secret command. This command sends a
changecipher message.
opened
Enable data messages. This command may be issued any
number of times, although only the first is signifi-
cant. It must follow at least one successful
changecipher command.
alert alertno
Send an alert message. Alertno may be a valid alert
code for either SSLv3.0 or TLS, and is mapped to an
appropriate code for the protocol in use. If it is a
fatal alert, the filter is set into an error state.
Application messages and handshake messages are communicated
using data and hand, respectively. Only one open(2) of hand
is allowed at a time.
Any record layer headers and trailers are inserted and
stripped automatically, and are not visible from the out-
side. The device tries to synchronize record boundaries
with reads and writes. Each read will return data from
exactly one record, and will return all of the data from the
Page 2 Plan 9 (printed 11/21/24)
TLS(3) TLS(3)
record as long as the buffer is big enough. Each write will
be converted into an integral number of records, with all
but potentially the last being maximal size. The maximum
record length supported is 16384 bytes. This behavior is
not specified in the protocols, and may not be followed by
other implementations.
If a fatal alert message is received, or a fatal alert com-
mand issued, the filter is set into an error state. All
further correspondence is halted, although some pending
operations may not be terminated. Operations on data will
fail with a 'tls error', and operations on hand will fail
with a textual decoding of the alert. The current non-fatal
alert messages are 'close notify', 'no renegotiation', and
'handshake canceled by user'. Receipt of one of these
alerts cause the next read on hand to terminate with an
error. If the alert is 'close notify', all future reads
will terminate with a tls hungup error. A 'close notify'
alert command will terminate all future writes or reads from
data with a 'tls hungup' error.
If an error is encountered while reading or writing the
underlying communications channel, the error is returned to
the offending operation. If the error is not 'interrupted',
the filter is set into the error state. In this case, all
future operations on hand will fail with a 'channel error'.
When all file descriptors for a filter have been closed, the
session is terminated and the filter reclaimed for future
use. A 'close notify' alert will be sent on the underlying
communications channel unless one has already been sent or
the filter is in the error state.
Reading stats or status returns information about the fil-
ter. Each datum is returned on a single line of the form
tag: data. Stats returns the number of bytes communicated
by the data and hand channels. The four lines returned are
tagged by, in order, DataIn, DataOut, HandIn, and HandOut.
Status returns lines following tags: State, Version, EncIn,
HashIn, NewEncIn, NewHashIn, EncOut, HashOut, NewEncOut, and
NewHashOut. State's value is a string describing the status
of the connection, and is one of the following:
'Handshaking', 'Established', 'RemoteClosed', 'LocalClosed',
'Alerting', 'Errored', or 'Closed'. Version's give the hex-
adecimal record layer version in use. The Enc and Hash
fields return name of the current algorithms in use or ready
to be used, if any.
Reading encalgs and hashalgs will give the space-separated
list of algorithms implemented. This will always include
clear, meaning no encryption or digesting. Currently imple-
mented encryption algorithms for use with TLSv1.0 and
Page 3 Plan 9 (printed 11/21/24)
TLS(3) TLS(3)
TLSv1.1 are: rc4_128, 3des_ede_cbc, aes_128_cbc and
aes_256_cbc. For TLSv1.2, which adds support for authenti-
cated encryption with associated data (AEAD), the following
ciphers are supported: ccpoly64_aead, ccpoly96_aead,
aes_128_gcm_aead and aes_256_gcm_aead. Currently imple-
mented hashing algorithms are: md5, sha1 and sha256. For an
AEAD cipher, the hashing algorithm should be set to clear.
SEE ALSO
listen(8), dial(2), pushtls(2)
SOURCE
/sys/src/9/port/devtls.c
Page 4 Plan 9 (printed 11/21/24)