From a8a74eb8dca5a226d6dfa128e4a9609bad622315 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Sun, 15 Dec 2019 20:34:56 +0000 Subject: [PATCH] README.make-secnet-sites: Algorithm negotiation control keywords Write down the proposed new scheme, before we implement it. Signed-off-by: Ian Jackson --- 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 2264d75..938ed44 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@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@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@10 13 2" and "dh + gfp 13 3" are considered the "same" algorithm, but "dh gfp 13 + 2" and "dh gfp@1 13 2" are not.) + + OUTPUT STRUCTURE The program produces a Secnet configuration fragment with the -- 2.30.2