Specify circuit test messages.

1 files changed, 167 insertions, 5 deletions

diff --git a/node/Packet.hpp b/node/Packet.hpp
index fa377964..2d439b11 100644
--- a/node/Packet.hpp
+++ b/node/Packet.hpp
@@ -553,10 +553,10 @@ public:
 		 * address that require re-establishing connectivity.
 		 *
 		 * Destination address types and formats (not all of these are used now):
-		 *   0 - None -- no destination address data present
-		 *   1 - Ethernet address -- format: <[6] Ethernet MAC>
-		 *   4 - 6-byte IPv4 UDP address/port -- format: <[4] IP>, <[2] port>
-		 *   6 - 18-byte IPv6 UDP address/port -- format: <[16] IP>, <[2] port>
+		 *   0x00 - None -- no destination address data present
+		 *   0x01 - Ethernet address -- format: <[6] Ethernet MAC>
+		 *   0x04 - 6-byte IPv4 UDP address/port -- format: <[4] IP>, <[2] port>
+		 *   0x06 - 18-byte IPv6 UDP address/port -- format: <[16] IP>, <[2] port>
 		 *
 		 * OK payload:
 		 *   <[8] timestamp (echoed from original HELLO)>
@@ -904,7 +904,169 @@ public:
 		 *
 		 * OK and ERROR are not generated.
 		 */
