.\"
.\" secnet 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 d of the License, or
+.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" secnet is distributed in the hope that it will be useful, but
Configuration file key defining active sites.
The default is \fBsites\fR.
+.SH "CAPABILITY NEGOTIATION"
+Sites negotiate with each other during key exchange
+in order to determine which cryptographic algorithms and other features
+\(en termed
+.I capabilities
+\(en
+they each support.
+Capabilities are assigned small integer numbers.
+In many cases,
+capability numbers can be assigned in the configuration file,
+as described below;
+but secnet's default assignments will often be satisfactory.
+.PP
+Capability numbers between 0 and 7 inclusive
+are reserved for local use:
+secnet will never make use of them without explicit configuration.
+This may be useful to migrate from one set of parameters
+for a particular cryptographic algorithm
+to different, incompatible, parameters for the same algorithm.
+Other capability numbers are assigned by default
+by various kinds of closures.
+See the descriptions below for details.
+.PP
+It is essential that a capability number mean the same thing
+to each of a pair of peers.
+It's possible to configure a site
+so that it uses different capability numbers for the same feature
+when it communicates with different peer sites,
+but this is likely to be more confusing than useful.
+
.SH "CONFIGURATION FILE"
.SS Overview
The default configuration file is \fI/etc/secnet/secnet.conf\fR.
.SS diffie-hellman
.PP
\fBdiffie-hellman(\fIMODULUS\fB, \fIGENERATOR\fR[\fB, \fICHECK\fR]\fB)\fR => \fIdh closure\fR
-.TP
-.I MODULUS
+.br
+\fBdiffie-hellman(\fIDICT\fB)\fR => \fIdh closure\fR
+Defines a Diffie\(enHellman group which uses
+traditional Diffie\(enHellman modulo a large prime number.
+Arguments may be provided
+either as positional arguments
+or in a dictionary.
+Dictionary keys are described below;
+those keys which correspond with positional arguments
+are mentioned in the individual descriptions.
+.TP
+.B p
String.
The prime modulus \fIp\fR in hex.
+Corresponds to the
+.I MODULUS
+argument.
.TP
-.I GENERATOR
+.B g
String.
The generator \fIg\fR in hex.
+Corresponds to the
+.I GENERATOR
+argument.
.TP
-.I CHECK
+.B check
Boolean.
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 same group must be used by all sites in the VPN.
+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
serves to obscure the exact length of messages. The default is 16,
.TP
.B capab-num
-The transform capability number to use when advertising this
-transform. Both ends must have the same meaning (or, at least, a
-compatible transform) for each transform capability number they have
-in common. The default for serpent-eax is 9.
-.IP
-Transform capability numbers in the range 8..15 are intended for
-allocation by the implementation, and may be assigned as the default
-for new transforms in the future. Transform capability numbers in the
-range 0..7 are reserved for definition by the user.
+The capability number to use when advertising this
+transform. The default for serpent-eax is 9.
.PP
A \fItransform closure\fR is a reversible means of transforming
messages for transmission over a (presumably) insecure network.
.SS sha1
\fBsha1\fR is a \fIhash closure\fR implementing the SHA-1 algorithm.
+.SS sha512
+\fBsha512\fR is a \fIhash closure\fR implementing the SHA-512 algorithm.
+
.SS site
\fBsite(\fIDICT\fB)\fR => \fIsite closure\fR
.PP
One or more \fItransform closures\fR.
Used to protect packets exchanged with the peer. These should
all have distinct \fBcapab-num\fR values, and the same \fBcapab-num\fR
-value should refer to the same (or a compatible) transform at both
+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 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.