term% cat index.txt TLS(3) Library Functions Manual TLS(3)
NAME
tls - TLS1 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 and Secure Sockets Layer version 3.0. It does not
implement the handshake protocols, which are responsible for mutual au‐
thentication 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 subdirectories num‐
bered 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 control file, ctl, of the newly allocated
filter. Reading the ctl file returns a text string containing the num‐
ber of the filter directory.
The filter initially cannot be used to pass messages and will not en‐
crypt 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 for TLSv1.0 (which
could be known as SSLv3.01.) This command must be issued before
any other command and before reading or writing any messages; it
may only be executed once.
version vers
Use vers format records for all future records, both outgoing
and incoming. This command may only be executed 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 cor‐
responding files. Secretdata is the base-64 encoded (see en‐
code(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 incoming and outgoing secrets are auto‐
matically 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; similarly, 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 mes‐
sage.
opened Enable data messages. This command may be issued any number of
times, although only the first is significant. 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 TLSv1.0, 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 auto‐
matically, and are not visible from the outside. 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 record as long as the buffer is big enough. Each write will
be converted into an integral number of records, with all but poten‐
tially the last being maximal size. The maximum record length sup‐
ported is 16384 bytes. This behavior is not specified in the proto‐
cols, and may not be followed by other implementations.
If a fatal alert message is received, or a fatal alert command issued,
the filter is set into an error state. All further correspondence is
halted, although some pending operations may not be terminated. Opera‐
tions 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 can‐
celed by user' (sic). Receipt of one of these alerts cause the next
read on hand to terminate with an error. If the alert is 'close no‐
tify', 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 com‐
munications 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 filter. Each da‐
tum 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 hexadecimal 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 al‐
gorithms implemented. This will always include clear, meaning no en‐
cryption or digesting. Currently implemented encryption algorithms are
'rc4_128', '3des_ede_cbc', 'aes_128_cbc' and 'aes_256_cbc'. Currently
implemented hashing algorithms are 'md5' and 'sha1'.
SEE ALSO
listen(8), dial(2), pushtls(2)
SOURCE
/sys/src/9/port/devtls.c
TLS(3)