server/tests.at (AWAIT_KXDONE): Ignore the correct server messages.

[tripe] / server / tripe.8.in

diff --git a/server/tripe.8.in b/server/tripe.8.in
index 2135c4e002bf536a9abd675f41e4dc09e61b8a23..fd0209d728f82f861de8d1e43e760c5b2cae3131 100644 (file)
--- a/server/tripe.8.in
+++ b/server/tripe.8.in
@@ -24,10 +24,10 @@
 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 .
 .\"--------------------------------------------------------------------------
 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 .
 .\"--------------------------------------------------------------------------

-.so ../defs.man.in \" @@@PRE@@@
+.so ../common/defs.man \" @@@PRE@@@

 .
 .\"--------------------------------------------------------------------------
 .
 .\"--------------------------------------------------------------------------

-.TH tripe 8 "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
+.TH tripe 8tripe "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"

 .
 .\"--------------------------------------------------------------------------
 .SH "NAME"
 .
 .\"--------------------------------------------------------------------------
 .SH "NAME"


@@ -38,7 +38,7 @@ tripe \- a simple VPN daemon
 .SH "SYNOPSIS"
 .
 .B tripe
 .SH "SYNOPSIS"
 .
 .B tripe

-.RB [ \-D ]
+.RB [ \-DF ]

 .RB [ \-d
 .IR dir ]
 .RB [ \-b
 .RB [ \-d
 .IR dir ]
 .RB [ \-b


@@ -55,6 +55,8 @@ tripe \- a simple VPN daemon
 .IR group ]
 .RB [ \-a
 .IR socket ]
 .IR group ]
 .RB [ \-a
 .IR socket ]

+.RB [ \-m
+.IR mode ]

 .RB [ \-T
 .IR trace-opts ]
 .br
 .RB [ \-T
 .IR trace-opts ]
 .br


@@ -106,7 +108,7 @@ will initialize by following these steps:
 It sets the directory named by the
 .B TRIPEDIR
 environment variable (or
 It sets the directory named by the
 .B TRIPEDIR
 environment variable (or

-.B "*(/c"
+.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.
 if the variable is unset) as the current directory.
 .hP 2.
 It acquires a UDP socket with an arbitrary kernel-selected port number.


@@ -117,8 +119,10 @@ admin command (see
 .BR tripe\-admin (5)).
 .hP 3.
 It loads the private key with the tag or type name
 .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
 .B tripe\-dh

-from the Catacomb-format file
+for backwards compatibility reasons) from the Catacomb-format file

 .BR keyring ,
 and loads the file
 .B keyring.pub
 .BR keyring ,
 and loads the file
 .B keyring.pub


@@ -173,6 +177,13 @@ standard output.  A better way to start
 in the background is with
 .BR tripectl (1).
 .TP
 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
 .BI "\-d, \-\-directory=" dir
 Makes
 .I dir


@@ -180,7 +191,7 @@ 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
 the environment variable
 .BR TRIPEDIR ;
 if that's not specified, a default default of

-.B "*(/c"
+.B "\*(/c"

 is used.  Give a current directory of
 .B .
 if you don't want it to change directory at all.
 is used.  Give a current directory of
 .B .
 if you don't want it to change directory at all.


@@ -208,12 +219,17 @@ to
 .IR user 's
 primary group, unless overridden by a
 .B \-G
 .IR user 's
 primary group, unless overridden by a
 .B \-G

-option.
+option.  The selected user (and group) will also be the owner of the
+administration socket.

 .TP
 .BI "\-G, \-\-setgid=" group
 .TP
 .BI "\-G, \-\-setgid=" group

-Set gid to that of
+If the current effective uid is zero (i.e., the daemon was invoked as
+.BR root )
+then set gid to that of

 .I group
 .I group

