1 /* 2 * Copyright (c)2013-2020 ZeroTier, Inc. 3 * 4 * Use of this software is governed by the Business Source License included 5 * in the LICENSE.TXT file in the project's root directory. 6 * 7 * Change Date: 2025-01-01 8 * 9 * On the date above, in accordance with the Business Source License, use 10 * of this software will be governed by version 2.0 of the Apache License. 11 */ 12 /****/ 13 14 #ifndef ZT_N_PACKET_HPP 15 #define ZT_N_PACKET_HPP 16 17 #include <stdint.h> 18 #include <string.h> 19 #include <stdio.h> 20 21 #include <string> 22 #include <iostream> 23 24 #include "Constants.hpp" 25 26 #include "Address.hpp" 27 #include "Poly1305.hpp" 28 #include "Salsa20.hpp" 29 #include "AES.hpp" 30 #include "Utils.hpp" 31 #include "Buffer.hpp" 32 33 /** 34 * Protocol version -- incremented only for major changes 35 * 36 * 1 - 0.2.0 ... 0.2.5 37 * 2 - 0.3.0 ... 0.4.5 38 * + Added signature and originating peer to multicast frame 39 * + Double size of multicast frame bloom filter 40 * 3 - 0.5.0 ... 0.6.0 41 * + Yet another multicast redesign 42 * + New crypto completely changes key agreement cipher 43 * 4 - 0.6.0 ... 1.0.6 44 * + BREAKING CHANGE: New identity format based on hashcash design 45 * 5 - 1.1.0 ... 1.1.5 46 * + Supports echo 47 * + Supports in-band world (root server definition) updates 48 * + Clustering! (Though this will work with protocol v4 clients.) 49 * + Otherwise backward compatible with protocol v4 50 * 6 - 1.1.5 ... 1.1.10 51 * + Network configuration format revisions including binary values 52 * 7 - 1.1.10 ... 1.1.17 53 * + Introduce trusted paths for local SDN use 54 * 8 - 1.1.17 ... 1.2.0 55 * + Multipart network configurations for large network configs 56 * + Tags and Capabilities 57 * + Inline push of CertificateOfMembership deprecated 58 * 9 - 1.2.0 ... 1.2.14 59 * 10 - 1.4.0 ... 1.4.6 60 * 11 - 1.4.7 ... 1.4.8 61 * + Multipath capability and load balancing (beta) 62 * 12 - 1.4.8 ... CURRENT (1.4 series) 63 * + AES-GMAC-SIV backported for faster peer-to-peer crypto 64 */ 65 #define ZT_PROTO_VERSION 12 66 67 /** 68 * Minimum supported protocol version 69 */ 70 #define ZT_PROTO_VERSION_MIN 4 71 72 /** 73 * Maximum hop count allowed by packet structure (3 bits, 0-7) 74 * 75 * This is a protocol constant. It's the maximum allowed by the length 76 * of the hop counter -- three bits. See node/Constants.hpp for the 77 * pragmatic forwarding limit, which is typically lower. 78 */ 79 #define ZT_PROTO_MAX_HOPS 7 80 81 /** 82 * Cipher suite: Curve25519/Poly1305/Salsa20/12/NOCRYPT 83 * 84 * This specifies Poly1305 MAC using a 32-bit key derived from the first 85 * 32 bytes of a Salsa20/12 keystream as in the Salsa20/12 cipher suite, 86 * but the payload is not encrypted. This is currently only used to send 87 * HELLO since that's the public key specification packet and must be 88 * sent in the clear. Key agreement is performed using Curve25519 elliptic 89 * curve Diffie-Hellman. 90 */ 91 #define ZT_PROTO_CIPHER_SUITE__C25519_POLY1305_NONE 0 92 93 /** 94 * Cipher suite: Curve25519/Poly1305/Salsa20/12 95 * 96 * This specifies Poly1305 using the first 32 bytes of a Salsa20/12 key 97 * stream as its one-time-use key followed by payload encryption with 98 * the remaining Salsa20/12 key stream. Key agreement is performed using 99 * Curve25519 elliptic curve Diffie-Hellman. 100 */ 101 #define ZT_PROTO_CIPHER_SUITE__C25519_POLY1305_SALSA2012 1 102 103 /** 104 * AES-GMAC-SIV backported from 2.x 105 */ 106 #define ZT_PROTO_CIPHER_SUITE__AES_GMAC_SIV 3 107 108 /** 109 * AES-GMAC-SIV first of two keys 110 */ 111 #define ZT_KBKDF_LABEL_AES_GMAC_SIV_K0 '0' 112 113 /** 114 * AES-GMAC-SIV second of two keys 115 */ 116 #define ZT_KBKDF_LABEL_AES_GMAC_SIV_K1 '1' 117 118 /** 119 * Cipher suite: NONE 120 * 121 * This differs from POLY1305/NONE in that *no* crypto is done, not even 122 * authentication. This is for trusted local LAN interconnects for internal 123 * SDN use within a data center. 124 * 125 * For this mode the MAC field becomes a trusted path ID and must match the 126 * configured ID of a trusted path or the packet is discarded. 127 */ 128 #define ZT_PROTO_CIPHER_SUITE__NO_CRYPTO_TRUSTED_PATH 2 129 130 /** 131 * DEPRECATED payload encrypted flag, may be re-used in the future. 132 * 133 * This has been replaced by the three-bit cipher suite selection field. 134 */ 135 #define ZT_PROTO_FLAG_ENCRYPTED 0x80 136 137 /** 138 * Header flag indicating that a packet is fragmented 139 * 140 * If this flag is set, the receiver knows to expect more than one fragment. 141 * See Packet::Fragment for details. 142 */ 143 #define ZT_PROTO_FLAG_FRAGMENTED 0x40 144 145 /** 146 * Verb flag indicating payload is compressed with LZ4 147 */ 148 #define ZT_PROTO_VERB_FLAG_COMPRESSED 0x80 149 150 /** 151 * Rounds used for Salsa20 encryption in ZT 152 * 153 * Discussion: 154 * 155 * DJB (Salsa20's designer) designed Salsa20 with a significant margin of 20 156 * rounds, but has said repeatedly that 12 is likely sufficient. So far (as of 157 * July 2015) there are no published attacks against 12 rounds, let alone 20. 158 * 159 * In cryptography, a "break" means something different from what it means in 160 * common discussion. If a cipher is 256 bits strong and someone finds a way 161 * to reduce key search to 254 bits, this constitutes a "break" in the academic 162 * literature. 254 bits is still far beyond what can be leveraged to accomplish 163 * a "break" as most people would understand it -- the actual decryption and 164 * reading of traffic. 165 * 166 * Nevertheless, "attacks only get better" as cryptographers like to say. As 167 * a result, they recommend not using anything that's shown any weakness even 168 * if that weakness is so far only meaningful to academics. It may be a sign 169 * of a deeper problem. 170 * 171 * So why choose a lower round count? 172 * 173 * Turns out the speed difference is nontrivial. On a Macbook Pro (Core i3) 20 174 * rounds of SSE-optimized Salsa20 achieves ~508mb/sec/core, while 12 rounds 175 * hits ~832mb/sec/core. ZeroTier is designed for multiple objectives: 176 * security, simplicity, and performance. In this case a deference was made 177 * for performance. 178 * 179 * Meta discussion: 180 * 181 * The cipher is not the thing you should be paranoid about. 182 * 183 * I'll qualify that. If the cipher is known to be weak, like RC4, or has a 184 * key size that is too small, like DES, then yes you should worry about 185 * the cipher. 186 * 187 * But if the cipher is strong and your adversary is anyone other than the 188 * intelligence apparatus of a major superpower, you are fine in that 189 * department. 190 * 191 * Go ahead. Search for the last ten vulnerabilities discovered in SSL. Not 192 * a single one involved the breaking of a cipher. Now broaden your search. 193 * Look for issues with SSH, IPSec, etc. The only cipher-related issues you 194 * will find might involve the use of RC4 or MD5, algorithms with known 195 * issues or small key/digest sizes. But even weak ciphers are difficult to 196 * exploit in the real world -- you usually need a lot of data and a lot of 197 * compute time. No, virtually EVERY security vulnerability you will find 198 * involves a problem with the IMPLEMENTATION not with the cipher. 199 * 200 * A flaw in ZeroTier's protocol or code is incredibly, unbelievably 201 * more likely than a flaw in Salsa20 or any other cipher or cryptographic 202 * primitive it uses. We're talking odds of dying in a car wreck vs. odds of 203 * being personally impacted on the head by a meteorite. Nobody without a 204 * billion dollar budget is going to break into your network by actually 205 * cracking Salsa20/12 (or even /8) in the field. 206 * 207 * So stop worrying about the cipher unless you are, say, the Kremlin and your 208 * adversary is the NSA and the GCHQ. In that case... well that's above my 209 * pay grade. I'll just say defense in depth. 210 */ 211 #define ZT_PROTO_SALSA20_ROUNDS 12 212 213 /** 214 * PUSH_DIRECT_PATHS flag: forget path 215 */ 216 #define ZT_PUSH_DIRECT_PATHS_FLAG_FORGET_PATH 0x01 217 218 /** 219 * PUSH_DIRECT_PATHS flag: cluster redirect 220 */ 221 #define ZT_PUSH_DIRECT_PATHS_FLAG_CLUSTER_REDIRECT 0x02 222 223 // Field indexes in packet header 224 #define ZT_PACKET_IDX_IV 0 225 #define ZT_PACKET_IDX_DEST 8 226 #define ZT_PACKET_IDX_SOURCE 13 227 #define ZT_PACKET_IDX_FLAGS 18 228 #define ZT_PACKET_IDX_MAC 19 229 #define ZT_PACKET_IDX_VERB 27 230 #define ZT_PACKET_IDX_PAYLOAD 28 231 232 /** 233 * Packet buffer size (can be changed) 234 */ 235 #define ZT_PROTO_MAX_PACKET_LENGTH (ZT_MAX_PACKET_FRAGMENTS * ZT_DEFAULT_PHYSMTU) 236 237 /** 238 * Minimum viable packet length (a.k.a. header length) 239 */ 240 #define ZT_PROTO_MIN_PACKET_LENGTH ZT_PACKET_IDX_PAYLOAD 241 242 // Indexes of fields in fragment header 243 #define ZT_PACKET_FRAGMENT_IDX_PACKET_ID 0 244 #define ZT_PACKET_FRAGMENT_IDX_DEST 8 245 #define ZT_PACKET_FRAGMENT_IDX_FRAGMENT_INDICATOR 13 246 #define ZT_PACKET_FRAGMENT_IDX_FRAGMENT_NO 14 247 #define ZT_PACKET_FRAGMENT_IDX_HOPS 15 248 #define ZT_PACKET_FRAGMENT_IDX_PAYLOAD 16 249 250 /** 251 * Magic number found at ZT_PACKET_FRAGMENT_IDX_FRAGMENT_INDICATOR 252 */ 253 #define ZT_PACKET_FRAGMENT_INDICATOR ZT_ADDRESS_RESERVED_PREFIX 254 255 /** 256 * Minimum viable fragment length 257 */ 258 #define ZT_PROTO_MIN_FRAGMENT_LENGTH ZT_PACKET_FRAGMENT_IDX_PAYLOAD 259 260 // Field indices for parsing verbs ------------------------------------------- 261 262 // Some verbs have variable-length fields. Those aren't fully defined here 263 // yet-- instead they are parsed using relative indexes in IncomingPacket. 264 // See their respective handler functions. 265 266 #define ZT_PROTO_VERB_HELLO_IDX_PROTOCOL_VERSION (ZT_PACKET_IDX_PAYLOAD) 267 #define ZT_PROTO_VERB_HELLO_IDX_MAJOR_VERSION (ZT_PROTO_VERB_HELLO_IDX_PROTOCOL_VERSION + 1) 268 #define ZT_PROTO_VERB_HELLO_IDX_MINOR_VERSION (ZT_PROTO_VERB_HELLO_IDX_MAJOR_VERSION + 1) 269 #define ZT_PROTO_VERB_HELLO_IDX_REVISION (ZT_PROTO_VERB_HELLO_IDX_MINOR_VERSION + 1) 270 #define ZT_PROTO_VERB_HELLO_IDX_TIMESTAMP (ZT_PROTO_VERB_HELLO_IDX_REVISION + 2) 271 #define ZT_PROTO_VERB_HELLO_IDX_IDENTITY (ZT_PROTO_VERB_HELLO_IDX_TIMESTAMP + 8) 272 273 #define ZT_PROTO_VERB_ERROR_IDX_IN_RE_VERB (ZT_PACKET_IDX_PAYLOAD) 274 #define ZT_PROTO_VERB_ERROR_IDX_IN_RE_PACKET_ID (ZT_PROTO_VERB_ERROR_IDX_IN_RE_VERB + 1) 275 #define ZT_PROTO_VERB_ERROR_IDX_ERROR_CODE (ZT_PROTO_VERB_ERROR_IDX_IN_RE_PACKET_ID + 8) 276 #define ZT_PROTO_VERB_ERROR_IDX_PAYLOAD (ZT_PROTO_VERB_ERROR_IDX_ERROR_CODE + 1) 277 278 #define ZT_PROTO_VERB_OK_IDX_IN_RE_VERB (ZT_PACKET_IDX_PAYLOAD) 279 #define ZT_PROTO_VERB_OK_IDX_IN_RE_PACKET_ID (ZT_PROTO_VERB_OK_IDX_IN_RE_VERB + 1) 280 #define ZT_PROTO_VERB_OK_IDX_PAYLOAD (ZT_PROTO_VERB_OK_IDX_IN_RE_PACKET_ID + 8) 281 282 #define ZT_PROTO_VERB_WHOIS_IDX_ZTADDRESS (ZT_PACKET_IDX_PAYLOAD) 283 284 #define ZT_PROTO_VERB_RENDEZVOUS_IDX_FLAGS (ZT_PACKET_IDX_PAYLOAD) 285 #define ZT_PROTO_VERB_RENDEZVOUS_IDX_ZTADDRESS (ZT_PROTO_VERB_RENDEZVOUS_IDX_FLAGS + 1) 286 #define ZT_PROTO_VERB_RENDEZVOUS_IDX_PORT (ZT_PROTO_VERB_RENDEZVOUS_IDX_ZTADDRESS + 5) 287 #define ZT_PROTO_VERB_RENDEZVOUS_IDX_ADDRLEN (ZT_PROTO_VERB_RENDEZVOUS_IDX_PORT + 2) 288 #define ZT_PROTO_VERB_RENDEZVOUS_IDX_ADDRESS (ZT_PROTO_VERB_RENDEZVOUS_IDX_ADDRLEN + 1) 289 290 #define ZT_PROTO_VERB_FRAME_IDX_NETWORK_ID (ZT_PACKET_IDX_PAYLOAD) 291 #define ZT_PROTO_VERB_FRAME_IDX_ETHERTYPE (ZT_PROTO_VERB_FRAME_IDX_NETWORK_ID + 8) 292 #define ZT_PROTO_VERB_FRAME_IDX_PAYLOAD (ZT_PROTO_VERB_FRAME_IDX_ETHERTYPE + 2) 293 294 #define ZT_PROTO_VERB_EXT_FRAME_IDX_NETWORK_ID (ZT_PACKET_IDX_PAYLOAD) 295 #define ZT_PROTO_VERB_EXT_FRAME_LEN_NETWORK_ID 8 296 #define ZT_PROTO_VERB_EXT_FRAME_IDX_FLAGS (ZT_PROTO_VERB_EXT_FRAME_IDX_NETWORK_ID + ZT_PROTO_VERB_EXT_FRAME_LEN_NETWORK_ID) 297 #define ZT_PROTO_VERB_EXT_FRAME_LEN_FLAGS 1 298 #define ZT_PROTO_VERB_EXT_FRAME_IDX_COM (ZT_PROTO_VERB_EXT_FRAME_IDX_FLAGS + ZT_PROTO_VERB_EXT_FRAME_LEN_FLAGS) 299 #define ZT_PROTO_VERB_EXT_FRAME_IDX_TO (ZT_PROTO_VERB_EXT_FRAME_IDX_FLAGS + ZT_PROTO_VERB_EXT_FRAME_LEN_FLAGS) 300 #define ZT_PROTO_VERB_EXT_FRAME_LEN_TO 6 301 #define ZT_PROTO_VERB_EXT_FRAME_IDX_FROM (ZT_PROTO_VERB_EXT_FRAME_IDX_TO + ZT_PROTO_VERB_EXT_FRAME_LEN_TO) 302 #define ZT_PROTO_VERB_EXT_FRAME_LEN_FROM 6 303 #define ZT_PROTO_VERB_EXT_FRAME_IDX_ETHERTYPE (ZT_PROTO_VERB_EXT_FRAME_IDX_FROM + ZT_PROTO_VERB_EXT_FRAME_LEN_FROM) 304 #define ZT_PROTO_VERB_EXT_FRAME_LEN_ETHERTYPE 2 305 #define ZT_PROTO_VERB_EXT_FRAME_IDX_PAYLOAD (ZT_PROTO_VERB_EXT_FRAME_IDX_ETHERTYPE + ZT_PROTO_VERB_EXT_FRAME_LEN_ETHERTYPE) 306 307 #define ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST_IDX_NETWORK_ID (ZT_PACKET_IDX_PAYLOAD) 308 #define ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST_IDX_DICT_LEN (ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST_IDX_NETWORK_ID + 8) 309 #define ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST_IDX_DICT (ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST_IDX_DICT_LEN + 2) 310 311 #define ZT_PROTO_VERB_MULTICAST_GATHER_IDX_NETWORK_ID (ZT_PACKET_IDX_PAYLOAD) 312 #define ZT_PROTO_VERB_MULTICAST_GATHER_IDX_FLAGS (ZT_PROTO_VERB_MULTICAST_GATHER_IDX_NETWORK_ID + 8) 313 #define ZT_PROTO_VERB_MULTICAST_GATHER_IDX_MAC (ZT_PROTO_VERB_MULTICAST_GATHER_IDX_FLAGS + 1) 314 #define ZT_PROTO_VERB_MULTICAST_GATHER_IDX_ADI (ZT_PROTO_VERB_MULTICAST_GATHER_IDX_MAC + 6) 315 #define ZT_PROTO_VERB_MULTICAST_GATHER_IDX_GATHER_LIMIT (ZT_PROTO_VERB_MULTICAST_GATHER_IDX_ADI + 4) 316 #define ZT_PROTO_VERB_MULTICAST_GATHER_IDX_COM (ZT_PROTO_VERB_MULTICAST_GATHER_IDX_GATHER_LIMIT + 4) 317 318 // Note: COM, GATHER_LIMIT, and SOURCE_MAC are optional, and so are specified without size 319 #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_NETWORK_ID (ZT_PACKET_IDX_PAYLOAD) 320 #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_FLAGS (ZT_PROTO_VERB_MULTICAST_FRAME_IDX_NETWORK_ID + 8) 321 #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_COM (ZT_PROTO_VERB_MULTICAST_FRAME_IDX_FLAGS + 1) 322 #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_GATHER_LIMIT (ZT_PROTO_VERB_MULTICAST_FRAME_IDX_FLAGS + 1) 323 #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_SOURCE_MAC (ZT_PROTO_VERB_MULTICAST_FRAME_IDX_FLAGS + 1) 324 #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_DEST_MAC (ZT_PROTO_VERB_MULTICAST_FRAME_IDX_FLAGS + 1) 325 #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_DEST_ADI (ZT_PROTO_VERB_MULTICAST_FRAME_IDX_DEST_MAC + 6) 326 #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_ETHERTYPE (ZT_PROTO_VERB_MULTICAST_FRAME_IDX_DEST_ADI + 4) 327 #define ZT_PROTO_VERB_MULTICAST_FRAME_IDX_FRAME (ZT_PROTO_VERB_MULTICAST_FRAME_IDX_ETHERTYPE + 2) 328 329 #define ZT_PROTO_VERB_HELLO__OK__IDX_TIMESTAMP (ZT_PROTO_VERB_OK_IDX_PAYLOAD) 330 #define ZT_PROTO_VERB_HELLO__OK__IDX_PROTOCOL_VERSION (ZT_PROTO_VERB_HELLO__OK__IDX_TIMESTAMP + 8) 331 #define ZT_PROTO_VERB_HELLO__OK__IDX_MAJOR_VERSION (ZT_PROTO_VERB_HELLO__OK__IDX_PROTOCOL_VERSION + 1) 332 #define ZT_PROTO_VERB_HELLO__OK__IDX_MINOR_VERSION (ZT_PROTO_VERB_HELLO__OK__IDX_MAJOR_VERSION + 1) 333 #define ZT_PROTO_VERB_HELLO__OK__IDX_REVISION (ZT_PROTO_VERB_HELLO__OK__IDX_MINOR_VERSION + 1) 334 335 #define ZT_PROTO_VERB_WHOIS__OK__IDX_IDENTITY (ZT_PROTO_VERB_OK_IDX_PAYLOAD) 336 337 #define ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST__OK__IDX_NETWORK_ID (ZT_PROTO_VERB_OK_IDX_PAYLOAD) 338 #define ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST__OK__IDX_DICT_LEN (ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST__OK__IDX_NETWORK_ID + 8) 339 #define ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST__OK__IDX_DICT (ZT_PROTO_VERB_NETWORK_CONFIG_REQUEST__OK__IDX_DICT_LEN + 2) 340 341 #define ZT_PROTO_VERB_MULTICAST_GATHER__OK__IDX_NETWORK_ID (ZT_PROTO_VERB_OK_IDX_PAYLOAD) 342 #define ZT_PROTO_VERB_MULTICAST_GATHER__OK__IDX_MAC (ZT_PROTO_VERB_MULTICAST_GATHER__OK__IDX_NETWORK_ID + 8) 343 #define ZT_PROTO_VERB_MULTICAST_GATHER__OK__IDX_ADI (ZT_PROTO_VERB_MULTICAST_GATHER__OK__IDX_MAC + 6) 344 #define ZT_PROTO_VERB_MULTICAST_GATHER__OK__IDX_GATHER_RESULTS (ZT_PROTO_VERB_MULTICAST_GATHER__OK__IDX_ADI + 4) 345 346 #define ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_NETWORK_ID (ZT_PROTO_VERB_OK_IDX_PAYLOAD) 347 #define ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_MAC (ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_NETWORK_ID + 8) 348 #define ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_ADI (ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_MAC + 6) 349 #define ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_FLAGS (ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_ADI + 4) 350 #define ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_COM_AND_GATHER_RESULTS (ZT_PROTO_VERB_MULTICAST_FRAME__OK__IDX_FLAGS + 1) 351 352 // --------------------------------------------------------------------------- 353 354 namespace ZeroTier { 355 356 /** 357 * ZeroTier packet 358 * 359 * Packet format: 360 * <[8] 64-bit packet ID / crypto IV / packet counter> 361 * <[5] destination ZT address> 362 * <[5] source ZT address> 363 * <[1] flags/cipher/hops> 364 * <[8] 64-bit MAC (or trusted path ID in trusted path mode)> 365 * [... -- begin encryption envelope -- ...] 366 * <[1] encrypted flags (MS 3 bits) and verb (LS 5 bits)> 367 * [... verb-specific payload ...] 368 * 369 * Packets smaller than 28 bytes are invalid and silently discarded. 370 * 371 * The 64-bit packet ID is a strongly random value used as a crypto IV. 372 * Its least significant 3 bits are also used as a monotonically increasing 373 * (and looping) counter for sending packets to a particular recipient. This 374 * can be used for link quality monitoring and reporting and has no crypto 375 * impact as it does not increase the likelihood of an IV collision. (The 376 * crypto we use is not sensitive to the nature of the IV, only that it does 377 * not repeat.) 378 * 379 * The flags/cipher/hops bit field is: FFCCCHHH where C is a 3-bit cipher 380 * selection allowing up to 7 cipher suites, F is outside-envelope flags, 381 * and H is hop count. 382 * 383 * The three-bit hop count is the only part of a packet that is mutable in 384 * transit without invalidating the MAC. All other bits in the packet are 385 * immutable. This is because intermediate nodes can increment the hop 386 * count up to 7 (protocol max). 387 * 388 * For unencrypted packets, MAC is computed on plaintext. Only HELLO is ever 389 * sent in the clear, as it's the "here is my public key" message. 390 */ 391 class Packet : public Buffer<ZT_PROTO_MAX_PACKET_LENGTH> 392 { 393 public: 394 /** 395 * A packet fragment 396 * 397 * Fragments are sent if a packet is larger than UDP MTU. The first fragment 398 * is sent with its normal header with the fragmented flag set. Remaining 399 * fragments are sent this way. 400 * 401 * The fragmented bit indicates that there is at least one fragment. Fragments 402 * themselves contain the total, so the receiver must "learn" this from the 403 * first fragment it receives. 404 * 405 * Fragments are sent with the following format: 406 * <[8] packet ID of packet whose fragment this belongs to> 407 * <[5] destination ZT address> 408 * <[1] 0xff, a reserved address, signals that this isn't a normal packet> 409 * <[1] total fragments (most significant 4 bits), fragment no (LS 4 bits)> 410 * <[1] ZT hop count (top 5 bits unused and must be zero)> 411 * <[...] fragment data> 412 * 413 * The protocol supports a maximum of 16 fragments. If a fragment is received 414 * before its main packet header, it should be cached for a brief period of 415 * time to see if its parent arrives. Loss of any fragment constitutes packet 416 * loss; there is no retransmission mechanism. The receiver must wait for full 417 * receipt to authenticate and decrypt; there is no per-fragment MAC. (But if 418 * fragments are corrupt, the MAC will fail for the whole assembled packet.) 419 */ 420 class Fragment : public Buffer<ZT_PROTO_MAX_PACKET_LENGTH> 421 { 422 public: Fragment()423 Fragment() : 424 Buffer<ZT_PROTO_MAX_PACKET_LENGTH>() 425 { 426 } 427 428 template<unsigned int C2> Fragment(const Buffer<C2> & b)429 Fragment(const Buffer<C2> &b) : 430 Buffer<ZT_PROTO_MAX_PACKET_LENGTH>(b) 431 { 432 } 433 Fragment(const void * data,unsigned int len)434 Fragment(const void *data,unsigned int len) : 435 Buffer<ZT_PROTO_MAX_PACKET_LENGTH>(data,len) 436 { 437 } 438 439 /** 440 * Initialize from a packet 441 * 442 * @param p Original assembled packet 443 * @param fragStart Start of fragment (raw index in packet data) 444 * @param fragLen Length of fragment in bytes 445 * @param fragNo Which fragment (>= 1, since 0 is Packet with end chopped off) 446 * @param fragTotal Total number of fragments (including 0) 447 */ Fragment(const Packet & p,unsigned int fragStart,unsigned int fragLen,unsigned int fragNo,unsigned int fragTotal)448 Fragment(const Packet &p,unsigned int fragStart,unsigned int fragLen,unsigned int fragNo,unsigned int fragTotal) 449 { 450 init(p,fragStart,fragLen,fragNo,fragTotal); 451 } 452 453 /** 454 * Initialize from a packet 455 * 456 * @param p Original assembled packet 457 * @param fragStart Start of fragment (raw index in packet data) 458 * @param fragLen Length of fragment in bytes 459 * @param fragNo Which fragment (>= 1, since 0 is Packet with end chopped off) 460 * @param fragTotal Total number of fragments (including 0) 461 */ init(const Packet & p,unsigned int fragStart,unsigned int fragLen,unsigned int fragNo,unsigned int fragTotal)462 inline void init(const Packet &p,unsigned int fragStart,unsigned int fragLen,unsigned int fragNo,unsigned int fragTotal) 463 { 464 if ((fragStart + fragLen) > p.size()) 465 throw ZT_EXCEPTION_OUT_OF_BOUNDS; 466 setSize(fragLen + ZT_PROTO_MIN_FRAGMENT_LENGTH); 467 468 // NOTE: this copies both the IV/packet ID and the destination address. 469 memcpy(field(ZT_PACKET_FRAGMENT_IDX_PACKET_ID,13),p.field(ZT_PACKET_IDX_IV,13),13); 470 471 (*this)[ZT_PACKET_FRAGMENT_IDX_FRAGMENT_INDICATOR] = ZT_PACKET_FRAGMENT_INDICATOR; 472 (*this)[ZT_PACKET_FRAGMENT_IDX_FRAGMENT_NO] = (char)(((fragTotal & 0xf) << 4) | (fragNo & 0xf)); 473 (*this)[ZT_PACKET_FRAGMENT_IDX_HOPS] = 0; 474 475 memcpy(field(ZT_PACKET_FRAGMENT_IDX_PAYLOAD,fragLen),p.field(fragStart,fragLen),fragLen); 476 } 477 478 /** 479 * Get this fragment's destination 480 * 481 * @return Destination ZT address 482 */ destination() const483 inline Address destination() const { return Address(field(ZT_PACKET_FRAGMENT_IDX_DEST,ZT_ADDRESS_LENGTH),ZT_ADDRESS_LENGTH); } 484 485 /** 486 * @return True if fragment is of a valid length 487 */ lengthValid() const488 inline bool lengthValid() const { return (size() >= ZT_PACKET_FRAGMENT_IDX_PAYLOAD); } 489 490 /** 491 * @return ID of packet this is a fragment of 492 */ packetId() const493 inline uint64_t packetId() const { return at<uint64_t>(ZT_PACKET_FRAGMENT_IDX_PACKET_ID); } 494 495 /** 496 * @return Total number of fragments in packet 497 */ totalFragments() const498 inline unsigned int totalFragments() const { return (((unsigned int)((*this)[ZT_PACKET_FRAGMENT_IDX_FRAGMENT_NO]) >> 4) & 0xf); } 499 500 /** 501 * @return Fragment number of this fragment 502 */ fragmentNumber() const503 inline unsigned int fragmentNumber() const { return ((unsigned int)((*this)[ZT_PACKET_FRAGMENT_IDX_FRAGMENT_NO]) & 0xf); } 504 505 /** 506 * @return Fragment ZT hop count 507 */ hops() const508 inline unsigned int hops() const { return (unsigned int)((*this)[ZT_PACKET_FRAGMENT_IDX_HOPS]); } 509 510 /** 511 * Increment this packet's hop count 512 */ incrementHops()513 inline void incrementHops() 514 { 515 (*this)[ZT_PACKET_FRAGMENT_IDX_HOPS] = (((*this)[ZT_PACKET_FRAGMENT_IDX_HOPS]) + 1) & ZT_PROTO_MAX_HOPS; 516 } 517 518 /** 519 * @return Length of payload in bytes 520 */ payloadLength() const521 inline unsigned int payloadLength() const { return ((size() > ZT_PACKET_FRAGMENT_IDX_PAYLOAD) ? (size() - ZT_PACKET_FRAGMENT_IDX_PAYLOAD) : 0); } 522 523 /** 524 * @return Raw packet payload 525 */ payload() const526 inline const unsigned char *payload() const 527 { 528 return field(ZT_PACKET_FRAGMENT_IDX_PAYLOAD,size() - ZT_PACKET_FRAGMENT_IDX_PAYLOAD); 529 } 530 }; 531 532 /** 533 * ZeroTier protocol verbs 534 */ 535 enum Verb /* Max value: 32 (5 bits) */ 536 { 537 /** 538 * No operation (ignored, no reply) 539 */ 540 VERB_NOP = 0x00, 541 542 /** 543 * Announcement of a node's existence and vitals: 544 * <[1] protocol version> 545 * <[1] software major version> 546 * <[1] software minor version> 547 * <[2] software revision> 548 * <[8] timestamp for determining latency> 549 * <[...] binary serialized identity (see Identity)> 550 * <[...] physical destination address of packet> 551 * <[8] 64-bit world ID of current planet> 552 * <[8] 64-bit timestamp of current planet> 553 * [... remainder if packet is encrypted using cryptField() ...] 554 * <[2] 16-bit number of moons> 555 * [<[1] 8-bit type ID of moon>] 556 * [<[8] 64-bit world ID of moon>] 557 * [<[8] 64-bit timestamp of moon>] 558 * [... additional moon type/ID/timestamp tuples ...] 559 * 560 * HELLO is sent in the clear as it is how peers share their identity 561 * public keys. A few additional fields are sent in the clear too, but 562 * these are things that are public info or are easy to determine. As 563 * of 1.2.0 we have added a few more fields, but since these could have 564 * the potential to be sensitive we introduced the encryption of the 565 * remainder of the packet. See cryptField(). Packet MAC is still 566 * performed of course, so authentication occurs as normal. 567 * 568 * Destination address is the actual wire address to which the packet 569 * was sent. See InetAddress::serialize() for format. 570 * 571 * OK payload: 572 * <[8] HELLO timestamp field echo> 573 * <[1] protocol version> 574 * <[1] software major version> 575 * <[1] software minor version> 576 * <[2] software revision> 577 * <[...] physical destination address of packet> 578 * <[2] 16-bit length of world update(s) or 0 if none> 579 * [[...] updates to planets and/or moons] 580 * 581 * With the exception of the timestamp, the other fields pertain to the 582 * respondent who is sending OK and are not echoes. 583 * 584 * Note that OK is fully encrypted so no selective cryptField() of 585 * potentially sensitive fields is needed. 586 * 587 * ERROR has no payload. 588 */ 589 VERB_HELLO = 0x01, 590 591 /** 592 * Error response: 593 * <[1] in-re verb> 594 * <[8] in-re packet ID> 595 * <[1] error code> 596 * <[...] error-dependent payload> 597 */ 598 VERB_ERROR = 0x02, 599 600 /** 601 * Success response: 602 * <[1] in-re verb> 603 * <[8] in-re packet ID> 604 * <[...] request-specific payload> 605 */ 606 VERB_OK = 0x03, 607 608 /** 609 * Query an identity by address: 610 * <[5] address to look up> 611 * [<[...] additional addresses to look up> 612 * 613 * OK response payload: 614 * <[...] binary serialized identity> 615 * [<[...] additional binary serialized identities>] 616 * 617 * If querying a cluster, duplicate OK responses may occasionally occur. 618 * These must be tolerated, which is easy since they'll have info you 619 * already have. 620 * 621 * If the address is not found, no response is generated. The semantics 622 * of WHOIS is similar to ARP and NDP in that persistent retrying can 623 * be performed. 624 */ 625 VERB_WHOIS = 0x04, 626 627 /** 628 * Relay-mediated NAT traversal or firewall punching initiation: 629 * <[1] flags (unused, currently 0)> 630 * <[5] ZeroTier address of peer that might be found at this address> 631 * <[2] 16-bit protocol address port> 632 * <[1] protocol address length (4 for IPv4, 16 for IPv6)> 633 * <[...] protocol address (network byte order)> 634 * 635 * An upstream node can send this to inform both sides of a relay of 636 * information they might use to establish a direct connection. 637 * 638 * Upon receipt a peer sends HELLO to establish a direct link. 639 * 640 * No OK or ERROR is generated. 641 */ 642 VERB_RENDEZVOUS = 0x05, 643 644 /** 645 * ZT-to-ZT unicast ethernet frame (shortened EXT_FRAME): 646 * <[8] 64-bit network ID> 647 * <[2] 16-bit ethertype> 648 * <[...] ethernet payload> 649 * 650 * MAC addresses are derived from the packet's source and destination 651 * ZeroTier addresses. This is a shortened EXT_FRAME that elides full 652 * Ethernet framing and other optional flags and features when they 653 * are not necessary. 654 * 655 * ERROR may be generated if a membership certificate is needed for a 656 * closed network. Payload will be network ID. 657 */ 658 VERB_FRAME = 0x06, 659 660 /** 661 * Full Ethernet frame with MAC addressing and optional fields: 662 * <[8] 64-bit network ID> 663 * <[1] flags> 664 * <[6] destination MAC or all zero for destination node> 665 * <[6] source MAC or all zero for node of origin> 666 * <[2] 16-bit ethertype> 667 * <[...] ethernet payload> 668 * 669 * Flags: 670 * 0x01 - Certificate of network membership attached (DEPRECATED) 671 * 0x02 - Most significant bit of subtype (see below) 672 * 0x04 - Middle bit of subtype (see below) 673 * 0x08 - Least significant bit of subtype (see below) 674 * 0x10 - ACK requested in the form of OK(EXT_FRAME) 675 * 676 * Subtypes (0..7): 677 * 0x0 - Normal frame (bridging can be determined by checking MAC) 678 * 0x1 - TEEd outbound frame 679 * 0x2 - REDIRECTed outbound frame 680 * 0x3 - WATCHed outbound frame (TEE with ACK, ACK bit also set) 681 * 0x4 - TEEd inbound frame 682 * 0x5 - REDIRECTed inbound frame 683 * 0x6 - WATCHed inbound frame 684 * 0x7 - (reserved for future use) 685 * 686 * An extended frame carries full MAC addressing, making it a 687 * superset of VERB_FRAME. It is used for bridged traffic, 688 * redirected or observed traffic via rules, and can in theory 689 * be used for multicast though MULTICAST_FRAME exists for that 690 * purpose and has additional options and capabilities. 691 * 692 * OK payload (if ACK flag is set): 693 * <[8] 64-bit network ID> 694 */ 695 VERB_EXT_FRAME = 0x07, 696 697 /** 698 * ECHO request (a.k.a. ping): 699 * <[...] arbitrary payload> 700 * 701 * This generates OK with a copy of the transmitted payload. No ERROR 702 * is generated. Response to ECHO requests is optional and ECHO may be 703 * ignored if a node detects a possible flood. 704 */ 705 VERB_ECHO = 0x08, 706 707 /** 708 * Announce interest in multicast group(s): 709 * <[8] 64-bit network ID> 710 * <[6] multicast Ethernet address> 711 * <[4] multicast additional distinguishing information (ADI)> 712 * [... additional tuples of network/address/adi ...] 713 * 714 * LIKEs may be sent to any peer, though a good implementation should 715 * restrict them to peers on the same network they're for and to network 716 * controllers and root servers. In the current network, root servers 717 * will provide the service of final multicast cache. 718 * 719 * VERB_NETWORK_CREDENTIALS should be pushed along with this, especially 720 * if using upstream (e.g. root) nodes as multicast databases. This allows 721 * GATHERs to be authenticated. 722 * 723 * OK/ERROR are not generated. 724 */ 725 VERB_MULTICAST_LIKE = 0x09, 726 727 /** 728 * Network credentials push: 729 * [<[...] one or more certificates of membership>] 730 * <[1] 0x00, null byte marking end of COM array> 731 * <[2] 16-bit number of capabilities> 732 * <[...] one or more serialized Capability> 733 * <[2] 16-bit number of tags> 734 * <[...] one or more serialized Tags> 735 * <[2] 16-bit number of revocations> 736 * <[...] one or more serialized Revocations> 737 * <[2] 16-bit number of certificates of ownership> 738 * <[...] one or more serialized CertificateOfOwnership> 739 * 740 * This can be sent by anyone at any time to push network credentials. 741 * These will of course only be accepted if they are properly signed. 742 * Credentials can be for any number of networks. 743 * 744 * The use of a zero byte to terminate the COM section is for legacy 745 * backward compatibility. Newer fields are prefixed with a length. 746 * 747 * OK/ERROR are not generated. 748 */ 749 VERB_NETWORK_CREDENTIALS = 0x0a, 750 751 /** 752 * Network configuration request: 753 * <[8] 64-bit network ID> 754 * <[2] 16-bit length of request meta-data dictionary> 755 * <[...] string-serialized request meta-data> 756 * <[8] 64-bit revision of netconf we currently have> 757 * <[8] 64-bit timestamp of netconf we currently have> 758 * 759 * This message requests network configuration from a node capable of 760 * providing it. 761 * 762 * Responses to this are always whole configs intended for the recipient. 763 * For patches and other updates a NETWORK_CONFIG is sent instead. 764 * 765 * It would be valid and correct as of 1.2.0 to use NETWORK_CONFIG always, 766 * but OK(NETWORK_CONFIG_REQUEST) should be sent for compatibility. 767 * 768 * OK response payload: 769 * <[8] 64-bit network ID> 770 * <[2] 16-bit length of network configuration dictionary chunk> 771 * <[...] network configuration dictionary (may be incomplete)> 772 * [ ... end of legacy single chunk response ... ] 773 * <[1] 8-bit flags> 774 * <[8] 64-bit config update ID (should never be 0)> 775 * <[4] 32-bit total length of assembled dictionary> 776 * <[4] 32-bit index of chunk> 777 * [ ... end signed portion ... ] 778 * <[1] 8-bit chunk signature type> 779 * <[2] 16-bit length of chunk signature> 780 * <[...] chunk signature> 781 * 782 * The chunk signature signs the entire payload of the OK response. 783 * Currently only one signature type is supported: ed25519 (1). 784 * 785 * Each config chunk is signed to prevent memory exhaustion or 786 * traffic crowding DOS attacks against config fragment assembly. 787 * 788 * If the packet is from the network controller it is permitted to end 789 * before the config update ID or other chunking related or signature 790 * fields. This is to support older controllers that don't include 791 * these fields and may be removed in the future. 792 * 793 * ERROR response payload: 794 * <[8] 64-bit network ID> 795 * <[2] 16-bit length of error-related data (optional)> 796 * <[...] error-related data (optional)> 797 * 798 * Error related data is a Dictionary containing things like a URL 799 * for authentication or a human-readable error message, and is 800 * optional and may be absent or empty. 801 */ 802 VERB_NETWORK_CONFIG_REQUEST = 0x0b, 803 804 /** 805 * Network configuration data push: 806 * <[8] 64-bit network ID> 807 * <[2] 16-bit length of network configuration dictionary chunk> 808 * <[...] network configuration dictionary (may be incomplete)> 809 * <[1] 8-bit flags> 810 * <[8] 64-bit config update ID (should never be 0)> 811 * <[4] 32-bit total length of assembled dictionary> 812 * <[4] 32-bit index of chunk> 813 * [ ... end signed portion ... ] 814 * <[1] 8-bit chunk signature type> 815 * <[2] 16-bit length of chunk signature> 816 * <[...] chunk signature> 817 * 818 * This is a direct push variant for network config updates. It otherwise 819 * carries the same payload as OK(NETWORK_CONFIG_REQUEST) and has the same 820 * semantics. 821 * 822 * The legacy mode missing the additional chunking fields is not supported 823 * here. 824 * 825 * Flags: 826 * 0x01 - Use fast propagation 827 * 828 * An OK should be sent if the config is successfully received and 829 * accepted. 830 * 831 * OK payload: 832 * <[8] 64-bit network ID> 833 * <[8] 64-bit config update ID> 834 */ 835 VERB_NETWORK_CONFIG = 0x0c, 836 837 /** 838 * Request endpoints for multicast distribution: 839 * <[8] 64-bit network ID> 840 * <[1] flags> 841 * <[6] MAC address of multicast group being queried> 842 * <[4] 32-bit ADI for multicast group being queried> 843 * <[4] 32-bit requested max number of multicast peers> 844 * [<[...] network certificate of membership>] 845 * 846 * Flags: 847 * 0x01 - COM is attached 848 * 849 * This message asks a peer for additional known endpoints that have 850 * LIKEd a given multicast group. It's sent when the sender wishes 851 * to send multicast but does not have the desired number of recipient 852 * peers. 853 * 854 * More than one OK response can occur if the response is broken up across 855 * multiple packets or if querying a clustered node. 856 * 857 * The COM should be included so that upstream nodes that are not 858 * members of our network can validate our request. 859 * 860 * OK response payload: 861 * <[8] 64-bit network ID> 862 * <[6] MAC address of multicast group being queried> 863 * <[4] 32-bit ADI for multicast group being queried> 864 * [begin gather results -- these same fields can be in OK(MULTICAST_FRAME)] 865 * <[4] 32-bit total number of known members in this multicast group> 866 * <[2] 16-bit number of members enumerated in this packet> 867 * <[...] series of 5-byte ZeroTier addresses of enumerated members> 868 * 869 * ERROR is not generated; queries that return no response are dropped. 870 */ 871 VERB_MULTICAST_GATHER = 0x0d, 872 873 /** 874 * Multicast frame: 875 * <[8] 64-bit network ID> 876 * <[1] flags> 877 * [<[4] 32-bit implicit gather limit>] 878 * [<[6] source MAC>] 879 * <[6] destination MAC (multicast address)> 880 * <[4] 32-bit multicast ADI (multicast address extension)> 881 * <[2] 16-bit ethertype> 882 * <[...] ethernet payload> 883 * 884 * Flags: 885 * 0x01 - Network certificate of membership attached (DEPRECATED) 886 * 0x02 - Implicit gather limit field is present 887 * 0x04 - Source MAC is specified -- otherwise it's computed from sender 888 * 0x08 - Please replicate (sent to multicast replicators) 889 * 890 * OK and ERROR responses are optional. OK may be generated if there are 891 * implicit gather results or if the recipient wants to send its own 892 * updated certificate of network membership to the sender. ERROR may be 893 * generated if a certificate is needed or if multicasts to this group 894 * are no longer wanted (multicast unsubscribe). 895 * 896 * OK response payload: 897 * <[8] 64-bit network ID> 898 * <[6] MAC address of multicast group> 899 * <[4] 32-bit ADI for multicast group> 900 * <[1] flags> 901 * [<[...] network certificate of membership (DEPRECATED)>] 902 * [<[...] implicit gather results if flag 0x01 is set>] 903 * 904 * OK flags (same bits as request flags): 905 * 0x01 - OK includes certificate of network membership (DEPRECATED) 906 * 0x02 - OK includes implicit gather results 907 * 908 * ERROR response payload: 909 * <[8] 64-bit network ID> 910 * <[6] multicast group MAC> 911 * <[4] 32-bit multicast group ADI> 912 */ 913 VERB_MULTICAST_FRAME = 0x0e, 914 915 /** 916 * Push of potential endpoints for direct communication: 917 * <[2] 16-bit number of paths> 918 * <[...] paths> 919 * 920 * Path record format: 921 * <[1] 8-bit path flags> 922 * <[2] length of extended path characteristics or 0 for none> 923 * <[...] extended path characteristics> 924 * <[1] address type> 925 * <[1] address length in bytes> 926 * <[...] address> 927 * 928 * Path record flags: 929 * 0x01 - Forget this path if currently known (not implemented yet) 930 * 0x02 - Cluster redirect -- use this in preference to others 931 * 932 * The receiver may, upon receiving a push, attempt to establish a 933 * direct link to one or more of the indicated addresses. It is the 934 * responsibility of the sender to limit which peers it pushes direct 935 * paths to to those with whom it has a trust relationship. The receiver 936 * must obey any restrictions provided such as exclusivity or blacklists. 937 * OK responses to this message are optional. 938 * 939 * Note that a direct path push does not imply that learned paths can't 940 * be used unless they are blacklisted explicitly or unless flag 0x01 941 * is set. 942 * 943 * OK and ERROR are not generated. 944 */ 945 VERB_PUSH_DIRECT_PATHS = 0x10, 946 947 // 0x11 -- deprecated 948 949 /** 950 * An acknowledgment of receipt of a series of recent packets from another 951 * peer. This is used to calculate relative throughput values and to detect 952 * packet loss. Only VERB_FRAME and VERB_EXT_FRAME packets are counted. 953 * 954 * ACK response format: 955 * <[4] 32-bit number of bytes received since last ACK> 956 * 957 * Upon receipt of this packet, the local peer will verify that the correct 958 * number of bytes were received by the remote peer. If these values do 959 * not agree that could be an indication of packet loss. 960 * 961 * Additionally, the local peer knows the interval of time that has 962 * elapsed since the last received ACK. With this information it can compute 963 * a rough estimate of the current throughput. 964 * 965 * This is sent at a maximum rate of once per every ZT_QOS_ACK_INTERVAL 966 */ 967 VERB_ACK = 0x12, 968 969 /** 970 * A packet containing timing measurements useful for estimating path quality. 971 * Composed of a list of <packet ID:internal sojourn time> pairs for an 972 * arbitrary set of recent packets. This is used to sample for latency and 973 * packet delay variance (PDV, "jitter"). 974 * 975 * QoS record format: 976 * 977 * <[8] 64-bit packet ID of previously-received packet> 978 * <[1] 8-bit packet sojourn time> 979 * <...repeat until end of max 1400 byte packet...> 980 * 981 * The number of possible records per QoS packet is: (1400 * 8) / 72 = 155 982 * This packet should be sent very rarely (every few seconds) as it can be 983 * somewhat large if the connection is saturated. Future versions might use 984 * a bloom table to probabilistically determine these values in a vastly 985 * more space-efficient manner. 986 * 987 * Note: The 'internal packet sojourn time' is a slight misnomer as it is a 988 * measure of the amount of time between when a packet was received and the 989 * egress time of its tracking QoS packet. 990 * 991 * This is sent at a maximum rate of once per every 992 * ZT_QOS_MEASUREMENT_INTERVAL 993 */ 994 VERB_QOS_MEASUREMENT = 0x13, 995 996 /** 997 * A message with arbitrary user-definable content: 998 * <[8] 64-bit arbitrary message type ID> 999 * [<[...] message payload>] 1000 * 1001 * This can be used to send arbitrary messages over VL1. It generates no 1002 * OK or ERROR and has no special semantics outside of whatever the user 1003 * (via the ZeroTier core API) chooses to give it. 1004 * 1005 * Message type IDs less than or equal to 65535 are reserved for use by 1006 * ZeroTier, Inc. itself. We recommend making up random ones for your own 1007 * implementations. 1008 */ 1009 VERB_USER_MESSAGE = 0x14, 1010 1011 /** 1012 * A trace for remote debugging or diagnostics: 1013 * <[...] null-terminated dictionary containing trace information> 1014 * [<[...] additional null-terminated dictionaries>] 1015 * 1016 * This message contains a remote trace event. Remote trace events can 1017 * be sent to observers configured at the network level for those that 1018 * pertain directly to activity on a network, or to global observers if 1019 * locally configured. 1020 * 1021 * The instance ID is a random 64-bit value generated by each ZeroTier 1022 * node on startup. This is helpful in identifying traces from different 1023 * members of a cluster. 1024 */ 1025 VERB_REMOTE_TRACE = 0x15, 1026 1027 /** 1028 * A request to a peer to use a specific path in a multi-path scenario: 1029 * <[2] 16-bit unsigned integer that encodes a path choice utility> 1030 * 1031 * This is sent when a node operating in multipath mode observes that 1032 * its inbound and outbound traffic aren't going over the same path. The 1033 * node will compute its perceived utility for using its chosen outbound 1034 * path and send this to a peer in an attempt to petition it to send 1035 * its traffic over this same path. 1036 * 1037 * Scenarios: 1038 * 1039 * (1) Remote peer utility is GREATER than ours: 1040 * - Remote peer will refuse the petition and continue using current path 1041 * (2) Remote peer utility is LESS than than ours: 1042 * - Remote peer will accept the petition and switch to our chosen path 1043 * (3) Remote peer utility is EQUAL to our own: 1044 * - To prevent confusion and flapping, both side will agree to use the 1045 * numerical values of their identities to determine which path to use. 1046 * The peer with the greatest identity will win. 1047 * 1048 * If a node petitions a peer repeatedly with no effect it will regard 1049 * that as a refusal by the remote peer, in this case if the utility is 1050 * negligible it will voluntarily switch to the remote peer's chosen path. 1051 */ 1052 VERB_PATH_NEGOTIATION_REQUEST = 0x16 1053 }; 1054 1055 /** 1056 * Error codes for VERB_ERROR 1057 */ 1058 enum ErrorCode 1059 { 1060 /* No error, not actually used in transit */ 1061 ERROR_NONE = 0x00, 1062 1063 /* Invalid request */ 1064 ERROR_INVALID_REQUEST = 0x01, 1065 1066 /* Bad/unsupported protocol version */ 1067 ERROR_BAD_PROTOCOL_VERSION = 0x02, 1068 1069 /* Unknown object queried */ 1070 ERROR_OBJ_NOT_FOUND = 0x03, 1071 1072 /* HELLO pushed an identity whose address is already claimed */ 1073 ERROR_IDENTITY_COLLISION = 0x04, 1074 1075 /* Verb or use case not supported/enabled by this node */ 1076 ERROR_UNSUPPORTED_OPERATION = 0x05, 1077 1078 /* Network membership certificate update needed */ 1079 ERROR_NEED_MEMBERSHIP_CERTIFICATE = 0x06, 1080 1081 /* Tried to join network, but you're not a member */ 1082 ERROR_NETWORK_ACCESS_DENIED_ = 0x07, /* extra _ at end to avoid Windows name conflict */ 1083 1084 /* Multicasts to this group are not wanted */ 1085 ERROR_UNWANTED_MULTICAST = 0x08, 1086 1087 /* Network requires external or 2FA authentication (e.g. SSO). */ 1088 ERROR_NETWORK_AUTHENTICATION_REQUIRED = 0x09 1089 }; 1090 1091 template<unsigned int C2> Packet(const Buffer<C2> & b)1092 Packet(const Buffer<C2> &b) : 1093 Buffer<ZT_PROTO_MAX_PACKET_LENGTH>(b) 1094 { 1095 } 1096 Packet(const void * data,unsigned int len)1097 Packet(const void *data,unsigned int len) : 1098 Buffer<ZT_PROTO_MAX_PACKET_LENGTH>(data,len) 1099 { 1100 } 1101 1102 /** 1103 * Construct a new empty packet with a unique random packet ID 1104 * 1105 * Flags and hops will be zero. Other fields and data region are undefined. 1106 * Use the header access methods (setDestination() and friends) to fill out 1107 * the header. Payload should be appended; initial size is header size. 1108 */ Packet()1109 Packet() : 1110 Buffer<ZT_PROTO_MAX_PACKET_LENGTH>(ZT_PROTO_MIN_PACKET_LENGTH) 1111 { 1112 Utils::getSecureRandom(field(ZT_PACKET_IDX_IV,8),8); 1113 (*this)[ZT_PACKET_IDX_FLAGS] = 0; // zero flags, cipher ID, and hops 1114 } 1115 1116 /** 1117 * Make a copy of a packet with a new initialization vector and destination address 1118 * 1119 * This can be used to take one draft prototype packet and quickly make copies to 1120 * encrypt for different destinations. 1121 * 1122 * @param prototype Prototype packet 1123 * @param dest Destination ZeroTier address for new packet 1124 */ Packet(const Packet & prototype,const Address & dest)1125 Packet(const Packet &prototype,const Address &dest) : 1126 Buffer<ZT_PROTO_MAX_PACKET_LENGTH>(prototype) 1127 { 1128 Utils::getSecureRandom(field(ZT_PACKET_IDX_IV,8),8); 1129 setDestination(dest); 1130 } 1131 1132 /** 1133 * Construct a new empty packet with a unique random packet ID 1134 * 1135 * @param dest Destination ZT address 1136 * @param source Source ZT address 1137 * @param v Verb 1138 */ Packet(const Address & dest,const Address & source,const Verb v)1139 Packet(const Address &dest,const Address &source,const Verb v) : 1140 Buffer<ZT_PROTO_MAX_PACKET_LENGTH>(ZT_PROTO_MIN_PACKET_LENGTH) 1141 { 1142 Utils::getSecureRandom(field(ZT_PACKET_IDX_IV,8),8); 1143 setDestination(dest); 1144 setSource(source); 1145 (*this)[ZT_PACKET_IDX_FLAGS] = 0; // zero flags and hops 1146 setVerb(v); 1147 } 1148 1149 /** 1150 * Reset this packet structure for reuse in place 1151 * 1152 * @param dest Destination ZT address 1153 * @param source Source ZT address 1154 * @param v Verb 1155 */ reset(const Address & dest,const Address & source,const Verb v)1156 inline void reset(const Address &dest,const Address &source,const Verb v) 1157 { 1158 setSize(ZT_PROTO_MIN_PACKET_LENGTH); 1159 Utils::getSecureRandom(field(ZT_PACKET_IDX_IV,8),8); 1160 setDestination(dest); 1161 setSource(source); 1162 (*this)[ZT_PACKET_IDX_FLAGS] = 0; // zero flags, cipher ID, and hops 1163 setVerb(v); 1164 } 1165 1166 /** 1167 * Generate a new IV / packet ID in place 1168 * 1169 * This can be used to re-use a packet buffer multiple times to send 1170 * technically different but otherwise identical copies of the same 1171 * packet. 1172 */ newInitializationVector()1173 inline void newInitializationVector() { Utils::getSecureRandom(field(ZT_PACKET_IDX_IV,8),8); } 1174 1175 /** 1176 * Set this packet's destination 1177 * 1178 * @param dest ZeroTier address of destination 1179 */ setDestination(const Address & dest)1180 inline void setDestination(const Address &dest) { dest.copyTo(field(ZT_PACKET_IDX_DEST,ZT_ADDRESS_LENGTH),ZT_ADDRESS_LENGTH); } 1181 1182 /** 1183 * Set this packet's source 1184 * 1185 * @param source ZeroTier address of source 1186 */ setSource(const Address & source)1187 inline void setSource(const Address &source) { source.copyTo(field(ZT_PACKET_IDX_SOURCE,ZT_ADDRESS_LENGTH),ZT_ADDRESS_LENGTH); } 1188 1189 /** 1190 * Get this packet's destination 1191 * 1192 * @return Destination ZT address 1193 */ destination() const1194 inline Address destination() const { return Address(field(ZT_PACKET_IDX_DEST,ZT_ADDRESS_LENGTH),ZT_ADDRESS_LENGTH); } 1195 1196 /** 1197 * Get this packet's source 1198 * 1199 * @return Source ZT address 1200 */ source() const1201 inline Address source() const { return Address(field(ZT_PACKET_IDX_SOURCE,ZT_ADDRESS_LENGTH),ZT_ADDRESS_LENGTH); } 1202 1203 /** 1204 * @return True if packet is of valid length 1205 */ lengthValid() const1206 inline bool lengthValid() const { return (size() >= ZT_PROTO_MIN_PACKET_LENGTH); } 1207 1208 /** 1209 * @return True if packet is fragmented (expect fragments) 1210 */ fragmented() const1211 inline bool fragmented() const { return (((unsigned char)(*this)[ZT_PACKET_IDX_FLAGS] & ZT_PROTO_FLAG_FRAGMENTED) != 0); } 1212 1213 /** 1214 * Set this packet's fragmented flag 1215 * 1216 * @param f Fragmented flag value 1217 */ setFragmented(bool f)1218 inline void setFragmented(bool f) 1219 { 1220 if (f) 1221 (*this)[ZT_PACKET_IDX_FLAGS] |= (char)ZT_PROTO_FLAG_FRAGMENTED; 1222 else (*this)[ZT_PACKET_IDX_FLAGS] &= (char)(~ZT_PROTO_FLAG_FRAGMENTED); 1223 } 1224 1225 /** 1226 * @return True if compressed (result only valid if unencrypted) 1227 */ compressed() const1228 inline bool compressed() const { return (((unsigned char)(*this)[ZT_PACKET_IDX_VERB] & ZT_PROTO_VERB_FLAG_COMPRESSED) != 0); } 1229 1230 /** 1231 * @return ZeroTier forwarding hops (0 to 7) 1232 */ hops() const1233 inline unsigned int hops() const { return ((unsigned int)(*this)[ZT_PACKET_IDX_FLAGS] & 0x07); } 1234 1235 /** 1236 * Increment this packet's hop count 1237 */ incrementHops()1238 inline void incrementHops() 1239 { 1240 unsigned char &b = (*this)[ZT_PACKET_IDX_FLAGS]; 1241 b = (b & 0xf8) | ((b + 1) & 0x07); 1242 } 1243 1244 /** 1245 * @return Cipher suite selector: 0 - 7 (see #defines) 1246 */ cipher() const1247 inline unsigned int cipher() const 1248 { 1249 return (((unsigned int)(*this)[ZT_PACKET_IDX_FLAGS] & 0x38) >> 3); 1250 } 1251 1252 /** 1253 * Set this packet's cipher suite 1254 */ setCipher(unsigned int c)1255 inline void setCipher(unsigned int c) 1256 { 1257 unsigned char &b = (*this)[ZT_PACKET_IDX_FLAGS]; 1258 b = (b & 0xc7) | (unsigned char)((c << 3) & 0x38); // bits: FFCCCHHH 1259 // Set DEPRECATED "encrypted" flag -- used by pre-1.0.3 peers 1260 if (c == ZT_PROTO_CIPHER_SUITE__C25519_POLY1305_SALSA2012) 1261 b |= ZT_PROTO_FLAG_ENCRYPTED; 1262 else b &= (~ZT_PROTO_FLAG_ENCRYPTED); 1263 } 1264 1265 /** 1266 * Get the trusted path ID for this packet (only meaningful if cipher is trusted path) 1267 * 1268 * @return Trusted path ID (from MAC field) 1269 */ trustedPathId() const1270 inline uint64_t trustedPathId() const { return at<uint64_t>(ZT_PACKET_IDX_MAC); } 1271 1272 /** 1273 * Set this packet's trusted path ID and set the cipher spec to trusted path 1274 * 1275 * @param tpid Trusted path ID 1276 */ setTrusted(const uint64_t tpid)1277 inline void setTrusted(const uint64_t tpid) 1278 { 1279 setCipher(ZT_PROTO_CIPHER_SUITE__NO_CRYPTO_TRUSTED_PATH); 1280 setAt(ZT_PACKET_IDX_MAC,tpid); 1281 } 1282 1283 /** 1284 * Get this packet's unique ID (the IV field interpreted as uint64_t) 1285 * 1286 * Note that the least significant 3 bits of this ID will change when armor() 1287 * is called to armor the packet for transport. This is because armor() will 1288 * mask the last 3 bits against the send counter for QoS monitoring use prior 1289 * to actually using the IV to encrypt and MAC the packet. Be aware of this 1290 * when grabbing the packetId of a new packet prior to armor/send. 1291 * 1292 * @return Packet ID 1293 */ packetId() const1294 inline uint64_t packetId() const { return at<uint64_t>(ZT_PACKET_IDX_IV); } 1295 1296 /** 1297 * Set packet verb 1298 * 1299 * This also has the side-effect of clearing any verb flags, such as 1300 * compressed, and so must only be done during packet composition. 1301 * 1302 * @param v New packet verb 1303 */ setVerb(Verb v)1304 inline void setVerb(Verb v) { (*this)[ZT_PACKET_IDX_VERB] = (char)v; } 1305 1306 /** 1307 * @return Packet verb (not including flag bits) 1308 */ verb() const1309 inline Verb verb() const { return (Verb)((*this)[ZT_PACKET_IDX_VERB] & 0x1f); } 1310 1311 /** 1312 * @return Length of packet payload 1313 */ payloadLength() const1314 inline unsigned int payloadLength() const { return ((size() < ZT_PROTO_MIN_PACKET_LENGTH) ? 0 : (size() - ZT_PROTO_MIN_PACKET_LENGTH)); } 1315 1316 /** 1317 * @return Raw packet payload 1318 */ payload() const1319 inline const unsigned char *payload() const { return field(ZT_PACKET_IDX_PAYLOAD,size() - ZT_PACKET_IDX_PAYLOAD); } 1320 1321 /** 1322 * Armor packet for transport 1323 * 1324 * @param key 32-byte key 1325 * @param encryptPayload If true, encrypt packet payload, else just MAC 1326 * @param aesKeys If non-NULL these are the two keys for AES-GMAC-SIV 1327 */ 1328 void armor(const void *key,bool encryptPayload,const AES aesKeys[2]); 1329 1330 /** 1331 * Verify and (if encrypted) decrypt packet 1332 * 1333 * This does not handle trusted path mode packets and will return false 1334 * for these. These are handled in IncomingPacket if the sending physical 1335 * address and MAC field match a trusted path. 1336 * 1337 * @param key 32-byte key 1338 * @param aesKeys If non-NULL these are the two keys for AES-GMAC-SIV 1339 * @return False if packet is invalid or failed MAC authenticity check 1340 */ 1341 bool dearmor(const void *key,const AES aesKeys[2]); 1342 1343 /** 1344 * Encrypt/decrypt a separately armored portion of a packet 1345 * 1346 * This is currently only used to mask portions of HELLO as an extra 1347 * security precaution since most of that message is sent in the clear. 1348 * 1349 * This must NEVER be used more than once in the same packet, as doing 1350 * so will result in re-use of the same key stream. 1351 * 1352 * @param key 32-byte key 1353 * @param start Start of encrypted portion 1354 * @param len Length of encrypted portion 1355 */ 1356 void cryptField(const void *key,unsigned int start,unsigned int len); 1357 1358 /** 1359 * Attempt to compress payload if not already (must be unencrypted) 1360 * 1361 * This requires that the payload at least contain the verb byte already 1362 * set. The compressed flag in the verb is set if compression successfully 1363 * results in a size reduction. If no size reduction occurs, compression 1364 * is not done and the flag is left cleared. 1365 * 1366 * @return True if compression occurred 1367 */ 1368 bool compress(); 1369 1370 /** 1371 * Attempt to decompress payload if it is compressed (must be unencrypted) 1372 * 1373 * If payload is compressed, it is decompressed and the compressed verb 1374 * flag is cleared. Otherwise nothing is done and true is returned. 1375 * 1376 * @return True if data is now decompressed and valid, false on error 1377 */ 1378 bool uncompress(); 1379 1380 private: 1381 static const unsigned char ZERO_KEY[32]; 1382 1383 /** 1384 * Deterministically mangle a 256-bit crypto key based on packet 1385 * 1386 * This uses extra data from the packet to mangle the secret, giving us an 1387 * effective IV that is somewhat more than 64 bits. This is "free" for 1388 * Salsa20 since it has negligible key setup time so using a different 1389 * key each time is fine. 1390 * 1391 * @param in Input key (32 bytes) 1392 * @param out Output buffer (32 bytes) 1393 */ _salsa20MangleKey(const unsigned char * in,unsigned char * out) const1394 inline void _salsa20MangleKey(const unsigned char *in,unsigned char *out) const 1395 { 1396 const unsigned char *d = (const unsigned char *)data(); 1397 1398 // IV and source/destination addresses. Using the addresses divides the 1399 // key space into two halves-- A->B and B->A (since order will change). 1400 for(unsigned int i=0;i<18;++i) // 8 + (ZT_ADDRESS_LENGTH * 2) == 18 1401 out[i] = in[i] ^ d[i]; 1402 1403 // Flags, but with hop count masked off. Hop count is altered by forwarding 1404 // nodes. It's one of the only parts of a packet modifiable by people 1405 // without the key. 1406 out[18] = in[18] ^ (d[ZT_PACKET_IDX_FLAGS] & 0xf8); 1407 1408 // Raw packet size in bytes -- thus each packet size defines a new 1409 // key space. 1410 out[19] = in[19] ^ (unsigned char)(size() & 0xff); 1411 out[20] = in[20] ^ (unsigned char)((size() >> 8) & 0xff); // little endian 1412 1413 // Rest of raw key is used unchanged 1414 for(unsigned int i=21;i<32;++i) 1415 out[i] = in[i]; 1416 } 1417 }; 1418 1419 } // namespace ZeroTier 1420 1421 #endif 1422