.\"
.\" 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"
.IR group ]
.RB [ \-a
.IR socket ]
+.RB [ \-m
+.IR mode ]
.RB [ \-T
.IR trace-opts ]
.br
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.
+It acquires a UDP socket. The default port is 4070
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
.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
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.
.TP
.BI "\-p, \-\-port=" port
Use the specified UDP port for all communications with peers, rather
-than an arbitarary kernel-assigned port.
+than the default port 4070. If this is zero, the kernel will assign a
+free port, which can be determined using the
+.B PORT
+administration command (see
+.BR tripe-admin (5)).
.TP
.BI "\-n, \-\-tunnel=" tunnel
Use the specified tunnel driver for new peers by default.
.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
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
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
-.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
+ \-e"now + 1 year" tripe
.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
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 .
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
.
.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" .
~mdw / tripe / blobdiff