Import sources from 2011-03-30 iso image - sys/man

1 files changed, 273 insertions, 0 deletions

diff --git a/sys/man/3/tls b/sys/man/3/tls
new file mode 100755
index 000000000..99f470d90
--- /dev/null
+++ b/sys/man/3/tls
@@ -0,0 +1,273 @@
+.TH TLS 3 
+.SH NAME
+tls \- TLS1 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 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
+.B 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.
+.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 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.
+.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 are
+.B 'rc4_128'
+and
+.BR '3des_ede_cbc' .
+Currently implemented hashing algorithms are
+.B 'md5'
+and
+.BR 'sha1' .
+.SH "SEE ALSO"
+.IR listen (8),
+.IR dial (2),
+.IR pushtls (2)
+.SH SOURCE
+.B /sys/src/9/port/devtls.c