.\"
.\" 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 ../common/defs.man \" @@@PRE@@@
.SH "SYNOPSIS"
.
.B tripe
-.RB [ \-DF ]
+.RB [ \-46DF ]
.RB [ \-d
.IR dir ]
.RB [ \-b
.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
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 "\-4, \-\-ipv4"
+Use only IPv4 addresses. The server will resolve names only to IPv4
+addresses, and not attempt to create IPv6 sockets.
+.TP
+.B "\-6, \-\-ipv6"
+Use only IPv6 addresses. The server will resolve names only to IPv6
+addresses, and not attempt to create IPv4 sockets. Note that v6-mapped
+IPv4 addresses won't work either.
+.TP
.B "\-D, \-\-daemon"
Dissociates from its terminal and starts running in the background after
completing the initialization procedure described above. If running as
.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.
The
.B tripe
server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys
-used for bulk data transfer. Currently
-.B tripe
-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
-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.
+used for bulk data transfer.
.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 .
+attribute.
If this attribute isn't present, then the key's type is examined: if
it's of the form
-.BR tripe\- group
+.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 \-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
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
Names the bulk-crypto transform to use. See below.
.TP
.B blkc
-Names a block cipher, used by some bulk-crypto transforms (e.g.,
+Names a blockcipher, used by some bulk-crypto transforms (e.g.,
.BR iiv ).
-The default is to use the block cipher underlying the chosen
+The default is to use the blockcipher underlying the chosen
.BR cipher ,
if any.
.TP
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
.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.
+IV, the IV is computed from the sequence number using a blockcipher.
This has two advantages over the
.B v0
transform. Firstly, it adds less overhead to encrypted messages
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
~mdw / tripe / blobdiff