keys/tripe-keys.master: Include a nontrivial `sig-fresh' example.

[tripe] / server / tripe.8.in

.\" -*-nroff-*-
.\".
.\" Manual for the server
.\"
.\" (c) 2008 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of Trivial IP Encryption (TrIPE).
.\"
.\" TrIPE is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" TrIPE is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with TrIPE; if not, write to the Free Software Foundation,
.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
.
.\"--------------------------------------------------------------------------
.so ../common/defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH tripe 8tripe "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.
.\"--------------------------------------------------------------------------
.SH "NAME"
.
tripe \- a simple VPN daemon
.
.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
.
.B tripe
.RB [ \-DF ]
.RB [ \-d
.IR dir ]
.RB [ \-b
.IR addr ]
.RB [ \-p
.IR port ]
.RB [ \-n
.IR tunnel ]
.br
	\c
.RB [ \-U
.IR user ]
.RB [ \-G
.IR group ]
.RB [ \-a
.IR socket ]
.RB [ \-m
.IR mode ]
.RB [ \-T
.IR trace-opts ]
.br
	\c
.RB [ \-k
.IR priv-keyring ]
.RB [ \-K
.IR pub-keyring ]
.RB [ \-t
.IR key-tag ]
.
.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
.
The
.B tripe
program is a server which can provide strong IP-level encryption and
authentication between co-operating hosts.  The program and its protocol
are deliberately very simple, to make analysing them easy and to help
build trust rapidly in the system.
.SS "Overview"
The
.B tripe
server manages a number of secure connections to other `peer' hosts.
Each daemon is given a private key of its own, and a file of public keys
for the peers with which it is meant to communicate.  It is responsible
for negotiating sets of symmetric keys with its peers, and for
encrypting, encapsulating and sending IP packets to its peers, and
decrypting, checking and de-encapsulating packets it receives from
them.
.PP
When the server starts, it creates a Unix-domain socket on which it
listens for administration commands.  It also logs warnings and
diagnostic information to the programs connected to its admin socket.
Clients connected to the socket can add new peers, and remove or find
out about existing peers.  The textual protocol used to give the
.B tripe
server admin commands is described in
.BR tripe\-admin (5).
A client program
.BR tripectl (1)
is provided to allow commands to be sent to the server either
interactively or by simple scripts.
.SS "Command-line arguments"
If not given any command-line arguments,
.B tripe
will initialize by following these steps:
.hP 1.
It sets the directory named by the
.B TRIPEDIR
environment variable (or
.B "\*(/c"
if the variable is unset) as the current directory.
.hP 2.
It acquires a UDP socket with an arbitrary kernel-selected port number.
It will use this socket to send and receive all communications with its
peer servers.  The port chosen may be discovered by means of the
.B PORT
admin command (see
.BR tripe\-admin (5)).
.hP 3.
It loads the private key with the tag or type name
.B tripe
(or, failing that,
.B tripe\-dh
for backwards compatibility reasons) from the Catacomb-format file
.BR keyring ,
and loads the file
.B keyring.pub
ready for extracting the public keys of peers as they're introduced.
(The format of these files is described in
.BR keyring (5).
They are maintained using the program
.BR key (1)
provided with the Catacomb distribution.)
.hP 4.
It creates and listens to the Unix-domain socket
.BR tripesock .
.PP
Following this, the server enters its main loop, accepting admin
connections and obeying any administrative commands, and communicating
with peers.  It also treats its standard input and standard output
streams as an admin connection, reading commands from standard input and
writing responses and diagnostics messages to standard output.  Finally,
it will reload keys from its keyring files if it notices that they've
changed (it checks inode number and modification time) \- there's no
need to send a signal.
.PP
Much of this behaviour may be altered by giving
.B tripe
suitable command-line options:
.TP
.B "\-h, \-\-help"
Writes a brief description of the command-line options available to
standard output and exits with status 0.
.TP
.B "\-v, \-\-version"
Writes
.BR tripe 's
version number to standard output and exits with status 0.
.TP
.B "\-u, \-\-usage"
Writes a brief usage summary to standard output and exits with status 0.
.TP
.B "\-\-tunnels"
Writes to standard output a list of the configured tunnel drivers, one
per line, and exits with status 0.  This is intended for the use of the
start-up script, so that it can check that it will actually work.
.TP
.B "\-D, \-\-daemon"
Dissociates from its terminal and starts running in the background after
completing the initialization procedure described above.  If running as
a daemon,
.B tripe
will not read commands from standard input or write diagnostics to
standard output.  A better way to start
.B tripe
in the background is with
.BR tripectl (1).
.TP
.B "\-F, \-\-foreground"
Runs the server in the `foreground'; i.e.,
.B tripe
will quit if it sees end-of-file on its standard input.  This is
incompatible with
.BR \-D .
.TP
.BI "\-d, \-\-directory=" dir
Makes
.I dir
the current directory.  The default directory to change to is given by
the environment variable
.BR TRIPEDIR ;
if that's not specified, a default default of
.B "\*(/c"
is used.  Give a current directory of
.B .
if you don't want it to change directory at all.
.TP
.BI "\-b, \-\-bind-address="addr
Bind the UDP socket to IP address
.I addr
rather than the default of
.BR INADDR_ANY .
This is useful if your main globally-routable IP address is one you want
to tunnel through the VPN.
.TP
.BI "\-p, \-\-port=" port
Use the specified UDP port for all communications with peers, rather
than an arbitarary kernel-assigned port.
.TP
.BI "\-n, \-\-tunnel=" tunnel
Use the specified tunnel driver for new peers by default.
.TP
.BI "\-U, \-\-setuid=" user
Set uid to that of
.I user
(either a user name or integer uid) after initialization.  Also set gid
to
.IR user 's
primary group, unless overridden by a
.B \-G
option.  The selected user (and group) will also be the owner of the
administration socket.
.TP
.BI "\-G, \-\-setgid=" group
If the current effective uid is zero (i.e., the daemon was invoked as
.BR root )
then set gid to that of
.I group
(either a group name or integer gid) after initialization.  In any
event, arrange hat the administration socket be owned by the given
.IR group .
.TP
.BI "\-k, \-\-priv\-keyring=" file
Reads the private key from
.I file
rather than the default
.BR keyring .
.TP
.BI "\-K, \-\-pub\-keyring=" file
Reads public keys from
.I file
rather than the default
.BR keyring.pub .
This can be the same as the private keyring, but that's not recommended.
.TP
.BI "\-t, \-\-tag=" tag
Uses the private key whose tag or type is
.I tag
rather than the default
.B tripe
or
.BR tripe\-dh .
.TP
.BI "\-a, \-\-admin\-socket=" socket
Accept admin connections to a Unix-domain socket named
.IR socket .
The default socket, if this option isn't specified, is given by the
environment variable
.BR TRIPESOCK ;
if that's not set either, then a default default of
.B "\*(/s/tripesock"
is used instead.
.TP
.BI "\-m, \-\-admin\-perms=" mode
Permissions (as an octal number) to set on the administration socket.  The
default is 600, which allows only the socket owner.  Setting 660 allows
members of the
.I group
configured through the
.B \-G
option to connect to the socket, which may be useful.  Allowing world access
is a terrible idea.
.TP
.BI "\-T, \-\-trace=" trace-opts
Allows the enabling or disabling of various internal diagnostics.  See
below for the list of options.
.SS "Key exchange group types"
The
.B tripe
server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys
used for bulk data transfer.
.PP
The server works out which it should be doing based on the key's
.B kx-group
attribute.
If this attribute isn't present, then the key's type is examined: if
it's of the form
.BI tripe\- group
then the
.I group
is used.  If no group is specified,
.B dh
is used as a fallback.
The following groups are defined.
.TP
.B dh
.RS
Use traditional Diffie\(enHellman in a
.IR "Schnorr group" :
a prime-order subgroup of the multiplicative group of
a finite field; this is the usual
.I g\*(ssx\*(se
mod
.I p
kind of Diffie\(en\&Hellman.
.PP
To create usual Schnorr-group keys, say something like
.VS
key add \-adh-param \-LS \-b3072 \-B256 \e
	\-eforever \-tparam tripe\-param kx-group=dh
.VE
to construct a parameters key; and create the private keys by
.VS
key add \-adh \-pparam \-talice \e
	\-e"now + 1 year" tripe
.VE
.RE
.sv -1
.TP
.B ec
.RS
Use elliptic curve Diffie\(enHellman.
An elliptic curve group is a prime-order
subgroup of the abelian group of
.BR K -rational
points on an elliptic curve defined over a finite field
.BR K .
.PP
Given current public knowledge, elliptic curves can provide similar or
better security to systems based on integer discrete log problems,
faster, and with less transmitted data.  It's a matter of controversy
whether this will continue to be the case.  The author uses elliptic
curves.
.PP
To create elliptic curve keys, say something like
.VS
key add \-aec\-param \-Cnist-p256 \-eforever \e
	\-tparam tripe\-param kx-group=ec
.VE
to construct a parameters key, using your preferred elliptic curve in
the
.B \-C
option (see
.BR key (1)
for details); and create the private keys by
.VS
key add \-aec \-pparam \-talice \e
	\-e"now + 1 year" tripe
.VE
.RE
.sv -1
.TP
.B x25519
.RS
Use Bernstein's X25519 Diffie\(enHellman function.
This is technically a variant on
the general elliptic curve Diffie\(enHellman
available through the
.B ec
setting,
but carefully designed and heavily optimized.
.PP
To create
.B x25519
keys,
say something like
.VS
key add \-aempty \-eforever \e
	\-tparam tripe\-param kx-group=x25519
.VE
to construct a parameters key
(see
.BR key (1)
for details);
and create the private keys by
.VS
key add \-ax25519 \-pparam \-talice \e
	\-e"now + 1 year" tripe
.VE
.RE
.sv -1
.TP
.B x448
.RS
Use Hamburg's X448 Diffie\(enHellman function.
Like
.B x25519
above,
this is technically a variant on
the general elliptic curve Diffie\(enHellman
available through the
.B ec
setting,
but carefully designed and heavily optimized.
.PP
To create
.B x448
keys,
say something like
.VS
key add \-aempty \-eforever \e
	\-tparam tripe\-param kx-group=x448
.VE
to construct a parameters key
(see
.BR key (1)
for details);
and create the private keys by
.VS
key add \-ax448 \-pparam \-talice \e
	\-e"now + 1 year" tripe
.VE
.RE
Note that the
.BR tripe-keys (8)
program provides a rather more convenient means for generating and
managing keys for
.BR tripe .
.SS "Using other symmetric algorithms"
The default symmetric algorithms
.B tripe
uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
(by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
mode, designed by Bellare, Canetti and Krawczyk).  These can all be
overridden by setting attributes on your private key, as follows.
.TP
.B bulk
Names the bulk-crypto transform to use.  See below.
.TP
.B blkc
Names a block cipher, used by some bulk-crypto transforms (e.g.,
.BR iiv ).
The default is to use the block cipher underlying the chosen
.BR cipher ,
if any.
.TP
.B cipher
Names the symmetric encryption scheme to use.  The default is
.BR blowfish\-cbc .
.TP
.B hash
Names the hash function to use.  The default is
.BR rmd160 .
.TP
.B mac
Names the message authentication code to use.  The name of the MAC may
be followed by a
.RB ` / '
and the desired tag length in bits.  The default is
.IB hash \-hmac
at half the underlying hash function's output length.
If the MAC's name contains a
.RB ` / '
character,
e.g.,
.RB ` sha512/256 ',
then an
.I additional
.RB ` / '
and the tag size is required to disambiguate,
so, e.g.,
one might write
.RB ` sha512/256/256 '.
.TP
.B mgf
A `mask-generation function', used in the key-exchange.  The default is
.IB hash \-mgf
and there's no good reason to change it.
.PP
The available bulk-crypto transforms are as follows.
.TP
.B v0
Originally this was the only transform available.  It's a standard
generic composition of a CPA-secure symmetric encryption scheme with a
MAC; initialization vectors for symmetric encryption are chosen at
random and included explicitly in the cryptogram.
.TP
.B iiv
A newer `implicit-IV' transform.  Rather than having an explicit random
IV, the IV is computed from the sequence number using a block cipher.
This has two advantages over the
.B v0
transform.  Firstly, it adds less overhead to encrypted messages
(because the IV no longer needs to be sent explicitly).  Secondly, and
more significantly, the transform is entirely deterministic, so (a) it
doesn't need the (possibly slow) random number generator, and (b) it
closes a kleptographic channel, over which a compromised implementation
could leak secret information to a third party.
.TP
.B naclbox
A transform based on the NaCl
.B crypto_secretbox
transformation.
The main difference is that NaCl uses XSalsa20,
while TrIPE uses plain Salsa20 or ChaCha,
because it doesn't need the larger nonce space.
You can set the
.B cipher
key attribute to one of
.BR salsa20 ,
.BR salsa20/12 ,
.BR salsa20/8 ,
.BR chacha20 ,
.BR chacha12 ,
or
.B chacha8
to select the main cipher.
You can set the
.B mac
key attribute to
.B poly1305
or
.B poly1305/128
but these are the default and no other choice is permitted.
(This is for forward compatibility,
in case other MACs and/or tag sizes are allowed later.)
.SS "Other key attributes"
The following attributes can also be set on keys.
.TP
.B serialization
Selects group-element serialization formats.
The recommended setting is
.BR constlen ,
which selects a constant-length encoding when hashing group elements.
The default,
for backwards compatibility, is
.BR v0 ;
but this is deprecated.
(The old format uses a variable length format for hashing,
which can leak information through timing.)
.SS "Using SLIP interfaces"
Though not for the faint of heart, it is possible to get
.B tripe
to read and write network packets to a pair of file descriptors using
SLIP encapsulation.  No fancy header compression of any kind is
supported.
.PP
Two usage modes are supported: a preallocation system, whereby SLIP
interfaces are created and passed to the
.B tripe
server at startup; and a dynamic system, where the server runs a script
to allocate a new SLIP interface when it needs one.  It is possible to
use a mixture of these two modes, starting
.B tripe
with a few preallocated interfaces and having it allocate more
dynamically as it needs them.
.PP
The behaviour of
.BR tripe 's
SLIP driver is controlled by the
.B TRIPE_SLIPIF
environment variable.  The server will not create SLIP tunnels if this
variable is not defined.  The variable's value is a colon-delimited list
of preallocated interfaces, followed optionally by the filename of a
script to run to dynamically allocate more interfaces.
.PP
A static allocation entry has the form
.IR infd [ \c
.BI , outfd \c
.RB ] \c
.BI = \c
.IR ifname ,
If the
.I outfd
is omitted, the same file descriptor is used for input and output.
.PP
The dynamic allocation script must be named by an absolute or relative
pathname, beginning with
.RB ` / '
or
.RB ` . '.
The server will pass the script an argument, which is the name of the
peer for which the interface is being created.  The script should
allocate a new SLIP interface (presumably by creating a pty pair),
configure it appropriately, and write the interface's name to its
standard output, followed by a newline.  It should then read and write
SLIP packets on its stdin and stdout.  The script's stdin will be closed
when the interface is no longer needed, and the server will attempt to
send it a
.B SIGTERM
signal (though this may fail if the script runs with higher privileges
than the server).
.PP
The output file descriptor should not block unless it really needs to:
the
.B tripe
daemon assumes that it won't, and will get wedged waiting for it to
accept output.
.SS "About the name"
The program's name is
.BR tripe ,
all in lower-case.  The name of the protocol it uses is `TrIPE', with
four capital letters and one lower-case.  The name stands for `Trivial
IP Encryption'.
.
.\"--------------------------------------------------------------------------
.SH "BUGS"
.
The code hasn't been audited.  It may contain security bugs.  If you
find one, please inform the author
.IR immediately .
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR key (1),
.BR tripectl (1),
.BR tripe\-admin (5),
.BR tripe\-keys (8).
.PP
.IR "The Trivial IP Encryption Protocol" ,
.IR "The Wrestlers Protocol" .
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------