-(either a group name or integer gid) after initialization.
+(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
 .TP
 .BI "\-k, \-\-priv\-keyring=" file
 Reads the private key from


@@ -232,6 +248,8 @@ This can be the same as the private keyring, but that's not recommended.
 Uses the private key whose tag or type is
 .I tag
 rather than the default
 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
 .BR tripe\-dh .
 .TP
 .BI "\-a, \-\-admin\-socket=" socket


@@ -241,195 +259,83 @@ 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
 environment variable
 .BR TRIPESOCK ;
 if that's not set either, then a default default of

-.B "*(/s/tripesock"
+.B "\*(/s/tripesock"

 is used instead.
 .TP
 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.
 .BI "\-T, \-\-trace=" trace-opts
 Allows the enabling or disabling of various internal diagnostics.  See
 below for the list of options.

-.SS "Setting up a VPN with tripe"
+.SS "Key exchange group types"

 The
 .B tripe
 The
 .B tripe

-server identifies peers by name.  While it's
-.I possible
-for each host to maintain its own naming system for its peers, this is
-likely to lead to confusion, and it's more sensible to organize a naming
-system that works everywhere.  How you manage this naming is up to you.
-The only restriction on the format of names is that they must be valid
-Catacomb key tags, since this is how
+server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys
+used for bulk data transfer.  Currently

 .B tripe
 .B tripe

-identifies which public key to use for a particular peer: they may not
-contain whitespace characters, or a colon
-.RB ` : '
-or dot
-.RB ` . ',
+can do Diffie\(en\&Hellman in two different kinds of cyclic groups:
+.I "Schnorr groups"
+(denoted
+.BR dh )
+and
+.I "elliptic curve groups"
+(denoted
+.BR ec ).

 .PP
 .PP

-Allocating IP addresses for VPNs can get quite complicated.  I'll
-attempt to illustrate with a relatively simple example.  Our objective
-will be to set up a virtual private network between two sites of
-.BR example.com .
-The two sites are using distinct IP address ranges from the private
-address space described in RFC1918: site A is using addresses from
-10.0.1.0/24 and site B is using 10.0.2.0/24.  Each site has a gateway
-host set up with both an address on the site's private network, and an
-externally-routable address from the public IP address space.  Site A's
-gateway machine,
-.BR alice ,
-has the addresses 10.0.1.1 and 200.0.1.1; site B's gateway is
-.B bob
-and has addresses 10.0.2.1 and 200.0.2.1.
-.hP 1.
-Install
-.B tripe
-on both of the gateway hosts.  Create the directory
-.BR /var/lib/tripe .
-.hP 2.
-On
-.BR alice ,
-make
-.B /var/lib/tripe
-the current directory and generate a Diffie-Hellman group:
-.RS
+A Schnorr group is 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.  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
+The server works out which it should be doing based on the key's
+.B kx-group
+attribute, which should be either
+.B dh
+or
+.BR ec .
+If this attribute isn't present, then the key's type is examined: if
+it's of the form
+.BR tripe\- group
+then the
+.I group
+is used.  If no group is specified,
+.B dh
+is used as a fallback.
+.PP
+To create usual Schnorr-group keys, say something like

 .VS
 .VS

-key add \-adh\-param \-LS \-b2048 \-B256 \e
-       \-eforever \-tparam tripe\-dh\-param
+key add \-adh-param \-LS \-b3072 \-B256 \e
+       \-eforever \-tparam tripe\-param kx-group=dh

 .VE
 .VE

-(See
-.BR key (1)
-from the Catacomb distribution for details about the
-.B key
-command.)  Also generate a private key for
-.BR alice :
+to construct a parameters key; and create the private keys by

 .VS
 key add \-adh \-pparam \-talice \e
 .VS
 key add \-adh \-pparam \-talice \e

-       \-e"now + 1 year" tripe\-dh
-.VE
-Extract the group parameters and
-.BR alice 's
-public key to
-.I separate
-files, and put the public key in
-.BR keyring.pub :
-.VS
-key extract param param
-key extract \-f\-secret alice.pub alice
-key \-kkeyring.pub merge alice.pub
-.VE
-Send the files
-.B param
-and
-.B alice.pub
-to
-.B bob
-in some secure way (e.g., in PGP-signed email, or by using SSH), so that
-you can be sure they've not been altered in transit.
-.RE
-.hP 3.
-On
-.B bob
-now, make
-.B /var/lib/tripe
-the current directory, and import the key material from
-.BR alice :
-.RS
-.VS
-key merge param
-key \-kkeyring.pub merge alice.pub
-.VE
-Generate a private key for
-.B bob
-and extract the public half, as before:
-.VS
-key add \-adh \-pparam \-tbob \e
-       \-e"now + 1 year" tripe\-dh
-key extract \-f\-secret bob.pub bob
-key \-kkeyring.pub merge bob.pub
-.VE
-and send
-.B bob.pub
-back to
-.B alice
-using some secure method.
-.RE
-.hP 4
-On
-.BR alice ,
-merge
-.B bob 's
-key into the public keyring.  Now, on each host, run
-.RS
-.VS
-key \-kkeyring.pub fingerprint
-.VE
-and check that the hashes match.  If the two sites have separate
-administrators, they should read the hashes to each other over the
-telephone (assuming that they can recognize each other's voices).
-.RE
-.hP 5.
-Start the
-.B tripe
-servers up.  Run
-.RS
-.VS
-tripectl \-slD
-.VE
-on each of
-.B alice
-and
-.BR bob .
-.RE
-.hP 6.
-To get
-.B alice
-talking to
-.BR bob ,
-run this shell script (or one like it):
-.RS
-.VS
-#! /bin/sh
-
-tripectl add bob 200.0.2.1 4070
-ifname=`tripectl ifname bob`
-ifconfig $ifname 10.0.1.1 pointopoint 10.0.2.1
-route add -net \e
-       10.0.2.0 netmask 255.255.255.0 \e
-       gw 10.0.2.1
+       \-e"now + 1 year" tripe

 .VE
 .VE

-Read
-.BR ifconfig (8)
-and
-.BR route (8)
-to find out about your system's variants of these commands.  The
-versions shown above assume a Linux system.
-Run a similar script on
-.BR bob ,
-to tell its
-.B tripe
-server to talk to
-.BR alice .
-.RE
-.hP 7.
-Congratulations.  The two servers will exchange keys and begin sending
-packets almost immediately.  You've set up a virtual private network.
-.SS "Using elliptic curve keys"
-The
-.B tripe
-server can use elliptic curve Diffie-Hellman for key exchange, rather
-than traditional integer Diffie-Hellman.  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
-The server works out which it
-should be doing based on the key type, which is either
-.B tripe\-dh
-for standard Diffie-Hellman, or
-.B tripe\-ec
-for elliptic curves.  To create elliptic curve keys, say something like
+To create elliptic curve keys, say something like

 .VS
 .VS

-key add \-aec\-param \-Cnist-p192 \-eforever \e
-       \-tparam tripe\-ec\-param
+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
 .VE
 to construct a parameters key, using your preferred elliptic curve in
 the


@@ -439,13 +345,13 @@ option (see
 for details); and create the private keys by
 .VS
 key add \-aec \-pparam \-talice \e
 for details); and create the private keys by
 .VS
 key add \-aec \-pparam \-talice \e

-       \-e"now + 1 year" tripe\-ec
+       \-e"now + 1 year" tripe

 .VE
 .VE

-Now start
-.B tripe
-with the
-.B \-ttripe\-ec
-option, and all should be well.
+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
 .SS "Using other symmetric algorithms"
 The default symmetric algorithms
 .B tripe


@@ -454,6 +360,15 @@ uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
 mode, designed by Bellare, Canetti and Krawczyk).  These can all be
 overridden by setting attributes on your private key, as follows.
 .TP
 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 .
 .B cipher
 Names the symmetric encryption scheme to use.  The default is
 .BR blowfish\-cbc .


@@ -474,6 +389,26 @@ at half the underlying hash function's output length.
 A `mask-generation function', used in the key-exchange.  The default is
 .IB hash \-mgf
 and there's no good reason to change it.
 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.

 .SS "Using SLIP interfaces"
 Though not for the faint of heart, it is possible to get
 .B tripe
 .SS "Using SLIP interfaces"
 Though not for the faint of heart, it is possible to get
 .B tripe


@@ -551,7 +486,8 @@ find one, please inform the author
 .
 .BR key (1),
 .BR tripectl (1),
 .
 .BR key (1),
 .BR tripectl (1),

-.BR tripe\-admin (5).
+.BR tripe\-admin (5),
+.BR tripe\-keys (8).

 .PP
 .IR "The Trivial IP Encryption Protocol" ,
 .IR "The Wrestlers Protocol" .
 .PP
 .IR "The Trivial IP Encryption Protocol" ,
 .IR "The Wrestlers Protocol" .