Document how the pass 1 implementation will operate.

pass-1/README.txt

@@ -0,0 +1,70 @@
+Pass 1
+======
+
+This pass consists of proof-of-concept code. The intent is to implement it as 
+quickly as possible, then refine it until we have code that scales to the level
+of "small ISP" - say, 1Gbit/sec - without a  ridiculous investment in hardware. 
+
+
+rloc-registry
+=============
+The "registry" is a plain file, with the canonical version administered
+centrally. It maps IP ranges to RLOCs, and stores the public key to use with
+each RLOC. Both wrapper and unwrapper need a copy of this file to work. We also
+include a tiny library for reading it. 
+
+wrapper
+=======
+The wrapper operates by taking the entire contents of the RLOC registry on
+startup, along with information about which RLOC(s) it is in, and which IP it is
+running on. It then drops a bgpfeeder-suitable file on disc that  will redirect
+all the EIDs in the rloc registry to its IP address, and waits for packets.
+
+Every time a packet comes in, wrapper reads it, then constructs and emits a
+corresponding wrapped packet. Probably using pcap to start.
+
+Don't bother implementing RLOC pools for ICMP yet. 
+
+unwrapper
+=========
+This component is fed a private key, and told which RLOC(s) to listen on. It
+dumps a bgpfeeder-compatible file to disc directing those RLOCs to it, then
+(again, probably using pcap) waits for wrapped packets to come to it. As it
+receives them, it decrypts them with the private key, then constructs the
+unwrapped equivalent and forwards it on.
+
+
+bgpfeeder
+=========
+This is a simple program that implements the BGP protocol. It's already written,
+and works. we use BGP to redirect traffic from the ISP core routers to the
+wrapping / unwrapping boxes because they already speak it. We use bgpfeeder
+because it already exists :)
+
+
+wrapper/unwrapper protocol
+==========================
+
+When we say "wrapper encrypts", "unwrapper decrypts" or "wrapped packet",
+there's an implicit protocol there. This is, more or less, it.
+
+First, the IP header the wrapper constructs sets the Protocol field to 253. We
+don't have an assigned number yet. This should be fine.
+
+The payload of this IP packet is the encrypted + unencrypted (if any) portion
+of the packet, prepended by 16 bits that are interpreted as the encrypted
+payload length.
+
+The wrapper encrypts either the IP header, or the entire IP packet (depending on
+setting). It takes the encrypted blob, plus the part of the packet (if any)
+that has been left out of the encryped part, adds 2 to the length, and sets that
+number as the wrapping IP header's payload length. It then writes the length of
+the encrypted portion of the total payload as the first 2 bytes of the payload,
+followed by the constructed blob. 
+
+The unwrapper receives the packet, reads the IP header, then reads the next two
+bytes. It takes the first n bytes of the remainder of the payload and decrypts
+it, then prepends that to the remaining bytes. What it ends up with should be a
+valid IP packet. It then alters the packet's TTL according to the wrapping
+packet's TTL field, and forwards it for further routing. 
+