d4a830e2e1
usefull for debugging, like: ./8.tlsclient -d /fd/3 tcp!code.9front.org!https |[0=3] auth/asn1dump
232 lines
3.8 KiB
Text
232 lines
3.8 KiB
Text
.TH TLSSRV 8
|
|
.SH NAME
|
|
tlssrv, tlsclient, tlssrvtunnel, tlsclienttunnel \- TLS server and client
|
|
.SH SYNOPSIS
|
|
.PP
|
|
.B tlssrv
|
|
[
|
|
.B -D
|
|
]
|
|
[
|
|
.BR - [ aA ]
|
|
[
|
|
.B -k
|
|
.I keyspec
|
|
]
|
|
]
|
|
[
|
|
.B -c
|
|
.I cert.pem
|
|
]
|
|
[
|
|
.B -l
|
|
.I
|
|
logfile
|
|
]
|
|
[
|
|
.B -r
|
|
.I remotesys
|
|
]
|
|
.I cmd
|
|
[
|
|
.I args ...
|
|
]
|
|
.PP
|
|
.B tlsclient
|
|
[
|
|
.B -D
|
|
]
|
|
[
|
|
.B -a
|
|
[
|
|
.B -k
|
|
.I keyspec
|
|
]
|
|
]
|
|
[
|
|
.B -c
|
|
.I clientcert.pem
|
|
]
|
|
[
|
|
.B -d
|
|
.I servercert
|
|
]
|
|
[
|
|
.B -t
|
|
.I trustedkeys
|
|
]
|
|
[
|
|
.B -x
|
|
.I excludedkeys
|
|
]
|
|
[
|
|
.B -n
|
|
.I servername
|
|
]
|
|
[
|
|
.B -o
|
|
]
|
|
.I address
|
|
[
|
|
.I cmd
|
|
[
|
|
.I args ...
|
|
]
|
|
]
|
|
.PP
|
|
.B tlssrvtunnel
|
|
.I plain-addr
|
|
.I crypt-addr
|
|
.I cert.pem
|
|
.PP
|
|
.B tlsclienttunnel
|
|
.I crypt-addr
|
|
.I plain-addr
|
|
.I trustedkeys
|
|
.SH DESCRIPTION
|
|
.I Tlssrv
|
|
is a helper program, typically exec'd in a
|
|
.B /bin/service
|
|
file to establish an SSL or TLS connection before launching
|
|
.I cmd
|
|
.IR args ;
|
|
a typical command might start the IMAP or HTTP server.
|
|
.I Cert.pem
|
|
is the server certificate;
|
|
.IR factotum (4)
|
|
should hold the corresponding private key.
|
|
The specified
|
|
.I logfile
|
|
is by convention the same as for the target server.
|
|
.I Remotesys
|
|
is mainly used for logging.
|
|
If the
|
|
.B -a
|
|
or
|
|
.B -A
|
|
flag is specified,
|
|
.B p9any
|
|
authentication is run before the TLS handshake and the resulting
|
|
plan9 session secret is used as a pre-shared key for TLS encryption.
|
|
This enables the use of TLS without certificates and also runs
|
|
the server command as the authorized user when the
|
|
.B -a
|
|
flag was specified.
|
|
.PP
|
|
.I Tlsclient
|
|
is the reverse of
|
|
.IR tlssrv :
|
|
it connects to
|
|
.IR address ,
|
|
starts TLS,
|
|
and then relays
|
|
between the network connection
|
|
and standard input and output or executes
|
|
.I cmd args
|
|
with standard input and output redirected to the connection.
|
|
The
|
|
.B -D
|
|
flag enables some debug output.
|
|
Specifying a certificate in pem(8) format with the
|
|
.B -c
|
|
flag, causes the client to submit this certificate upon
|
|
server's request. A corresponding key has to be present in
|
|
.IR factotum (4).
|
|
The
|
|
.B -d
|
|
flag writes the server's certificate to the file
|
|
.I servercert
|
|
in binary ASN.1 encoding.
|
|
If the server doesnt provide a certificate, an empty
|
|
file is created.
|
|
If the
|
|
.B -t
|
|
flag
|
|
(and, optionally, the
|
|
.B -x
|
|
flag)
|
|
is given, the remote server must present a public key
|
|
whose SHA1 or SHA256 hash is listed in the file
|
|
.I trustedkeys
|
|
but not in the file
|
|
.IR excludedkeys .
|
|
See
|
|
.IR thumbprint (6)
|
|
for more information. The
|
|
.B -n
|
|
option passes the string
|
|
.I servername
|
|
in the TLS hello message (Server Name Idenfitication)
|
|
which is usefull when talking to webservers.
|
|
When the
|
|
.B -o
|
|
option was specified,
|
|
.I address
|
|
is interpreted as a filename to be opend read-write instead of
|
|
a dial string.
|
|
.PP
|
|
.I Tlssrvtunnel
|
|
and
|
|
.I tlsclienttunnel
|
|
use these tools and
|
|
.I listen1
|
|
(see
|
|
.IR listen (8))
|
|
to provide TLS network tunnels, allowing legacy
|
|
application to take advantage of TLS encryption.
|
|
.SH EXAMPLES
|
|
Listen for TLS-encrypted IMAP by creating a server certificate
|
|
.B /sys/lib/tls/imap.pem
|
|
and a listener script
|
|
.B /bin/service.auth/tcp993
|
|
containing:
|
|
.IP
|
|
.EX
|
|
#!/bin/rc
|
|
exec tlssrv -c/sys/lib/tls/imap.pem -limap4d -r`{cat $3/remote} \e
|
|
/bin/ip/imap4d -p -dyourdomain -r`{cat $3/remote} \e
|
|
>[2]/sys/log/imap4d
|
|
.EE
|
|
.PP
|
|
Interact with the server, putting the appropriate hash into
|
|
.B /sys/lib/tls/mail
|
|
and running:
|
|
.IP
|
|
.EX
|
|
tlsclient -t /sys/lib/tls/mail tcp!server!imaps
|
|
.EE
|
|
.PP
|
|
Create a TLS-encrypted VNC connection from a client on
|
|
.B kremvax
|
|
to a server on
|
|
.BR moscvax :
|
|
.IP
|
|
.EX
|
|
mosc% vncs -d :3
|
|
mosc% tlssrvtunnel tcp!moscvax!5903 tcp!*!12345 \e
|
|
/usr/you/lib/cert.pem
|
|
krem% tlsclienttunnel tcp!moscvax!12345 tcp!*!5905 \e
|
|
/usr/you/lib/cert.thumb
|
|
krem% vncv kremvax:5
|
|
.EE
|
|
.LP
|
|
(The port numbers passed to the VNC tools are offset by 5900 from the
|
|
actual TCP port numbers.)
|
|
.SH FILES
|
|
.TP
|
|
.B /sys/lib/tls
|
|
.SH SOURCE
|
|
.B /sys/src/cmd/tlssrv.c
|
|
.br
|
|
.B /sys/src/cmd/tlsclient.c
|
|
.br
|
|
.B /rc/bin/tlssrvtunnel
|
|
.br
|
|
.B /rc/bin/tlsclienttunnel
|
|
.SH "SEE ALSO"
|
|
.IR factotum (4),
|
|
.IR listen (8),
|
|
.IR rsa (8)
|
|
.br
|
|
Unix's
|
|
.I stunnel
|