plan9fox/sys/man/3/tls

.TH TLS 3 
.SH NAME
tls \- TLS and SSL3 record layer
.SH SYNOPSIS
.nf
.B bind -a #a /net

.B /net/tls/clone
.B /net/tls/encalgs
.B /net/tls/hashalgs
.BI /net/tls/ n 
.BI /net/tls/ n /ctl
.BI /net/tls/ n /data
.BI /net/tls/ n /hand
.BI /net/tls/ n /stats
.BI /net/tls/ n /status
.fi
.SH 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 protocols, which are responsible for
mutual authentication and key exchange.
The
.I tls
device can be thought of as filters providing optional encryption and anti-tampering.
.PP
The top level directory contains a
.B clone
file and subdirectories numbered from zero through at least the last active filter.
Opening the
.B clone
file reserves a filter.
The file descriptor returned from the
.IR open (2)
will point to the control file,
.BR ctl ,
of the newly allocated filter.
Reading the
.B ctl
file returns a text string containing the number of the filter directory.
.PP
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
.BR ctl .
.PP
The following commands are supported:
.TP
.BI fd \ open-fd\ vers
Pass record messages over the communications channel
.IR open-fd .
Initially, outgoing messages use version
.I vers
format records, but incoming messages of either version are accepted.
Valid versions are
.B 0x300
for SSLv3.0 and
.BR 0x301 ,
.B 0x302
and
.B 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 executed once.
.TP
.BI version \ vers
Use
.I vers
format records for all future records,
both outgoing and incoming.
This command may only be executed once.
.TP
.BI secret \ hashalg\ encalg\ isclient\ secretdata
Set up the digesting and encryption algorithms and secrets.
.I Hashalg
and
.I encalg
must be algorithm names returned by the corresponding files.
.I Secretdata
is the base-64 encoded (see
.IR 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 incoming and outgoing secrets are automatically selected by devtls based on the
.I isclient
argument, which must be non-zero for the client of the TLS handshake,
and zero for the server.
.br
This command must be issued after
.BR version ,
and may be issued more than once.
At least one new
.I secret
command must be issued before each
.I changecipher
command; similarly, at least one new
.I secret command
must precede each incoming changecipher message.
.TP
.BI changecipher
Enable outgoing encryption and digesting as configured by the previous
.I secret
command.
This command sends a
.I changecipher
message.
.TP
.BI 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
.I changecipher
command.
.TP
.BI alert \ alertno
Send an alert message.
.I 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.
.PP
Application messages and handshake messages are communicated using
.I data
and
.IR hand ,
respectively.
Only one
.IR open (2)
of
.I hand
is allowed at a time.
.PP
Any record layer headers and trailers are inserted and
stripped automatically, 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 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.
.PP
If a fatal alert message is received, or a fatal
.I alert
command issued, the filter is set into an error state.
All further correspondence is halted,
although some pending operations may not be terminated.
Operations on
.I data
will fail with a
.BR "'tls error'" ,
and operations on
.I hand
will fail with a textual decoding of the alert.
The current non-fatal alert messages are
.BR "'close notify'" ,
.BR "'no renegotiation'" ,
and
.BR "'handshake canceled by user'" .
Receipt of one of these alerts cause the next read on
.I hand
to terminate with an error.
If the alert is
.BR "'close notify'",
all future reads will terminate with a
.B "tls hungup"
error.
A
.B "'close notify'"
.I alert
command will terminate all future writes or reads from
.I data
with a
.B "'tls hungup'"
error.
.PP
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
.BR "'interrupted'" ,
the filter is set into the error state.
In this case, all future operations on
.I hand
will fail with a
.BR "'channel error'" .
.PP
When all file descriptors for a filter have been closed,
the session is terminated and the filter reclaimed for future use.
A
.B "'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.
.PP
Reading
.I stats
or
.I status
returns information about the filter.
Each datum is returned on a single line of the form
.IB tag ": " data .
.I Stats
returns the number of bytes communicated by the
.B data
and
.B hand
channels.
The four lines returned are tagged by, in order,
.BR DataIn ,
.BR DataOut ,
.BR HandIn ,
and
.BR HandOut .
.I Status
returns lines following tags:
.BR State ,
.BR Version ,
.BR EncIn ,
.BR HashIn ,
.BR NewEncIn ,
.BR NewHashIn ,
.BR EncOut ,
.BR HashOut ,
.BR NewEncOut ,
and
.BR NewHashOut .
.BR State 's
value is a string describing the status of the connection,
and is one of the following:
.BR 'Handshaking' ,
.BR 'Established' ,
.BR 'RemoteClosed' ,
.BR 'LocalClosed' ,
.BR 'Alerting' ,
.BR 'Errored' ,
or
.BR 'Closed' .
.BR Version 's
give the hexadecimal record layer version in use.
The
.B Enc
and
.B Hash
fields return name of the current algorithms in use
or ready to be used, if any.
.PP
Reading
.I encalgs
and 
.I hashalgs
will give the space-separated list of algorithms implemented.
This will always include
.BR clear ,
meaning no encryption or digesting.
Currently implemented encryption algorithms for use with TLSv1.0 and TLSv1.1 are:
.BR rc4_128 ,
.BR 3des_ede_cbc ,
.B aes_128_cbc
and
.BR aes_256_cbc .
For TLSv1.2, which adds support for authenticated encryption with
associated data (AEAD), the following ciphers are supported:
.BR ccpoly64_aead ,
.BR ccpoly96_aead ,
.B aes_128_gcm_aead
and
.BR aes_256_gcm_aead .
Currently implemented hashing algorithms are:
.BR md5 ,
.B sha1
and
.BR sha256 .
For an AEAD cipher, the hashing algorithm should be set to
.BR clear .
.SH "SEE ALSO"
.IR listen (8),
.IR dial (2),
.IR pushtls (2)
.SH SOURCE
.B /sys/src/9/port/devtls.c