Packet.hpp 52 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391
  1. /*
  2. * ZeroTier One - Network Virtualization Everywhere
  3. * Copyright (C) 2011-2016 ZeroTier, Inc. https://www.zerotier.com/
  4. *
  5. * This program is free software: you can redistribute it and/or modify
  6. * it under the terms of the GNU General Public License as published by
  7. * the Free Software Foundation, either version 3 of the License, or
  8. * (at your option) any later version.
  9. *
  10. * This program is distributed in the hope that it will be useful,
  11. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13. * GNU General Public License for more details.
  14. *
  15. * You should have received a copy of the GNU General Public License
  16. * along with this program. If not, see <http://www.gnu.org/licenses/>.
  17. */
  18. #ifndef ZT_N_PACKET_HPP
  19. #define ZT_N_PACKET_HPP
  20. #include <stdint.h>
  21. #include <string.h>
  22. #include <stdio.h>
  23. #include <string>
  24. #include <iostream>
  25. #include "Constants.hpp"
  26. #include "Address.hpp"
  27. #include "Poly1305.hpp"
  28. #include "Salsa20.hpp"
  29. #include "Utils.hpp"
  30. #include "Buffer.hpp"
  31. #ifdef ZT_USE_SYSTEM_LZ4
  32. #include <lz4.h>
  33. #else
  34. #include "../ext/lz4/lz4.h"
  35. #endif
  36. /**
  37. * Protocol version -- incremented only for major changes
  38. *
  39. * 1 - 0.2.0 ... 0.2.5
  40. * 2 - 0.3.0 ... 0.4.5
  41. * + Added signature and originating peer to multicast frame
  42. * + Double size of multicast frame bloom filter
  43. * 3 - 0.5.0 ... 0.6.0
  44. * + Yet another multicast redesign
  45. * + New crypto completely changes key agreement cipher
  46. * 4 - 0.6.0 ... 1.0.6
  47. * + BREAKING CHANGE: New identity format based on hashcash design
  48. * 5 - 1.1.0 ... 1.1.5
  49. * + Supports circuit test, proof of work, and echo
  50. * + Supports in-band world (root server definition) updates
  51. * + Clustering! (Though this will work with protocol v4 clients.)
  52. * + Otherwise backward compatible with protocol v4
  53. * 6 - 1.1.5 ... 1.1.10
  54. * + Network configuration format revisions including binary values
  55. * 7 - 1.1.10 -- 1.2.0
  56. * + Introduce trusted paths for local SDN use
  57. * 8 - 1.2.0 -- CURRENT
  58. * + Multipart network configurations for large network configs
  59. * + Tags and Capabilities
  60. * + Inline push of CertificateOfMembership deprecated
  61. * + Certificates of representation for federation and mesh
  62. */
  63. #define ZT_PROTO_VERSION 8
  64. /**
  65. * Minimum supported protocol version
  66. */
  67. #define ZT_PROTO_VERSION_MIN 4
  68. /**
  69. * Maximum hop count allowed by packet structure (3 bits, 0-7)
  70. *
  71. * This is a protocol constant. It's the maximum allowed by the length
  72. * of the hop counter -- three bits. See node/Constants.hpp for the
  73. * pragmatic forwarding limit, which is typically lower.
  74. */
  75. #define ZT_PROTO_MAX_HOPS 7
  76. /**
  77. * Cipher suite: Curve25519/Poly1305/Salsa20/12/NOCRYPT
  78. *
  79. * This specifies Poly1305 MAC using a 32-bit key derived from the first
  80. * 32 bytes of a Salsa20/12 keystream as in the Salsa20/12 cipher suite,
  81. * but the payload is not encrypted. This is currently only used to send
  82. * HELLO since that's the public key specification packet and must be
  83. * sent in the clear. Key agreement is performed using Curve25519 elliptic
  84. * curve Diffie-Hellman.
  85. */
  86. #define ZT_PROTO_CIPHER_SUITE__C25519_POLY1305_NONE 0
  87. /**
  88. * Cipher suite: Curve25519/Poly1305/Salsa20/12
  89. *
  90. * This specifies Poly1305 using the first 32 bytes of a Salsa20/12 key
  91. * stream as its one-time-use key followed by payload encryption with
  92. * the remaining Salsa20/12 key stream. Key agreement is performed using
  93. * Curve25519 elliptic curve Diffie-Hellman.
  94. */
  95. #define ZT_PROTO_CIPHER_SUITE__C25519_POLY1305_SALSA2012 1
  96. /**
  97. * Cipher suite: NONE
  98. *
  99. * This differs from POLY1305/NONE in that *no* crypto is done, not even
  100. * authentication. This is for trusted local LAN interconnects for internal
  101. * SDN use within a data center.
  102. *
  103. * For this mode the MAC field becomes a trusted path ID and must match the
  104. * configured ID of a trusted path or the packet is discarded.
  105. */
  106. #define ZT_PROTO_CIPHER_SUITE__NO_CRYPTO_TRUSTED_PATH 2
  107. /**
  108. * DEPRECATED payload encrypted flag, may be re-used in the future.
  109. *
  110. * This has been replaced by the three-bit cipher suite selection field.
  111. */
  112. #define ZT_PROTO_FLAG_ENCRYPTED 0x80
  113. /**
  114. * Header flag indicating that a packet is fragmented
  115. *
  116. * If this flag is set, the receiver knows to expect more than one fragment.
  117. * See Packet::Fragment for details.
  118. */
  119. #define ZT_PROTO_FLAG_FRAGMENTED 0x40
  120. /**
  121. * Verb flag indicating payload is compressed with LZ4
  122. */
  123. #define ZT_PROTO_VERB_FLAG_COMPRESSED 0x80
  124. /**
  125. * Rounds used for Salsa20 encryption in ZT
  126. *
  127. * Discussion:
  128. *
  129. * DJB (Salsa20's designer) designed Salsa20 with a significant margin of 20
  130. * rounds, but has said repeatedly that 12 is likely sufficient. So far (as of
  131. * July 2015) there are no published attacks against 12 rounds, let alone 20.
  132. *
  133. * In cryptography, a "break" means something different from what it means in
  134. * common discussion. If a cipher is 256 bits strong and someone finds a way
  135. * to reduce key search to 254 bits, this constitues a "break" in the academic
  136. * literature. 254 bits is still far beyond what can be leveraged to accomplish
  137. * a "break" as most people would understand it -- the actual decryption and
  138. * reading of traffic.
  139. *
  140. * Nevertheless, "attacks only get better" as cryptographers like to say. As
  141. * a result, they recommend not using anything that's shown any weakness even
  142. * if that weakness is so far only meaningful to academics. It may be a sign
  143. * of a deeper problem.
  144. *
  145. * So why choose a lower round count?
  146. *
  147. * Turns out the speed difference is nontrivial. On a Macbook Pro (Core i3) 20
  148. * rounds of SSE-optimized Salsa20 achieves ~508mb/sec/core, while 12 rounds
  149. * hits ~832mb/sec/core. ZeroTier is designed for multiple objectives:
  150. * security, simplicity, and performance. In this case a deference was made
  151. * for performance.
  152. *
  153. * Meta discussion:
  154. *
  155. * The cipher is not the thing you should be paranoid about.
  156. *
  157. * I'll qualify that. If the cipher is known to be weak, like RC4, or has a
  158. * key size that is too small, like DES, then yes you should worry about
  159. * the cipher.
  160. *
  161. * But if the cipher is strong and your adversary is anyone other than the
  162. * intelligence apparatus of a major superpower, you are fine in that
  163. * department.
  164. *
  165. * Go ahead. Search for the last ten vulnerabilities discovered in SSL. Not
  166. * a single one involved the breaking of a cipher. Now broaden your search.
  167. * Look for issues with SSH, IPSec, etc. The only cipher-related issues you
  168. * will find might involve the use of RC4 or MD5, algorithms with known
  169. * issues or small key/digest sizes. But even weak ciphers are difficult to
  170. * exploit in the real world -- you usually need a lot of data and a lot of
  171. * compute time. No, virtually EVERY security vulnerability you will find
  172. * involves a problem with the IMPLEMENTATION not with the cipher.
  173. *
  174. * A flaw in ZeroTier's protocol or code is incredibly, unbelievably
  175. * more likely than a flaw in Salsa20 or any other cipher or cryptographic
  176. * primitive it uses. We're talking odds of dying in a car wreck vs. odds of
  177. * being personally impacted on the head by a meteorite. Nobody without a
  178. * billion dollar budget is going to break into your network by actually
  179. * cracking Salsa20/12 (or even /8) in the field.
  180. *
  181. * So stop worrying about the cipher unless you are, say, the Kremlin and your
  182. * adversary is the NSA and the GCHQ. In that case... well that's above my
  183. * pay grade. I'll just say defense in depth.
  184. */
  185. #define ZT_PROTO_SALSA20_ROUNDS 12
  186. /**
  187. * PUSH_DIRECT_PATHS flag: forget path
  188. */
  189. #define ZT_PUSH_DIRECT_PATHS_FLAG_FORGET_PATH 0x01
  190. /**
  191. * PUSH_DIRECT_PATHS flag: cluster redirect
  192. */
  193. #define ZT_PUSH_DIRECT_PATHS_FLAG_CLUSTER_REDIRECT 0x02
  194. // Field indexes in packet header
  195. #define ZT_PACKET_IDX_IV 0
  196. #define ZT_PACKET_IDX_DEST 8
  197. #define ZT_PACKET_IDX_SOURCE 13
  198. #define ZT_PACKET_IDX_FLAGS 18
  199. #define ZT_PACKET_IDX_MAC 19
  200. #define ZT_PACKET_IDX_VERB 27
  201. #define ZT_PACKET_IDX_PAYLOAD 28
  202. /**
  203. * Packet buffer size (can be changed)
  204. *
  205. * The current value is big enough for ZT_MAX_PACKET_FRAGMENTS, the pragmatic
  206. * packet fragment limit, times the default UDP MTU. Most packets won't be
  207. * this big.
  208. */
  209. #define ZT_PROTO_MAX_PACKET_LENGTH (ZT_MAX_PACKET_FRAGMENTS * ZT_UDP_DEFAULT_PAYLOAD_MTU)
  210. /**
  211. * Minimum viable packet length (a.k.a. header length)
  212. */
  213. #define ZT_PROTO_MIN_PACKET_LENGTH ZT_PACKET_IDX_PAYLOAD
  214. // Indexes of fields in fragment header
  215. #define ZT_PACKET_FRAGMENT_IDX_PACKET_ID 0
  216. #define ZT_PACKET_FRAGMENT_IDX_DEST 8
  217. #define ZT_PACKET_FRAGMENT_IDX_FRAGMENT_INDICATOR 13
  218. #define ZT_PACKET_FRAGMENT_IDX_FRAGMENT_NO 14
  219. #define ZT_PACKET_FRAGMENT_IDX_HOPS 15
  220. #define ZT_PACKET_FRAGMENT_IDX_PAYLOAD 16
  221. /**
  222. * Magic number found at ZT_PACKET_FRAGMENT_IDX_FRAGMENT_INDICATOR
  223. */
  224. #define ZT_PACKET_FRAGMENT_INDICATOR ZT_ADDRESS_RESERVED_PREFIX
  225. /**
  226. * Minimum viable fragment length
  227. */
  228. #define ZT_PROTO_MIN_FRAGMENT_LENGTH ZT_PACKET_FRAGMENT_IDX_PAYLOAD
  229. // Field incides for parsing verbs -------------------------------------------
  230. // Some verbs have variable-length fields. Those aren't fully defined here
  231. // yet-- instead they are parsed using relative indexes in IncomingPacket.
  232. // See their respective handler functions.
  233. #define ZT_PROTO_VERB_HELLO_IDX_PROTOCOL_VERSION (ZT_PACKET_IDX_PAYLOAD)
  234. #define ZT_PROTO_VERB_HELLO_IDX_MAJOR_VERSION (ZT_PROTO_VERB_HELLO_IDX_PROTOCOL_VERSION + 1)
  235. #define ZT_PROTO_VERB_HELLO_IDX_MINOR_VERSION (ZT_PROTO_VERB_HELLO_IDX_MAJOR_VERSION + 1)
  236. #define ZT_PROTO_VERB_HELLO_IDX_REVISION (ZT_PROTO_VERB_HELLO_IDX_MINOR_VERSION + 1)
  237. #define ZT_PROTO_VERB_HELLO_IDX_TIMESTAMP (ZT_PROTO_VERB_HELLO_IDX_REVISION + 2)
  238. #define ZT_PROTO_VERB_HELLO_IDX_IDENTITY (ZT_PROTO_VERB_HELLO_IDX_TIMESTAMP + 8)
  239. #define ZT_PROTO_VERB_ERROR_IDX_IN_RE_VERB (ZT_PACKET_IDX_PAYLOAD)
  240. #define ZT_PROTO_VERB_ERROR_IDX_IN_RE_PACKET_ID (ZT_PROTO_VERB_ERROR_IDX_IN_RE_VERB + 1)
  241. #define ZT_PROTO_VERB_ERROR_IDX_ERROR_CODE (ZT_PROTO_VERB_ERROR_IDX_IN_RE_PACKET_ID + 8)
  242. #define ZT_PROTO_VERB_ERROR_IDX_PAYLOAD (ZT_PROTO_VERB_ERROR_IDX_ERROR_CODE + 1)
  243. #define ZT_PROTO_VERB_OK_IDX_IN_RE_VERB (ZT_PACKET_IDX_PAYLOAD)
  244. #define ZT_PROTO_VERB_OK_IDX_IN_RE_PACKET_ID (ZT_PROTO_VERB_OK_IDX_IN_RE_VERB + 1)
  245. #define ZT_PROTO_VERB_OK_IDX_PAYLOAD (ZT_PROTO_VERB_OK_IDX_IN_RE_PACKET_ID + 8)
  246. #define ZT_PROTO_VERB_WHOIS_IDX_ZTADDRESS (ZT_PACKET_IDX_PAYLOAD)
  247. #define ZT_PROTO_VERB_RENDEZVOUS_IDX_FLAGS (ZT_PACKET_IDX_PAYLOAD)
  248. #define ZT_PROTO_VERB_RENDEZVOUS_IDX_ZTADDRESS (ZT_PROTO_VERB_RENDEZVOUS_IDX_FLAGS + 1)
  249. #define ZT_PROTO_VERB_RENDEZVOUS_IDX_PORT (ZT_PROTO_VERB_RENDEZVOUS_IDX_ZTADDRESS + 5)
  250. #define ZT_PROTO_VERB_RENDEZVOUS_IDX_ADDRLEN (ZT_PROTO_VERB_RENDEZVOUS_IDX_PORT + 2)
  251. #define ZT_PROTO_VERB_RENDEZVOUS_IDX_ADDRESS (ZT_PROTO_VERB_RENDEZVOUS_IDX_ADDRLEN + 1)
  252. #define ZT_PROTO_VERB_FRAME_IDX_NETWORK_ID (ZT_PACKET_IDX_PAYLOAD)
  253. #define ZT_PROTO_VERB_FRAME_IDX_ETHERTYPE (ZT_PROTO_VERB_FRAME_IDX_NETWORK_ID + 8)
  254. #define ZT_PROTO_VERB_FRAME_IDX_PAYLOAD (ZT_PROTO_VERB_FRAME_IDX_ETHERTYPE + 2)
  255. #define ZT_PROTO_VERB_EXT_FRAME_IDX_NETWORK_ID (ZT_PACKET_IDX_PAYLOAD)
  256. #define ZT_PROTO_VERB_EXT_FRAME_LEN_NETWORK_ID 8
  257. #define ZT_PROTO_VERB_EXT_FRAME_IDX_FLAGS (ZT_PROTO_VERB_EXT_FRAME_IDX_NETWORK_ID + ZT_PROTO_VERB_EXT_FRAME_LEN_NETWORK_ID)
  258. #define ZT_PROTO_VERB_EXT_FRAME_LEN_FLAGS 1
  259. #define ZT_PROTO_VERB_EXT_FRAME_IDX_COM (ZT_PROTO_VERB_EXT_FRAME_IDX_FLAGS + ZT_PROTO_VERB_EXT_FRAME_LEN_FLAGS)
  260. #define ZT_PROTO_VERB_EXT_FRAME_IDX_TO (ZT_PROTO_VERB_EXT_FRAME_IDX_FLAGS + ZT_PROTO_VERB_EXT_FRAME_LEN_FLAGS)
  261. #define ZT_PROTO_VERB_EXT_FRAME_LEN_TO 6
  262. #define ZT_PROTO_VERB_EXT_FRAME_IDX_FROM (ZT_PROTO_VERB_EXT_FRAME_IDX_TO + ZT_PROTO_VERB_EXT_FRAME_LEN_TO)
  263. #define ZT_PROTO_VERB_EXT_FRAME_LEN_FROM 6
  264. #define ZT_PROTO_VERB_EXT_FRAME_IDX_ETHERTYPE (ZT_PROTO_VERB_EXT_FRAME_IDX_FROM + ZT_PROTO_VERB_EXT_FRAME_LEN_FROM)
  265. #define ZT_PROTO_VERB_EXT_FRAME_LEN_ETHERTYPE 2
  266. #define ZT_PROTO_VERB_EXT_FRAME_IDX_PAYLOAD (ZT_PROTO_VERB_EXT_FRAME_IDX_ETHERTYPE + ZT_PROTO_VERB_EXT_FRAME_LEN_ETHERTYPE)
  267. #define ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST_IDX_NETWORK_ID (ZT_PACKET_IDX_PAYLOAD)
  268. #define ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST_IDX_DICT_LEN (ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST_IDX_NETWORK_ID + 8)
  269. #define ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST_IDX_DICT (ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST_IDX_DICT_LEN + 2)
  270. #define ZT_PROTO_VERB_MULTICAST_GATHER_IDX_NETWORK_ID (ZT_PACKET_IDX_PAYLOAD)
  271. #define ZT_PROTO_VERB_MULTICAST_GATHER_IDX_FLAGS (ZT_PROTO_VERB_MULTICAST_GATHER_IDX_NETWORK_ID + 8)
  272. #define ZT_PROTO_VERB_MULTICAST_GATHER_IDX_MAC (ZT_PROTO_VERB_MULTICAST_GATHER_IDX_FLAGS + 1)
  273. #define ZT_PROTO_VERB_MULTICAST_GATHER_IDX_ADI (ZT_PROTO_VERB_MULTICAST_GATHER_IDX_MAC + 6)
  274. #define ZT_PROTO_VERB_MULTICAST_GATHER_IDX_GATHER_LIMIT (ZT_PROTO_VERB_MULTICAST_GATHER_IDX_ADI + 4)
  275. #define ZT_PROTO_VERB_MULTICAST_GATHER_IDX_COM (ZT_PROTO_VERB_MULTICAST_GATHER_IDX_GATHER_LIMIT + 4)
  276. // Note: COM, GATHER_LIMIT, and SOURCE_MAC are optional, and so are specified without size
  277. #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_NETWORK_ID (ZT_PACKET_IDX_PAYLOAD)
  278. #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_FLAGS (ZT_PROTO_VERB_MULTICAST_FRAME_IDX_NETWORK_ID + 8)
  279. #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_COM (ZT_PROTO_VERB_MULTICAST_FRAME_IDX_FLAGS + 1)
  280. #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_GATHER_LIMIT (ZT_PROTO_VERB_MULTICAST_FRAME_IDX_FLAGS + 1)
  281. #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_SOURCE_MAC (ZT_PROTO_VERB_MULTICAST_FRAME_IDX_FLAGS + 1)
  282. #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_DEST_MAC (ZT_PROTO_VERB_MULTICAST_FRAME_IDX_FLAGS + 1)
  283. #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_DEST_ADI (ZT_PROTO_VERB_MULTICAST_FRAME_IDX_DEST_MAC + 6)
  284. #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_ETHERTYPE (ZT_PROTO_VERB_MULTICAST_FRAME_IDX_DEST_ADI + 4)
  285. #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_FRAME (ZT_PROTO_VERB_MULTICAST_FRAME_IDX_ETHERTYPE + 2)
  286. #define ZT_PROTO_VERB_HELLO__OK__IDX_TIMESTAMP (ZT_PROTO_VERB_OK_IDX_PAYLOAD)
  287. #define ZT_PROTO_VERB_HELLO__OK__IDX_PROTOCOL_VERSION (ZT_PROTO_VERB_HELLO__OK__IDX_TIMESTAMP + 8)
  288. #define ZT_PROTO_VERB_HELLO__OK__IDX_MAJOR_VERSION (ZT_PROTO_VERB_HELLO__OK__IDX_PROTOCOL_VERSION + 1)
  289. #define ZT_PROTO_VERB_HELLO__OK__IDX_MINOR_VERSION (ZT_PROTO_VERB_HELLO__OK__IDX_MAJOR_VERSION + 1)
  290. #define ZT_PROTO_VERB_HELLO__OK__IDX_REVISION (ZT_PROTO_VERB_HELLO__OK__IDX_MINOR_VERSION + 1)
  291. #define ZT_PROTO_VERB_WHOIS__OK__IDX_IDENTITY (ZT_PROTO_VERB_OK_IDX_PAYLOAD)
  292. #define ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST__OK__IDX_NETWORK_ID (ZT_PROTO_VERB_OK_IDX_PAYLOAD)
  293. #define ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST__OK__IDX_DICT_LEN (ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST__OK__IDX_NETWORK_ID + 8)
  294. #define ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST__OK__IDX_DICT (ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST__OK__IDX_DICT_LEN + 2)
  295. #define ZT_PROTO_VERB_MULTICAST_GATHER__OK__IDX_NETWORK_ID (ZT_PROTO_VERB_OK_IDX_PAYLOAD)
  296. #define ZT_PROTO_VERB_MULTICAST_GATHER__OK__IDX_MAC (ZT_PROTO_VERB_MULTICAST_GATHER__OK__IDX_NETWORK_ID + 8)
  297. #define ZT_PROTO_VERB_MULTICAST_GATHER__OK__IDX_ADI (ZT_PROTO_VERB_MULTICAST_GATHER__OK__IDX_MAC + 6)
  298. #define ZT_PROTO_VERB_MULTICAST_GATHER__OK__IDX_GATHER_RESULTS (ZT_PROTO_VERB_MULTICAST_GATHER__OK__IDX_ADI + 4)
  299. #define ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_NETWORK_ID (ZT_PROTO_VERB_OK_IDX_PAYLOAD)
  300. #define ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_MAC (ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_NETWORK_ID + 8)
  301. #define ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_ADI (ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_MAC + 6)
  302. #define ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_FLAGS (ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_ADI + 4)
  303. #define ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_COM_AND_GATHER_RESULTS (ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_FLAGS + 1)
  304. // ---------------------------------------------------------------------------
  305. namespace ZeroTier {
  306. /**
  307. * ZeroTier packet
  308. *
  309. * Packet format:
  310. * <[8] 64-bit random packet ID and crypto initialization vector>
  311. * <[5] destination ZT address>
  312. * <[5] source ZT address>
  313. * <[1] flags/cipher/hops>
  314. * <[8] 64-bit MAC (or trusted path ID in trusted path mode)>
  315. * [... -- begin encryption envelope -- ...]
  316. * <[1] encrypted flags (MS 3 bits) and verb (LS 5 bits)>
  317. * [... verb-specific payload ...]
  318. *
  319. * Packets smaller than 28 bytes are invalid and silently discarded.
  320. *
  321. * The flags/cipher/hops bit field is: FFCCCHHH where C is a 3-bit cipher
  322. * selection allowing up to 7 cipher suites, F is outside-envelope flags,
  323. * and H is hop count.
  324. *
  325. * The three-bit hop count is the only part of a packet that is mutable in
  326. * transit without invalidating the MAC. All other bits in the packet are
  327. * immutable. This is because intermediate nodes can increment the hop
  328. * count up to 7 (protocol max).
  329. *
  330. * For unencrypted packets, MAC is computed on plaintext. Only HELLO is ever
  331. * sent in the clear, as it's the "here is my public key" message.
  332. */
  333. class Packet : public Buffer<ZT_PROTO_MAX_PACKET_LENGTH>
  334. {
  335. public:
  336. /**
  337. * A packet fragment
  338. *
  339. * Fragments are sent if a packet is larger than UDP MTU. The first fragment
  340. * is sent with its normal header with the fragmented flag set. Remaining
  341. * fragments are sent this way.
  342. *
  343. * The fragmented bit indicates that there is at least one fragment. Fragments
  344. * themselves contain the total, so the receiver must "learn" this from the
  345. * first fragment it receives.
  346. *
  347. * Fragments are sent with the following format:
  348. * <[8] packet ID of packet whose fragment this belongs to>
  349. * <[5] destination ZT address>
  350. * <[1] 0xff, a reserved address, signals that this isn't a normal packet>
  351. * <[1] total fragments (most significant 4 bits), fragment no (LS 4 bits)>
  352. * <[1] ZT hop count (top 5 bits unused and must be zero)>
  353. * <[...] fragment data>
  354. *
  355. * The protocol supports a maximum of 16 fragments. If a fragment is received
  356. * before its main packet header, it should be cached for a brief period of
  357. * time to see if its parent arrives. Loss of any fragment constitutes packet
  358. * loss; there is no retransmission mechanism. The receiver must wait for full
  359. * receipt to authenticate and decrypt; there is no per-fragment MAC. (But if
  360. * fragments are corrupt, the MAC will fail for the whole assembled packet.)
  361. */
  362. class Fragment : public Buffer<ZT_PROTO_MAX_PACKET_LENGTH>
  363. {
  364. public:
  365. Fragment() :
  366. Buffer<ZT_PROTO_MAX_PACKET_LENGTH>()
  367. {
  368. }
  369. template<unsigned int C2>
  370. Fragment(const Buffer<C2> &b)
  371. throw(std::out_of_range) :
  372. Buffer<ZT_PROTO_MAX_PACKET_LENGTH>(b)
  373. {
  374. }
  375. Fragment(const void *data,unsigned int len) :
  376. Buffer<ZT_PROTO_MAX_PACKET_LENGTH>(data,len)
  377. {
  378. }
  379. /**
  380. * Initialize from a packet
  381. *
  382. * @param p Original assembled packet
  383. * @param fragStart Start of fragment (raw index in packet data)
  384. * @param fragLen Length of fragment in bytes
  385. * @param fragNo Which fragment (>= 1, since 0 is Packet with end chopped off)
  386. * @param fragTotal Total number of fragments (including 0)
  387. * @throws std::out_of_range Packet size would exceed buffer
  388. */
  389. Fragment(const Packet &p,unsigned int fragStart,unsigned int fragLen,unsigned int fragNo,unsigned int fragTotal)
  390. throw(std::out_of_range)
  391. {
  392. init(p,fragStart,fragLen,fragNo,fragTotal);
  393. }
  394. /**
  395. * Initialize from a packet
  396. *
  397. * @param p Original assembled packet
  398. * @param fragStart Start of fragment (raw index in packet data)
  399. * @param fragLen Length of fragment in bytes
  400. * @param fragNo Which fragment (>= 1, since 0 is Packet with end chopped off)
  401. * @param fragTotal Total number of fragments (including 0)
  402. * @throws std::out_of_range Packet size would exceed buffer
  403. */
  404. inline void init(const Packet &p,unsigned int fragStart,unsigned int fragLen,unsigned int fragNo,unsigned int fragTotal)
  405. throw(std::out_of_range)
  406. {
  407. if ((fragStart + fragLen) > p.size())
  408. throw std::out_of_range("Packet::Fragment: tried to construct fragment of packet past its length");
  409. setSize(fragLen + ZT_PROTO_MIN_FRAGMENT_LENGTH);
  410. // NOTE: this copies both the IV/packet ID and the destination address.
  411. memcpy(field(ZT_PACKET_FRAGMENT_IDX_PACKET_ID,13),p.field(ZT_PACKET_IDX_IV,13),13);
  412. (*this)[ZT_PACKET_FRAGMENT_IDX_FRAGMENT_INDICATOR] = ZT_PACKET_FRAGMENT_INDICATOR;
  413. (*this)[ZT_PACKET_FRAGMENT_IDX_FRAGMENT_NO] = (char)(((fragTotal & 0xf) << 4) | (fragNo & 0xf));
  414. (*this)[ZT_PACKET_FRAGMENT_IDX_HOPS] = 0;
  415. memcpy(field(ZT_PACKET_FRAGMENT_IDX_PAYLOAD,fragLen),p.field(fragStart,fragLen),fragLen);
  416. }
  417. /**
  418. * Get this fragment's destination
  419. *
  420. * @return Destination ZT address
  421. */
  422. inline Address destination() const { return Address(field(ZT_PACKET_FRAGMENT_IDX_DEST,ZT_ADDRESS_LENGTH),ZT_ADDRESS_LENGTH); }
  423. /**
  424. * @return True if fragment is of a valid length
  425. */
  426. inline bool lengthValid() const { return (size() >= ZT_PACKET_FRAGMENT_IDX_PAYLOAD); }
  427. /**
  428. * @return ID of packet this is a fragment of
  429. */
  430. inline uint64_t packetId() const { return at<uint64_t>(ZT_PACKET_FRAGMENT_IDX_PACKET_ID); }
  431. /**
  432. * @return Total number of fragments in packet
  433. */
  434. inline unsigned int totalFragments() const { return (((unsigned int)((*this)[ZT_PACKET_FRAGMENT_IDX_FRAGMENT_NO]) >> 4) & 0xf); }
  435. /**
  436. * @return Fragment number of this fragment
  437. */
  438. inline unsigned int fragmentNumber() const { return ((unsigned int)((*this)[ZT_PACKET_FRAGMENT_IDX_FRAGMENT_NO]) & 0xf); }
  439. /**
  440. * @return Fragment ZT hop count
  441. */
  442. inline unsigned int hops() const { return (unsigned int)((*this)[ZT_PACKET_FRAGMENT_IDX_HOPS]); }
  443. /**
  444. * Increment this packet's hop count
  445. */
  446. inline void incrementHops()
  447. {
  448. (*this)[ZT_PACKET_FRAGMENT_IDX_HOPS] = (((*this)[ZT_PACKET_FRAGMENT_IDX_HOPS]) + 1) & ZT_PROTO_MAX_HOPS;
  449. }
  450. /**
  451. * @return Length of payload in bytes
  452. */
  453. inline unsigned int payloadLength() const { return ((size() > ZT_PACKET_FRAGMENT_IDX_PAYLOAD) ? (size() - ZT_PACKET_FRAGMENT_IDX_PAYLOAD) : 0); }
  454. /**
  455. * @return Raw packet payload
  456. */
  457. inline const unsigned char *payload() const
  458. {
  459. return field(ZT_PACKET_FRAGMENT_IDX_PAYLOAD,size() - ZT_PACKET_FRAGMENT_IDX_PAYLOAD);
  460. }
  461. };
  462. /**
  463. * ZeroTier protocol verbs
  464. */
  465. enum Verb /* Max value: 32 (5 bits) */
  466. {
  467. /**
  468. * No operation (ignored, no reply)
  469. */
  470. VERB_NOP = 0x00,
  471. /**
  472. * Announcement of a node's existence:
  473. * <[1] protocol version>
  474. * <[1] software major version>
  475. * <[1] software minor version>
  476. * <[2] software revision>
  477. * <[8] timestamp (ms since epoch)>
  478. * <[...] binary serialized identity (see Identity)>
  479. * <[1] destination address type>
  480. * [<[...] destination address to which packet was sent>]
  481. * <[8] 64-bit world ID of current world>
  482. * <[8] 64-bit timestamp of current world>
  483. *
  484. * This is the only message that ever must be sent in the clear, since it
  485. * is used to push an identity to a new peer.
  486. *
  487. * The destination address is the wire address to which this packet is
  488. * being sent, and in OK is *also* the destination address of the OK
  489. * packet. This can be used by the receiver to detect NAT, learn its real
  490. * external address if behind NAT, and detect changes to its external
  491. * address that require re-establishing connectivity.
  492. *
  493. * Destination address types and formats (not all of these are used now):
  494. * 0x00 - None -- no destination address data present
  495. * 0x01 - Ethernet address -- format: <[6] Ethernet MAC>
  496. * 0x04 - 6-byte IPv4 UDP address/port -- format: <[4] IP>, <[2] port>
  497. * 0x06 - 18-byte IPv6 UDP address/port -- format: <[16] IP>, <[2] port>
  498. *
  499. * OK payload:
  500. * <[8] timestamp (echoed from original HELLO)>
  501. * <[1] protocol version (of responder)>
  502. * <[1] software major version (of responder)>
  503. * <[1] software minor version (of responder)>
  504. * <[2] software revision (of responder)>
  505. * <[1] destination address type (for this OK, not copied from HELLO)>
  506. * [<[...] destination address>]
  507. * <[2] 16-bit length of world update or 0 if none>
  508. * [[...] world update]
  509. *
  510. * ERROR has no payload.
  511. */
  512. VERB_HELLO = 0x01,
  513. /**
  514. * Error response:
  515. * <[1] in-re verb>
  516. * <[8] in-re packet ID>
  517. * <[1] error code>
  518. * <[...] error-dependent payload>
  519. */
  520. VERB_ERROR = 0x02,
  521. /**
  522. * Success response:
  523. * <[1] in-re verb>
  524. * <[8] in-re packet ID>
  525. * <[...] request-specific payload>
  526. */
  527. VERB_OK = 0x03,
  528. /**
  529. * Query an identity by address:
  530. * <[5] address to look up>
  531. * [<[...] additional addresses to look up>
  532. *
  533. * OK response payload:
  534. * <[...] binary serialized identity>
  535. * [<[...] additional binary serialized identities>]
  536. *
  537. * If querying a cluster, duplicate OK responses may occasionally occur.
  538. * These must be tolerated, which is easy since they'll have info you
  539. * already have.
  540. *
  541. * If the address is not found, no response is generated. The semantics
  542. * of WHOIS is similar to ARP and NDP in that persistent retrying can
  543. * be performed.
  544. */
  545. VERB_WHOIS = 0x04,
  546. /**
  547. * Relay-mediated NAT traversal or firewall punching initiation:
  548. * <[1] flags (unused, currently 0)>
  549. * <[5] ZeroTier address of peer that might be found at this address>
  550. * <[2] 16-bit protocol address port>
  551. * <[1] protocol address length (4 for IPv4, 16 for IPv6)>
  552. * <[...] protocol address (network byte order)>
  553. *
  554. * This is sent by a relaying node to initiate NAT traversal between two
  555. * peers that are communicating by way of indirect relay. The relay will
  556. * send this to both peers at the same time on a periodic basis, telling
  557. * each where it might find the other on the network.
  558. *
  559. * Upon receipt a peer sends HELLO to establish a direct link.
  560. *
  561. * No OK or ERROR is generated.
  562. */
  563. VERB_RENDEZVOUS = 0x05,
  564. /**
  565. * ZT-to-ZT unicast ethernet frame (shortened EXT_FRAME):
  566. * <[8] 64-bit network ID>
  567. * <[2] 16-bit ethertype>
  568. * <[...] ethernet payload>
  569. *
  570. * MAC addresses are derived from the packet's source and destination
  571. * ZeroTier addresses. This is a shortened EXT_FRAME that elides full
  572. * Ethernet framing and other optional flags and features when they
  573. * are not necessary.
  574. *
  575. * ERROR may be generated if a membership certificate is needed for a
  576. * closed network. Payload will be network ID.
  577. */
  578. VERB_FRAME = 0x06,
  579. /**
  580. * Full Ethernet frame with MAC addressing and optional fields:
  581. * <[8] 64-bit network ID>
  582. * <[1] flags>
  583. * <[6] destination MAC or all zero for destination node>
  584. * <[6] source MAC or all zero for node of origin>
  585. * <[2] 16-bit ethertype>
  586. * <[...] ethernet payload>
  587. *
  588. * Flags:
  589. * 0x01 - Certificate of network membership attached (DEPRECATED)
  590. * 0x02 - This is a TEE'd or REDIRECT'ed packet
  591. * 0x04 - TEE/REDIRECT'ed packet is from inbound side
  592. *
  593. * An extended frame carries full MAC addressing, making them a
  594. * superset of VERB_FRAME. They're used for bridging or when we
  595. * want to attach a certificate since FRAME does not support that.
  596. *
  597. * ERROR may be generated if a membership certificate is needed for a
  598. * closed network. Payload will be network ID.
  599. */
  600. VERB_EXT_FRAME = 0x07,
  601. /**
  602. * ECHO request (a.k.a. ping):
  603. * <[...] arbitrary payload>
  604. *
  605. * This generates OK with a copy of the transmitted payload. No ERROR
  606. * is generated. Response to ECHO requests is optional and ECHO may be
  607. * ignored if a node detects a possible flood.
  608. */
  609. VERB_ECHO = 0x08,
  610. /**
  611. * Announce interest in multicast group(s):
  612. * <[8] 64-bit network ID>
  613. * <[6] multicast Ethernet address>
  614. * <[4] multicast additional distinguishing information (ADI)>
  615. * [... additional tuples of network/address/adi ...]
  616. *
  617. * LIKEs may be sent to any peer, though a good implementation should
  618. * restrict them to peers on the same network they're for and to network
  619. * controllers and root servers. In the current network, root servers
  620. * will provide the service of final multicast cache.
  621. *
  622. * VERB_NETWORK_CREDENTIALS should be pushed along with this, especially
  623. * if using upstream (e.g. root) nodes as multicast databases. This allows
  624. * GATHERs to be authenticated.
  625. *
  626. * OK/ERROR are not generated.
  627. */
  628. VERB_MULTICAST_LIKE = 0x09,
  629. /**
  630. * Network membership credential push:
  631. * <[...] serialized certificate of membership>
  632. * [<[...] additional certificates of membership>]
  633. * <[1] 0x00, null byte marking end of COM array>
  634. * <[2] 16-bit number of capabilities>
  635. * <[...] one or more serialized Capability>
  636. * <[2] 16-bit number of tags>
  637. * <[...] one or more serialized Tags>
  638. *
  639. * This is sent in response to ERROR_NEED_MEMBERSHIP_CERTIFICATE and may
  640. * be pushed at any other time to keep exchanged certificates up to date.
  641. *
  642. * COMs and other credentials need not be for the same network, since each
  643. * includes its own network ID and signature.
  644. *
  645. * OK/ERROR are not generated.
  646. */
  647. VERB_NETWORK_CREDENTIALS = 0x0a,
  648. /**
  649. * Network configuration request:
  650. * <[8] 64-bit network ID>
  651. * <[2] 16-bit length of request meta-data dictionary>
  652. * <[...] string-serialized request meta-data>
  653. * <[8] 64-bit revision of netconf we currently have>
  654. * <[8] 64-bit timestamp of netconf we currently have>
  655. *
  656. * This message requests network configuration from a node capable of
  657. * providing it. If the optional revision is included, a response is
  658. * only generated if there is a newer network configuration available.
  659. *
  660. * OK response payload:
  661. * <[8] 64-bit network ID>
  662. * <[2] 16-bit length of network configuration dictionary chunk>
  663. * <[...] network configuration dictionary (may be incomplete)>
  664. * <[4] 32-bit total length of assembled dictionary>
  665. * <[4] 32-bit index of chunk in this reply>
  666. *
  667. * ERROR response payload:
  668. * <[8] 64-bit network ID>
  669. */
  670. VERB_NETWORK_CONFIG_REQUEST = 0x0b,
  671. /**
  672. * Network configuration update push:
  673. * <[8] network ID to refresh>
  674. * <[2] 16-bit number of address/timestamp pairs to blacklist>
  675. * [<[5] ZeroTier address of peer being revoked>]
  676. * [<[8] blacklist credentials older than this timestamp>]
  677. * [<[...] additional address/timestamp pairs>]
  678. *
  679. * This can be sent by a network controller to both request that a network
  680. * config be updated and push instantaneous revocations of specific peers
  681. * or peer credentials.
  682. *
  683. * Specific revocations can be pushed to blacklist a specific peer's
  684. * credentials (COM, tags, and capabilities) if older than a specified
  685. * timestamp. This can be used to accomplish expedited revocation of
  686. * a peer's access to things on a network or to the network itself among
  687. * those other peers that can currently reach the controller. This is not
  688. * the only mechanism for revocation of course, but it's the fastest.
  689. */
  690. VERB_NETWORK_CONFIG_REFRESH = 0x0c,
  691. /**
  692. * Request endpoints for multicast distribution:
  693. * <[8] 64-bit network ID>
  694. * <[1] flags>
  695. * <[6] MAC address of multicast group being queried>
  696. * <[4] 32-bit ADI for multicast group being queried>
  697. * <[4] 32-bit requested max number of multicast peers>
  698. * [<[...] network certificate of membership>]
  699. *
  700. * Flags:
  701. * 0x01 - COM is attached
  702. *
  703. * This message asks a peer for additional known endpoints that have
  704. * LIKEd a given multicast group. It's sent when the sender wishes
  705. * to send multicast but does not have the desired number of recipient
  706. * peers.
  707. *
  708. * More than one OK response can occur if the response is broken up across
  709. * multiple packets or if querying a clustered node.
  710. *
  711. * The COM should be included so that upstream nodes that are not
  712. * members of our network can validate our request.
  713. *
  714. * OK response payload:
  715. * <[8] 64-bit network ID>
  716. * <[6] MAC address of multicast group being queried>
  717. * <[4] 32-bit ADI for multicast group being queried>
  718. * [begin gather results -- these same fields can be in OK(MULTICAST_FRAME)]
  719. * <[4] 32-bit total number of known members in this multicast group>
  720. * <[2] 16-bit number of members enumerated in this packet>
  721. * <[...] series of 5-byte ZeroTier addresses of enumerated members>
  722. *
  723. * ERROR is not generated; queries that return no response are dropped.
  724. */
  725. VERB_MULTICAST_GATHER = 0x0d,
  726. /**
  727. * Multicast frame:
  728. * <[8] 64-bit network ID>
  729. * <[1] flags>
  730. * [<[4] 32-bit implicit gather limit>]
  731. * [<[6] source MAC>]
  732. * <[6] destination MAC (multicast address)>
  733. * <[4] 32-bit multicast ADI (multicast address extension)>
  734. * <[2] 16-bit ethertype>
  735. * <[...] ethernet payload>
  736. *
  737. * Flags:
  738. * 0x01 - Network certificate of membership attached (DEPRECATED)
  739. * 0x02 - Implicit gather limit field is present
  740. * 0x04 - Source MAC is specified -- otherwise it's computed from sender
  741. *
  742. * OK and ERROR responses are optional. OK may be generated if there are
  743. * implicit gather results or if the recipient wants to send its own
  744. * updated certificate of network membership to the sender. ERROR may be
  745. * generated if a certificate is needed or if multicasts to this group
  746. * are no longer wanted (multicast unsubscribe).
  747. *
  748. * OK response payload:
  749. * <[8] 64-bit network ID>
  750. * <[6] MAC address of multicast group>
  751. * <[4] 32-bit ADI for multicast group>
  752. * <[1] flags>
  753. * [<[...] network certficate of membership (DEPRECATED)>]
  754. * [<[...] implicit gather results if flag 0x01 is set>]
  755. *
  756. * OK flags (same bits as request flags):
  757. * 0x01 - OK includes certificate of network membership (DEPRECATED)
  758. * 0x02 - OK includes implicit gather results
  759. *
  760. * ERROR response payload:
  761. * <[8] 64-bit network ID>
  762. * <[6] multicast group MAC>
  763. * <[4] 32-bit multicast group ADI>
  764. */
  765. VERB_MULTICAST_FRAME = 0x0e,
  766. // 0x0f is reserved for an old deprecated message
  767. /**
  768. * Push of potential endpoints for direct communication:
  769. * <[2] 16-bit number of paths>
  770. * <[...] paths>
  771. *
  772. * Path record format:
  773. * <[1] 8-bit path flags>
  774. * <[2] length of extended path characteristics or 0 for none>
  775. * <[...] extended path characteristics>
  776. * <[1] address type>
  777. * <[1] address length in bytes>
  778. * <[...] address>
  779. *
  780. * Path record flags:
  781. * 0x01 - Forget this path if currently known (not implemented yet)
  782. * 0x02 - Cluster redirect -- use this in preference to others
  783. *
  784. * The receiver may, upon receiving a push, attempt to establish a
  785. * direct link to one or more of the indicated addresses. It is the
  786. * responsibility of the sender to limit which peers it pushes direct
  787. * paths to to those with whom it has a trust relationship. The receiver
  788. * must obey any restrictions provided such as exclusivity or blacklists.
  789. * OK responses to this message are optional.
  790. *
  791. * Note that a direct path push does not imply that learned paths can't
  792. * be used unless they are blacklisted explicitly or unless flag 0x01
  793. * is set.
  794. *
  795. * Only a subset of this functionality is currently implemented: basic
  796. * path pushing and learning. Blacklisting and trust are not fully
  797. * implemented yet (encryption is still always used).
  798. *
  799. * OK and ERROR are not generated.
  800. */
  801. VERB_PUSH_DIRECT_PATHS = 0x10,
  802. /**
  803. * Source-routed circuit test message:
  804. * <[5] address of originator of circuit test>
  805. * <[2] 16-bit flags>
  806. * <[8] 64-bit timestamp>
  807. * <[8] 64-bit test ID (arbitrary, set by tester)>
  808. * <[2] 16-bit originator credential length (includes type)>
  809. * [[1] originator credential type (for authorizing test)]
  810. * [[...] originator credential]
  811. * <[2] 16-bit length of additional fields>
  812. * [[...] additional fields]
  813. * [ ... end of signed portion of request ... ]
  814. * <[2] 16-bit length of signature of request>
  815. * <[...] signature of request by originator>
  816. * <[2] 16-bit length of additional fields>
  817. * [[...] additional fields]
  818. * <[...] next hop(s) in path>
  819. *
  820. * Flags:
  821. * 0x01 - Report back to originator at all hops
  822. * 0x02 - Report back to originator at last hop
  823. *
  824. * Originator credential types:
  825. * 0x01 - 64-bit network ID for which originator is controller
  826. *
  827. * Path record format:
  828. * <[1] 8-bit flags (unused, must be zero)>
  829. * <[1] 8-bit breadth (number of next hops)>
  830. * <[...] one or more ZeroTier addresses of next hops>
  831. *
  832. * The circuit test allows a device to send a message that will traverse
  833. * the network along a specified path, with each hop optionally reporting
  834. * back to the tester via VERB_CIRCUIT_TEST_REPORT.
  835. *
  836. * Each circuit test packet includes a digital signature by the originator
  837. * of the request, as well as a credential by which that originator claims
  838. * authorization to perform the test. Currently this signature is ed25519,
  839. * but in the future flags might be used to indicate an alternative
  840. * algorithm. For example, the originator might be a network controller.
  841. * In this case the test might be authorized if the recipient is a member
  842. * of a network controlled by it, and if the previous hop(s) are also
  843. * members. Each hop may include its certificate of network membership.
  844. *
  845. * Circuit test paths consist of a series of records. When a node receives
  846. * an authorized circuit test, it:
  847. *
  848. * (1) Reports back to circuit tester as flags indicate
  849. * (2) Reads and removes the next hop from the packet's path
  850. * (3) Sends the packet along to next hop(s), if any.
  851. *
  852. * It is perfectly legal for a path to contain the same hop more than
  853. * once. In fact, this can be a very useful test to determine if a hop
  854. * can be reached bidirectionally and if so what that connectivity looks
  855. * like.
  856. *
  857. * The breadth field in source-routed path records allows a hop to forward
  858. * to more than one recipient, allowing the tester to specify different
  859. * forms of graph traversal in a test.
  860. *
  861. * There is no hard limit to the number of hops in a test, but it is
  862. * practically limited by the maximum size of a (possibly fragmented)
  863. * ZeroTier packet.
  864. *
  865. * Support for circuit tests is optional. If they are not supported, the
  866. * node should respond with an UNSUPPORTED_OPERATION error. If a circuit
  867. * test request is not authorized, it may be ignored or reported as
  868. * an INVALID_REQUEST. No OK messages are generated, but TEST_REPORT
  869. * messages may be sent (see below).
  870. *
  871. * ERROR packet format:
  872. * <[8] 64-bit timestamp (echoed from original>
  873. * <[8] 64-bit test ID (echoed from original)>
  874. */
  875. VERB_CIRCUIT_TEST = 0x11,
  876. /**
  877. * Circuit test hop report:
  878. * <[8] 64-bit timestamp (echoed from original test)>
  879. * <[8] 64-bit test ID (echoed from original test)>
  880. * <[8] 64-bit reserved field (set to 0, currently unused)>
  881. * <[1] 8-bit vendor ID (set to 0, currently unused)>
  882. * <[1] 8-bit reporter protocol version>
  883. * <[1] 8-bit reporter software major version>
  884. * <[1] 8-bit reporter software minor version>
  885. * <[2] 16-bit reporter software revision>
  886. * <[2] 16-bit reporter OS/platform or 0 if not specified>
  887. * <[2] 16-bit reporter architecture or 0 if not specified>
  888. * <[2] 16-bit error code (set to 0, currently unused)>
  889. * <[8] 64-bit report flags (set to 0, currently unused)>
  890. * <[8] 64-bit packet ID of received CIRCUIT_TEST packet>
  891. * <[5] upstream ZeroTier address from which CIRCUIT_TEST was received>
  892. * <[1] 8-bit packet hop count of received CIRCUIT_TEST>
  893. * <[...] local wire address on which packet was received>
  894. * <[...] remote wire address from which packet was received>
  895. * <[2] 16-bit length of additional fields>
  896. * <[...] additional fields>
  897. * <[1] 8-bit number of next hops (breadth)>
  898. * <[...] next hop information>
  899. *
  900. * Next hop information record format:
  901. * <[5] ZeroTier address of next hop>
  902. * <[...] current best direct path address, if any, 0 if none>
  903. *
  904. * Circuit test reports can be sent by hops in a circuit test to report
  905. * back results. They should include information about the sender as well
  906. * as about the paths to which next hops are being sent.
  907. *
  908. * If a test report is received and no circuit test was sent, it should be
  909. * ignored. This message generates no OK or ERROR response.
  910. */
  911. VERB_CIRCUIT_TEST_REPORT = 0x12,
  912. /**
  913. * Request proof of work:
  914. * <[1] 8-bit proof of work type>
  915. * <[1] 8-bit proof of work difficulty>
  916. * <[2] 16-bit length of proof of work challenge>
  917. * <[...] proof of work challenge>
  918. *
  919. * This requests that a peer perform a proof of work calucation. It can be
  920. * sent by highly trusted peers (e.g. root servers, network controllers)
  921. * under suspected denial of service conditions in an attempt to filter
  922. * out "non-serious" peers and remain responsive to those proving their
  923. * intent to actually communicate.
  924. *
  925. * If the peer obliges to perform the work, it does so and responds with
  926. * an OK containing the result. Otherwise it may ignore the message or
  927. * response with an ERROR_INVALID_REQUEST or ERROR_UNSUPPORTED_OPERATION.
  928. *
  929. * Proof of work type IDs:
  930. * 0x01 - Salsa20/12+SHA512 hashcash function
  931. *
  932. * Salsa20/12+SHA512 is based on the following composite hash function:
  933. *
  934. * (1) Compute SHA512(candidate)
  935. * (2) Use the first 256 bits of the result of #1 as a key to encrypt
  936. * 131072 zero bytes with Salsa20/12 (with a zero IV).
  937. * (3) Compute SHA512(the result of step #2)
  938. * (4) Accept this candiate if the first [difficulty] bits of the result
  939. * from step #3 are zero. Otherwise generate a new candidate and try
  940. * again.
  941. *
  942. * This is performed repeatedly on candidates generated by appending the
  943. * supplied challenge to an arbitrary nonce until a valid candidate
  944. * is found. This chosen prepended nonce is then returned as the result
  945. * in OK.
  946. *
  947. * OK payload:
  948. * <[2] 16-bit length of result>
  949. * <[...] computed proof of work>
  950. *
  951. * ERROR has no payload.
  952. */
  953. VERB_REQUEST_PROOF_OF_WORK = 0x13,
  954. /**
  955. * A message with arbitrary user-definable content:
  956. * <[8] 64-bit arbitrary message type ID>
  957. * [<[...] message payload>]
  958. *
  959. * This can be used to send arbitrary messages over VL1. It generates no
  960. * OK or ERROR and has no special semantics outside of whatever the user
  961. * (via the ZeroTier core API) chooses to give it.
  962. */
  963. VERB_USER_MESSAGE = 0x14
  964. };
  965. /**
  966. * Error codes for VERB_ERROR
  967. */
  968. enum ErrorCode
  969. {
  970. /* No error, not actually used in transit */
  971. ERROR_NONE = 0x00,
  972. /* Invalid request */
  973. ERROR_INVALID_REQUEST = 0x01,
  974. /* Bad/unsupported protocol version */
  975. ERROR_BAD_PROTOCOL_VERSION = 0x02,
  976. /* Unknown object queried */
  977. ERROR_OBJ_NOT_FOUND = 0x03,
  978. /* HELLO pushed an identity whose address is already claimed */
  979. ERROR_IDENTITY_COLLISION = 0x04,
  980. /* Verb or use case not supported/enabled by this node */
  981. ERROR_UNSUPPORTED_OPERATION = 0x05,
  982. /* Tried to join network, but you're not a member */
  983. ERROR_NETWORK_ACCESS_DENIED_ = 0x07, /* extra _ at end to avoid Windows name conflict */
  984. /* Multicasts to this group are not wanted */
  985. ERROR_UNWANTED_MULTICAST = 0x08
  986. };
  987. #ifdef ZT_TRACE
  988. static const char *verbString(Verb v)
  989. throw();
  990. static const char *errorString(ErrorCode e)
  991. throw();
  992. #endif
  993. template<unsigned int C2>
  994. Packet(const Buffer<C2> &b) :
  995. Buffer<ZT_PROTO_MAX_PACKET_LENGTH>(b)
  996. {
  997. }
  998. Packet(const void *data,unsigned int len) :
  999. Buffer<ZT_PROTO_MAX_PACKET_LENGTH>(data,len)
  1000. {
  1001. }
  1002. /**
  1003. * Construct a new empty packet with a unique random packet ID
  1004. *
  1005. * Flags and hops will be zero. Other fields and data region are undefined.
  1006. * Use the header access methods (setDestination() and friends) to fill out
  1007. * the header. Payload should be appended; initial size is header size.
  1008. */
  1009. Packet() :
  1010. Buffer<ZT_PROTO_MAX_PACKET_LENGTH>(ZT_PROTO_MIN_PACKET_LENGTH)
  1011. {
  1012. Utils::getSecureRandom(field(ZT_PACKET_IDX_IV,8),8);
  1013. (*this)[ZT_PACKET_IDX_FLAGS] = 0; // zero flags, cipher ID, and hops
  1014. }
  1015. /**
  1016. * Make a copy of a packet with a new initialization vector and destination address
  1017. *
  1018. * This can be used to take one draft prototype packet and quickly make copies to
  1019. * encrypt for different destinations.
  1020. *
  1021. * @param prototype Prototype packet
  1022. * @param dest Destination ZeroTier address for new packet
  1023. */
  1024. Packet(const Packet &prototype,const Address &dest) :
  1025. Buffer<ZT_PROTO_MAX_PACKET_LENGTH>(prototype)
  1026. {
  1027. Utils::getSecureRandom(field(ZT_PACKET_IDX_IV,8),8);
  1028. setDestination(dest);
  1029. }
  1030. /**
  1031. * Construct a new empty packet with a unique random packet ID
  1032. *
  1033. * @param dest Destination ZT address
  1034. * @param source Source ZT address
  1035. * @param v Verb
  1036. */
  1037. Packet(const Address &dest,const Address &source,const Verb v) :
  1038. Buffer<ZT_PROTO_MAX_PACKET_LENGTH>(ZT_PROTO_MIN_PACKET_LENGTH)
  1039. {
  1040. Utils::getSecureRandom(field(ZT_PACKET_IDX_IV,8),8);
  1041. setDestination(dest);
  1042. setSource(source);
  1043. (*this)[ZT_PACKET_IDX_FLAGS] = 0; // zero flags and hops
  1044. setVerb(v);
  1045. }
  1046. /**
  1047. * Reset this packet structure for reuse in place
  1048. *
  1049. * @param dest Destination ZT address
  1050. * @param source Source ZT address
  1051. * @param v Verb
  1052. */
  1053. inline void reset(const Address &dest,const Address &source,const Verb v)
  1054. {
  1055. setSize(ZT_PROTO_MIN_PACKET_LENGTH);
  1056. Utils::getSecureRandom(field(ZT_PACKET_IDX_IV,8),8);
  1057. setDestination(dest);
  1058. setSource(source);
  1059. (*this)[ZT_PACKET_IDX_FLAGS] = 0; // zero flags, cipher ID, and hops
  1060. setVerb(v);
  1061. }
  1062. /**
  1063. * Generate a new IV / packet ID in place
  1064. *
  1065. * This can be used to re-use a packet buffer multiple times to send
  1066. * technically different but otherwise identical copies of the same
  1067. * packet.
  1068. */
  1069. inline void newInitializationVector() { Utils::getSecureRandom(field(ZT_PACKET_IDX_IV,8),8); }
  1070. /**
  1071. * Set this packet's destination
  1072. *
  1073. * @param dest ZeroTier address of destination
  1074. */
  1075. inline void setDestination(const Address &dest) { dest.copyTo(field(ZT_PACKET_IDX_DEST,ZT_ADDRESS_LENGTH),ZT_ADDRESS_LENGTH); }
  1076. /**
  1077. * Set this packet's source
  1078. *
  1079. * @param source ZeroTier address of source
  1080. */
  1081. inline void setSource(const Address &source) { source.copyTo(field(ZT_PACKET_IDX_SOURCE,ZT_ADDRESS_LENGTH),ZT_ADDRESS_LENGTH); }
  1082. /**
  1083. * Get this packet's destination
  1084. *
  1085. * @return Destination ZT address
  1086. */
  1087. inline Address destination() const { return Address(field(ZT_PACKET_IDX_DEST,ZT_ADDRESS_LENGTH),ZT_ADDRESS_LENGTH); }
  1088. /**
  1089. * Get this packet's source
  1090. *
  1091. * @return Source ZT address
  1092. */
  1093. inline Address source() const { return Address(field(ZT_PACKET_IDX_SOURCE,ZT_ADDRESS_LENGTH),ZT_ADDRESS_LENGTH); }
  1094. /**
  1095. * @return True if packet is of valid length
  1096. */
  1097. inline bool lengthValid() const { return (size() >= ZT_PROTO_MIN_PACKET_LENGTH); }
  1098. /**
  1099. * @return True if packet is fragmented (expect fragments)
  1100. */
  1101. inline bool fragmented() const { return (((unsigned char)(*this)[ZT_PACKET_IDX_FLAGS] & ZT_PROTO_FLAG_FRAGMENTED) != 0); }
  1102. /**
  1103. * Set this packet's fragmented flag
  1104. *
  1105. * @param f Fragmented flag value
  1106. */
  1107. inline void setFragmented(bool f)
  1108. {
  1109. if (f)
  1110. (*this)[ZT_PACKET_IDX_FLAGS] |= (char)ZT_PROTO_FLAG_FRAGMENTED;
  1111. else (*this)[ZT_PACKET_IDX_FLAGS] &= (char)(~ZT_PROTO_FLAG_FRAGMENTED);
  1112. }
  1113. /**
  1114. * @return True if compressed (result only valid if unencrypted)
  1115. */
  1116. inline bool compressed() const { return (((unsigned char)(*this)[ZT_PACKET_IDX_VERB] & ZT_PROTO_VERB_FLAG_COMPRESSED) != 0); }
  1117. /**
  1118. * @return ZeroTier forwarding hops (0 to 7)
  1119. */
  1120. inline unsigned int hops() const { return ((unsigned int)(*this)[ZT_PACKET_IDX_FLAGS] & 0x07); }
  1121. /**
  1122. * Increment this packet's hop count
  1123. */
  1124. inline void incrementHops()
  1125. {
  1126. unsigned char &b = (*this)[ZT_PACKET_IDX_FLAGS];
  1127. b = (b & 0xf8) | ((b + 1) & 0x07);
  1128. }
  1129. /**
  1130. * @return Cipher suite selector: 0 - 7 (see #defines)
  1131. */
  1132. inline unsigned int cipher() const
  1133. {
  1134. return (((unsigned int)(*this)[ZT_PACKET_IDX_FLAGS] & 0x38) >> 3);
  1135. }
  1136. /**
  1137. * Set this packet's cipher suite
  1138. */
  1139. inline void setCipher(unsigned int c)
  1140. {
  1141. unsigned char &b = (*this)[ZT_PACKET_IDX_FLAGS];
  1142. b = (b & 0xc7) | (unsigned char)((c << 3) & 0x38); // bits: FFCCCHHH
  1143. // Set DEPRECATED "encrypted" flag -- used by pre-1.0.3 peers
  1144. if (c == ZT_PROTO_CIPHER_SUITE__C25519_POLY1305_SALSA2012)
  1145. b |= ZT_PROTO_FLAG_ENCRYPTED;
  1146. else b &= (~ZT_PROTO_FLAG_ENCRYPTED);
  1147. }
  1148. /**
  1149. * Get the trusted path ID for this packet (only meaningful if cipher is trusted path)
  1150. *
  1151. * @return Trusted path ID (from MAC field)
  1152. */
  1153. inline uint64_t trustedPathId() const { return at<uint64_t>(ZT_PACKET_IDX_MAC); }
  1154. /**
  1155. * Set this packet's trusted path ID and set the cipher spec to trusted path
  1156. *
  1157. * @param tpid Trusted path ID
  1158. */
  1159. inline void setTrusted(const uint64_t tpid)
  1160. {
  1161. setCipher(ZT_PROTO_CIPHER_SUITE__NO_CRYPTO_TRUSTED_PATH);
  1162. setAt(ZT_PACKET_IDX_MAC,tpid);
  1163. }
  1164. /**
  1165. * Get this packet's unique ID (the IV field interpreted as uint64_t)
  1166. *
  1167. * @return Packet ID
  1168. */
  1169. inline uint64_t packetId() const { return at<uint64_t>(ZT_PACKET_IDX_IV); }
  1170. /**
  1171. * Set packet verb
  1172. *
  1173. * This also has the side-effect of clearing any verb flags, such as
  1174. * compressed, and so must only be done during packet composition.
  1175. *
  1176. * @param v New packet verb
  1177. */
  1178. inline void setVerb(Verb v) { (*this)[ZT_PACKET_IDX_VERB] = (char)v; }
  1179. /**
  1180. * @return Packet verb (not including flag bits)
  1181. */
  1182. inline Verb verb() const { return (Verb)((*this)[ZT_PACKET_IDX_VERB] & 0x1f); }
  1183. /**
  1184. * @return Length of packet payload
  1185. */
  1186. inline unsigned int payloadLength() const { return ((size() < ZT_PROTO_MIN_PACKET_LENGTH) ? 0 : (size() - ZT_PROTO_MIN_PACKET_LENGTH)); }
  1187. /**
  1188. * @return Raw packet payload
  1189. */
  1190. inline const unsigned char *payload() const { return field(ZT_PACKET_IDX_PAYLOAD,size() - ZT_PACKET_IDX_PAYLOAD); }
  1191. /**
  1192. * Armor packet for transport
  1193. *
  1194. * @param key 32-byte key
  1195. * @param encryptPayload If true, encrypt packet payload, else just MAC
  1196. */
  1197. void armor(const void *key,bool encryptPayload);
  1198. /**
  1199. * Verify and (if encrypted) decrypt packet
  1200. *
  1201. * This does not handle trusted path mode packets and will return false
  1202. * for these. These are handled in IncomingPacket if the sending physical
  1203. * address and MAC field match a trusted path.
  1204. *
  1205. * @param key 32-byte key
  1206. * @return False if packet is invalid or failed MAC authenticity check
  1207. */
  1208. bool dearmor(const void *key);
  1209. /**
  1210. * Attempt to compress payload if not already (must be unencrypted)
  1211. *
  1212. * This requires that the payload at least contain the verb byte already
  1213. * set. The compressed flag in the verb is set if compression successfully
  1214. * results in a size reduction. If no size reduction occurs, compression
  1215. * is not done and the flag is left cleared.
  1216. *
  1217. * @return True if compression occurred
  1218. */
  1219. bool compress();
  1220. /**
  1221. * Attempt to decompress payload if it is compressed (must be unencrypted)
  1222. *
  1223. * If payload is compressed, it is decompressed and the compressed verb
  1224. * flag is cleared. Otherwise nothing is done and true is returned.
  1225. *
  1226. * @return True if data is now decompressed and valid, false on error
  1227. */
  1228. bool uncompress();
  1229. private:
  1230. static const unsigned char ZERO_KEY[32];
  1231. /**
  1232. * Deterministically mangle a 256-bit crypto key based on packet
  1233. *
  1234. * This uses extra data from the packet to mangle the secret, giving us an
  1235. * effective IV that is somewhat more than 64 bits. This is "free" for
  1236. * Salsa20 since it has negligible key setup time so using a different
  1237. * key each time is fine.
  1238. *
  1239. * @param in Input key (32 bytes)
  1240. * @param out Output buffer (32 bytes)
  1241. */
  1242. inline void _salsa20MangleKey(const unsigned char *in,unsigned char *out) const
  1243. {
  1244. const unsigned char *d = (const unsigned char *)data();
  1245. // IV and source/destination addresses. Using the addresses divides the
  1246. // key space into two halves-- A->B and B->A (since order will change).
  1247. for(unsigned int i=0;i<18;++i) // 8 + (ZT_ADDRESS_LENGTH * 2) == 18
  1248. out[i] = in[i] ^ d[i];
  1249. // Flags, but with hop count masked off. Hop count is altered by forwarding
  1250. // nodes. It's one of the only parts of a packet modifiable by people
  1251. // without the key.
  1252. out[18] = in[18] ^ (d[ZT_PACKET_IDX_FLAGS] & 0xf8);
  1253. // Raw packet size in bytes -- thus each packet size defines a new
  1254. // key space.
  1255. out[19] = in[19] ^ (unsigned char)(size() & 0xff);
  1256. out[20] = in[20] ^ (unsigned char)((size() >> 8) & 0xff); // little endian
  1257. // Rest of raw key is used unchanged
  1258. for(unsigned int i=21;i<32;++i)
  1259. out[i] = in[i];
  1260. }
  1261. };
  1262. } // namespace ZeroTier
  1263. #endif