-#* Design of new, multi-subnet secnet protocol
+* Design of new, multi-subnet secnet protocol
-Like the first version, we're tunnelling IP packets inside UDP
-packets. To defeat various restrictions which may be imposed on us by
-network providers (like the prohibition of incoming TCP connections)
-we're sticking with UDP for everything this time, including key setup.
+Like the first (1995/6) version, we're tunnelling IP packets inside
+UDP packets. To defeat various restrictions which may be imposed on us
+by network providers (like the prohibition of incoming TCP
+connections) we're sticking with UDP for everything this time,
+including key setup. This means we have to handle retries, etc.
Other new features include being able to deal with subnets hidden
behind changing 'real' IP addresses, and the ability to choose
** Configuration and structure
+[The original plan]
+
The network is made up from a number of 'sites'. These are collections
of machines with private IP addresses. The new secnet code runs on
machines which have interfaces on the private site network and some
tunnel endpoint, but this is not vital. Individual tunnels are
identified by their two endpoint names.
+[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 configuration is held in memory as a data structure as follows:
+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 root is a Dictionary. Dictionaries hold (key,value) pairs. Keys
-are atoms. Values are lists, dictionaries or closures. Lists can hold
-the following types: string, number.
+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.
-Closures cannot be constructed directly; they are added to the
-'default' dictionary before the configuration file is read. Invocation
-of a closure can return any type of value.
+Some keywords are valid at any 'level' of the distributed 'sites'
+file, indicating defaults.
+The keywords are:
-Configuration file format: the file describes a dictionary.
+vpn n: we are now declaring information to do with VPN 'n'. Must come first.
-key value;
+location n: we are now declaring information for location 'n'.
-value is item[,item...]
+site n: we are now declaring information for site 'n'.
+endsite: we're finished declaring information for the current site
-item can be "string", number, path (looks up in dictionary),
-{dictionary}, value(value), value{dictionary}. If item is a list it
-is copied into the list - we can't have lists of lists.
+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
-A path is [/]key[\[index\]][/key[\[index\]]...], defining a lookup
-from the current dictionary (or parents) or the root. If a key refers
-to a list of more than one item then an index number (base 0) in
-square brackets can be used to specify the list item number.
+dh x y: the current VPN uses the specified group; x=modulus, y=generator
-Items of the form value1(value2) invoke executable value1 with an
-argument of value2. The return value can be a string or dictionary,
-but not a list. (Invocation happens after the entire configuration
-file has been read.)
+hash x: which hash function to use. Valid options are 'md5' and 'sha1'.
-Items of the form value{dict} invoke executable value with an argument
-of a single-element list, containing dict. It's just syntactic sugar
-for value({dict}).
+admin n: administrator email address for current level
+key-lifetime n
+setup-retries n
+setup-timeout n
+wait-time n
+renegotiate-time n
-When a key is used (rather than defined) it is looked up in the
-current dictionary, and if it isn't found it is looked up in the
-(lexical) parent, until the root is reached.
+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.
-What sorts of crypto-related things do we need to define?
+'normal' run: perform setup in the foreground, and then background.
-sources of randomness
-block algorithms
-block cipher modes?
-hash functions
-padding functions
-public key signature algorithms
-public key crypto key stores
-key setup algorithms
+'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.
** Protocols
Definitions:
-A is the originating gateway machine
-B is the destination gateway machine
+A is the originating gateway machine name
+B is the destination gateway machine name
+A+ and B+ are the names with optional additional data, see below
PK_A is the public RSA key of A
PK_B is the public RSA key of B
PK_A^-1 is the private RSA key of A
Note that 'i' may be re-used from one session to the next, whereas 'n'
is always fresh.
+The optional additional data after the sender's name consists of some
+initial subset of the following list of items:
+ * A 32-bit integer with a set of capability flags, representing the
+ abilities of the sender.
+ * More data which is yet to be defined and which must be ignored
+ by receivers.
+The optional additional data after the receiver's name is not
+currently used. If any is seen, it must be ignored.
+
+Capability flag bits must be in one the following two categories:
+
+1. Early capability flags must be advertised in MSG1 or MSG2, as
+ applicable. If MSG3 or MSG4 advertise any "early" capability bits,
+ MSG1 or MSG3 (as applicable) must have advertised them too. Sadly,
+ advertising an early capability flag will produce MSG1s which are
+ not understood by versions of secnet which predate the capability
+ mechanism.
+
+2. Late capability flags are advertised in MSG2 or MSG3, as
+ applicable. They may also appear in MSG1, but this is not
+ guaranteed. MSG4 must advertise the same set as MSG2.
+
+No capability flags are currently defined. Unknown capability flags
+should be treated as late ones.
+
+
Messages:
-1) A->B: *,iA,msg1,A,B,nA
+1) A->B: *,iA,msg1,A+,B+,nA
+
+i* must be encoded as 0. (However, it is permitted for a site to use
+zero as its "index" for another site.)
-2) B->A: iA,iB,msg2,B,A,nB,nA
+2) B->A: iA,iB,msg2,B+,A+,nB,nA
(The order of B and A reverses in alternate messages so that the same
code can be used to construct them...)
-3) A->B: {iB,iA,msg3,A,B,nA,nB,g^x mod m}_PK_A^-1
+3) A->B: {iB,iA,msg3,A+,B+,nA,nB,g^x mod m}_PK_A^-1
If message 1 was a replay then A will not generate message 3, because
it doesn't recognise nA.
If message 2 was from an attacker then B will not generate message 4,
because it doesn't recognise nB.
-4) B->A: {iA,iB,msg4,B,A,nB,nA,g^y mod m}_PK_B^-1
+4) B->A: {iA,iB,msg4,B+,A+,nB,nA,g^y mod m}_PK_B^-1
At this point, A and B share a key, k. B must keep retransmitting
message 4 until it receives a packet encrypted using key k.
sent when a key times out, or the tunnel is forcibly terminated for
some reason.
-8) i?,i?,NAK/msg8
+**** Protocol sub-goal 3: send a packet
+
+8) i?,i?,msg0,(send-packet/msg9,packet)_k
+
+**** Other messages
+
+9) i?,i?,NAK (NAK is encoded as zero)
If the link-layer can't work out what to do with a packet (session has
-gone away, etc.) it can transmit a NAK back to the sender. The sender
-can then try to verify whether the session is alive by sending ping
-packets, and forget the key if it isn't. Potential denial-of-service
-if the attacker can stop the ping/pong packets getting through (the
-key will be forgotten and another key setup must take place), but if
-they can delete packets then we've lost anyway...
+gone away, etc.) it can transmit a NAK back to the sender.
-The attacker can of course forge NAKs since they aren't protected. But
-if they can only forge packets then they won't be able to stop the
-ping/pong working. Trust in NAKs can be rate-limited...
+This can alert the sender to the situation where the sender has a key
+but the receiver doesn't (eg because it has been restarted). The
+sender, on receiving the NAK, will try to initiate a key exchange.
-Alternative idea: if you receive a packet you can't decode, because
-there's no key established, then initiate key setup...
+Forged (or overly delayed) NAKs can cause wasted resources due to
+spurious key exchange initiation, but there is a limit on this because
+of the key exchange retry timeout.
-**** Protocol sub-goal 3: send a packet
+10) i?,i?,msg8,A,B,nA,nB,msg?
+
+This is an obsolete form of NAK packet which is not sent by any even
+vaguely recent version of secnet. (In fact, there is no evidence in
+the git history of it ever being sent.)
-9) i?,i?,msg0,(send-packet/msg9,packet)_k
+This message number is reserved.
~ian / secnet.git / blobdiff