288 lines
7.3 KiB
Text
288 lines
7.3 KiB
Text
.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
|