X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=secnet.8;h=48cfaba2ff3c871babf36b59f20160d6cff4c0ce;hb=HEAD;hp=ef07a76031a36b76910583e910c7f04799e5e401;hpb=af43f0b77a10716921d13c047d1d3c39570cae17;p=secnet.git

diff --git a/secnet.8 b/secnet.8
index ef07a76..c92a0e3 100644
--- a/secnet.8
+++ b/secnet.8
@@ -1,3 +1,21 @@
+.\" Man page for secnet.
+.\"
+.\" See the secnet.git README, or the Debian copyright file, for full
+.\" list of copyright holders.
+.\"
+.\" 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 3 of the License, or
+.\" (at your option) any later version.
+.\" 
+.\" secnet is distributed in the hope that it will be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+.\" General Public License for more details.
+.\" 
+.\" You should have received a copy of the GNU General Public License
+.\" version 3 along with secnet; if not, see
+.\" https://www.gnu.org/licenses/gpl.html.
 .TH secnet 8
 
 .SH NAME
@@ -45,6 +63,36 @@ Check configuration and exit.
 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.
@@ -266,7 +314,6 @@ Boolean.
 If \fBtrue\fR (the default) then check if \fIp\fR is prime.
 .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
@@ -415,8 +462,8 @@ A \fIrandomsource closure\fR is a source of random numbers.
 .PP
 Read the contents of the file \fIPATH\fR (a string) and return it as a string.
 
-.SS serpent256-cbc
-\fBserpent256-cbc(\fIDICT\fB)\fR => \fItransform closure\fR
+.SS eax-serpent
+\fBeax-serpent(\fIDICT\fB)\fR => \fItransform closure\fR
 .PP
 Valid keys in the \fIDICT\fR argument are:
 .TP
@@ -425,15 +472,43 @@ The maximum acceptable difference between the sequence number in a
 received, decrypted message and the previous one.
 The default is 10.
 It may be necessary to increase this is if connectivity is poor.
+.TP
+.B tag-length-bytes
+The length of the message authentication tag.  The default is 16,
+for a 128-bit tag length.  It must be no longer than the Serpent
+blocksize, 16.  Must be have the same value at both ends.
+.TP
+.B padding-rounding
+Messages are padded to a multiple of this many bytes.  This
+serves to obscure the exact length of messages.  The default is 16,
+.TP
+.B capab-num
+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.
 It is responsible for both confidentiality and integrity.
+
+.SS serpent256-cbc
+\fBserpent256-cbc(\fIDICT\fB)\fR => \fItransform closure\fR
+.PP
+This transform
+is deprecated as its security properties are poor; it should be
+specified only alongside a better transform such as eax-serpent.
+.PP
+Valid keys in the \fIDICT\fR argument are:
+.TP
+.B capab-num
+As above.  The default for serpent256-cbc is 8.
+.TP
+.B max-sequence-skew
+As above.
 .PP
 Note that this uses a big-endian variant of the Serpent block cipher
 (which is not compatible with most other Serpent implementations).
 .SS rsa-private
-\fBrsa-private(\fIPATH\fB\fR[, \fICHECK\fR]\fB)\fR => \fIrsaprivkey closure\fR
+\fBrsa-private(\fIPATH\fB\fR[, \fICHECK\fR]\fB)\fR => \fIsigprivkey closure\fR
 .TP
 .I PATH
 String.
@@ -446,7 +521,7 @@ Boolean.
 If \fBtrue\fR (the default) then check that the key is valid.
 
 .SS rsa-public
-\fBrsa-public(\fIKEY\fB, \fIMODULUS\fB)\fR => \fIrsapubkey closure\fR
+\fBrsa-public(\fIKEY\fB, \fIMODULUS\fB)\fR => \fIsigpubkey closure\fR
 .TP
 .I KEY
 String.
@@ -485,7 +560,7 @@ A \fIresolver closure\fR.
 A \fIrandomsource closure\fR.
 .TP
 .B local-key
-An \fIrsaprivkey closure\fR.
+An \fIsigprivkey closure\fR.
 The key used to prove our identity to the peer.
 .TP
 .B address
@@ -499,12 +574,17 @@ Number.
 The port to contact the peer.
 .TP
 .B key
-An \fIrsapubkey closure\fR.
+An \fIsigpubkey closure\fR.
 The key used to verify the peer's identity.
 .TP
 .B transform
-A \fItransform closure\fR.
-Used to protect packets exchanged with the peer.
+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 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.