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.
.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.
.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.)
~mdw / secnet / blobdiff