site: support multiple transforms

[secnet.git] / secnet.8

diff --git a/secnet.8 b/secnet.8
index 869d297d9a71f10d22966473074ed9a49745f528..48cfaba2ff3c871babf36b59f20160d6cff4c0ce 100644 (file)
--- a/secnet.8
+++ b/secnet.8
@@ -415,8 +415,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
+\eax-fBserpent(\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,11 +425,48 @@ 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 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.

 .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
 \fBrsa-private(\fIPATH\fB\fR[, \fICHECK\fR]\fB)\fR => \fIrsaprivkey closure\fR
 .TP
 .SS rsa-private
 \fBrsa-private(\fIPATH\fB\fR[, \fICHECK\fR]\fB)\fR => \fIrsaprivkey closure\fR
 .TP


@@ -501,8 +538,13 @@ An \fIrsapubkey 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 refer to the same (or a compatible) transform 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.