.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"
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
overridden by setting attributes on your private key, as follows.
.TP
.B bulk
-Names the bulk-crypto transform to use. Currently the only choice is
-.BR v0 .
+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
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
~mdw / tripe / blobdiff