MERGE current "dev" into "netcon" -- should not affect netcon itself but will retest -- brings ZeroTier core up to 1.1.0

1 files changed, 143 insertions, 64 deletions

diff --git a/node/Packet.hpp b/node/Packet.hpp
index 409762c7..ef0251e3 100644
--- a/node/Packet.hpp
+++ b/node/Packet.hpp
@@ -46,22 +46,24 @@
 #include "../ext/lz4/lz4.h"
 
 /**
- * Protocol version -- incremented only for MAJOR changes
+ * Protocol version -- incremented only for major changes
  *
  * 1 - 0.2.0 ... 0.2.5
  * 2 - 0.3.0 ... 0.4.5
- *   * Added signature and originating peer to multicast frame
- *   * Double size of multicast frame bloom filter
+ *   + Added signature and originating peer to multicast frame
+ *   + Double size of multicast frame bloom filter
  * 3 - 0.5.0 ... 0.6.0
- *   * Yet another multicast redesign
- *   * New crypto completely changes key agreement cipher
- * 4 - 0.6.0 ... CURRENT
- *   * New identity format based on hashcash design
- *
- * This isn't going to change again for a long time unless your
- * author wakes up again at 4am with another great idea. :P
+ *   + Yet another multicast redesign
+ *   + New crypto completely changes key agreement cipher
+ * 4 - 0.6.0 ... 1.0.6
+ *   + New identity format based on hashcash design
+ * 5 - 1.1.0 ... CURRENT
+ *   + Supports circuit test, proof of work, and echo
+ *   + Supports in-band world (root server definition) updates
+ *   + Clustering! (Though this will work with protocol v4 clients.)
+ *   + Otherwise backward compatible with protocol v4
  */
-#define ZT_PROTO_VERSION 4
+#define ZT_PROTO_VERSION 5
 
 /**
  * Minimum supported protocol version
@@ -233,15 +235,6 @@
  */
 #define ZT_PROTO_MIN_FRAGMENT_LENGTH ZT_PACKET_FRAGMENT_IDX_PAYLOAD
 
-// Destination address types from HELLO, OK(HELLO), and other message types
-#define ZT_PROTO_DEST_ADDRESS_TYPE_NONE 0
-#define ZT_PROTO_DEST_ADDRESS_TYPE_ZEROTIER 1   // reserved but unused
-#define ZT_PROTO_DEST_ADDRESS_TYPE_ETHERNET 2   // future use
-#define ZT_PROTO_DEST_ADDRESS_TYPE_BLUETOOTH 3  // future use
-#define ZT_PROTO_DEST_ADDRESS_TYPE_IPV4 4
-#define ZT_PROTO_DEST_ADDRESS_TYPE_LTE_DIRECT 5 // future use
-#define ZT_PROTO_DEST_ADDRESS_TYPE_IPV6 6
-
 // Ephemeral key record flags
 #define ZT_PROTO_EPHEMERAL_KEY_FLAG_FIPS 0x01   // future use
 
@@ -329,8 +322,6 @@
 
 #define ZT_PROTO_VERB_WHOIS__OK__IDX_IDENTITY (ZT_PROTO_VERB_OK_IDX_PAYLOAD)
 
-#define ZT_PROTO_VERB_WHOIS__ERROR__IDX_ZTADDRESS (ZT_PROTO_VERB_ERROR_IDX_PAYLOAD)
-
 #define ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST__OK__IDX_NETWORK_ID (ZT_PROTO_VERB_OK_IDX_PAYLOAD)
 #define ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST__OK__IDX_DICT_LEN (ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST__OK__IDX_NETWORK_ID + 8)
 #define ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST__OK__IDX_DICT (ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST__OK__IDX_DICT_LEN + 2)
