+[The new plan]
+
+It appears that people want to be able to use secnet on mobile
+machines like laptops as well as to interconnect sites. In particular,
+they want to be able to use their laptop in three situations:
+
+1) connected to their internal LAN by a cable; no tunnel involved
+2) connected via wireless, using a tunnel to protect traffic
+3) connected to some other network, using a tunnel to access the
+internal LAN.
+
+They want the laptop to keep the same IP address all the time.
+
+Case (1) is simple.
+
+Case (2) requires that the laptop run a copy of secnet, and have a
+tunnel configured between it and the main internal LAN default
+gateway. secnet must support the concept of a 'soft' tunnel where it
+adds a route and causes the gateway to do proxy-ARP when the tunnel is
+up, and removes the route again when the tunnel is down.
+
+The usual prohibition of packets coming in from one tunnel and going
+out another must be relaxed in this case (in particular, the
+destination address of packets from these 'mobile station' tunnels may
+be another tunnel as well as the host).
+
+(Quick sanity check: if chiark's secnet address was in
+192.168.73.0/24, would this work properly? Yes, because there will be
+an explicit route to it, and proxy ARP will be done for it. Do we want
+packets from the chiark tunnel to be able to go out along other
+routes? No. So, spotting a 'local' address in a remote site's list of
+networks isn't sufficient to switch on routing for a site. We need an
+explicit option. NB packets may be routed if the source OR the
+destination is marked as allowing routing [otherwise packets couldn't
+get back from eg. chiark to a laptop at greenend]).
+
+[the even newer plan]
+
+secnet sites are configured to grant access to particular IP address
+ranges to the holder of a particular public key. The key can certify
+other keys, which will then be permitted to use a subrange of the IP
+address range of the certifying key.
+
+This means that secnet won't know in advance (i.e. at configuration
+time) how many tunnels it might be required to support, so we have to
+be able to create them (and routes, and so on) on the fly.
+
+** VPN-level configuration
+
+At a high level we just want to be able to indicate which groups of
+users can claim ownership of which ranges of IP addresses. Assuming
+these users (or their representatives) all have accounts on a single
+machine, we can automate the submission of keys and other information
+to make up a 'sites' file for the entire VPN.
+
+The distributed 'sites' file should be in a more restricted format
+than the secnet configuration file, to prevent attackers who manage to
+distribute bogus sites files from taking over their victim's machines.
+
+The distributed 'sites' file is read one line at a time. Each line
+consists of a keyword followed by other information. It defines a
+number of VPNs; within each VPN it defines a number of locations;
+within each location it defines a number of sites. These VPNs,
+locations and sites are turned into a secnet.conf file fragment using
+a script.
+
+Some keywords are valid at any 'level' of the distributed 'sites'
+file, indicating defaults.
+
+The keywords are:
+
+vpn n: we are now declaring information to do with VPN 'n'. Must come first.
+
+location n: we are now declaring information for location 'n'.
+
+site n: we are now declaring information for site 'n'.
+endsite: we're finished declaring information for the current site
+
+restrict-nets a b c ...: restrict the allowable 'networks' for the current
+ level to those in this list.
+end-definitions: prevent definition of further vpns and locations, and
+ modification of defaults at VPN level
+
+dh x y: the current VPN uses the specified group; x=modulus, y=generator
+
+hash x: which hash function to use. Valid options are 'md5' and 'sha1'.
+
+admin n: administrator email address for current level
+
+key-lifetime n
+setup-retries n
+setup-timeout n
+wait-time n
+renegotiate-time n
+
+address a b: a=dnsname, b=port
+networks a b c ...
+pubkey x y z: x=keylen, y=encryption key, z=modulus
+mobile: declare this to be a 'mobile' site
+
+** Logging etc.
+
+There are several possible ways of running secnet:
+
+'reporting' only: --version, --help, etc. command line options and the
+--just-check-config mode.
+
+'normal' run: perform setup in the foreground, and then background.
+
+'failed' run: setup in the foreground, and terminate with an error
+before going to background.
+
+'reporting' modes should never output anything except to stdout/stderr.
+'normal' and 'failed' runs output to stdout/stderr before
+backgrounding, then thereafter output only to log destinations.
+
+** Site long-term keys
+
+We use authenticated DH. Sites identify themselves to each other
+using long-term signing keys.
+
+These signing keys may be for a variety of algorithms. (An algorithm
+specifies completely how to do a signature and verification.)
+
+Each site may have several keys. This helps support key rollover and
+algorithm agility. Several keys of different algorithms can form a
+key group. Usually a key group consists of keys generated at the same
+time. A key is identified by a 4-byte group id (invented by its
+publisher and opaque) plus a 1-byte algorithm id (defined by the
+protocol spec for each algorithm).
+
+Keys are published in key sets. A key set is a collection of key
+groups (including older keys as well as newer ones) published at a
+particular time. Key sets have their own 4-byte ids; these are
+invented by the publisher but are ordered using sequence number
+arithmetic. This allows reliers to favour new sets over old ones.
+
+Within each key set, some groups may be marked as `fallback'. This
+means a group that should be tolerated by a relier only if the relier
+doesn't support any non-fallback keys.
+
+Keys within groups, and groups within sets, are ordered (by the
+publisher of the set), from most to least preferred.
+
+When deciding which public keys to accept, a relier should:
+ Process each group within the key set.
+ Discard unknown algorithms.
+ Choose a preferred algorithm:
+ Earliest in the group
+ (or local config could have algorithm prefererence).
+ Discard empty groups.
+ Discard unneeded fallback groups:
+ If any (non-empty) non-fallback groups found, discard all
+ fallback groups. Otherwise there are only fallback groups;
+ discard all but first group in the set.
+ Discard any keys exceeding limit on number of keys honoured:
+ Limit is at least 4
+ Discard keys later in the set
+ In wire protocol, offer the resulting subset of keyids to
+ the peer and a allow the signer to select which key to use
+ from that subset.
+
+In configuration and key management, long-term private and public keys
+are octet strings. Private keys are generally stored in disk files,
+one key per file. The octet string for a private key should identify
+the algorithm so that passing the private key to the code for the
+wrong algorithm does not produce results which would leak or weaken
+the key. The octet string for a public key need not identify the
+algorithm; when it's loaded the algorithm will be known from context.
+
+The group id 00000000 is special. It should contain only one key,
+algorithm 00. Key 0000000000 refers to the rsa1 key promulgated
+before the key rollover/advertisement protocols, or the key which
+should be used by sites running old software.
+
+The key set id 00000000 is special and is considered older than all
+othere key sets (ie this is an exception to the sequence number
+arithmetic). It is the implied key set id of the rsa1 key
+promulgated before the key rollover/advertisement protocols.
+
+The algorithm 00 is special and refers to the old rsa1 signature
+protocol but unusually does not identify the hash function. The hash
+function is conventional and must be specified out of band. In known
+existing installations it is SHA-1.
+