ZeroTierOne.h 52 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885
  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. /*
  19. * This defines the external C API for ZeroTier's core network virtualization
  20. * engine.
  21. */
  22. #ifndef ZT_ZEROTIERONE_H
  23. #define ZT_ZEROTIERONE_H
  24. #include <stdint.h>
  25. // For the struct sockaddr_storage structure
  26. #if defined(_WIN32) || defined(_WIN64)
  27. #include <WinSock2.h>
  28. #include <WS2tcpip.h>
  29. #include <Windows.h>
  30. #else /* not Windows */
  31. #include <arpa/inet.h>
  32. #include <netinet/in.h>
  33. #include <sys/types.h>
  34. #include <sys/socket.h>
  35. #endif /* Windows or not */
  36. #ifdef __cplusplus
  37. extern "C" {
  38. #endif
  39. /****************************************************************************/
  40. /* Core constants */
  41. /****************************************************************************/
  42. /**
  43. * Default UDP port for devices running a ZeroTier endpoint
  44. */
  45. #define ZT_DEFAULT_PORT 9993
  46. /**
  47. * Maximum MTU for ZeroTier virtual networks
  48. *
  49. * This is pretty much an unchangeable global constant. To make it change
  50. * across nodes would require logic to send ICMP packet too big messages,
  51. * which would complicate things. 1500 has been good enough on most LANs
  52. * for ages, so a larger MTU should be fine for the forseeable future. This
  53. * typically results in two UDP packets per single large frame. Experimental
  54. * results seem to show that this is good. Larger MTUs resulting in more
  55. * fragments seemed too brittle on slow/crummy links for no benefit.
  56. *
  57. * If this does change, also change it in tap.h in the tuntaposx code under
  58. * mac-tap.
  59. *
  60. * Overhead for a normal frame split into two packets:
  61. *
  62. * 1414 = 1444 (typical UDP MTU) - 28 (packet header) - 2 (ethertype)
  63. * 1428 = 1444 (typical UDP MTU) - 16 (fragment header)
  64. * SUM: 2842
  65. *
  66. * We use 2800, which leaves some room for other payload in other types of
  67. * messages such as multicast propagation or future support for bridging.
  68. */
  69. #define ZT_MAX_MTU 2800
  70. /**
  71. * Maximum length of network short name
  72. */
  73. #define ZT_MAX_NETWORK_SHORT_NAME_LENGTH 127
  74. /**
  75. * Maximum number of pushed routes on a network
  76. */
  77. #define ZT_MAX_NETWORK_ROUTES 32
  78. /**
  79. * Maximum number of statically assigned IP addresses per network endpoint using ZT address management (not DHCP)
  80. */
  81. #define ZT_MAX_ZT_ASSIGNED_ADDRESSES 16
  82. /**
  83. * Maximum number of "specialists" on a network -- bridges, relays, etc.
  84. */
  85. #define ZT_MAX_NETWORK_SPECIALISTS 256
  86. /**
  87. * Maximum number of static physical to ZeroTier address mappings (typically relays, etc.)
  88. */
  89. #define ZT_MAX_NETWORK_PINNED 16
  90. /**
  91. * Maximum number of rule table entries per network (can be increased)
  92. */
  93. #define ZT_MAX_NETWORK_RULES 256
  94. /**
  95. * Maximum number of multicast group subscriptions per network
  96. */
  97. #define ZT_MAX_NETWORK_MULTICAST_SUBSCRIPTIONS 4096
  98. /**
  99. * Maximum number of direct network paths to a given peer
  100. */
  101. #define ZT_MAX_PEER_NETWORK_PATHS 4
  102. /**
  103. * Maximum number of trusted physical network paths
  104. */
  105. #define ZT_MAX_TRUSTED_PATHS 16
  106. /**
  107. * Maximum number of hops in a ZeroTier circuit test
  108. *
  109. * This is more or less the max that can be fit in a given packet (with
  110. * fragmentation) and only one address per hop.
  111. */
  112. #define ZT_CIRCUIT_TEST_MAX_HOPS 256
  113. /**
  114. * Maximum number of addresses per hop in a circuit test
  115. */
  116. #define ZT_CIRCUIT_TEST_MAX_HOP_BREADTH 8
  117. /**
  118. * Maximum number of cluster members (and max member ID plus one)
  119. */
  120. #define ZT_CLUSTER_MAX_MEMBERS 128
  121. /**
  122. * Maximum number of physical ZeroTier addresses a cluster member can report
  123. */
  124. #define ZT_CLUSTER_MAX_ZT_PHYSICAL_ADDRESSES 16
  125. /**
  126. * Maximum allowed cluster message length in bytes
  127. */
  128. #define ZT_CLUSTER_MAX_MESSAGE_LENGTH (1500 - 48)
  129. /**
  130. * A null/empty sockaddr (all zero) to signify an unspecified socket address
  131. */
  132. extern const struct sockaddr_storage ZT_SOCKADDR_NULL;
  133. /****************************************************************************/
  134. /* Structures and other types */
  135. /****************************************************************************/
  136. /**
  137. * Function return code: OK (0) or error results
  138. *
  139. * Use ZT_ResultCode_isFatal() to check for a fatal error. If a fatal error
  140. * occurs, the node should be considered to not be working correctly. These
  141. * indicate serious problems like an inaccessible data store or a compile
  142. * problem.
  143. */
  144. enum ZT_ResultCode
  145. {
  146. /**
  147. * Operation completed normally
  148. */
  149. ZT_RESULT_OK = 0,
  150. // Fatal errors (>0, <1000)
  151. /**
  152. * Ran out of memory
  153. */
  154. ZT_RESULT_FATAL_ERROR_OUT_OF_MEMORY = 1,
  155. /**
  156. * Data store is not writable or has failed
  157. */
  158. ZT_RESULT_FATAL_ERROR_DATA_STORE_FAILED = 2,
  159. /**
  160. * Internal error (e.g. unexpected exception indicating bug or build problem)
  161. */
  162. ZT_RESULT_FATAL_ERROR_INTERNAL = 3,
  163. // Non-fatal errors (>1000)
  164. /**
  165. * Network ID not valid
  166. */
  167. ZT_RESULT_ERROR_NETWORK_NOT_FOUND = 1000,
  168. /**
  169. * The requested operation is not supported on this version or build
  170. */
  171. ZT_RESULT_ERROR_UNSUPPORTED_OPERATION = 1001,
  172. /**
  173. * The requestion operation was given a bad parameter or was called in an invalid state
  174. */
  175. ZT_RESULT_ERROR_BAD_PARAMETER = 1002
  176. };
  177. /**
  178. * @param x Result code
  179. * @return True if result code indicates a fatal error
  180. */
  181. #define ZT_ResultCode_isFatal(x) ((((int)(x)) > 0)&&(((int)(x)) < 1000))
  182. /**
  183. * Status codes sent to status update callback when things happen
  184. */
  185. enum ZT_Event
  186. {
  187. /**
  188. * Node has been initialized
  189. *
  190. * This is the first event generated, and is always sent. It may occur
  191. * before Node's constructor returns.
  192. *
  193. * Meta-data: none
  194. */
  195. ZT_EVENT_UP = 0,
  196. /**
  197. * Node is offline -- network does not seem to be reachable by any available strategy
  198. *
  199. * Meta-data: none
  200. */
  201. ZT_EVENT_OFFLINE = 1,
  202. /**
  203. * Node is online -- at least one upstream node appears reachable
  204. *
  205. * Meta-data: none
  206. */
  207. ZT_EVENT_ONLINE = 2,
  208. /**
  209. * Node is shutting down
  210. *
  211. * This is generated within Node's destructor when it is being shut down.
  212. * It's done for convenience, since cleaning up other state in the event
  213. * handler may appear more idiomatic.
  214. *
  215. * Meta-data: none
  216. */
  217. ZT_EVENT_DOWN = 3,
  218. /**
  219. * Your identity has collided with another node's ZeroTier address
  220. *
  221. * This happens if two different public keys both hash (via the algorithm
  222. * in Identity::generate()) to the same 40-bit ZeroTier address.
  223. *
  224. * This is something you should "never" see, where "never" is defined as
  225. * once per 2^39 new node initializations / identity creations. If you do
  226. * see it, you're going to see it very soon after a node is first
  227. * initialized.
  228. *
  229. * This is reported as an event rather than a return code since it's
  230. * detected asynchronously via error messages from authoritative nodes.
  231. *
  232. * If this occurs, you must shut down and delete the node, delete the
  233. * identity.secret record/file from the data store, and restart to generate
  234. * a new identity. If you don't do this, you will not be able to communicate
  235. * with other nodes.
  236. *
  237. * We'd automate this process, but we don't think silently deleting
  238. * private keys or changing our address without telling the calling code
  239. * is good form. It violates the principle of least surprise.
  240. *
  241. * You can technically get away with not handling this, but we recommend
  242. * doing so in a mature reliable application. Besides, handling this
  243. * condition is a good way to make sure it never arises. It's like how
  244. * umbrellas prevent rain and smoke detectors prevent fires. They do, right?
  245. *
  246. * Meta-data: none
  247. */
  248. ZT_EVENT_FATAL_ERROR_IDENTITY_COLLISION = 4,
  249. /**
  250. * Trace (debugging) message
  251. *
  252. * These events are only generated if this is a TRACE-enabled build.
  253. *
  254. * Meta-data: C string, TRACE message
  255. */
  256. ZT_EVENT_TRACE = 5
  257. };
  258. /**
  259. * Current node status
  260. */
  261. typedef struct
  262. {
  263. /**
  264. * 40-bit ZeroTier address of this node
  265. */
  266. uint64_t address;
  267. /**
  268. * Current world ID
  269. */
  270. uint64_t worldId;
  271. /**
  272. * Current world revision/timestamp
  273. */
  274. uint64_t worldTimestamp;
  275. /**
  276. * Public identity in string-serialized form (safe to send to others)
  277. *
  278. * This pointer will remain valid as long as the node exists.
  279. */
  280. const char *publicIdentity;
  281. /**
  282. * Full identity including secret key in string-serialized form
  283. *
  284. * This pointer will remain valid as long as the node exists.
  285. */
  286. const char *secretIdentity;
  287. /**
  288. * True if some kind of connectivity appears available
  289. */
  290. int online;
  291. } ZT_NodeStatus;
  292. /**
  293. * Virtual network status codes
  294. */
  295. enum ZT_VirtualNetworkStatus
  296. {
  297. /**
  298. * Waiting for network configuration (also means revision == 0)
  299. */
  300. ZT_NETWORK_STATUS_REQUESTING_CONFIGURATION = 0,
  301. /**
  302. * Configuration received and we are authorized
  303. */
  304. ZT_NETWORK_STATUS_OK = 1,
  305. /**
  306. * Netconf master told us 'nope'
  307. */
  308. ZT_NETWORK_STATUS_ACCESS_DENIED = 2,
  309. /**
  310. * Netconf master exists, but this virtual network does not
  311. */
  312. ZT_NETWORK_STATUS_NOT_FOUND = 3,
  313. /**
  314. * Initialization of network failed or other internal error
  315. */
  316. ZT_NETWORK_STATUS_PORT_ERROR = 4,
  317. /**
  318. * ZeroTier core version too old
  319. */
  320. ZT_NETWORK_STATUS_CLIENT_TOO_OLD = 5
  321. };
  322. /**
  323. * Virtual network type codes
  324. */
  325. enum ZT_VirtualNetworkType
  326. {
  327. /**
  328. * Private networks are authorized via certificates of membership
  329. */
  330. ZT_NETWORK_TYPE_PRIVATE = 0,
  331. /**
  332. * Public networks have no access control -- they'll always be AUTHORIZED
  333. */
  334. ZT_NETWORK_TYPE_PUBLIC = 1
  335. };
  336. /**
  337. * The type of a virtual network rules table entry
  338. *
  339. * These must range from 0 to 127 (0x7f) because the most significant bit
  340. * is reserved as a NOT flag.
  341. *
  342. * Each rule is composed of one or more MATCHes followed by an ACTION.
  343. */
  344. enum ZT_VirtualNetworkRuleType
  345. {
  346. // 0 to 31 reserved for actions
  347. /**
  348. * Drop frame
  349. */
  350. ZT_NETWORK_RULE_ACTION_DROP = 0,
  351. /**
  352. * Accept and pass frame
  353. */
  354. ZT_NETWORK_RULE_ACTION_ACCEPT = 1,
  355. /**
  356. * Forward a copy of this frame to an observer (by ZT address)
  357. */
  358. ZT_NETWORK_RULE_ACTION_TEE = 2,
  359. /**
  360. * Drop and redirect this frame to another node (by ZT address)
  361. */
  362. ZT_NETWORK_RULE_ACTION_REDIRECT = 3,
  363. // 32 to 127 reserved for match criteria
  364. /**
  365. * Source ZeroTier address -- analogous to an Ethernet port ID on a switch
  366. */
  367. ZT_NETWORK_RULE_MATCH_SOURCE_ZEROTIER_ADDRESS = 32,
  368. /**
  369. * Destination ZeroTier address -- analogous to an Ethernet port ID on a switch
  370. */
  371. ZT_NETWORK_RULE_MATCH_DEST_ZEROTIER_ADDRESS = 33,
  372. /**
  373. * Ethernet VLAN ID
  374. */
  375. ZT_NETWORK_RULE_MATCH_VLAN_ID = 34,
  376. /**
  377. * Ethernet VLAN PCP
  378. */
  379. ZT_NETWORK_RULE_MATCH_VLAN_PCP = 35,
  380. /**
  381. * Ethernet VLAN DEI
  382. */
  383. ZT_NETWORK_RULE_MATCH_VLAN_DEI = 36,
  384. /**
  385. * Ethernet frame type
  386. */
  387. ZT_NETWORK_RULE_MATCH_ETHERTYPE = 37,
  388. /**
  389. * Source Ethernet MAC address
  390. */
  391. ZT_NETWORK_RULE_MATCH_MAC_SOURCE = 38,
  392. /**
  393. * Destination Ethernet MAC address
  394. */
  395. ZT_NETWORK_RULE_MATCH_MAC_DEST = 39,
  396. /**
  397. * Source IPv4 address
  398. */
  399. ZT_NETWORK_RULE_MATCH_IPV4_SOURCE = 40,
  400. /**
  401. * Destination IPv4 address
  402. */
  403. ZT_NETWORK_RULE_MATCH_IPV4_DEST = 41,
  404. /**
  405. * Source IPv6 address
  406. */
  407. ZT_NETWORK_RULE_MATCH_IPV6_SOURCE = 42,
  408. /**
  409. * Destination IPv6 address
  410. */
  411. ZT_NETWORK_RULE_MATCH_IPV6_DEST = 43,
  412. /**
  413. * IP TOS (type of service)
  414. */
  415. ZT_NETWORK_RULE_MATCH_IP_TOS = 44,
  416. /**
  417. * IP protocol
  418. */
  419. ZT_NETWORK_RULE_MATCH_IP_PROTOCOL = 45,
  420. /**
  421. * IP source port range (start-end, inclusive)
  422. */
  423. ZT_NETWORK_RULE_MATCH_IP_SOURCE_PORT_RANGE = 46,
  424. /**
  425. * IP destination port range (start-end, inclusive)
  426. */
  427. ZT_NETWORK_RULE_MATCH_IP_DEST_PORT_RANGE = 47,
  428. /**
  429. * Packet characteristics (set of flags)
  430. */
  431. ZT_NETWORK_RULE_MATCH_CHARACTERISTICS = 48,
  432. /**
  433. * Frame size range (start-end, inclusive)
  434. */
  435. ZT_NETWORK_RULE_MATCH_FRAME_SIZE_RANGE = 49
  436. };
  437. /**
  438. * Network flow rule
  439. *
  440. * NOTE: Currently (1.1.x) only etherType is supported! Other things will
  441. * have no effect until the rules engine is fully implemented.
  442. *
  443. * Rules are stored in a table in which one or more match entries is followed
  444. * by an action. If more than one match precedes an action, the rule is
  445. * the AND of all matches. An action with no match is always taken since it
  446. * matches anything. If nothing matches, the default action is DROP.
  447. *
  448. * This is designed to be a more memory-efficient way of storing rules than
  449. * a wide table, yet still fast and simple to access in code.
  450. */
  451. typedef struct
  452. {
  453. /**
  454. * Least significant 7 bits: ZT_VirtualNetworkRuleType, most significant 1 bit is NOT bit
  455. *
  456. * If the NOT bit is set, then matches will be interpreted as "does not
  457. * match." The NOT bit has no effect on actions.
  458. *
  459. * Use "& 0x7f" to get the enum and "& 0x80" to get the NOT flag.
  460. *
  461. * The union 'v' is a variant type, and this selects which field in 'v' is
  462. * actually used and valid.
  463. */
  464. uint8_t t;
  465. /**
  466. * Union containing the value of this rule -- which field is used depends on 't'
  467. */
  468. union {
  469. /**
  470. * IPv6 address in big-endian / network byte order and netmask bits
  471. */
  472. struct {
  473. uint8_t ip[16];
  474. uint8_t mask;
  475. } ipv6;
  476. /**
  477. * IPv4 address in big-endian / network byte order
  478. */
  479. struct {
  480. uint32_t ip;
  481. uint8_t mask;
  482. } ipv4;
  483. /**
  484. * Packet characteristic flags being matched
  485. */
  486. uint64_t characteristics;
  487. /**
  488. * IP port range -- start-end inclusive -- host byte order
  489. */
  490. uint16_t port[2];
  491. /**
  492. * 40-bit ZeroTier address (in least significant bits, host byte order)
  493. */
  494. uint64_t zt;
  495. /**
  496. * 48-bit Ethernet MAC address in big-endian order
  497. */
  498. uint8_t mac[6];
  499. /**
  500. * VLAN ID in host byte order
  501. */
  502. uint16_t vlanId;
  503. /**
  504. * VLAN PCP (least significant 3 bits)
  505. */
  506. uint8_t vlanPcp;
  507. /**
  508. * VLAN DEI (single bit / boolean)
  509. */
  510. uint8_t vlanDei;
  511. /**
  512. * Ethernet type in host byte order
  513. */
  514. uint16_t etherType;
  515. /**
  516. * IP protocol
  517. */
  518. uint8_t ipProtocol;
  519. /**
  520. * IP type of service a.k.a. DSCP field
  521. */
  522. uint8_t ipTos;
  523. /**
  524. * Ethernet packet size in host byte order (start-end, inclusive)
  525. */
  526. uint16_t frameSize[2];
  527. } v;
  528. } ZT_VirtualNetworkRule;
  529. /**
  530. * A route to be pushed on a virtual network
  531. */
  532. typedef struct
  533. {
  534. /**
  535. * Target network / netmask bits (in port field) or NULL or 0.0.0.0/0 for default
  536. */
  537. struct sockaddr_storage target;
  538. /**
  539. * Gateway IP address (port ignored) or NULL (family == 0) for LAN-local (no gateway)
  540. */
  541. struct sockaddr_storage via;
  542. /**
  543. * Route flags
  544. */
  545. uint16_t flags;
  546. /**
  547. * Route metric (not currently used)
  548. */
  549. uint16_t metric;
  550. } ZT_VirtualNetworkRoute;
  551. /**
  552. * An Ethernet multicast group
  553. */
  554. typedef struct
  555. {
  556. /**
  557. * MAC address (least significant 48 bits)
  558. */
  559. uint64_t mac;
  560. /**
  561. * Additional distinguishing information (usually zero)
  562. */
  563. unsigned long adi;
  564. } ZT_MulticastGroup;
  565. /**
  566. * Virtual network configuration update type
  567. */
  568. enum ZT_VirtualNetworkConfigOperation
  569. {
  570. /**
  571. * Network is coming up (either for the first time or after service restart)
  572. */
  573. ZT_VIRTUAL_NETWORK_CONFIG_OPERATION_UP = 1,
  574. /**
  575. * Network configuration has been updated
  576. */
  577. ZT_VIRTUAL_NETWORK_CONFIG_OPERATION_CONFIG_UPDATE = 2,
  578. /**
  579. * Network is going down (not permanently)
  580. */
  581. ZT_VIRTUAL_NETWORK_CONFIG_OPERATION_DOWN = 3,
  582. /**
  583. * Network is going down permanently (leave/delete)
  584. */
  585. ZT_VIRTUAL_NETWORK_CONFIG_OPERATION_DESTROY = 4
  586. };
  587. /**
  588. * What trust hierarchy role does this peer have?
  589. */
  590. enum ZT_PeerRole {
  591. ZT_PEER_ROLE_LEAF = 0, // ordinary node
  592. ZT_PEER_ROLE_RELAY = 1, // relay node
  593. ZT_PEER_ROLE_ROOT = 2 // root server
  594. };
  595. /**
  596. * Vendor ID
  597. */
  598. enum ZT_Vendor {
  599. ZT_VENDOR_UNSPECIFIED = 0,
  600. ZT_VENDOR_ZEROTIER = 1
  601. };
  602. /**
  603. * Platform type
  604. */
  605. enum ZT_Platform {
  606. ZT_PLATFORM_UNSPECIFIED = 0,
  607. ZT_PLATFORM_LINUX = 1,
  608. ZT_PLATFORM_WINDOWS = 2,
  609. ZT_PLATFORM_MACOS = 3,
  610. ZT_PLATFORM_ANDROID = 4,
  611. ZT_PLATFORM_IOS = 5,
  612. ZT_PLATFORM_SOLARIS_SMARTOS = 6,
  613. ZT_PLATFORM_FREEBSD = 7,
  614. ZT_PLATFORM_NETBSD = 8,
  615. ZT_PLATFORM_OPENBSD = 9,
  616. ZT_PLATFORM_RISCOS = 10,
  617. ZT_PLATFORM_VXWORKS = 11,
  618. ZT_PLATFORM_FREERTOS = 12,
  619. ZT_PLATFORM_SYSBIOS = 13,
  620. ZT_PLATFORM_HURD = 14
  621. };
  622. /**
  623. * Architecture type
  624. */
  625. enum ZT_Architecture {
  626. ZT_ARCHITECTURE_UNSPECIFIED = 0,
  627. ZT_ARCHITECTURE_X86 = 1,
  628. ZT_ARCHITECTURE_X64 = 2,
  629. ZT_ARCHITECTURE_ARM32 = 3,
  630. ZT_ARCHITECTURE_ARM64 = 4,
  631. ZT_ARCHITECTURE_MIPS32 = 5,
  632. ZT_ARCHITECTURE_MIPS64 = 6,
  633. ZT_ARCHITECTURE_POWER32 = 7,
  634. ZT_ARCHITECTURE_POWER64 = 8,
  635. ZT_ARCHITECTURE_OPENRISC32 = 9,
  636. ZT_ARCHITECTURE_OPENRISC64 = 10,
  637. ZT_ARCHITECTURE_SPARC32 = 11,
  638. ZT_ARCHITECTURE_SPARC64 = 12,
  639. ZT_ARCHITECTURE_DOTNET_CLR = 13,
  640. ZT_ARCHITECTURE_JAVA_JVM = 14
  641. };
  642. /**
  643. * Virtual network configuration
  644. */
  645. typedef struct
  646. {
  647. /**
  648. * 64-bit ZeroTier network ID
  649. */
  650. uint64_t nwid;
  651. /**
  652. * Ethernet MAC (48 bits) that should be assigned to port
  653. */
  654. uint64_t mac;
  655. /**
  656. * Network name (from network configuration master)
  657. */
  658. char name[ZT_MAX_NETWORK_SHORT_NAME_LENGTH + 1];
  659. /**
  660. * Network configuration request status
  661. */
  662. enum ZT_VirtualNetworkStatus status;
  663. /**
  664. * Network type
  665. */
  666. enum ZT_VirtualNetworkType type;
  667. /**
  668. * Maximum interface MTU
  669. */
  670. unsigned int mtu;
  671. /**
  672. * If nonzero, the network this port belongs to indicates DHCP availability
  673. *
  674. * This is a suggestion. The underlying implementation is free to ignore it
  675. * for security or other reasons. This is simply a netconf parameter that
  676. * means 'DHCP is available on this network.'
  677. */
  678. int dhcp;
  679. /**
  680. * If nonzero, this port is allowed to bridge to other networks
  681. *
  682. * This is informational. If this is false (0), bridged packets will simply
  683. * be dropped and bridging won't work.
  684. */
  685. int bridge;
  686. /**
  687. * If nonzero, this network supports and allows broadcast (ff:ff:ff:ff:ff:ff) traffic
  688. */
  689. int broadcastEnabled;
  690. /**
  691. * If the network is in PORT_ERROR state, this is the (negative) error code most recently reported
  692. */
  693. int portError;
  694. /**
  695. * Revision number as reported by controller or 0 if still waiting for config
  696. */
  697. unsigned long netconfRevision;
  698. /**
  699. * Number of assigned addresses
  700. */
  701. unsigned int assignedAddressCount;
  702. /**
  703. * ZeroTier-assigned addresses (in sockaddr_storage structures)
  704. *
  705. * For IP, the port number of the sockaddr_XX structure contains the number
  706. * of bits in the address netmask. Only the IP address and port are used.
  707. * Other fields like interface number can be ignored.
  708. *
  709. * This is only used for ZeroTier-managed address assignments sent by the
  710. * virtual network's configuration master.
  711. */
  712. struct sockaddr_storage assignedAddresses[ZT_MAX_ZT_ASSIGNED_ADDRESSES];
  713. /**
  714. * Number of ZT-pushed routes
  715. */
  716. unsigned int routeCount;
  717. /**
  718. * Routes (excluding those implied by assigned addresses and their masks)
  719. */
  720. ZT_VirtualNetworkRoute routes[ZT_MAX_NETWORK_ROUTES];
  721. } ZT_VirtualNetworkConfig;
  722. /**
  723. * A list of networks
  724. */
  725. typedef struct
  726. {
  727. ZT_VirtualNetworkConfig *networks;
  728. unsigned long networkCount;
  729. } ZT_VirtualNetworkList;
  730. /**
  731. * Physical network path to a peer
  732. */
  733. typedef struct
  734. {
  735. /**
  736. * Address of endpoint
  737. */
  738. struct sockaddr_storage address;
  739. /**
  740. * Time of last send in milliseconds or 0 for never
  741. */
  742. uint64_t lastSend;
  743. /**
  744. * Time of last receive in milliseconds or 0 for never
  745. */
  746. uint64_t lastReceive;
  747. /**
  748. * Is this a trusted path? If so this will be its nonzero ID.
  749. */
  750. uint64_t trustedPathId;
  751. /**
  752. * Is path active?
  753. */
  754. int active;
  755. /**
  756. * Is path preferred?
  757. */
  758. int preferred;
  759. } ZT_PeerPhysicalPath;
  760. /**
  761. * Peer status result buffer
  762. */
  763. typedef struct
  764. {
  765. /**
  766. * ZeroTier address (40 bits)
  767. */
  768. uint64_t address;
  769. /**
  770. * Time we last received a unicast frame from this peer
  771. */
  772. uint64_t lastUnicastFrame;
  773. /**
  774. * Time we last received a multicast rame from this peer
  775. */
  776. uint64_t lastMulticastFrame;
  777. /**
  778. * Remote major version or -1 if not known
  779. */
  780. int versionMajor;
  781. /**
  782. * Remote minor version or -1 if not known
  783. */
  784. int versionMinor;
  785. /**
  786. * Remote revision or -1 if not known
  787. */
  788. int versionRev;
  789. /**
  790. * Last measured latency in milliseconds or zero if unknown
  791. */
  792. unsigned int latency;
  793. /**
  794. * What trust hierarchy role does this device have?
  795. */
  796. enum ZT_PeerRole role;
  797. /**
  798. * Number of paths (size of paths[])
  799. */
  800. unsigned int pathCount;
  801. /**
  802. * Known network paths to peer
  803. */
  804. ZT_PeerPhysicalPath paths[ZT_MAX_PEER_NETWORK_PATHS];
  805. } ZT_Peer;
  806. /**
  807. * List of peers
  808. */
  809. typedef struct
  810. {
  811. ZT_Peer *peers;
  812. unsigned long peerCount;
  813. } ZT_PeerList;
  814. /**
  815. * ZeroTier circuit test configuration and path
  816. */
  817. typedef struct {
  818. /**
  819. * Test ID -- an arbitrary 64-bit identifier
  820. */
  821. uint64_t testId;
  822. /**
  823. * Timestamp -- sent with test and echoed back by each reporter
  824. */
  825. uint64_t timestamp;
  826. /**
  827. * Originator credential: network ID
  828. *
  829. * If this is nonzero, a network ID will be set for this test and
  830. * the originator must be its primary network controller. This is
  831. * currently the only authorization method available, so it must
  832. * be set to run a test.
  833. */
  834. uint64_t credentialNetworkId;
  835. /**
  836. * Hops in circuit test (a.k.a. FIFO for graph traversal)
  837. */
  838. struct {
  839. /**
  840. * Hop flags (currently unused, must be zero)
  841. */
  842. unsigned int flags;
  843. /**
  844. * Number of addresses in this hop (max: ZT_CIRCUIT_TEST_MAX_HOP_BREADTH)
  845. */
  846. unsigned int breadth;
  847. /**
  848. * 40-bit ZeroTier addresses (most significant 24 bits ignored)
  849. */
  850. uint64_t addresses[ZT_CIRCUIT_TEST_MAX_HOP_BREADTH];
  851. } hops[ZT_CIRCUIT_TEST_MAX_HOPS];
  852. /**
  853. * Number of hops (max: ZT_CIRCUIT_TEST_MAX_HOPS)
  854. */
  855. unsigned int hopCount;
  856. /**
  857. * If non-zero, circuit test will report back at every hop
  858. */
  859. int reportAtEveryHop;
  860. /**
  861. * An arbitrary user-settable pointer
  862. */
  863. void *ptr;
  864. /**
  865. * Pointer for internal use -- initialize to zero and do not modify
  866. */
  867. void *_internalPtr;
  868. } ZT_CircuitTest;
  869. /**
  870. * Circuit test result report
  871. */
  872. typedef struct {
  873. /**
  874. * Sender of report (current hop)
  875. */
  876. uint64_t current;
  877. /**
  878. * Previous hop
  879. */
  880. uint64_t upstream;
  881. /**
  882. * 64-bit test ID
  883. */
  884. uint64_t testId;
  885. /**
  886. * Timestamp from original test (echoed back at each hop)
  887. */
  888. uint64_t timestamp;
  889. /**
  890. * Timestamp on remote device
  891. */
  892. uint64_t remoteTimestamp;
  893. /**
  894. * 64-bit packet ID of packet received by the reporting device
  895. */
  896. uint64_t sourcePacketId;
  897. /**
  898. * Flags (currently unused, will be zero)
  899. */
  900. uint64_t flags;
  901. /**
  902. * ZeroTier protocol-level hop count of packet received by reporting device (>0 indicates relayed)
  903. */
  904. unsigned int sourcePacketHopCount;
  905. /**
  906. * Error code (currently unused, will be zero)
  907. */
  908. unsigned int errorCode;
  909. /**
  910. * Remote device vendor ID
  911. */
  912. enum ZT_Vendor vendor;
  913. /**
  914. * Remote device protocol compliance version
  915. */
  916. unsigned int protocolVersion;
  917. /**
  918. * Software major version
  919. */
  920. unsigned int majorVersion;
  921. /**
  922. * Software minor version
  923. */
  924. unsigned int minorVersion;
  925. /**
  926. * Software revision
  927. */
  928. unsigned int revision;
  929. /**
  930. * Platform / OS
  931. */
  932. enum ZT_Platform platform;
  933. /**
  934. * System architecture
  935. */
  936. enum ZT_Architecture architecture;
  937. /**
  938. * Local device address on which packet was received by reporting device
  939. *
  940. * This may have ss_family equal to zero (null address) if unspecified.
  941. */
  942. struct sockaddr_storage receivedOnLocalAddress;
  943. /**
  944. * Remote address from which reporter received the test packet
  945. *
  946. * This may have ss_family set to zero (null address) if unspecified.
  947. */
  948. struct sockaddr_storage receivedFromRemoteAddress;
  949. /**
  950. * Next hops to which packets are being or will be sent by the reporter
  951. *
  952. * In addition to reporting back, the reporter may send the test on if
  953. * there are more recipients in the FIFO. If it does this, it can report
  954. * back the address(es) that make up the next hop and the physical address
  955. * for each if it has one. The physical address being null/unspecified
  956. * typically indicates that no direct path exists and the next packet
  957. * will be relayed.
  958. */
  959. struct {
  960. /**
  961. * 40-bit ZeroTier address
  962. */
  963. uint64_t address;
  964. /**
  965. * Physical address or null address (ss_family == 0) if unspecified or unknown
  966. */
  967. struct sockaddr_storage physicalAddress;
  968. } nextHops[ZT_CIRCUIT_TEST_MAX_HOP_BREADTH];
  969. /**
  970. * Number of next hops reported in nextHops[]
  971. */
  972. unsigned int nextHopCount;
  973. } ZT_CircuitTestReport;
  974. /**
  975. * A cluster member's status
  976. */
  977. typedef struct {
  978. /**
  979. * This cluster member's ID (from 0 to 1-ZT_CLUSTER_MAX_MEMBERS)
  980. */
  981. unsigned int id;
  982. /**
  983. * Number of milliseconds since last 'alive' heartbeat message received via cluster backplane address
  984. */
  985. unsigned int msSinceLastHeartbeat;
  986. /**
  987. * Non-zero if cluster member is alive
  988. */
  989. int alive;
  990. /**
  991. * X, Y, and Z coordinates of this member (if specified, otherwise zero)
  992. *
  993. * What these mean depends on the location scheme being used for
  994. * location-aware clustering. At present this is GeoIP and these
  995. * will be the X, Y, and Z coordinates of the location on a spherical
  996. * approximation of Earth where Earth's core is the origin (in km).
  997. * They don't have to be perfect and need only be comparable with others
  998. * to find shortest path via the standard vector distance formula.
  999. */
  1000. int x,y,z;
  1001. /**
  1002. * Cluster member's last reported load
  1003. */
  1004. uint64_t load;
  1005. /**
  1006. * Number of peers
  1007. */
  1008. uint64_t peers;
  1009. /**
  1010. * Physical ZeroTier endpoints for this member (where peers are sent when directed here)
  1011. */
  1012. struct sockaddr_storage zeroTierPhysicalEndpoints[ZT_CLUSTER_MAX_ZT_PHYSICAL_ADDRESSES];
  1013. /**
  1014. * Number of physical ZeroTier endpoints this member is announcing
  1015. */
  1016. unsigned int numZeroTierPhysicalEndpoints;
  1017. } ZT_ClusterMemberStatus;
  1018. /**
  1019. * ZeroTier cluster status
  1020. */
  1021. typedef struct {
  1022. /**
  1023. * My cluster member ID (a record for 'self' is included in member[])
  1024. */
  1025. unsigned int myId;
  1026. /**
  1027. * Number of cluster members
  1028. */
  1029. unsigned int clusterSize;
  1030. /**
  1031. * Cluster member statuses
  1032. */
  1033. ZT_ClusterMemberStatus members[ZT_CLUSTER_MAX_MEMBERS];
  1034. } ZT_ClusterStatus;
  1035. /**
  1036. * An instance of a ZeroTier One node (opaque)
  1037. */
  1038. typedef void ZT_Node;
  1039. /****************************************************************************/
  1040. /* Callbacks used by Node API */
  1041. /****************************************************************************/
  1042. /**
  1043. * Callback called to update virtual network port configuration
  1044. *
  1045. * This can be called at any time to update the configuration of a virtual
  1046. * network port. The parameter after the network ID specifies whether this
  1047. * port is being brought up, updated, brought down, or permanently deleted.
  1048. *
  1049. * This in turn should be used by the underlying implementation to create
  1050. * and configure tap devices at the OS (or virtual network stack) layer.
  1051. *
  1052. * The supplied config pointer is not guaranteed to remain valid, so make
  1053. * a copy if you want one.
  1054. *
  1055. * This should not call multicastSubscribe() or other network-modifying
  1056. * methods, as this could cause a deadlock in multithreaded or interrupt
  1057. * driven environments.
  1058. *
  1059. * This must return 0 on success. It can return any OS-dependent error code
  1060. * on failure, and this results in the network being placed into the
  1061. * PORT_ERROR state.
  1062. */
  1063. typedef int (*ZT_VirtualNetworkConfigFunction)(
  1064. ZT_Node *, /* Node */
  1065. void *, /* User ptr */
  1066. uint64_t, /* Network ID */
  1067. void **, /* Modifiable network user PTR */
  1068. enum ZT_VirtualNetworkConfigOperation, /* Config operation */
  1069. const ZT_VirtualNetworkConfig *); /* Network configuration */
  1070. /**
  1071. * Function to send a frame out to a virtual network port
  1072. *
  1073. * Parameters: (1) node, (2) user ptr, (3) network ID, (4) source MAC,
  1074. * (5) destination MAC, (6) ethertype, (7) VLAN ID, (8) frame data,
  1075. * (9) frame length.
  1076. */
  1077. typedef void (*ZT_VirtualNetworkFrameFunction)(
  1078. ZT_Node *, /* Node */
  1079. void *, /* User ptr */
  1080. uint64_t, /* Network ID */
  1081. void **, /* Modifiable network user PTR */
  1082. uint64_t, /* Source MAC */
  1083. uint64_t, /* Destination MAC */
  1084. unsigned int, /* Ethernet type */
  1085. unsigned int, /* VLAN ID (0 for none) */
  1086. const void *, /* Frame data */
  1087. unsigned int); /* Frame length */
  1088. /**
  1089. * Callback for events
  1090. *
  1091. * Events are generated when the node's status changes in a significant way
  1092. * and on certain non-fatal errors and events of interest. The final void
  1093. * parameter points to event meta-data. The type of event meta-data (and
  1094. * whether it is present at all) is event type dependent. See the comments
  1095. * in the definition of ZT_Event.
  1096. */
  1097. typedef void (*ZT_EventCallback)(
  1098. ZT_Node *,
  1099. void *,
  1100. enum ZT_Event,
  1101. const void *);
  1102. /**
  1103. * Function to get an object from the data store
  1104. *
  1105. * Parameters: (1) object name, (2) buffer to fill, (3) size of buffer, (4)
  1106. * index in object to start reading, (5) result parameter that must be set
  1107. * to the actual size of the object if it exists.
  1108. *
  1109. * Object names can contain forward slash (/) path separators. They will
  1110. * never contain .. or backslash (\), so this is safe to map as a Unix-style
  1111. * path if the underlying storage permits. For security reasons we recommend
  1112. * returning errors if .. or \ are used.
  1113. *
  1114. * The function must return the actual number of bytes read. If the object
  1115. * doesn't exist, it should return -1. -2 should be returned on other errors
  1116. * such as errors accessing underlying storage.
  1117. *
  1118. * If the read doesn't fit in the buffer, the max number of bytes should be
  1119. * read. The caller may call the function multiple times to read the whole
  1120. * object.
  1121. */
  1122. typedef long (*ZT_DataStoreGetFunction)(
  1123. ZT_Node *,
  1124. void *,
  1125. const char *,
  1126. void *,
  1127. unsigned long,
  1128. unsigned long,
  1129. unsigned long *);
  1130. /**
  1131. * Function to store an object in the data store
  1132. *
  1133. * Parameters: (1) node, (2) user ptr, (3) object name, (4) object data,
  1134. * (5) object size, (6) secure? (bool).
  1135. *
  1136. * If secure is true, the file should be set readable and writable only
  1137. * to the user running ZeroTier One. What this means is platform-specific.
  1138. *
  1139. * Name semantics are the same as the get function. This must return zero on
  1140. * success. You can return any OS-specific error code on failure, as these
  1141. * may be visible in logs or error messages and might aid in debugging.
  1142. *
  1143. * If the data pointer is null, this must be interpreted as a delete
  1144. * operation.
  1145. */
  1146. typedef int (*ZT_DataStorePutFunction)(
  1147. ZT_Node *,
  1148. void *,
  1149. const char *,
  1150. const void *,
  1151. unsigned long,
  1152. int);
  1153. /**
  1154. * Function to send a ZeroTier packet out over the wire
  1155. *
  1156. * Parameters:
  1157. * (1) Node
  1158. * (2) User pointer
  1159. * (3) Local interface address
  1160. * (4) Remote address
  1161. * (5) Packet data
  1162. * (6) Packet length
  1163. * (7) Desired IP TTL or 0 to use default
  1164. *
  1165. * If there is only one local interface it is safe to ignore the local
  1166. * interface address. Otherwise if running with multiple interfaces, the
  1167. * correct local interface should be chosen by address unless NULL. If
  1168. * the ss_family field is zero (NULL address), a random or preferred
  1169. * default interface should be used.
  1170. *
  1171. * If TTL is nonzero, packets should have their IP TTL value set to this
  1172. * value if possible. If this is not possible it is acceptable to ignore
  1173. * this value and send anyway with normal or default TTL.
  1174. *
  1175. * The function must return zero on success and may return any error code
  1176. * on failure. Note that success does not (of course) guarantee packet
  1177. * delivery. It only means that the packet appears to have been sent.
  1178. */
  1179. typedef int (*ZT_WirePacketSendFunction)(
  1180. ZT_Node *, /* Node */
  1181. void *, /* User ptr */
  1182. const struct sockaddr_storage *, /* Local address */
  1183. const struct sockaddr_storage *, /* Remote address */
  1184. const void *, /* Packet data */
  1185. unsigned int, /* Packet length */
  1186. unsigned int); /* TTL or 0 to use default */
  1187. /**
  1188. * Function to check whether a path should be used for ZeroTier traffic
  1189. *
  1190. * Paramters:
  1191. * (1) Node
  1192. * (2) User pointer
  1193. * (3) Local interface address
  1194. * (4) Remote address
  1195. *
  1196. * This function must return nonzero (true) if the path should be used.
  1197. *
  1198. * If no path check function is specified, ZeroTier will still exclude paths
  1199. * that overlap with ZeroTier-assigned and managed IP address blocks. But the
  1200. * use of a path check function is recommended to ensure that recursion does
  1201. * not occur in cases where addresses are assigned by the OS or managed by
  1202. * an out of band mechanism like DHCP. The path check function should examine
  1203. * all configured ZeroTier interfaces and check to ensure that the supplied
  1204. * addresses will not result in ZeroTier traffic being sent over a ZeroTier
  1205. * interface (recursion).
  1206. *
  1207. * Obviously this is not required in configurations where this can't happen,
  1208. * such as network containers or embedded.
  1209. */
  1210. typedef int (*ZT_PathCheckFunction)(
  1211. ZT_Node *, /* Node */
  1212. void *, /* User ptr */
  1213. const struct sockaddr_storage *, /* Local address */
  1214. const struct sockaddr_storage *); /* Remote address */
  1215. /****************************************************************************/
  1216. /* C Node API */
  1217. /****************************************************************************/
  1218. /**
  1219. * Create a new ZeroTier One node
  1220. *
  1221. * Note that this can take a few seconds the first time it's called, as it
  1222. * will generate an identity.
  1223. *
  1224. * @param node Result: pointer is set to new node instance on success
  1225. * @param uptr User pointer to pass to functions/callbacks
  1226. * @param now Current clock in milliseconds
  1227. * @param dataStoreGetFunction Function called to get objects from persistent storage
  1228. * @param dataStorePutFunction Function called to put objects in persistent storage
  1229. * @param virtualNetworkConfigFunction Function to be called when virtual LANs are created, deleted, or their config parameters change
  1230. * @param pathCheckFunction A function to check whether a path should be used for ZeroTier traffic, or NULL to allow any path
  1231. * @param eventCallback Function to receive status updates and non-fatal error notices
  1232. * @return OK (0) or error code if a fatal error condition has occurred
  1233. */
  1234. enum ZT_ResultCode ZT_Node_new(
  1235. ZT_Node **node,
  1236. void *uptr,
  1237. uint64_t now,
  1238. ZT_DataStoreGetFunction dataStoreGetFunction,
  1239. ZT_DataStorePutFunction dataStorePutFunction,
  1240. ZT_WirePacketSendFunction wirePacketSendFunction,
  1241. ZT_VirtualNetworkFrameFunction virtualNetworkFrameFunction,
  1242. ZT_VirtualNetworkConfigFunction virtualNetworkConfigFunction,
  1243. ZT_PathCheckFunction pathCheckFunction,
  1244. ZT_EventCallback eventCallback);
  1245. /**
  1246. * Delete a node and free all resources it consumes
  1247. *
  1248. * If you are using multiple threads, all other threads must be shut down
  1249. * first. This can crash if processXXX() methods are in progress.
  1250. *
  1251. * @param node Node to delete
  1252. */
  1253. void ZT_Node_delete(ZT_Node *node);
  1254. /**
  1255. * Process a packet received from the physical wire
  1256. *
  1257. * @param node Node instance
  1258. * @param now Current clock in milliseconds
  1259. * @param localAddress Local address, or point to ZT_SOCKADDR_NULL if unspecified
  1260. * @param remoteAddress Origin of packet
  1261. * @param packetData Packet data
  1262. * @param packetLength Packet length
  1263. * @param nextBackgroundTaskDeadline Value/result: set to deadline for next call to processBackgroundTasks()
  1264. * @return OK (0) or error code if a fatal error condition has occurred
  1265. */
  1266. enum ZT_ResultCode ZT_Node_processWirePacket(
  1267. ZT_Node *node,
  1268. uint64_t now,
  1269. const struct sockaddr_storage *localAddress,
  1270. const struct sockaddr_storage *remoteAddress,
  1271. const void *packetData,
  1272. unsigned int packetLength,
  1273. volatile uint64_t *nextBackgroundTaskDeadline);
  1274. /**
  1275. * Process a frame from a virtual network port (tap)
  1276. *
  1277. * @param node Node instance
  1278. * @param now Current clock in milliseconds
  1279. * @param nwid ZeroTier 64-bit virtual network ID
  1280. * @param sourceMac Source MAC address (least significant 48 bits)
  1281. * @param destMac Destination MAC address (least significant 48 bits)
  1282. * @param etherType 16-bit Ethernet frame type
  1283. * @param vlanId 10-bit VLAN ID or 0 if none
  1284. * @param frameData Frame payload data
  1285. * @param frameLength Frame payload length
  1286. * @param nextBackgroundTaskDeadline Value/result: set to deadline for next call to processBackgroundTasks()
  1287. * @return OK (0) or error code if a fatal error condition has occurred
  1288. */
  1289. enum ZT_ResultCode ZT_Node_processVirtualNetworkFrame(
  1290. ZT_Node *node,
  1291. uint64_t now,
  1292. uint64_t nwid,
  1293. uint64_t sourceMac,
  1294. uint64_t destMac,
  1295. unsigned int etherType,
  1296. unsigned int vlanId,
  1297. const void *frameData,
  1298. unsigned int frameLength,
  1299. volatile uint64_t *nextBackgroundTaskDeadline);
  1300. /**
  1301. * Perform periodic background operations
  1302. *
  1303. * @param node Node instance
  1304. * @param now Current clock in milliseconds
  1305. * @param nextBackgroundTaskDeadline Value/result: set to deadline for next call to processBackgroundTasks()
  1306. * @return OK (0) or error code if a fatal error condition has occurred
  1307. */
  1308. enum ZT_ResultCode ZT_Node_processBackgroundTasks(ZT_Node *node,uint64_t now,volatile uint64_t *nextBackgroundTaskDeadline);
  1309. /**
  1310. * Join a network
  1311. *
  1312. * This may generate calls to the port config callback before it returns,
  1313. * or these may be deffered if a netconf is not available yet.
  1314. *
  1315. * If we are already a member of the network, nothing is done and OK is
  1316. * returned.
  1317. *
  1318. * @param node Node instance
  1319. * @param nwid 64-bit ZeroTier network ID
  1320. * @param uptr An arbitrary pointer to associate with this network (default: NULL)
  1321. * @return OK (0) or error code if a fatal error condition has occurred
  1322. */
  1323. enum ZT_ResultCode ZT_Node_join(ZT_Node *node,uint64_t nwid,void *uptr);
  1324. /**
  1325. * Leave a network
  1326. *
  1327. * If a port has been configured for this network this will generate a call
  1328. * to the port config callback with a NULL second parameter to indicate that
  1329. * the port is now deleted.
  1330. *
  1331. * The uptr parameter is optional and is NULL by default. If it is not NULL,
  1332. * the pointer it points to is set to this network's uptr on success.
  1333. *
  1334. * @param node Node instance
  1335. * @param nwid 64-bit network ID
  1336. * @param uptr Target pointer is set to uptr (if not NULL)
  1337. * @return OK (0) or error code if a fatal error condition has occurred
  1338. */
  1339. enum ZT_ResultCode ZT_Node_leave(ZT_Node *node,uint64_t nwid,void **uptr);
  1340. /**
  1341. * Subscribe to an Ethernet multicast group
  1342. *
  1343. * ADI stands for additional distinguishing information. This defaults to zero
  1344. * and is rarely used. Right now its only use is to enable IPv4 ARP to scale,
  1345. * and this must be done.
  1346. *
  1347. * For IPv4 ARP, the implementation must subscribe to 0xffffffffffff (the
  1348. * broadcast address) but with an ADI equal to each IPv4 address in host
  1349. * byte order. This converts ARP from a non-scalable broadcast protocol to
  1350. * a scalable multicast protocol with perfect address specificity.
  1351. *
  1352. * If this is not done, ARP will not work reliably.
  1353. *
  1354. * Multiple calls to subscribe to the same multicast address will have no
  1355. * effect. It is perfectly safe to do this.
  1356. *
  1357. * This does not generate an update call to networkConfigCallback().
  1358. *
  1359. * @param node Node instance
  1360. * @param nwid 64-bit network ID
  1361. * @param multicastGroup Ethernet multicast or broadcast MAC (least significant 48 bits)
  1362. * @param multicastAdi Multicast ADI (least significant 32 bits only, use 0 if not needed)
  1363. * @return OK (0) or error code if a fatal error condition has occurred
  1364. */
  1365. enum ZT_ResultCode ZT_Node_multicastSubscribe(ZT_Node *node,uint64_t nwid,uint64_t multicastGroup,unsigned long multicastAdi);
  1366. /**
  1367. * Unsubscribe from an Ethernet multicast group (or all groups)
  1368. *
  1369. * If multicastGroup is zero (0), this will unsubscribe from all groups. If
  1370. * you are not subscribed to a group this has no effect.
  1371. *
  1372. * This does not generate an update call to networkConfigCallback().
  1373. *
  1374. * @param node Node instance
  1375. * @param nwid 64-bit network ID
  1376. * @param multicastGroup Ethernet multicast or broadcast MAC (least significant 48 bits)
  1377. * @param multicastAdi Multicast ADI (least significant 32 bits only, use 0 if not needed)
  1378. * @return OK (0) or error code if a fatal error condition has occurred
  1379. */
  1380. enum ZT_ResultCode ZT_Node_multicastUnsubscribe(ZT_Node *node,uint64_t nwid,uint64_t multicastGroup,unsigned long multicastAdi);
  1381. /**
  1382. * Get this node's 40-bit ZeroTier address
  1383. *
  1384. * @param node Node instance
  1385. * @return ZeroTier address (least significant 40 bits of 64-bit int)
  1386. */
  1387. uint64_t ZT_Node_address(ZT_Node *node);
  1388. /**
  1389. * Get the status of this node
  1390. *
  1391. * @param node Node instance
  1392. * @param status Buffer to fill with current node status
  1393. */
  1394. void ZT_Node_status(ZT_Node *node,ZT_NodeStatus *status);
  1395. /**
  1396. * Get a list of known peer nodes
  1397. *
  1398. * The pointer returned here must be freed with freeQueryResult()
  1399. * when you are done with it.
  1400. *
  1401. * @param node Node instance
  1402. * @return List of known peers or NULL on failure
  1403. */
  1404. ZT_PeerList *ZT_Node_peers(ZT_Node *node);
  1405. /**
  1406. * Get the status of a virtual network
  1407. *
  1408. * The pointer returned here must be freed with freeQueryResult()
  1409. * when you are done with it.
  1410. *
  1411. * @param node Node instance
  1412. * @param nwid 64-bit network ID
  1413. * @return Network configuration or NULL if we are not a member of this network
  1414. */
  1415. ZT_VirtualNetworkConfig *ZT_Node_networkConfig(ZT_Node *node,uint64_t nwid);
  1416. /**
  1417. * Enumerate and get status of all networks
  1418. *
  1419. * @param node Node instance
  1420. * @return List of networks or NULL on failure
  1421. */
  1422. ZT_VirtualNetworkList *ZT_Node_networks(ZT_Node *node);
  1423. /**
  1424. * Free a query result buffer
  1425. *
  1426. * Use this to free the return values of listNetworks(), listPeers(), etc.
  1427. *
  1428. * @param node Node instance
  1429. * @param qr Query result buffer
  1430. */
  1431. void ZT_Node_freeQueryResult(ZT_Node *node,void *qr);
  1432. /**
  1433. * Add a local interface address
  1434. *
  1435. * This is used to make ZeroTier aware of those local interface addresses
  1436. * that you wish to use for ZeroTier communication. This is optional, and if
  1437. * it is not used ZeroTier will rely upon upstream peers (and roots) to
  1438. * perform empirical address discovery and NAT traversal. But the use of this
  1439. * method is recommended as it improves peer discovery when both peers are
  1440. * on the same LAN.
  1441. *
  1442. * It is the responsibility of the caller to take care that these are never
  1443. * ZeroTier interface addresses, whether these are assigned by ZeroTier or
  1444. * are otherwise assigned to an interface managed by this ZeroTier instance.
  1445. * This can cause recursion or other undesirable behavior.
  1446. *
  1447. * This returns a boolean indicating whether or not the address was
  1448. * accepted. ZeroTier will only communicate over certain address types
  1449. * and (for IP) address classes.
  1450. *
  1451. * @param addr Local interface address
  1452. * @return Boolean: non-zero if address was accepted and added
  1453. */
  1454. int ZT_Node_addLocalInterfaceAddress(ZT_Node *node,const struct sockaddr_storage *addr);
  1455. /**
  1456. * Clear local interface addresses
  1457. */
  1458. void ZT_Node_clearLocalInterfaceAddresses(ZT_Node *node);
  1459. /**
  1460. * Set a network configuration master instance for this node
  1461. *
  1462. * Normal nodes should not need to use this. This is for nodes with
  1463. * special compiled-in support for acting as network configuration
  1464. * masters / controllers.
  1465. *
  1466. * The supplied instance must be a C++ object that inherits from the
  1467. * NetworkConfigMaster base class in node/. No type checking is performed,
  1468. * so a pointer to anything else will result in a crash.
  1469. *
  1470. * @param node ZertTier One node
  1471. * @param networkConfigMasterInstance Instance of NetworkConfigMaster C++ class or NULL to disable
  1472. * @return OK (0) or error code if a fatal error condition has occurred
  1473. */
  1474. void ZT_Node_setNetconfMaster(ZT_Node *node,void *networkConfigMasterInstance);
  1475. /**
  1476. * Initiate a VL1 circuit test
  1477. *
  1478. * This sends an initial VERB_CIRCUIT_TEST and reports results back to the
  1479. * supplied callback until circuitTestEnd() is called. The supplied
  1480. * ZT_CircuitTest structure should be initially zeroed and then filled
  1481. * in with settings and hops.
  1482. *
  1483. * It is the caller's responsibility to call circuitTestEnd() and then
  1484. * to dispose of the test structure. Otherwise this node will listen
  1485. * for results forever.
  1486. *
  1487. * @param node Node instance
  1488. * @param test Test configuration
  1489. * @param reportCallback Function to call each time a report is received
  1490. * @return OK or error if, for example, test is too big for a packet or support isn't compiled in
  1491. */
  1492. enum ZT_ResultCode ZT_Node_circuitTestBegin(ZT_Node *node,ZT_CircuitTest *test,void (*reportCallback)(ZT_Node *, ZT_CircuitTest *,const ZT_CircuitTestReport *));
  1493. /**
  1494. * Stop listening for results to a given circuit test
  1495. *
  1496. * This does not free the 'test' structure. The caller may do that
  1497. * after calling this method to unregister it.
  1498. *
  1499. * Any reports that are received for a given test ID after it is
  1500. * terminated are ignored.
  1501. *
  1502. * @param node Node instance
  1503. * @param test Test configuration to unregister
  1504. */
  1505. void ZT_Node_circuitTestEnd(ZT_Node *node,ZT_CircuitTest *test);
  1506. /**
  1507. * Initialize cluster operation
  1508. *
  1509. * This initializes the internal structures and state for cluster operation.
  1510. * It takes two function pointers. The first is to a function that can be
  1511. * used to send data to cluster peers (mechanism is not defined by Node),
  1512. * and the second is to a function that can be used to get the location of
  1513. * a physical address in X,Y,Z coordinate space (e.g. as cartesian coordinates
  1514. * projected from the center of the Earth).
  1515. *
  1516. * Send function takes an arbitrary pointer followed by the cluster member ID
  1517. * to send data to, a pointer to the data, and the length of the data. The
  1518. * maximum message length is ZT_CLUSTER_MAX_MESSAGE_LENGTH (65535). Messages
  1519. * must be delivered whole and may be dropped or transposed, though high
  1520. * failure rates are undesirable and can cause problems. Validity checking or
  1521. * CRC is also not required since the Node validates the authenticity of
  1522. * cluster messages using cryptogrphic methods and will silently drop invalid
  1523. * messages.
  1524. *
  1525. * Address to location function is optional and if NULL geo-handoff is not
  1526. * enabled (in this case x, y, and z in clusterInit are also unused). It
  1527. * takes an arbitrary pointer followed by a physical address and three result
  1528. * parameters for x, y, and z. It returns zero on failure or nonzero if these
  1529. * three coordinates have been set. Coordinate space is arbitrary and can be
  1530. * e.g. coordinates on Earth relative to Earth's center. These can be obtained
  1531. * from latitutde and longitude with versions of the Haversine formula.
  1532. *
  1533. * See: http://stackoverflow.com/questions/1185408/converting-from-longitude-latitude-to-cartesian-coordinates
  1534. *
  1535. * Neither the send nor the address to location function should block. If the
  1536. * address to location function does not have a location for an address, it
  1537. * should return zero and then look up the address for future use since it
  1538. * will be called again in (typically) 1-3 minutes.
  1539. *
  1540. * Note that both functions can be called from any thread from which the
  1541. * various Node functions are called, and so must be thread safe if multiple
  1542. * threads are being used.
  1543. *
  1544. * @param node Node instance
  1545. * @param myId My cluster member ID (less than or equal to ZT_CLUSTER_MAX_MEMBERS)
  1546. * @param zeroTierPhysicalEndpoints Preferred physical address(es) for ZeroTier clients to contact this cluster member (for peer redirect)
  1547. * @param numZeroTierPhysicalEndpoints Number of physical endpoints in zeroTierPhysicalEndpoints[] (max allowed: 255)
  1548. * @param x My cluster member's X location
  1549. * @param y My cluster member's Y location
  1550. * @param z My cluster member's Z location
  1551. * @param sendFunction Function to be called to send data to other cluster members
  1552. * @param sendFunctionArg First argument to sendFunction()
  1553. * @param addressToLocationFunction Function to be called to get the location of a physical address or NULL to disable geo-handoff
  1554. * @param addressToLocationFunctionArg First argument to addressToLocationFunction()
  1555. * @return OK or UNSUPPORTED_OPERATION if this Node was not built with cluster support
  1556. */
  1557. enum ZT_ResultCode ZT_Node_clusterInit(
  1558. ZT_Node *node,
  1559. unsigned int myId,
  1560. const struct sockaddr_storage *zeroTierPhysicalEndpoints,
  1561. unsigned int numZeroTierPhysicalEndpoints,
  1562. int x,
  1563. int y,
  1564. int z,
  1565. void (*sendFunction)(void *,unsigned int,const void *,unsigned int),
  1566. void *sendFunctionArg,
  1567. int (*addressToLocationFunction)(void *,const struct sockaddr_storage *,int *,int *,int *),
  1568. void *addressToLocationFunctionArg);
  1569. /**
  1570. * Add a member to this cluster
  1571. *
  1572. * Calling this without having called clusterInit() will do nothing.
  1573. *
  1574. * @param node Node instance
  1575. * @param memberId Member ID (must be less than or equal to ZT_CLUSTER_MAX_MEMBERS)
  1576. * @return OK or error if clustering is disabled, ID invalid, etc.
  1577. */
  1578. enum ZT_ResultCode ZT_Node_clusterAddMember(ZT_Node *node,unsigned int memberId);
  1579. /**
  1580. * Remove a member from this cluster
  1581. *
  1582. * Calling this without having called clusterInit() will do nothing.
  1583. *
  1584. * @param node Node instance
  1585. * @param memberId Member ID to remove (nothing happens if not present)
  1586. */
  1587. void ZT_Node_clusterRemoveMember(ZT_Node *node,unsigned int memberId);
  1588. /**
  1589. * Handle an incoming cluster state message
  1590. *
  1591. * The message itself contains cluster member IDs, and invalid or badly
  1592. * addressed messages will be silently discarded.
  1593. *
  1594. * Calling this without having called clusterInit() will do nothing.
  1595. *
  1596. * @param node Node instance
  1597. * @param msg Cluster message
  1598. * @param len Length of cluster message
  1599. */
  1600. void ZT_Node_clusterHandleIncomingMessage(ZT_Node *node,const void *msg,unsigned int len);
  1601. /**
  1602. * Get the current status of the cluster from this node's point of view
  1603. *
  1604. * Calling this without clusterInit() or without cluster support will just
  1605. * zero out the structure and show a cluster size of zero.
  1606. *
  1607. * @param node Node instance
  1608. * @param cs Cluster status structure to fill with data
  1609. */
  1610. void ZT_Node_clusterStatus(ZT_Node *node,ZT_ClusterStatus *cs);
  1611. /**
  1612. * Set trusted paths
  1613. *
  1614. * A trusted path is a physical network (network/bits) over which both
  1615. * encryption and authentication can be skipped to improve performance.
  1616. * Each trusted path must have a non-zero unique ID that is the same across
  1617. * all participating nodes.
  1618. *
  1619. * We don't recommend using trusted paths at all unless you really *need*
  1620. * near-bare-metal performance. Even on a LAN authentication and encryption
  1621. * are never a bad thing, and anything that introduces an "escape hatch"
  1622. * for encryption should be treated with the utmost care.
  1623. *
  1624. * Calling with NULL pointers for networks and ids and a count of zero clears
  1625. * all trusted paths.
  1626. *
  1627. * @param node Node instance
  1628. * @param networks Array of [count] networks
  1629. * @param ids Array of [count] corresponding non-zero path IDs (zero path IDs are ignored)
  1630. * @param count Number of trusted paths-- values greater than ZT_MAX_TRUSTED_PATHS are clipped
  1631. */
  1632. void ZT_Node_setTrustedPaths(ZT_Node *node,const struct sockaddr_storage *networks,const uint64_t *ids,unsigned int count);
  1633. /**
  1634. * Do things in the background until Node dies
  1635. *
  1636. * This function can be called from one or more background threads to process
  1637. * certain tasks in the background to improve foreground performance. It will
  1638. * not return until the Node is shut down. If threading is not enabled in
  1639. * this build it will return immediately and will do nothing.
  1640. *
  1641. * This is completely optional. If this is never called, all processing is
  1642. * done in the foreground in the various processXXXX() methods.
  1643. *
  1644. * This does NOT replace or eliminate the need to call the normal
  1645. * processBackgroundTasks() function in your main loop. This mechanism is
  1646. * used to offload the processing of expensive mssages onto background
  1647. * handler threads to prevent foreground performance degradation under
  1648. * high load.
  1649. *
  1650. * @param node Node instance
  1651. */
  1652. void ZT_Node_backgroundThreadMain(ZT_Node *node);
  1653. /**
  1654. * Get ZeroTier One version
  1655. *
  1656. * @param major Result: major version
  1657. * @param minor Result: minor version
  1658. * @param revision Result: revision
  1659. */
  1660. void ZT_version(int *major,int *minor,int *revision);
  1661. #ifdef __cplusplus
  1662. }
  1663. #endif
  1664. #endif