make-secnet-sites: OpBase.write_out: Tolerate sitesfile is None

[secnet.git] / secnet.8

diff --git a/secnet.8 b/secnet.8
index 869d297d9a71f10d22966473074ed9a49745f528..c92a0e3a8d90f8220055f2f104621decfc0ea69b 100644 (file)
--- 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
 .TH secnet 8
 
 .SH NAME


@@ -45,6 +63,36 @@ Check configuration and exit.
 Configuration file key defining active sites.
 The default is \fBsites\fR.
 
 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.
 .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.
 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
 
 .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.
 
 .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
 .PP
 Valid keys in the \fIDICT\fR argument are:
 .TP


@@ -425,13 +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.
 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.
 
 .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
 .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.
 .TP
 .I PATH
 String.


@@ -444,7 +521,7 @@ Boolean.
 If \fBtrue\fR (the default) then check that the key is valid.
 
 .SS rsa-public
 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.
 .TP
 .I KEY
 String.


@@ -483,7 +560,7 @@ A \fIresolver closure\fR.
 A \fIrandomsource closure\fR.
 .TP
 .B local-key
 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
 The key used to prove our identity to the peer.
 .TP
 .B address


@@ -497,12 +574,17 @@ Number.
 The port to contact the peer.
 .TP
 .B key
 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
 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.
 .TP
 .B dh
 A \fIdh closure\fR.