server/, keys/: Alternative serialization formats for hashing.

[tripe] / server / tripe.8.in

diff --git a/server/tripe.8.in b/server/tripe.8.in
index 930fcfe..bdac421 100644 (file)
--- a/server/tripe.8.in
+++ b/server/tripe.8.in
@@ -279,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


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


@@ -347,6 +348,7 @@ 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

 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


@@ -410,6 +412,20 @@ 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.
 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.

+.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