X-Git-Url: https://git.distorted.org.uk/~mdw/tripe/blobdiff_plain/fc916a0942e6ef8f63aefb96119d0e4fd7c7efbb..e713954af6c6dd7c05877b9002247c4cbd336b31:/server/tripe.8.in

diff --git a/server/tripe.8.in b/server/tripe.8.in
index 2135c4e0..fcfdb324 100644
--- a/server/tripe.8.in
+++ b/server/tripe.8.in
@@ -9,25 +9,24 @@
 .\"
 .\" 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 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 3 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.
+.\" 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.
+.\" along with TrIPE.  If not, see <https://www.gnu.org/licenses/>.
 .
 .\"--------------------------------------------------------------------------
-.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"
@@ -38,7 +37,7 @@ tripe \- a simple VPN daemon
 .SH "SYNOPSIS"
 .
 .B tripe
-.RB [ \-D ]
+.RB [ \-DF ]
 .RB [ \-d
 .IR dir ]
 .RB [ \-b
@@ -55,6 +54,8 @@ tripe \- a simple VPN daemon
 .IR group ]
 .RB [ \-a
 .IR socket ]
+.RB [ \-m
+.IR mode ]
 .RB [ \-T
 .IR trace-opts ]
 .br
@@ -106,7 +107,7 @@ will initialize by following these steps:
 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.
@@ -117,8 +118,10 @@ 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
-from the Catacomb-format file
+for backwards compatibility reasons) from the Catacomb-format file
 .BR keyring ,
 and loads the file
 .B keyring.pub
@@ -173,6 +176,13 @@ standard output.  A better way to start
 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
@@ -180,7 +190,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
-.B "*(/c"
+.B "\*(/c"
 is used.  Give a current directory of
 .B .
 if you don't want it to change directory at all.
@@ -208,12 +218,17 @@ to
 .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
-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
-(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
@@ -232,6 +247,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
+.B tripe
+or
 .BR tripe\-dh .
 .TP
 .BI "\-a, \-\-admin\-socket=" socket
@@ -241,211 +258,164 @@ 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"
+.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 "Setting up a VPN with tripe"
+.SS "Key exchange group types"
 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
-.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 ` . ',
+server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys
+used for bulk data transfer.
 .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:
+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 \-b2048 \-B256 \e
-	\-eforever \-tparam tripe\-dh\-param
+key add \-adh-param \-LS \-b3072 \-B256 \e
+	\-eforever \-tparam tripe\-param kx-group=dh
 .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
-	\-e"now + 1 year" tripe\-dh
+	\-e"now + 1 year" tripe
 .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 :
+.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 merge param
-key \-kkeyring.pub merge alice.pub
+key add \-aec\-param \-Cnist-p256 \-eforever \e
+	\-tparam tripe\-param kx-group=ec
 .VE
-Generate a private key for
-.B bob
-and extract the public half, as before:
+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 \-adh \-pparam \-tbob \e
-	\-e"now + 1 year" tripe\-dh
-key extract \-f\-secret bob.pub bob
-key \-kkeyring.pub merge bob.pub
+key add \-aec \-pparam \-talice \e
+	\-e"now + 1 year" tripe
 .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
+.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 \-kkeyring.pub fingerprint
+key add \-aempty \-eforever \e
+	\-tparam tripe\-param kx-group=x25519
 .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
+to construct a parameters key
+(see
+.BR key (1)
+for details);
+and create the private keys by
 .VS
-tripectl \-slD
+key add \-ax25519 \-pparam \-talice \e
+	\-e"now + 1 year" tripe
 .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):
+.sv -1
+.TP
+.B x448
 .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.
+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
-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
+.B x448
+keys,
+say something like
 .VS
-key add \-aec\-param \-Cnist-p192 \-eforever \e
-	\-tparam tripe\-ec\-param
+key add \-aempty \-eforever \e
+	\-tparam tripe\-param kx-group=x448
 .VE
-to construct a parameters key, using your preferred elliptic curve in
-the
-.B \-C
-option (see
+to construct a parameters key
+(see
 .BR key (1)
-for details); and create the private keys by
+for details);
+and create the private keys by
 .VS
-key add \-aec \-pparam \-talice \e
-	\-e"now + 1 year" tripe\-ec
+key add \-ax448 \-pparam \-talice \e
+	\-e"now + 1 year" tripe
 .VE
-Now start
-.B tripe
-with the
-.B \-ttripe\-ec
-option, and all should be well.
+.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
@@ -454,6 +424,16 @@ 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
+.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 .
@@ -469,11 +449,85 @@ be followed by a
 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
@@ -551,7 +605,8 @@ find one, please inform the author
 .
 .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" .