keys/tripe-keys.master: Include a nontrivial `sig-fresh' example.

[tripe] / server / tripe.8.in

diff --git a/server/tripe.8.in b/server/tripe.8.in
index f43ab5f8ca4b8d9155390618a9a98c80f4ada28e..3997e1dbf2537f6106c72dac37b839ee5242ca14 100644 (file)
--- a/server/tripe.8.in
+++ b/server/tripe.8.in
@@ -27,7 +27,7 @@
 .so ../common/defs.man \" @@@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"
 .
 .\"--------------------------------------------------------------------------
 .SH "NAME"


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


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


@@ -256,6 +262,16 @@ 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.


@@ -263,48 +279,31 @@ below for the list of options.
 The
 .B tripe
 server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys
 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
 .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
 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.
 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
 .PP
 To create usual Schnorr-group keys, say something like
 .VS


@@ -316,6 +315,24 @@ to construct a parameters key; and create the private keys by
 key add \-adh \-pparam \-talice \e
        \-e"now + 1 year" tripe
 .VE
 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
 To create elliptic curve keys, say something like
 .VS
 key add \-aec\-param \-Cnist-p256 \-eforever \e


@@ -331,6 +348,70 @@ for details); and create the private keys by
 key add \-aec \-pparam \-talice \e
        \-e"now + 1 year" tripe
 .VE
 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
 Note that the
 .BR tripe-keys (8)
 program provides a rather more convenient means for generating and


@@ -344,6 +425,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
 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 .
 .B cipher
 Names the symmetric encryption scheme to use.  The default is
 .BR blowfish\-cbc .


@@ -359,11 +450,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.
 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.
 .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
 .SS "Using SLIP interfaces"
 Though not for the faint of heart, it is possible to get
 .B tripe