-		VERB_PUSH_DIRECT_PATHS = 16
+		VERB_PUSH_DIRECT_PATHS = 16,
+
+		/* Source-routed circuit test message:
+		 *   <[5] address of originator of circuit test>
+		 *   <[2] 16-bit flags>
+		 *   <[8] 64-bit timestamp>
+		 *   <[8] 64-bit test ID (arbitrary, set by tester)>
+		 *   <[1] originator credential type (for authorizing test)>
+		 *   <[...] credential>
+		 *   <[2] 16-bit length of additional fields>
+		 *   <[...] additional fields>
+		 *   <[2] 16-bit length of signature of request>
+		 *   <[...] signature of request by originator>
+		 *   <[1] previous hop credential type>
+		 *   <[...] previous hop credential>
+		 *   <[...] next hop(s) in path>
+		 *
+		 * Flags:
+		 *   0x01 - Report back to originator at each hop
+		 *   0x02 - Report back to originator at last hop
+		 *
+		 * Originator credential types:
+		 *   0x00 - No credentials included
+		 *   0x01 - 64-bit network ID for which originator is controller
+		 *
+		 * Previous hop credential types:
+		 *   0x00 - No credentials included
+		 *   0x01 - Certificate of network membership
+		 *
+		 * Path record format:
+		 *   <[1] 8-bit flags>
+		 *   <[1] 8-bit breadth (number of next hops)>
+		 *   <[...] one or more ZeroTier addresses of next hops>
+		 *
+		 * Path record flags (in each path record):
+		 *   0x80 - End of path (should be set on last entry)
+		 *
+		 * The circuit test allows a device to send a message that will traverse
+		 * the network along a specified path, with each hop optionally reporting
+		 * back to the tester via VERB_CIRCUIT_TEST_REPORT.
+		 *
+		 * Each circuit test packet includes a digital signature by the originator
+		 * of the request, as well as a credential by which that originator claims
+		 * authorization to perform the test. Currently this signature is ed25519,
+		 * but in the future flags might be used to indicate an alternative
+		 * algorithm. For example, the originator might be a network controller.
+		 * In this case the test might be authorized if the recipient is a member
+		 * of a network controlled by it, and if the previous hop(s) are also
+		 * members. Each hop may include its certificate of network membership.
+		 *
+		 * Circuit test paths consist of a series of records. When a node receives
+		 * an authorized circuit test, it:
+		 *
+		 * (1) Reports back to circuit tester as flags indicate
+		 * (2) Reads and removes the next hop from the packet's path
+		 * (3) Sends the packet along to next hop(s), if any.
+		 *
+		 * It is perfectly legal for a path to contain the same hop more than
+		 * once. In fact, this can be a very useful test to determine if a hop
+		 * can be reached bidirectionally and if so what that connectivity looks
+		 * like.
+		 *
+		 * The breadth field in source-routed path records allows a hop to forward
+		 * to more than one recipient, allowing the tester to specify different
+		 * forms of graph traversal in a test.
+		 *
+		 * There is no hard limit to the number of hops in a test, but it is
+		 * practically limited by the maximum size of a (possibly fragmented)
+		 * ZeroTier packet.
+		 *
+		 * Support for circuit tests is optional. If they are not supported, the
+		 * node should respond with an UNSUPPORTED_OPERATION error. If a circuit
+		 * test request is not authorized, it may be ignored or reported as
+		 * an INVALID_REQUEST. No OK messages are generated, but TEST_REPORT
+		 * messages may be sent (see below).
+		 *
+		 * ERROR packet format:
+		 *   <[8] 64-bit timestamp (echoed from original>
+		 *   <[8] 64-bit test ID (echoed from original)>
+		 */
+		VERB_CIRCUIT_TEST = 17,
+
+		/* 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)>
+		 *   <[1] 8-bit vendor ID (set to 0, currently unused)>
+		 *   <[1] 8-bit reporter protocol version>
+		 *   <[1] 8-bit reporter major version>
+		 *   <[1] 8-bit reporter minor version>
+		 *   <[2] 16-bit reporter revision>
+		 *   <[2] 16-bit reporter OS/platform>
+		 *   <[2] 16-bit reporter architecture>
+		 *   <[2] 16-bit error code (set to 0, currently unused)>
+		 *   <[8] 64-bit report flags>
+		 *   <[8] 64-bit source packet ID>
+		 *   <[1] 8-bit source packet hop count>
+		 *   <[1] 8-bit source address type>
+		 *   [<[...] source address>]
+		 *   <[2] 16-bit length of network information>
+		 *   <[...] network information>
+		 *   <[2] 16-bit length of additional fields>
+		 *   <[...] additional fields>
+		 *   <[2] 16-bit number of next hops to which something is being sent>
+		 *   <[...] next hop information>
+		 *
+		 * Circuit test report flags:
+		 *   (currently none, must be zero)
+		 *
+		 * Next hop information record format:
+		 *   <[5] ZeroTier address of next hop>
+		 *   <[1] 8-bit destination wire address type>
+		 *   <[...] destination wire address>
+		 *
+		 * See enums below for OS/platform and architecture. Source address format
+		 * is the same as specified in HELLO.
+		 *
+		 * Circuit test reports can be sent by hops in a circuit test to report
+		 * back results. They should include information about the sender as well
+		 * as about the paths to which next hops are being sent.
+		 *
+		 * 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
+	};
+
+	/**
+	 * Platforms reported in circuit tests
+	 */
+	enum CircuitTestReportPlatform
+	{
+		CIRCUIT_TEST_REPORT_PLATFORM_UNSPECIFIED = 0,
+		CIRCUIT_TEST_REPORT_PLATFORM_LINUX = 1,
+		CIRCUIT_TEST_REPORT_PLATFORM_WINDOWS = 2,
+		CIRCUIT_TEST_REPORT_PLATFORM_MACOS = 3,
+		CIRCUIT_TEST_REPORT_PLATFORM_ANDROID = 4,
+		CIRCUIT_TEST_REPORT_PLATFORM_IOS = 5,
+		CIRCUIT_TEST_REPORT_PLATFORM_SOLARIS_SMARTOS = 6,
+		CIRCUIT_TEST_REPORT_PLATFORM_FREEBSD = 7,
+		CIRCUIT_TEST_REPORT_PLATFORM_NETBSD = 8,
+		CIRCUIT_TEST_REPORT_PLATFORM_OPENBSD = 9,
+		CIRCUIT_TEST_REPORT_PLATFORM_RISCOS = 10,
+		CIRCUIT_TEST_REPORT_PLATFORM_VXWORKS = 11,
+		CIRCUIT_TEST_REPORT_PLATFORM_FREERTOS = 12,
+		CIRCUIT_TEST_REPORT_PLATFORM_SYSBIOS = 13,
+		CIRCUIT_TEST_REPORT_PLATFORM_HURD = 14
+	};
+
+	/**
+	 * Architectures reported in circuit tests
+	 */
+	enum CircuitTestReportArchitecture
+	{
+		CIRCUIT_TEST_REPORT_ARCH_UNSPECIFIED = 0,
+		CIRCUIT_TEST_REPORT_ARCH_X86 = 1,
+		CIRCUIT_TEST_REPORT_ARCH_X64 = 2,
+		CIRCUIT_TEST_REPORT_ARCH_ARM32 = 3,
+		CIRCUIT_TEST_REPORT_ARCH_ARM64 = 4,
+		CIRCUIT_TEST_REPORT_ARCH_MIPS32 = 5,
+		CIRCUIT_TEST_REPORT_ARCH_MIPS64 = 6,
+		CIRCUIT_TEST_REPORT_ARCH_POWER32 = 7,
+		CIRCUIT_TEST_REPORT_ARCH_POWER64 = 8
 	};
 
 	/**