server/{keyexch.c,keyset.c}: Eliminate `ks_tregen'.

[tripe] / server / tripe.8.in

diff --git a/server/tripe.8.in b/server/tripe.8.in
index ad71bc918b7e1adbfa571738f09621411d42e03b..14ee0ab705cd4d16ce7e4ba1bddecaa24d7011ba 100644 (file)
--- a/server/tripe.8.in
+++ b/server/tripe.8.in
@@ -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


@@ -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


@@ -219,9 +223,13 @@ option.  The selected user (and group) will also be the owner of the
 administration socket.
 .TP
 .BI "\-G, \-\-setgid=" group
 administration socket.
 .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


@@ -240,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


@@ -252,192 +262,80 @@ if that's not set either, then a default default of
 .B "\*(/s/tripesock"
 is used instead.
 .TP
 .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.
 .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
+       \-e"now + 1 year" tripe

 .VE
 .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
+To create elliptic curve keys, say something like

 .VS
 .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
-.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
-.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


@@ -447,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


@@ -559,7 +457,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" .