@@ -354,11 +345,11 @@ namespace ZeroTier {
  * ZeroTier packet
  *
  * Packet format:
- *   <[8] random initialization vector (doubles as 64-bit packet ID)>
+ *   <[8] 64-bit random packet ID and crypto initialization vector>
  *   <[5] destination ZT address>
  *   <[5] source ZT address>
  *   <[1] flags/cipher (top 5 bits) and ZT hop count (last 3 bits)>
- *   <[8] 8-bit MAC (currently first 8 bytes of poly1305 tag)>
+ *   <[8] 64-bit MAC>
  *   [... -- begin encryption envelope -- ...]
  *   <[1] encrypted flags (top 3 bits) and verb (last 5 bits)>
  *   [... verb-specific payload ...]
@@ -374,6 +365,10 @@ namespace ZeroTier {
  * immutable. This is because intermediate nodes can increment the hop
  * count up to 7 (protocol max).
  *
+ * A hop count of 7 also indicates that receiving peers should not attempt
+ * to learn direct paths from this packet. (Right now direct paths are only
+ * learned from direct packets anyway.)
+ *
  * http://tonyarcieri.com/all-the-crypto-code-youve-ever-written-is-probably-broken
  *
  * For unencrypted packets, MAC is computed on plaintext. Only HELLO is ever
@@ -530,10 +525,13 @@ public:
 	 */
 	enum Verb /* Max value: 32 (5 bits) */
 	{
-		/* No operation, payload ignored, no reply */
+		/**
+		 * No operation (ignored, no reply)
+		 */
 		VERB_NOP = 0,
 
-		/* Announcement of a node's existence:
+		/**
+		 * Announcement of a node's existence:
 		 *   <[1] protocol version>
 		 *   <[1] software major version>
 		 *   <[1] software minor version>
@@ -542,6 +540,8 @@ public:
 		 *   <[...] binary serialized identity (see Identity)>
 		 *   <[1] destination address type>
 		 *   [<[...] destination address>]
+		 *   <[8] 64-bit world ID of current world>
+		 *   <[8] 64-bit timestamp of current world>
 		 *
 		 * This is the only message that ever must be sent in the clear, since it
 		 * is used to push an identity to a new peer.
@@ -566,12 +566,15 @@ public:
 		 *   <[2] software revision (of responder)>
 		 *   <[1] destination address type (for this OK, not copied from HELLO)>
 		 *   [<[...] destination address>]
+		 *   <[2] 16-bit length of world update or 0 if none>
+		 *   [[...] world update]
 		 *
 		 * ERROR has no payload.
 		 */
 		VERB_HELLO = 1,
 
-		/* Error response:
+		/**
+		 * Error response:
 		 *   <[1] in-re verb>
 		 *   <[8] in-re packet ID>
 		 *   <[1] error code>
@@ -579,25 +582,31 @@ public:
 		 */
 		VERB_ERROR = 2,
 
-		/* Success response:
+		/**
+		 * Success response:
 		 *   <[1] in-re verb>
 		 *   <[8] in-re packet ID>
 		 *   <[...] request-specific payload>
 		 */
 		VERB_OK = 3,
 
-		/* Query an identity by address:
+		/**
+		 * Query an identity by address:
 		 *   <[5] address to look up>
 		 *
 		 * OK response payload:
 		 *   <[...] binary serialized identity>
 		 *
-		 * ERROR response payload:
-		 *   <[5] address>
+		 * If querying a cluster, duplicate OK responses may occasionally occur.
+		 * These should be discarded.
+		 *
+		 * If the address is not found, no response is generated. WHOIS requests
+		 * will time out much like ARP requests and similar do in L2.
 		 */
 		VERB_WHOIS = 4,
 
-		/* Meet another node at a given protocol address:
+		/**
+		 * Meet another node at a given protocol address:
 		 *   <[1] flags (unused, currently 0)>
 		 *   <[5] ZeroTier address of peer that might be found at this address>
 		 *   <[2] 16-bit protocol address port>
@@ -616,11 +625,16 @@ public:
 		 * may also ignore these messages if a peer is not known or is not being
 		 * actively communicated with.
 		 *
+		 * Unfortunately the physical address format in this message pre-dates
+		 * InetAddress's serialization format. :( ZeroTier is four years old and
+		 * yes we've accumulated a tiny bit of cruft here and there.
+		 *
 		 * No OK or ERROR is generated.
 		 */
 		VERB_RENDEZVOUS = 5,
 
-		/* ZT-to-ZT unicast ethernet frame (shortened EXT_FRAME):
+		/**
+		 * ZT-to-ZT unicast ethernet frame (shortened EXT_FRAME):
 		 *   <[8] 64-bit network ID>
 		 *   <[2] 16-bit ethertype>
 		 *   <[...] ethernet payload>
@@ -635,7 +649,8 @@ public:
 		 */
 		VERB_FRAME = 6,
 
-		/* Full Ethernet frame with MAC addressing and optional fields:
+		/**
+		 * Full Ethernet frame with MAC addressing and optional fields:
 		 *   <[8] 64-bit network ID>
 		 *   <[1] flags>
 		 *  [<[...] certificate of network membership>]
@@ -658,23 +673,44 @@ public:
 		 */
 		VERB_EXT_FRAME = 7,
 
-		/* DEPRECATED */
-		VERB_P5_MULTICAST_FRAME = 8,
+		/**
+		 * ECHO request (a.k.a. ping):
+		 *   <[...] arbitrary payload to be echoed back>
+		 *
+		 * This generates OK with a copy of the transmitted payload. No ERROR
+		 * is generated. Response to ECHO requests is optional.
+		 *
+		 * Support for fragmented echo packets is optional and their use is not
+		 * recommended.
+		 */
+		VERB_ECHO = 8,
 
-		/* Announce interest in multicast group(s):
+		/**
+		 * Announce interest in multicast group(s):
 		 *   <[8] 64-bit network ID>
 		 *   <[6] multicast Ethernet address>
 		 *   <[4] multicast additional distinguishing information (ADI)>
 		 *   [... additional tuples of network/address/adi ...]
 		 *
-		 * LIKEs are sent to peers with whom you have a direct peer to peer
-		 * connection, and always including root servers.
+		 * LIKEs may be sent to any peer, though a good implementation should
+		 * restrict them to peers on the same network they're for and to network
+		 * controllers and root servers. In the current network, root servers
+		 * will provide the service of final multicast cache.
+		 *
+		 * It is recommended that NETWORK_MEMBERSHIP_CERTIFICATE pushes be sent
+		 * along with MULTICAST_LIKE when pushing LIKEs to peers that do not
+		 * share a network membership (such as root servers), since this can be
+		 * used to authenticate GATHER requests and limit responses to peers
+		 * authorized to talk on a network. (Should be an optional field here,
+		 * but saving one or two packets every five minutes is not worth an
+		 * ugly hack or protocol rev.)
 		 *
 		 * OK/ERROR are not generated.
 		 */
 		VERB_MULTICAST_LIKE = 9,
 
-		/* Network member certificate replication/push:
+		/**
+		 * Network member certificate replication/push:
 		 *   <[...] serialized certificate of membership>
 		 *   [ ... additional certificates may follow ...]
 		 *
@@ -685,7 +721,8 @@ public:
 		 */
 		VERB_NETWORK_MEMBERSHIP_CERTIFICATE = 10,
 
-		/* Network configuration request:
+		/**
+		 * Network configuration request:
 		 *   <[8] 64-bit network ID>
 		 *   <[2] 16-bit length of request meta-data dictionary>
 		 *   <[...] string-serialized request meta-data>
@@ -720,7 +757,8 @@ public:
 		 */
 		VERB_NETWORK_CONFIG_REQUEST = 11,
 
-		/* Network configuration refresh request:
+		/**
+		 * Network configuration refresh request:
 		 *   <[...] array of 64-bit network IDs>
 		 *
 		 * This can be sent by the network controller to inform a node that it
@@ -731,7 +769,8 @@ public:
 		 */
 		VERB_NETWORK_CONFIG_REFRESH = 12,
 
-		/* Request endpoints for multicast distribution:
+		/**
+		 * Request endpoints for multicast distribution:
 		 *   <[8] 64-bit network ID>
 		 *   <[1] flags>
 		 *   <[6] MAC address of multicast group being queried>
@@ -747,6 +786,9 @@ public:
 		 * to send multicast but does not have the desired number of recipient
 		 * peers.
 		 *
+		 * More than one OK response can occur if the response is broken up across
+		 * multiple packets or if querying a clustered node.
+		 *
 		 * OK response payload:
 		 *   <[8] 64-bit network ID>
 		 *   <[6] MAC address of multicast group being queried>
@@ -756,20 +798,12 @@ public:
 		 *   <[2] 16-bit number of members enumerated in this packet>
 		 *   <[...] series of 5-byte ZeroTier addresses of enumerated members>
 		 *
-		 * If no endpoints are known, OK and ERROR are both optional. It's okay
-		 * to return nothing in that case since gathering is "lazy."
-		 *
-		 * ERROR response payload:
-		 *   <[8] 64-bit network ID>
-		 *   <[6] MAC address of multicast group being queried>
-		 *   <[4] 32-bit ADI for multicast group being queried>
-		 *
-		 * ERRORs are optional and are only generated if permission is denied,
-		 * certificate of membership is out of date, etc.
+		 * ERROR is not generated; queries that return no response are dropped.
 		 */
 		VERB_MULTICAST_GATHER = 13,
 
-		/* Multicast frame:
+		/**
+		 * Multicast frame:
 		 *   <[8] 64-bit network ID>
 		 *   <[1] flags>
 		 *  [<[...] network certificate of membership>]
@@ -810,7 +844,8 @@ public:
 		 */
 		VERB_MULTICAST_FRAME = 14,
 
-		/* Ephemeral (PFS) key push: (UNFINISHED, NOT IMPLEMENTED YET)
+		/**
+		 * Ephemeral (PFS) key push: (UNFINISHED, NOT IMPLEMENTED YET)
 		 *   <[2] flags (unused and reserved, must be 0)>
 		 *   <[2] length of padding / extra field section>
 		 *   <[...] padding / extra field section>
@@ -866,7 +901,8 @@ public:
 		 */
 		VERB_SET_EPHEMERAL_KEY = 15,
 
-		/* Push of potential endpoints for direct communication:
+		/**
+		 * Push of potential endpoints for direct communication:
 		 *   <[2] 16-bit number of paths>
 		 *   <[...] paths>
 		 *
@@ -880,13 +916,10 @@ public:
 		 *
 		 * Path record flags:
 		 *   0x01 - Forget this path if it is currently known
-		 *   0x02 - Blacklist this path, do not use
+		 *   0x02 - (Unused)
 		 *   0x04 - Disable encryption (trust: privacy)
 		 *   0x08 - Disable encryption and authentication (trust: ultimate)
 		 *
-		 * Address types and addresses are of the same format as the destination
-		 * address type and address in HELLO.
-		 *
 		 * The receiver may, upon receiving a push, attempt to establish a
 		 * direct link to one or more of the indicated addresses. It is the
 		 * responsibility of the sender to limit which peers it pushes direct
@@ -906,7 +939,8 @@ public:
 		 */
 		VERB_PUSH_DIRECT_PATHS = 16,
 
-		/* Source-routed circuit test message:
+		/**
+		 * Source-routed circuit test message:
 		 *   <[5] address of originator of circuit test>
 		 *   <[2] 16-bit flags>
 		 *   <[8] 64-bit timestamp>
@@ -984,7 +1018,8 @@ public:
 		 */
 		VERB_CIRCUIT_TEST = 17,
 
-		/* Circuit test hop report:
+		/**
+		 * Circuit test hop report:
 		 *   <[8] 64-bit timestamp (from original test)>
 		 *   <[8] 64-bit test ID (from original test)>
 		 *   <[8] 64-bit reporter timestamp (reporter's clock, 0 if unspec)>
@@ -998,6 +1033,7 @@ public:
 		 *   <[2] 16-bit error code (set to 0, currently unused)>
 		 *   <[8] 64-bit report flags (set to 0, currently unused)>
 		 *   <[8] 64-bit source packet ID>
+		 *   <[5] upstream ZeroTier address from which test was received>
 		 *   <[1] 8-bit source packet hop count (ZeroTier hop count)>
 		 *   <[...] local wire address on which packet was received>
 		 *   <[...] remote wire address from which packet was received>
@@ -1017,7 +1053,50 @@ public:
 		 * If a test report is received and no circuit test was sent, it should be
 		 * ignored. This message generates no OK or ERROR response.
 		 */
-		VERB_CIRCUIT_TEST_REPORT = 18
+		VERB_CIRCUIT_TEST_REPORT = 18,
+
+		/**
+		 * Request proof of work:
+		 *   <[1] 8-bit proof of work type>
+		 *   <[1] 8-bit proof of work difficulty>
+		 *   <[2] 16-bit length of proof of work challenge>
+		 *   <[...] proof of work challenge>
+		 *
+		 * This requests that a peer perform a proof of work calucation. It can be
+		 * sent by highly trusted peers (e.g. root servers, network controllers)
+		 * under suspected denial of service conditions in an attempt to filter
+		 * out "non-serious" peers and remain responsive to those proving their
+		 * intent to actually communicate.
+		 *
+		 * If the peer obliges to perform the work, it does so and responds with
+		 * an OK containing the result. Otherwise it may ignore the message or
+		 * response with an ERROR_INVALID_REQUEST or ERROR_UNSUPPORTED_OPERATION.
+		 *
+		 * Proof of work type IDs:
+		 *   0x01 - Salsa20/12+SHA512 hashcash function
+		 *
+		 * Salsa20/12+SHA512 is based on the following composite hash function:
+		 *
+		 * (1) Compute SHA512(candidate)
+		 * (2) Use the first 256 bits of the result of #1 as a key to encrypt
+		 *     131072 zero bytes with Salsa20/12 (with a zero IV).
+		 * (3) Compute SHA512(the result of step #2)
+		 * (4) Accept this candiate if the first [difficulty] bits of the result
+		 *     from step #3 are zero. Otherwise generate a new candidate and try
+		 *     again.
+		 *
+		 * This is performed repeatedly on candidates generated by appending the
+		 * supplied challenge to an arbitrary nonce until a valid candidate
+		 * is found. This chosen prepended nonce is then returned as the result
+		 * in OK.
+		 *
+		 * OK payload:
+		 *   <[2] 16-bit length of result>
+		 *   <[...] computed proof of work>
+		 *
+		 * ERROR has no payload.
+		 */
+		VERB_REQUEST_PROOF_OF_WORK = 19
 	};
 
 	/**
@@ -1034,7 +1113,7 @@ public:
 		/* Bad/unsupported protocol version */
 		ERROR_BAD_PROTOCOL_VERSION = 2,
 
-		/* Unknown object queried (e.g. with WHOIS) */
+		/* Unknown object queried */
 		ERROR_OBJ_NOT_FOUND = 3,
 
 		/* HELLO pushed an identity whose address is already claimed */