.\"
.\" 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.
.TP
.BI "\-T, \-\-trace=" trace-opts
Allows the enabling or disabling of various internal diagnostics. See
-below for the list of options.
+the
+.B TRACE
+command in
+.BR trace-admin (5)
+for the list of options.
.SS "Key exchange group types"
The
.B tripe
\-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
closes a kleptographic channel, over which a compromised implementation
could leak secret information to a third party.
.TP
+.B aead
+A transform based on an all-in-one `authenticated encryption with
+additional data' scheme. The scheme is named in the
+.B cipher
+attribute; the default is
+.BR rijndael-ocb3 .
+If the
+.B mac
+attribute is given, it must be either
+.B aead
+or
+.BR aead/ \c
+.IR tagsz ,
+where
+.I tagsz
+is the desired tag length in bits; alternatively, the tag length can be
+set in the
+.B tagsz
+attribute. The chosen AEAD scheme must accept at least a 64-bit nonce
+(this rules out OCB3 and CCM with 64-bit blockciphers); it mustn't
+require an absurdly large nonce size (none of the schemes implemented in
+Catacomb present a problem here, but it bears mentioning); it must
+actually support additional header data (which rules out the
+.B naclbox
+schemes, but see the
+.B naclbox
+transform below); and it must produce an empty ciphertext when
+encrypting an empty message (again, all of Catacomb's schemes meet this
+requirement).
+.TP
.B naclbox
A transform based on the NaCl
.B crypto_secretbox
~mdw / tripe / blobdiff