make-secnet-sites: Introduce a notion of listish types.

[secnet] / secnet.8

diff --git a/secnet.8 b/secnet.8
index f8cd48f..087273d 100644 (file)
--- a/secnet.8
+++ b/secnet.8
@@ -331,8 +331,44 @@ If \fBtrue\fR (the default) then check if \fIp\fR is prime.
 Corresponds to the
 .I CHECK
 argument.
+.TP
+.B capab-num
+The capability number to use when advertising
+this Diffie\(enHellman group.
+The default capability number is 10.
+
+.PP
+A \fIdh closure\fR defines a group to be used for key exchange.
+
+.SS x25519
+.PP
+\fBx25519
+.PP
+A premade \fIdh closure\fR
+which uses Daniel Bernstein's X25519 key-exchange function.
+This uses an elliptic curve called Curve25519,
+defined over a 255-bit field.
+The function is fast and very well-studied.
 .PP
 A \fIdh closure\fR defines a group to be used for key exchange.
+The
+.B x25519
+Diffie\(enHellman group always uses capability number 24.
+
+.SS x448
+.PP
+\fBx448
+.PP
+A premade \fIdh closure\fR
+which uses Mike Hamburg's X448 key-exchange function.
+This uses an elliptic curve called Ed448-Goldilocks,
+defined over a 448-bit field.
+The function is unusually quick and fairly well studied.
+.PP
+A \fIdh closure\fR defines a group to be used for key exchange.
+The
+.B x448
+Diffie\(enHellman group always uses capability number 25.
 
 .SS logfile
 \fBlogfile(\fIDICT\fB)\fR => \fIlog closure\fR
@@ -609,8 +645,18 @@ first.  (The end which sends MSG1,MSG3 ends up choosing; the ordering
 at the other end is irrelevant.)
 .TP
 .B dh
-A \fIdh closure\fR.
-The group to use in key exchange.
+A list of one or more \fIdh closure\fRs.
+The groups to use in key exchange.
+These should all have distinct
+.B capab-num
+values,
+and the same
+.B capab-num
+value should have the same (or a compatible) meaning at both ends.
+The list should be in order of preference,
+most preferred first.
+(The end which sends MSG1,MSG3 ends up choosing;
+the ordering at the other end is irrelevant.)
 .TP
 .B hash
 The hash function used during setup.