[SECNET RFC PATCH] README.make-secnet-sites: Algorithm negotiation control keywords

[Ian Jackson]

Write down the proposed new scheme, before we implement it.

Signed-off-by: Ian Jackson <ijackson at chiark.greenend.org.uk>
---
 README.make-secnet-sites | 110 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 100 insertions(+), 10 deletions(-)

diff --git a/README.make-secnet-sites b/README.make-secnet-sites
index 2264d7501..938ed44ac 100644
--- a/README.make-secnet-sites
+++ b/README.make-secnet-sites
@@ -187,17 +187,32 @@ INPUT SYNTAX
 		Acceptable at all levels; required separately at VPN and
 		location levels.
 
-	dh P G
-	dh GROUP-NAME
-		Assigns a Diffie--Hellman closure to the `dh' key.  If
-		MODULUS and GENERATOR are given, the closure is
-		constructed as `diffie-hellman(P, G)'.  If a GROUP-NAME
-		is given, it must be one of `x25519' or `x448', and the
-		like-named pre-existing DH closure is used.  This is a
-		listish property: it can be set more than once and the
-		values are accumulated into a list in the output.
+	transform [ALGO-NEGO-CONTROL] [TRANSFORM [ARGUMENTS...]]
+		Specifically, and by default:
+	transform eax-serpent
+	transform serpent256-cbc
+		Controls the negotiation of the symmetric crypto
+		transform used for bulk data encryption.  Maps to the
+		"transform" parameter in output sites.conf.  This is
+		an algorithm cnegotiation control keyword - see the
+		correspoding section, below.
+
+	dh [ALGO-NEGO-CONTROL] [DH-ALGO [ARGUMENTS]]
+		Specifically, and by default:
+	dh x448
+	dh x25519
+		Additionally available:
+	dh gfp[@BIT] P G
+		Controls the negotiation of the asymmetric key
+		agreement algorithm.  Maps to the "dh" key in the
+		output sites.conf.
+
+		For gfp at BIT, BIT is the capability bit number, which
+		should be 0..7 or 10 (the default).  The closure is
+		then constructed as `diffie-hellman(P, G)'.
 
-		Acceptable at all levels; required at site level.
+	dh P G
+		Compatibily alias for "dh gfp P G" aka "dh gfp at 10 P G"
 
 	hash HASH-NAME
 		Assigns the HASH-NAME to the `hash' key.  The HASH-NAME
@@ -275,6 +290,81 @@ INPUT SYNTAX
 		If not specified, 00000000.
 
 
+    ALGORITHM NEGOTIATION CONTROL
+
+	The keywords "transform" and "dh" control advertisement of
+	algorithms to the peer, and choice of algorithm based on the
+	peer advertisement.
+
+	Each "item" (VPN, location, site) has a list of algorithms it
+	is prepared to use, in order from most to least preferred.
+	Additionally a secnet distribution has a built-in default,
+	and of course a set of known algorithms.
+
+	Each item inherits the list of algorithms from its parent (the
+	VPN inherits the built-in default list) and may then modify
+	it.  The modifications are all specified with same KEYWORD,
+	followed perhaps by options and perhaps by algorithm names.
+	We talk of "inherited" as opposed to "local" (eg "local list",
+	the list for this item; "the local config", the KEYWORD
+	directives for this item):
+
+	  * A list of algorithms to use or prefer.  Zero or more:
+		KEYWORD [--future] ALGO [ARGUMENTS...]
+	    These algorithms are "locally specified" and will appear
+	    at the start of the local list, subject to --prefer-newer.
+
+	  * Whether to allow "new" algorithms and where to put them:
+		KEYWORD --prefer-new	# the default
+		KEYWORD --allow-new
+		KEYWORD --no-new
+
+	    An algorithm is "new" if it seems to postdate the local
+	    config, according to the following rule: A "new" algorithm
+	    is one which appears in the inherited strictly ahead of
+	    all ALGOs mentioned by name anywhere in the local config.
+
+	    With --prefer-new "new" algorithms go to the front of
+	    the local list.  With --allow-new they appear directly
+	    after the locally configured algorithms.
+
+	  * Whether and how to include other non-"new" algorithms:
+		KEYWORD --use-older
+		  Other algoriths in the inherited list, not "new" and
+		  not locally specified, go to the end of the list
+		  for this item.  Default.
+
+		KEYWORD --no-older
+		  These algorithms are not included.
+
+	  * Final modifications, may be repeated:
+		KEYWORD --oldest ALGO
+		   Delete from the local list all algorithms that
+		   appear in it after ALGO.  (If ALGO not in the
+		   inherited list, ignored.)
+		KEYWORD --no ALGORITHM
+		   Delete it from the local list, if it appears.
+		KEYWORD --allow ALGORITHM
+		   Add it to the local list at the end.
+
+	It is not generally error to simply refer to an algorithm that
+	is not known to this version of make-secnet-sites, with one
+	exception: If an algorithm that is not known appears in the
+	local list for any site, it is an error unless --future or
+	--allow was used; in that case it is ignored.  It is not an
+	error for the resulting list for a site to be empty, but that
+	would prevent the site from appearing at all.
+
+	For algorithm names that are actually families, such as
+	traditional Diffie-Hellman over integers mod p ("dh gfp"),
+	ALGORITHM may end in @BIT to specify the capability bit.  Then
+	different ALGORITHMs with the same base algorithm but possibly
+	different parameters are considered different iff they imply a
+	different capability bit number (so "dh gfp at 10 13 2" and "dh
+	gfp 13 3" are considered the "same" algorithm, but "dh gfp 13
+	2" and "dh gfp at 1 13 2" are not.)
+
+
 OUTPUT STRUCTURE
 
 	The program produces a Secnet configuration fragment with the
-- 
2.11.0