From: Mark Wooding <mdw@distorted.org.uk>
Date: Sat, 29 Apr 2017 12:55:40 +0000 (+0100)
Subject: secnet.8, magic.h: Rephrase documentation of `capab-num' settings.
X-Git-Url: https://git.distorted.org.uk/~mdw/secnet/commitdiff_plain/3dc839cecdf5ea11336d51c9dbe4b7cd83b0f3f7

secnet.8, magic.h: Rephrase documentation of `capab-num' settings.

In particular, I've abolished the idea of a specific class of `transform
capabilities'.  They're all just capabilities, and they need to mean the
same thing at both ends.

Signed-off-by: Mark Wooding <mdw@distorted.org.uk>
---

diff --git a/magic.h b/magic.h
index 5b0407e..e0ea8aa 100644
--- a/magic.h
+++ b/magic.h
@@ -42,15 +42,15 @@
 /* remaining bits are unused */
 
 /*
- * The transform capability mask is a set of bits, one for each
- * transform supported.  The transform capability numbers are set in
- * the configuration (and should correspond between the two sites),
- * although there are sensible defaults.
+ * The capability mask is a set of bits, one for each optional feature
+ * supported.  The capability numbers for transforms are set in the
+ * configuration (and should correspond between the two sites), although
+ * there are sensible defaults.
  *
- * Advertising a nonzero transform capability mask promises that
- * the receiver understands LABEL_MSG3BIS messages, which
- * contain an additional byte specifying the transform capability
- * number actually chosen by the MSG3 sender.
+ * Advertising a nonzero capability mask promises that the receiver
+ * understands LABEL_MSG3BIS messages, which contain an additional byte
+ * specifying the transform capability number actually chosen by the MSG3
+ * sender.
  *
  * Aside from that, an empty bitmask is treated the same as
  *  1u<<CAPAB_BIT_ANCIENTTRANSFORM
diff --git a/secnet.8 b/secnet.8
index 9ffa605..22aea6b 100644
--- a/secnet.8
+++ b/secnet.8
@@ -453,14 +453,14 @@ 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
+The capability number to use when advertising this
+transform.  Both ends must have the same meaning (or, at least,
+refer to compatible constructions) for each 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
+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
+for new transforms in the future.  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
@@ -558,7 +558,7 @@ The key used to verify the peer's identity.
 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.)