ZeroTierOne.h 54 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894
  1. /*
  2. * ZeroTier One - Network Virtualization Everywhere
  3. * Copyright (C) 2011-2017 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. *
  20. * You can be released from the requirements of the license by purchasing
  21. * a commercial license. Buying such a license is mandatory as soon as you
  22. * develop commercial closed-source software that incorporates or links
  23. * directly against ZeroTier software without disclosing the source code
  24. * of your own application.
  25. */
  26. /*
  27. * This defines the external C API for ZeroTier's core network virtualization
  28. * engine.
  29. */
  30. #ifndef ZT_ZEROTIER_API_H
  31. #define ZT_ZEROTIER_API_H
  32. #include <stdint.h>
  33. // For the struct sockaddr_storage structure
  34. #if defined(_WIN32) || defined(_WIN64)
  35. #include <WinSock2.h>
  36. #include <WS2tcpip.h>
  37. #include <Windows.h>
  38. #else /* not Windows */
  39. #include <arpa/inet.h>
  40. #include <netinet/in.h>
  41. #include <sys/types.h>
  42. #include <sys/socket.h>
  43. #endif /* Windows or not */
  44. #if defined (_MSC_VER)
  45. #ifdef ZT_EXPORT
  46. #define ZT_SDK_API __declspec(dllexport)
  47. #else
  48. #define ZT_SDK_API __declspec(dllimport)
  49. #ifdef _DEBUG
  50. #ifdef _WIN64
  51. #pragma comment(lib, "ZeroTierOne_x64d.lib")
  52. #else
  53. #pragma comment(lib, "ZeroTierOne_x86d.lib")
  54. #endif
  55. #else
  56. #ifdef _WIN64
  57. #pragma comment(lib, "ZeroTierOne_x64.lib")
  58. #else
  59. #pragma comment(lib, "ZeroTierOne_x86.lib")
  60. #endif
  61. #endif
  62. #endif
  63. #else
  64. #define ZT_SDK_API
  65. #endif
  66. #ifdef __cplusplus
  67. extern "C" {
  68. #endif
  69. /****************************************************************************/
  70. /* Core constants */
  71. /****************************************************************************/
  72. /**
  73. * Default UDP port for devices running a ZeroTier endpoint
  74. */
  75. #define ZT_DEFAULT_PORT 9993
  76. /**
  77. * Minimum MTU, which is the minimum allowed by IPv6 and several specs
  78. */
  79. #define ZT_MIN_MTU 1280
  80. /**
  81. * Maximum MTU for ZeroTier virtual networks
  82. */
  83. #define ZT_MAX_MTU 10000
  84. /**
  85. * Default payload MTU for UDP packets
  86. *
  87. * This is 1500 - IPv6 UDP overhead - PPPoE overhead and is safe for 99.9% of
  88. * all Internet links.
  89. */
  90. #define ZT_DEFAULT_PHYSMTU 1444
  91. #define ZT_UDP_DEFAULT_PAYLOAD_MTU 1444
  92. /**
  93. * Maximum physical UDP payload
  94. */
  95. #define ZT_MAX_PHYSPAYLOAD 10100
  96. /**
  97. * Headroom for max physical MTU
  98. */
  99. #define ZT_MAX_HEADROOM 224
  100. /**
  101. * Maximum payload MTU for UDP packets
  102. */
  103. #define ZT_MAX_PHYSMTU (ZT_MAX_PHYSPAYLOAD + ZT_MAX_HEADROOM)
  104. /**
  105. * Maximum size of a remote trace message's serialized Dictionary
  106. */
  107. #define ZT_MAX_REMOTE_TRACE_SIZE 10000
  108. /**
  109. * Maximum length of network short name
  110. */
  111. #define ZT_MAX_NETWORK_SHORT_NAME_LENGTH 127
  112. /**
  113. * Maximum number of pushed routes on a network
  114. */
  115. #define ZT_MAX_NETWORK_ROUTES 32
  116. /**
  117. * Maximum number of statically assigned IP addresses per network endpoint using ZT address management (not DHCP)
  118. */
  119. #define ZT_MAX_ZT_ASSIGNED_ADDRESSES 16
  120. /**
  121. * Maximum number of "specialists" on a network -- bridges, relays, etc.
  122. */
  123. #define ZT_MAX_NETWORK_SPECIALISTS 256
  124. /**
  125. * Maximum number of multicast group subscriptions per network
  126. */
  127. #define ZT_MAX_NETWORK_MULTICAST_SUBSCRIPTIONS 4096
  128. /**
  129. * Rules engine revision ID, which specifies rules engine capabilities
  130. */
  131. #define ZT_RULES_ENGINE_REVISION 1
  132. /**
  133. * Maximum number of base (non-capability) network rules
  134. */
  135. #define ZT_MAX_NETWORK_RULES 1024
  136. /**
  137. * Maximum number of per-member capabilities per network
  138. */
  139. #define ZT_MAX_NETWORK_CAPABILITIES 128
  140. /**
  141. * Maximum number of per-member tags per network
  142. */
  143. #define ZT_MAX_NETWORK_TAGS 128
  144. /**
  145. * Maximum number of direct network paths to a given peer
  146. */
  147. #define ZT_MAX_PEER_NETWORK_PATHS 4
  148. /**
  149. * Maximum number of trusted physical network paths
  150. */
  151. #define ZT_MAX_TRUSTED_PATHS 16
  152. /**
  153. * Maximum number of rules per capability
  154. */
  155. #define ZT_MAX_CAPABILITY_RULES 64
  156. /**
  157. * Maximum number of certificates of ownership to assign to a single network member
  158. */
  159. #define ZT_MAX_CERTIFICATES_OF_OWNERSHIP 4
  160. /**
  161. * Global maximum length for capability chain of custody (including initial issue)
  162. */
  163. #define ZT_MAX_CAPABILITY_CUSTODY_CHAIN_LENGTH 7
  164. /**
  165. * Maximum value for link quality (min is 0)
  166. */
  167. #define ZT_PATH_LINK_QUALITY_MAX 0xff
  168. /**
  169. * Packet characteristics flag: packet direction, 1 if inbound 0 if outbound
  170. */
  171. #define ZT_RULE_PACKET_CHARACTERISTICS_INBOUND 0x8000000000000000ULL
  172. /**
  173. * Packet characteristics flag: multicast or broadcast destination MAC
  174. */
  175. #define ZT_RULE_PACKET_CHARACTERISTICS_MULTICAST 0x4000000000000000ULL
  176. /**
  177. * Packet characteristics flag: broadcast destination MAC
  178. */
  179. #define ZT_RULE_PACKET_CHARACTERISTICS_BROADCAST 0x2000000000000000ULL
  180. /**
  181. * Packet characteristics flag: sending IP address has a certificate of ownership
  182. */
  183. #define ZT_RULE_PACKET_CHARACTERISTICS_SENDER_IP_AUTHENTICATED 0x1000000000000000ULL
  184. /**
  185. * Packet characteristics flag: sending MAC address has a certificate of ownership
  186. */
  187. #define ZT_RULE_PACKET_CHARACTERISTICS_SENDER_MAC_AUTHENTICATED 0x0800000000000000ULL
  188. /**
  189. * Packet characteristics flag: TCP left-most reserved bit
  190. */
  191. #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_RESERVED_0 0x0000000000000800ULL
  192. /**
  193. * Packet characteristics flag: TCP middle reserved bit
  194. */
  195. #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_RESERVED_1 0x0000000000000400ULL
  196. /**
  197. * Packet characteristics flag: TCP right-most reserved bit
  198. */
  199. #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_RESERVED_2 0x0000000000000200ULL
  200. /**
  201. * Packet characteristics flag: TCP NS flag
  202. */
  203. #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_NS 0x0000000000000100ULL
  204. /**
  205. * Packet characteristics flag: TCP CWR flag
  206. */
  207. #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_CWR 0x0000000000000080ULL
  208. /**
  209. * Packet characteristics flag: TCP ECE flag
  210. */
  211. #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_ECE 0x0000000000000040ULL
  212. /**
  213. * Packet characteristics flag: TCP URG flag
  214. */
  215. #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_URG 0x0000000000000020ULL
  216. /**
  217. * Packet characteristics flag: TCP ACK flag
  218. */
  219. #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_ACK 0x0000000000000010ULL
  220. /**
  221. * Packet characteristics flag: TCP PSH flag
  222. */
  223. #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_PSH 0x0000000000000008ULL
  224. /**
  225. * Packet characteristics flag: TCP RST flag
  226. */
  227. #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_RST 0x0000000000000004ULL
  228. /**
  229. * Packet characteristics flag: TCP SYN flag
  230. */
  231. #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_SYN 0x0000000000000002ULL
  232. /**
  233. * Packet characteristics flag: TCP FIN flag
  234. */
  235. #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_FIN 0x0000000000000001ULL
  236. // Fields in remote trace dictionaries
  237. #define ZT_REMOTE_TRACE_FIELD__EVENT "event"
  238. #define ZT_REMOTE_TRACE_FIELD__NODE_ID "nodeId"
  239. #define ZT_REMOTE_TRACE_FIELD__PACKET_ID "packetId"
  240. #define ZT_REMOTE_TRACE_FIELD__PACKET_VERB "packetVerb"
  241. #define ZT_REMOTE_TRACE_FIELD__PACKET_TRUSTED_PATH_ID "packetTrustedPathId"
  242. #define ZT_REMOTE_TRACE_FIELD__PACKET_TRUSTED_PATH_APPROVED "packetTrustedPathApproved"
  243. #define ZT_REMOTE_TRACE_FIELD__PACKET_HOPS "packetHops"
  244. #define ZT_REMOTE_TRACE_FIELD__OLD_REMOTE_PHYADDR "oldRemotePhyAddr"
  245. #define ZT_REMOTE_TRACE_FIELD__REMOTE_ZTADDR "remoteZtAddr"
  246. #define ZT_REMOTE_TRACE_FIELD__REMOTE_PHYADDR "remotePhyAddr"
  247. #define ZT_REMOTE_TRACE_FIELD__LOCAL_ZTADDR "localZtAddr"
  248. #define ZT_REMOTE_TRACE_FIELD__LOCAL_PHYADDR "localPhyAddr"
  249. #define ZT_REMOTE_TRACE_FIELD__LOCAL_SOCKET "localSocket"
  250. #define ZT_REMOTE_TRACE_FIELD__IP_SCOPE "phyAddrIpScope"
  251. #define ZT_REMOTE_TRACE_FIELD__NETWORK_ID "networkId"
  252. #define ZT_REMOTE_TRACE_FIELD__SOURCE_ZTADDR "sourceZtAddr"
  253. #define ZT_REMOTE_TRACE_FIELD__DEST_ZTADDR "destZtAddr"
  254. #define ZT_REMOTE_TRACE_FIELD__SOURCE_MAC "sourceMac"
  255. #define ZT_REMOTE_TRACE_FIELD__DEST_MAC "destMac"
  256. #define ZT_REMOTE_TRACE_FIELD__ETHERTYPE "etherType"
  257. #define ZT_REMOTE_TRACE_FIELD__VLAN_ID "vlanId"
  258. #define ZT_REMOTE_TRACE_FIELD__FRAME_LENGTH "frameLength"
  259. #define ZT_REMOTE_TRACE_FIELD__FRAME_DATA "frameData"
  260. #define ZT_REMOTE_TRACE_FIELD__FILTER_FLAG_NOTEE "filterNoTee"
  261. #define ZT_REMOTE_TRACE_FIELD__FILTER_FLAG_INBOUND "filterInbound"
  262. #define ZT_REMOTE_TRACE_FIELD__FILTER_RESULT "filterResult"
  263. #define ZT_REMOTE_TRACE_FIELD__FILTER_BASE_RULE_LOG "filterBaseRuleLog"
  264. #define ZT_REMOTE_TRACE_FIELD__FILTER_CAP_RULE_LOG "filterCapRuleLog"
  265. #define ZT_REMOTE_TRACE_FIELD__FILTER_CAP_ID "filterMatchingCapId"
  266. #define ZT_REMOTE_TRACE_FIELD__CREDENTIAL_TYPE "credType"
  267. #define ZT_REMOTE_TRACE_FIELD__CREDENTIAL_ID "credId"
  268. #define ZT_REMOTE_TRACE_FIELD__CREDENTIAL_TIMESTAMP "credTs"
  269. #define ZT_REMOTE_TRACE_FIELD__CREDENTIAL_INFO "credInfo"
  270. #define ZT_REMOTE_TRACE_FIELD__CREDENTIAL_ISSUED_TO "credIssuedTo"
  271. #define ZT_REMOTE_TRACE_FIELD__CREDENTIAL_REVOCATION_TARGET "credRevocationTarget"
  272. #define ZT_REMOTE_TRACE_FIELD__REASON "reason"
  273. #define ZT_REMOTE_TRACE_FIELD__NETWORK_CONTROLLER_ID "networkControllerId"
  274. // Event types in remote traces
  275. #define ZT_REMOTE_TRACE_EVENT__RESETTING_PATHS_IN_SCOPE 0x1000
  276. #define ZT_REMOTE_TRACE_EVENT__TX_TIMED_OUT 0x1001
  277. #define ZT_REMOTE_TRACE_EVENT__PEER_CONFIRMING_UNKNOWN_PATH 0x1002
  278. #define ZT_REMOTE_TRACE_EVENT__PEER_LEARNED_NEW_PATH 0x1003
  279. #define ZT_REMOTE_TRACE_EVENT__PEER_REDIRECTED 0x1004
  280. #define ZT_REMOTE_TRACE_EVENT__PACKET_MAC_FAILURE 0x1005
  281. #define ZT_REMOTE_TRACE_EVENT__PACKET_INVALID 0x1006
  282. #define ZT_REMOTE_TRACE_EVENT__DROPPED_HELLO 0x1006
  283. #define ZT_REMOTE_TRACE_EVENT__OUTGOING_NETWORK_FRAME_DROPPED 0x2000
  284. #define ZT_REMOTE_TRACE_EVENT__INCOMING_NETWORK_ACCESS_DENIED 0x2001
  285. #define ZT_REMOTE_TRACE_EVENT__INCOMING_NETWORK_FRAME_DROPPED 0x2002
  286. #define ZT_REMOTE_TRACE_EVENT__CREDENTIAL_REJECTED 0x2003
  287. #define ZT_REMOTE_TRACE_EVENT__CREDENTIAL_ACCEPTED 0x2004
  288. #define ZT_REMOTE_TRACE_EVENT__NETWORK_CONFIG_REQUEST_SENT 0x2005
  289. #define ZT_REMOTE_TRACE_EVENT__NETWORK_FILTER_TRACE 0x2006
  290. // Event types in remote traces in hex string form
  291. #define ZT_REMOTE_TRACE_EVENT__RESETTING_PATHS_IN_SCOPE_S "1000"
  292. #define ZT_REMOTE_TRACE_EVENT__TX_TIMED_OUT_S "1001"
  293. #define ZT_REMOTE_TRACE_EVENT__PEER_CONFIRMING_UNKNOWN_PATH_S "1002"
  294. #define ZT_REMOTE_TRACE_EVENT__PEER_LEARNED_NEW_PATH_S "1003"
  295. #define ZT_REMOTE_TRACE_EVENT__PEER_REDIRECTED_S "1004"
  296. #define ZT_REMOTE_TRACE_EVENT__PACKET_MAC_FAILURE_S "1005"
  297. #define ZT_REMOTE_TRACE_EVENT__PACKET_INVALID_S "1006"
  298. #define ZT_REMOTE_TRACE_EVENT__DROPPED_HELLO_S "1006"
  299. #define ZT_REMOTE_TRACE_EVENT__OUTGOING_NETWORK_FRAME_DROPPED_S "2000"
  300. #define ZT_REMOTE_TRACE_EVENT__INCOMING_NETWORK_ACCESS_DENIED_S "2001"
  301. #define ZT_REMOTE_TRACE_EVENT__INCOMING_NETWORK_FRAME_DROPPED_S "2002"
  302. #define ZT_REMOTE_TRACE_EVENT__CREDENTIAL_REJECTED_S "2003"
  303. #define ZT_REMOTE_TRACE_EVENT__CREDENTIAL_ACCEPTED_S "2004"
  304. #define ZT_REMOTE_TRACE_EVENT__NETWORK_CONFIG_REQUEST_SENT_S "2005"
  305. #define ZT_REMOTE_TRACE_EVENT__NETWORK_FILTER_TRACE_S "2006"
  306. /****************************************************************************/
  307. /* Structures and other types */
  308. /****************************************************************************/
  309. /**
  310. * Function return code: OK (0) or error results
  311. *
  312. * Use ZT_ResultCode_isFatal() to check for a fatal error. If a fatal error
  313. * occurs, the node should be considered to not be working correctly. These
  314. * indicate serious problems like an inaccessible data store or a compile
  315. * problem.
  316. */
  317. enum ZT_ResultCode
  318. {
  319. /**
  320. * Operation completed normally
  321. */
  322. ZT_RESULT_OK = 0,
  323. /**
  324. * Call produced no error but no action was taken
  325. */
  326. ZT_RESULT_OK_IGNORED = 1,
  327. // Fatal errors (>100, <1000)
  328. /**
  329. * Ran out of memory
  330. */
  331. ZT_RESULT_FATAL_ERROR_OUT_OF_MEMORY = 100,
  332. /**
  333. * Data store is not writable or has failed
  334. */
  335. ZT_RESULT_FATAL_ERROR_DATA_STORE_FAILED = 101,
  336. /**
  337. * Internal error (e.g. unexpected exception indicating bug or build problem)
  338. */
  339. ZT_RESULT_FATAL_ERROR_INTERNAL = 102,
  340. // Non-fatal errors (>1000)
  341. /**
  342. * Network ID not valid
  343. */
  344. ZT_RESULT_ERROR_NETWORK_NOT_FOUND = 1000,
  345. /**
  346. * The requested operation is not supported on this version or build
  347. */
  348. ZT_RESULT_ERROR_UNSUPPORTED_OPERATION = 1001,
  349. /**
  350. * The requestion operation was given a bad parameter or was called in an invalid state
  351. */
  352. ZT_RESULT_ERROR_BAD_PARAMETER = 1002
  353. };
  354. /**
  355. * @param x Result code
  356. * @return True if result code indicates a fatal error
  357. */
  358. #define ZT_ResultCode_isFatal(x) ((((int)(x)) >= 100)&&(((int)(x)) < 1000))
  359. /**
  360. * Status codes sent to status update callback when things happen
  361. */
  362. enum ZT_Event
  363. {
  364. /**
  365. * Node has been initialized
  366. *
  367. * This is the first event generated, and is always sent. It may occur
  368. * before Node's constructor returns.
  369. *
  370. * Meta-data: none
  371. */
  372. ZT_EVENT_UP = 0,
  373. /**
  374. * Node is offline -- network does not seem to be reachable by any available strategy
  375. *
  376. * Meta-data: none
  377. */
  378. ZT_EVENT_OFFLINE = 1,
  379. /**
  380. * Node is online -- at least one upstream node appears reachable
  381. *
  382. * Meta-data: none
  383. */
  384. ZT_EVENT_ONLINE = 2,
  385. /**
  386. * Node is shutting down
  387. *
  388. * This is generated within Node's destructor when it is being shut down.
  389. * It's done for convenience, since cleaning up other state in the event
  390. * handler may appear more idiomatic.
  391. *
  392. * Meta-data: none
  393. */
  394. ZT_EVENT_DOWN = 3,
  395. /**
  396. * Your identity has collided with another node's ZeroTier address
  397. *
  398. * This happens if two different public keys both hash (via the algorithm
  399. * in Identity::generate()) to the same 40-bit ZeroTier address.
  400. *
  401. * This is something you should "never" see, where "never" is defined as
  402. * once per 2^39 new node initializations / identity creations. If you do
  403. * see it, you're going to see it very soon after a node is first
  404. * initialized.
  405. *
  406. * This is reported as an event rather than a return code since it's
  407. * detected asynchronously via error messages from authoritative nodes.
  408. *
  409. * If this occurs, you must shut down and delete the node, delete the
  410. * identity.secret record/file from the data store, and restart to generate
  411. * a new identity. If you don't do this, you will not be able to communicate
  412. * with other nodes.
  413. *
  414. * We'd automate this process, but we don't think silently deleting
  415. * private keys or changing our address without telling the calling code
  416. * is good form. It violates the principle of least surprise.
  417. *
  418. * You can technically get away with not handling this, but we recommend
  419. * doing so in a mature reliable application. Besides, handling this
  420. * condition is a good way to make sure it never arises. It's like how
  421. * umbrellas prevent rain and smoke detectors prevent fires. They do, right?
  422. *
  423. * Meta-data: none
  424. */
  425. ZT_EVENT_FATAL_ERROR_IDENTITY_COLLISION = 4,
  426. /**
  427. * Trace (debugging) message
  428. *
  429. * These events are only generated if this is a TRACE-enabled build.
  430. *
  431. * Meta-data: C string, TRACE message
  432. */
  433. ZT_EVENT_TRACE = 5,
  434. /**
  435. * VERB_USER_MESSAGE received
  436. *
  437. * These are generated when a VERB_USER_MESSAGE packet is received via
  438. * ZeroTier VL1.
  439. *
  440. * Meta-data: ZT_UserMessage structure
  441. */
  442. ZT_EVENT_USER_MESSAGE = 6,
  443. /**
  444. * Remote trace received
  445. *
  446. * These are generated when a VERB_REMOTE_TRACE is received. Note
  447. * that any node can fling one of these at us. It is your responsibility
  448. * to filter and determine if it's worth paying attention to. If it's
  449. * not just drop it. Most nodes that are not active controllers ignore
  450. * these, and controllers only save them if they pertain to networks
  451. * with remote tracing enabled.
  452. *
  453. * Meta-data: ZT_RemoteTrace structure
  454. */
  455. ZT_EVENT_REMOTE_TRACE = 7
  456. };
  457. /**
  458. * Payload of REMOTE_TRACE event
  459. */
  460. typedef struct
  461. {
  462. /**
  463. * ZeroTier address of sender
  464. */
  465. uint64_t origin;
  466. /**
  467. * Null-terminated Dictionary containing key/value pairs sent by origin
  468. *
  469. * This *should* be a dictionary, but the implementation only checks
  470. * that it is a valid non-empty C-style null-terminated string. Be very
  471. * careful to use a well-tested parser to parse this as it represents
  472. * data received from a potentially un-trusted peer on the network.
  473. * Invalid payloads should be dropped.
  474. *
  475. * The contents of data[] may be modified.
  476. */
  477. char *data;
  478. /**
  479. * Length of dict[] in bytes, including terminating null
  480. */
  481. unsigned int len;
  482. } ZT_RemoteTrace;
  483. /**
  484. * User message used with ZT_EVENT_USER_MESSAGE
  485. *
  486. * These are direct VL1 P2P messages for application use. Encryption and
  487. * authentication in the ZeroTier protocol will guarantee the origin
  488. * address and message content, but you are responsible for any other
  489. * levels of authentication or access control that are required. Any node
  490. * in the world can send you a user message! (Unless your network is air
  491. * gapped.)
  492. */
  493. typedef struct
  494. {
  495. /**
  496. * ZeroTier address of sender (least significant 40 bits)
  497. */
  498. uint64_t origin;
  499. /**
  500. * User message type ID
  501. */
  502. uint64_t typeId;
  503. /**
  504. * User message data (not including type ID)
  505. */
  506. const void *data;
  507. /**
  508. * Length of data in bytes
  509. */
  510. unsigned int length;
  511. } ZT_UserMessage;
  512. /**
  513. * Current node status
  514. */
  515. typedef struct
  516. {
  517. /**
  518. * 40-bit ZeroTier address of this node
  519. */
  520. uint64_t address;
  521. /**
  522. * Public identity in string-serialized form (safe to send to others)
  523. *
  524. * This pointer will remain valid as long as the node exists.
  525. */
  526. const char *publicIdentity;
  527. /**
  528. * Full identity including secret key in string-serialized form
  529. *
  530. * This pointer will remain valid as long as the node exists.
  531. */
  532. const char *secretIdentity;
  533. /**
  534. * True if some kind of connectivity appears available
  535. */
  536. int online;
  537. } ZT_NodeStatus;
  538. /**
  539. * Virtual network status codes
  540. */
  541. enum ZT_VirtualNetworkStatus
  542. {
  543. /**
  544. * Waiting for network configuration (also means revision == 0)
  545. */
  546. ZT_NETWORK_STATUS_REQUESTING_CONFIGURATION = 0,
  547. /**
  548. * Configuration received and we are authorized
  549. */
  550. ZT_NETWORK_STATUS_OK = 1,
  551. /**
  552. * Netconf master told us 'nope'
  553. */
  554. ZT_NETWORK_STATUS_ACCESS_DENIED = 2,
  555. /**
  556. * Netconf master exists, but this virtual network does not
  557. */
  558. ZT_NETWORK_STATUS_NOT_FOUND = 3,
  559. /**
  560. * Initialization of network failed or other internal error
  561. */
  562. ZT_NETWORK_STATUS_PORT_ERROR = 4,
  563. /**
  564. * ZeroTier core version too old
  565. */
  566. ZT_NETWORK_STATUS_CLIENT_TOO_OLD = 5
  567. };
  568. /**
  569. * Virtual network type codes
  570. */
  571. enum ZT_VirtualNetworkType
  572. {
  573. /**
  574. * Private networks are authorized via certificates of membership
  575. */
  576. ZT_NETWORK_TYPE_PRIVATE = 0,
  577. /**
  578. * Public networks have no access control -- they'll always be AUTHORIZED
  579. */
  580. ZT_NETWORK_TYPE_PUBLIC = 1
  581. };
  582. /**
  583. * The type of a virtual network rules table entry
  584. *
  585. * These must be from 0 to 63 since the most significant two bits of each
  586. * rule type are NOT (MSB) and AND/OR.
  587. *
  588. * Each rule is composed of zero or more MATCHes followed by an ACTION.
  589. * An ACTION with no MATCHes is always taken.
  590. */
  591. enum ZT_VirtualNetworkRuleType
  592. {
  593. // 0 to 15 reserved for actions
  594. /**
  595. * Drop frame
  596. */
  597. ZT_NETWORK_RULE_ACTION_DROP = 0,
  598. /**
  599. * Accept and pass frame
  600. */
  601. ZT_NETWORK_RULE_ACTION_ACCEPT = 1,
  602. /**
  603. * Forward a copy of this frame to an observer (by ZT address)
  604. */
  605. ZT_NETWORK_RULE_ACTION_TEE = 2,
  606. /**
  607. * Exactly like TEE but mandates ACKs from observer
  608. */
  609. ZT_NETWORK_RULE_ACTION_WATCH = 3,
  610. /**
  611. * Drop and redirect this frame to another node (by ZT address)
  612. */
  613. ZT_NETWORK_RULE_ACTION_REDIRECT = 4,
  614. /**
  615. * Stop evaluating rule set (drops unless there are capabilities, etc.)
  616. */
  617. ZT_NETWORK_RULE_ACTION_BREAK = 5,
  618. /**
  619. * Maximum ID for an ACTION, anything higher is a MATCH
  620. */
  621. ZT_NETWORK_RULE_ACTION__MAX_ID = 15,
  622. // 16 to 63 reserved for match criteria
  623. ZT_NETWORK_RULE_MATCH_SOURCE_ZEROTIER_ADDRESS = 24,
  624. ZT_NETWORK_RULE_MATCH_DEST_ZEROTIER_ADDRESS = 25,
  625. ZT_NETWORK_RULE_MATCH_VLAN_ID = 26,
  626. ZT_NETWORK_RULE_MATCH_VLAN_PCP = 27,
  627. ZT_NETWORK_RULE_MATCH_VLAN_DEI = 28,
  628. ZT_NETWORK_RULE_MATCH_MAC_SOURCE = 29,
  629. ZT_NETWORK_RULE_MATCH_MAC_DEST = 30,
  630. ZT_NETWORK_RULE_MATCH_IPV4_SOURCE = 31,
  631. ZT_NETWORK_RULE_MATCH_IPV4_DEST = 32,
  632. ZT_NETWORK_RULE_MATCH_IPV6_SOURCE = 33,
  633. ZT_NETWORK_RULE_MATCH_IPV6_DEST = 34,
  634. ZT_NETWORK_RULE_MATCH_IP_TOS = 35,
  635. ZT_NETWORK_RULE_MATCH_IP_PROTOCOL = 36,
  636. ZT_NETWORK_RULE_MATCH_ETHERTYPE = 37,
  637. ZT_NETWORK_RULE_MATCH_ICMP = 38,
  638. ZT_NETWORK_RULE_MATCH_IP_SOURCE_PORT_RANGE = 39,
  639. ZT_NETWORK_RULE_MATCH_IP_DEST_PORT_RANGE = 40,
  640. ZT_NETWORK_RULE_MATCH_CHARACTERISTICS = 41,
  641. ZT_NETWORK_RULE_MATCH_FRAME_SIZE_RANGE = 42,
  642. ZT_NETWORK_RULE_MATCH_RANDOM = 43,
  643. ZT_NETWORK_RULE_MATCH_TAGS_DIFFERENCE = 44,
  644. ZT_NETWORK_RULE_MATCH_TAGS_BITWISE_AND = 45,
  645. ZT_NETWORK_RULE_MATCH_TAGS_BITWISE_OR = 46,
  646. ZT_NETWORK_RULE_MATCH_TAGS_BITWISE_XOR = 47,
  647. ZT_NETWORK_RULE_MATCH_TAGS_EQUAL = 48,
  648. ZT_NETWORK_RULE_MATCH_TAG_SENDER = 49,
  649. ZT_NETWORK_RULE_MATCH_TAG_RECEIVER = 50,
  650. /**
  651. * Maximum ID allowed for a MATCH entry in the rules table
  652. */
  653. ZT_NETWORK_RULE_MATCH__MAX_ID = 63
  654. };
  655. /**
  656. * Network flow rule
  657. *
  658. * Rules are stored in a table in which one or more match entries is followed
  659. * by an action. If more than one match precedes an action, the rule is
  660. * the AND of all matches. An action with no match is always taken since it
  661. * matches anything. If nothing matches, the default action is DROP.
  662. *
  663. * This is designed to be a more memory-efficient way of storing rules than
  664. * a wide table, yet still fast and simple to access in code.
  665. */
  666. typedef struct
  667. {
  668. /**
  669. * Type and flags
  670. *
  671. * Bits are: NOTTTTTT
  672. *
  673. * N - If true, sense of match is inverted (no effect on actions)
  674. * O - If true, result is ORed with previous instead of ANDed (no effect on actions)
  675. * T - Rule or action type
  676. *
  677. * AND with 0x3f to get type, 0x80 to get NOT bit, and 0x40 to get OR bit.
  678. */
  679. uint8_t t;
  680. /**
  681. * Union containing the value of this rule -- which field is used depends on 't'
  682. */
  683. union {
  684. /**
  685. * IPv6 address in big-endian / network byte order and netmask bits
  686. */
  687. struct {
  688. uint8_t ip[16];
  689. uint8_t mask;
  690. } ipv6;
  691. /**
  692. * IPv4 address in big-endian / network byte order
  693. */
  694. struct {
  695. uint32_t ip;
  696. uint8_t mask;
  697. } ipv4;
  698. /**
  699. * Packet characteristic flags being matched
  700. */
  701. uint64_t characteristics;
  702. /**
  703. * IP port range -- start-end inclusive -- host byte order
  704. */
  705. uint16_t port[2];
  706. /**
  707. * 40-bit ZeroTier address (in least significant bits, host byte order)
  708. */
  709. uint64_t zt;
  710. /**
  711. * 0 = never, UINT32_MAX = always
  712. */
  713. uint32_t randomProbability;
  714. /**
  715. * 48-bit Ethernet MAC address in big-endian order
  716. */
  717. uint8_t mac[6];
  718. /**
  719. * VLAN ID in host byte order
  720. */
  721. uint16_t vlanId;
  722. /**
  723. * VLAN PCP (least significant 3 bits)
  724. */
  725. uint8_t vlanPcp;
  726. /**
  727. * VLAN DEI (single bit / boolean)
  728. */
  729. uint8_t vlanDei;
  730. /**
  731. * Ethernet type in host byte order
  732. */
  733. uint16_t etherType;
  734. /**
  735. * IP protocol
  736. */
  737. uint8_t ipProtocol;
  738. /**
  739. * IP type of service a.k.a. DSCP field
  740. */
  741. struct {
  742. uint8_t mask;
  743. uint8_t value[2];
  744. } ipTos;
  745. /**
  746. * Ethernet packet size in host byte order (start-end, inclusive)
  747. */
  748. uint16_t frameSize[2];
  749. /**
  750. * ICMP type and code
  751. */
  752. struct {
  753. uint8_t type; // ICMP type, always matched
  754. uint8_t code; // ICMP code if matched
  755. uint8_t flags; // flag 0x01 means also match code, otherwise only match type
  756. } icmp;
  757. /**
  758. * For tag-related rules
  759. */
  760. struct {
  761. uint32_t id;
  762. uint32_t value;
  763. } tag;
  764. /**
  765. * Destinations for TEE and REDIRECT
  766. */
  767. struct {
  768. uint64_t address;
  769. uint32_t flags;
  770. uint16_t length;
  771. } fwd;
  772. } v;
  773. } ZT_VirtualNetworkRule;
  774. /**
  775. * A route to be pushed on a virtual network
  776. */
  777. typedef struct
  778. {
  779. /**
  780. * Target network / netmask bits (in port field) or NULL or 0.0.0.0/0 for default
  781. */
  782. struct sockaddr_storage target;
  783. /**
  784. * Gateway IP address (port ignored) or NULL (family == 0) for LAN-local (no gateway)
  785. */
  786. struct sockaddr_storage via;
  787. /**
  788. * Route flags
  789. */
  790. uint16_t flags;
  791. /**
  792. * Route metric (not currently used)
  793. */
  794. uint16_t metric;
  795. } ZT_VirtualNetworkRoute;
  796. /**
  797. * An Ethernet multicast group
  798. */
  799. typedef struct
  800. {
  801. /**
  802. * MAC address (least significant 48 bits)
  803. */
  804. uint64_t mac;
  805. /**
  806. * Additional distinguishing information (usually zero)
  807. */
  808. unsigned long adi;
  809. } ZT_MulticastGroup;
  810. /**
  811. * Virtual network configuration update type
  812. */
  813. enum ZT_VirtualNetworkConfigOperation
  814. {
  815. /**
  816. * Network is coming up (either for the first time or after service restart)
  817. */
  818. ZT_VIRTUAL_NETWORK_CONFIG_OPERATION_UP = 1,
  819. /**
  820. * Network configuration has been updated
  821. */
  822. ZT_VIRTUAL_NETWORK_CONFIG_OPERATION_CONFIG_UPDATE = 2,
  823. /**
  824. * Network is going down (not permanently)
  825. */
  826. ZT_VIRTUAL_NETWORK_CONFIG_OPERATION_DOWN = 3,
  827. /**
  828. * Network is going down permanently (leave/delete)
  829. */
  830. ZT_VIRTUAL_NETWORK_CONFIG_OPERATION_DESTROY = 4
  831. };
  832. /**
  833. * What trust hierarchy role does this peer have?
  834. */
  835. enum ZT_PeerRole
  836. {
  837. ZT_PEER_ROLE_LEAF = 0, // ordinary node
  838. ZT_PEER_ROLE_MOON = 1, // moon root
  839. ZT_PEER_ROLE_PLANET = 2 // planetary root
  840. };
  841. /**
  842. * Vendor ID
  843. */
  844. enum ZT_Vendor
  845. {
  846. ZT_VENDOR_UNSPECIFIED = 0,
  847. ZT_VENDOR_ZEROTIER = 1
  848. };
  849. /**
  850. * Platform type
  851. */
  852. enum ZT_Platform
  853. {
  854. ZT_PLATFORM_UNSPECIFIED = 0,
  855. ZT_PLATFORM_LINUX = 1,
  856. ZT_PLATFORM_WINDOWS = 2,
  857. ZT_PLATFORM_MACOS = 3,
  858. ZT_PLATFORM_ANDROID = 4,
  859. ZT_PLATFORM_IOS = 5,
  860. ZT_PLATFORM_SOLARIS_SMARTOS = 6,
  861. ZT_PLATFORM_FREEBSD = 7,
  862. ZT_PLATFORM_NETBSD = 8,
  863. ZT_PLATFORM_OPENBSD = 9,
  864. ZT_PLATFORM_RISCOS = 10,
  865. ZT_PLATFORM_VXWORKS = 11,
  866. ZT_PLATFORM_FREERTOS = 12,
  867. ZT_PLATFORM_SYSBIOS = 13,
  868. ZT_PLATFORM_HURD = 14,
  869. ZT_PLATFORM_WEB = 15
  870. };
  871. /**
  872. * Architecture type
  873. */
  874. enum ZT_Architecture
  875. {
  876. ZT_ARCHITECTURE_UNSPECIFIED = 0,
  877. ZT_ARCHITECTURE_X86 = 1,
  878. ZT_ARCHITECTURE_X64 = 2,
  879. ZT_ARCHITECTURE_ARM32 = 3,
  880. ZT_ARCHITECTURE_ARM64 = 4,
  881. ZT_ARCHITECTURE_MIPS32 = 5,
  882. ZT_ARCHITECTURE_MIPS64 = 6,
  883. ZT_ARCHITECTURE_POWER32 = 7,
  884. ZT_ARCHITECTURE_POWER64 = 8,
  885. ZT_ARCHITECTURE_OPENRISC32 = 9,
  886. ZT_ARCHITECTURE_OPENRISC64 = 10,
  887. ZT_ARCHITECTURE_SPARC32 = 11,
  888. ZT_ARCHITECTURE_SPARC64 = 12,
  889. ZT_ARCHITECTURE_DOTNET_CLR = 13,
  890. ZT_ARCHITECTURE_JAVA_JVM = 14,
  891. ZT_ARCHITECTURE_WEB = 15
  892. };
  893. /**
  894. * Virtual network configuration
  895. */
  896. typedef struct
  897. {
  898. /**
  899. * 64-bit ZeroTier network ID
  900. */
  901. uint64_t nwid;
  902. /**
  903. * Ethernet MAC (48 bits) that should be assigned to port
  904. */
  905. uint64_t mac;
  906. /**
  907. * Network name (from network configuration master)
  908. */
  909. char name[ZT_MAX_NETWORK_SHORT_NAME_LENGTH + 1];
  910. /**
  911. * Network configuration request status
  912. */
  913. enum ZT_VirtualNetworkStatus status;
  914. /**
  915. * Network type
  916. */
  917. enum ZT_VirtualNetworkType type;
  918. /**
  919. * Maximum interface MTU
  920. */
  921. unsigned int mtu;
  922. /**
  923. * Recommended MTU to avoid fragmentation at the physical layer (hint)
  924. */
  925. unsigned int physicalMtu;
  926. /**
  927. * If nonzero, the network this port belongs to indicates DHCP availability
  928. *
  929. * This is a suggestion. The underlying implementation is free to ignore it
  930. * for security or other reasons. This is simply a netconf parameter that
  931. * means 'DHCP is available on this network.'
  932. */
  933. int dhcp;
  934. /**
  935. * If nonzero, this port is allowed to bridge to other networks
  936. *
  937. * This is informational. If this is false (0), bridged packets will simply
  938. * be dropped and bridging won't work.
  939. */
  940. int bridge;
  941. /**
  942. * If nonzero, this network supports and allows broadcast (ff:ff:ff:ff:ff:ff) traffic
  943. */
  944. int broadcastEnabled;
  945. /**
  946. * If the network is in PORT_ERROR state, this is the (negative) error code most recently reported
  947. */
  948. int portError;
  949. /**
  950. * Revision number as reported by controller or 0 if still waiting for config
  951. */
  952. unsigned long netconfRevision;
  953. /**
  954. * Number of assigned addresses
  955. */
  956. unsigned int assignedAddressCount;
  957. /**
  958. * ZeroTier-assigned addresses (in sockaddr_storage structures)
  959. *
  960. * For IP, the port number of the sockaddr_XX structure contains the number
  961. * of bits in the address netmask. Only the IP address and port are used.
  962. * Other fields like interface number can be ignored.
  963. *
  964. * This is only used for ZeroTier-managed address assignments sent by the
  965. * virtual network's configuration master.
  966. */
  967. struct sockaddr_storage assignedAddresses[ZT_MAX_ZT_ASSIGNED_ADDRESSES];
  968. /**
  969. * Number of ZT-pushed routes
  970. */
  971. unsigned int routeCount;
  972. /**
  973. * Routes (excluding those implied by assigned addresses and their masks)
  974. */
  975. ZT_VirtualNetworkRoute routes[ZT_MAX_NETWORK_ROUTES];
  976. } ZT_VirtualNetworkConfig;
  977. /**
  978. * A list of networks
  979. */
  980. typedef struct
  981. {
  982. ZT_VirtualNetworkConfig *networks;
  983. unsigned long networkCount;
  984. } ZT_VirtualNetworkList;
  985. /**
  986. * Physical network path to a peer
  987. */
  988. typedef struct
  989. {
  990. /**
  991. * Address of endpoint
  992. */
  993. struct sockaddr_storage address;
  994. /**
  995. * Time of last send in milliseconds or 0 for never
  996. */
  997. uint64_t lastSend;
  998. /**
  999. * Time of last receive in milliseconds or 0 for never
  1000. */
  1001. uint64_t lastReceive;
  1002. /**
  1003. * Is this a trusted path? If so this will be its nonzero ID.
  1004. */
  1005. uint64_t trustedPathId;
  1006. /**
  1007. * Path link quality from 0 to 255 (always 255 if peer does not support)
  1008. */
  1009. int linkQuality;
  1010. /**
  1011. * Is path expired?
  1012. */
  1013. int expired;
  1014. /**
  1015. * Is path preferred?
  1016. */
  1017. int preferred;
  1018. } ZT_PeerPhysicalPath;
  1019. /**
  1020. * Peer status result buffer
  1021. */
  1022. typedef struct
  1023. {
  1024. /**
  1025. * ZeroTier address (40 bits)
  1026. */
  1027. uint64_t address;
  1028. /**
  1029. * Remote major version or -1 if not known
  1030. */
  1031. int versionMajor;
  1032. /**
  1033. * Remote minor version or -1 if not known
  1034. */
  1035. int versionMinor;
  1036. /**
  1037. * Remote revision or -1 if not known
  1038. */
  1039. int versionRev;
  1040. /**
  1041. * Last measured latency in milliseconds or zero if unknown
  1042. */
  1043. unsigned int latency;
  1044. /**
  1045. * What trust hierarchy role does this device have?
  1046. */
  1047. enum ZT_PeerRole role;
  1048. /**
  1049. * Number of paths (size of paths[])
  1050. */
  1051. unsigned int pathCount;
  1052. /**
  1053. * Known network paths to peer
  1054. */
  1055. ZT_PeerPhysicalPath paths[ZT_MAX_PEER_NETWORK_PATHS];
  1056. } ZT_Peer;
  1057. /**
  1058. * List of peers
  1059. */
  1060. typedef struct
  1061. {
  1062. ZT_Peer *peers;
  1063. unsigned long peerCount;
  1064. } ZT_PeerList;
  1065. /**
  1066. * ZeroTier core state objects
  1067. */
  1068. enum ZT_StateObjectType
  1069. {
  1070. /**
  1071. * Null object -- ignored
  1072. */
  1073. ZT_STATE_OBJECT_NULL = 0,
  1074. /**
  1075. * Public address and public key
  1076. *
  1077. * Object ID: this node's address if known, or 0 if unknown (first query)
  1078. * Canonical path: <HOME>/identity.public
  1079. * Persistence: required
  1080. */
  1081. ZT_STATE_OBJECT_IDENTITY_PUBLIC = 1,
  1082. /**
  1083. * Full identity with secret key
  1084. *
  1085. * Object ID: this node's address if known, or 0 if unknown (first query)
  1086. * Canonical path: <HOME>/identity.secret
  1087. * Persistence: required, should be stored with restricted permissions e.g. mode 0600 on *nix
  1088. */
  1089. ZT_STATE_OBJECT_IDENTITY_SECRET = 2,
  1090. /**
  1091. * The planet (there is only one per... well... planet!)
  1092. *
  1093. * Object ID: world ID of planet, or 0 if unknown (first query)
  1094. * Canonical path: <HOME>/planet
  1095. * Persistence: recommended
  1096. */
  1097. ZT_STATE_OBJECT_PLANET = 3,
  1098. /**
  1099. * A moon (federated root set)
  1100. *
  1101. * Object ID: world ID of moon
  1102. * Canonical path: <HOME>/moons.d/<ID>.moon (16-digit hex ID)
  1103. * Persistence: required if moon memberships should persist
  1104. */
  1105. ZT_STATE_OBJECT_MOON = 4,
  1106. /**
  1107. * Peer and related state
  1108. *
  1109. * Object ID: peer address
  1110. * Canonical path: <HOME>/peers.d/<ID> (10-digit address
  1111. * Persistence: optional, can be cleared at any time
  1112. */
  1113. ZT_STATE_OBJECT_PEER = 5,
  1114. /**
  1115. * Network configuration
  1116. *
  1117. * Object ID: peer address
  1118. * Canonical path: <HOME>/networks.d/<NETWORKID>.conf (16-digit hex ID)
  1119. * Persistence: required if network memberships should persist
  1120. */
  1121. ZT_STATE_OBJECT_NETWORK_CONFIG = 6
  1122. };
  1123. /**
  1124. * An instance of a ZeroTier One node (opaque)
  1125. */
  1126. typedef void ZT_Node;
  1127. /****************************************************************************/
  1128. /* Callbacks used by Node API */
  1129. /****************************************************************************/
  1130. /**
  1131. * Callback called to update virtual network port configuration
  1132. *
  1133. * This can be called at any time to update the configuration of a virtual
  1134. * network port. The parameter after the network ID specifies whether this
  1135. * port is being brought up, updated, brought down, or permanently deleted.
  1136. *
  1137. * This in turn should be used by the underlying implementation to create
  1138. * and configure tap devices at the OS (or virtual network stack) layer.
  1139. *
  1140. * The supplied config pointer is not guaranteed to remain valid, so make
  1141. * a copy if you want one.
  1142. *
  1143. * This should not call multicastSubscribe() or other network-modifying
  1144. * methods, as this could cause a deadlock in multithreaded or interrupt
  1145. * driven environments.
  1146. *
  1147. * This must return 0 on success. It can return any OS-dependent error code
  1148. * on failure, and this results in the network being placed into the
  1149. * PORT_ERROR state.
  1150. */
  1151. typedef int (*ZT_VirtualNetworkConfigFunction)(
  1152. ZT_Node *, /* Node */
  1153. void *, /* User ptr */
  1154. void *, /* Thread ptr */
  1155. uint64_t, /* Network ID */
  1156. void **, /* Modifiable network user PTR */
  1157. enum ZT_VirtualNetworkConfigOperation, /* Config operation */
  1158. const ZT_VirtualNetworkConfig *); /* Network configuration */
  1159. /**
  1160. * Function to send a frame out to a virtual network port
  1161. *
  1162. * Parameters: (1) node, (2) user ptr, (3) network ID, (4) source MAC,
  1163. * (5) destination MAC, (6) ethertype, (7) VLAN ID, (8) frame data,
  1164. * (9) frame length.
  1165. */
  1166. typedef void (*ZT_VirtualNetworkFrameFunction)(
  1167. ZT_Node *, /* Node */
  1168. void *, /* User ptr */
  1169. void *, /* Thread ptr */
  1170. uint64_t, /* Network ID */
  1171. void **, /* Modifiable network user PTR */
  1172. uint64_t, /* Source MAC */
  1173. uint64_t, /* Destination MAC */
  1174. unsigned int, /* Ethernet type */
  1175. unsigned int, /* VLAN ID (0 for none) */
  1176. const void *, /* Frame data */
  1177. unsigned int); /* Frame length */
  1178. /**
  1179. * Callback for events
  1180. *
  1181. * Events are generated when the node's status changes in a significant way
  1182. * and on certain non-fatal errors and events of interest. The final void
  1183. * parameter points to event meta-data. The type of event meta-data (and
  1184. * whether it is present at all) is event type dependent. See the comments
  1185. * in the definition of ZT_Event.
  1186. */
  1187. typedef void (*ZT_EventCallback)(
  1188. ZT_Node *, /* Node */
  1189. void *, /* User ptr */
  1190. void *, /* Thread ptr */
  1191. enum ZT_Event, /* Event type */
  1192. const void *); /* Event payload (if applicable) */
  1193. /**
  1194. * Callback for storing and/or publishing state information
  1195. *
  1196. * See ZT_StateObjectType docs for information about each state object type
  1197. * and when and if it needs to be persisted.
  1198. *
  1199. * An object of length -1 is sent to indicate that an object should be
  1200. * deleted.
  1201. */
  1202. typedef void (*ZT_StatePutFunction)(
  1203. ZT_Node *, /* Node */
  1204. void *, /* User ptr */
  1205. void *, /* Thread ptr */
  1206. enum ZT_StateObjectType, /* State object type */
  1207. const uint64_t [2], /* State object ID (if applicable) */
  1208. const void *, /* State object data */
  1209. int); /* Length of data or -1 to delete */
  1210. /**
  1211. * Callback for retrieving stored state information
  1212. *
  1213. * This function should return the number of bytes actually stored to the
  1214. * buffer or -1 if the state object was not found or the buffer was too
  1215. * small to store it.
  1216. */
  1217. typedef int (*ZT_StateGetFunction)(
  1218. ZT_Node *, /* Node */
  1219. void *, /* User ptr */
  1220. void *, /* Thread ptr */
  1221. enum ZT_StateObjectType, /* State object type */
  1222. const uint64_t [2], /* State object ID (if applicable) */
  1223. void *, /* Buffer to store state object data */
  1224. unsigned int); /* Length of data buffer in bytes */
  1225. /**
  1226. * Function to send a ZeroTier packet out over the physical wire (L2/L3)
  1227. *
  1228. * Parameters:
  1229. * (1) Node
  1230. * (2) User pointer
  1231. * (3) Local socket or -1 for "all" or "any"
  1232. * (4) Remote address
  1233. * (5) Packet data
  1234. * (6) Packet length
  1235. * (7) Desired IP TTL or 0 to use default
  1236. *
  1237. * If there is only one local socket, the local socket can be ignored.
  1238. * If the local socket is -1, the packet should be sent out from all
  1239. * bound local sockets or a random bound local socket.
  1240. *
  1241. * If TTL is nonzero, packets should have their IP TTL value set to this
  1242. * value if possible. If this is not possible it is acceptable to ignore
  1243. * this value and send anyway with normal or default TTL.
  1244. *
  1245. * The function must return zero on success and may return any error code
  1246. * on failure. Note that success does not (of course) guarantee packet
  1247. * delivery. It only means that the packet appears to have been sent.
  1248. */
  1249. typedef int (*ZT_WirePacketSendFunction)(
  1250. ZT_Node *, /* Node */
  1251. void *, /* User ptr */
  1252. void *, /* Thread ptr */
  1253. int64_t, /* Local socket */
  1254. const struct sockaddr_storage *, /* Remote address */
  1255. const void *, /* Packet data */
  1256. unsigned int, /* Packet length */
  1257. unsigned int); /* TTL or 0 to use default */
  1258. /**
  1259. * Function to check whether a path should be used for ZeroTier traffic
  1260. *
  1261. * Paramters:
  1262. * (1) Node
  1263. * (2) User pointer
  1264. * (3) ZeroTier address or 0 for none/any
  1265. * (4) Local socket or -1 if unknown
  1266. * (5) Remote address
  1267. *
  1268. * This function must return nonzero (true) if the path should be used.
  1269. *
  1270. * If no path check function is specified, ZeroTier will still exclude paths
  1271. * that overlap with ZeroTier-assigned and managed IP address blocks. But the
  1272. * use of a path check function is recommended to ensure that recursion does
  1273. * not occur in cases where addresses are assigned by the OS or managed by
  1274. * an out of band mechanism like DHCP. The path check function should examine
  1275. * all configured ZeroTier interfaces and check to ensure that the supplied
  1276. * addresses will not result in ZeroTier traffic being sent over a ZeroTier
  1277. * interface (recursion).
  1278. */
  1279. typedef int (*ZT_PathCheckFunction)(
  1280. ZT_Node *, /* Node */
  1281. void *, /* User ptr */
  1282. void *, /* Thread ptr */
  1283. uint64_t, /* ZeroTier address */
  1284. int64_t, /* Local socket or -1 if unknown */
  1285. const struct sockaddr_storage *); /* Remote address */
  1286. /**
  1287. * Function to get physical addresses for ZeroTier peers
  1288. *
  1289. * Parameters:
  1290. * (1) Node
  1291. * (2) User pointer
  1292. * (3) ZeroTier address (least significant 40 bits)
  1293. * (4) Desried address family or -1 for any
  1294. * (5) Buffer to fill with result
  1295. *
  1296. * If provided this function will be occasionally called to get physical
  1297. * addresses that might be tried to reach a ZeroTier address. It must
  1298. * return a nonzero (true) value if the result buffer has been filled
  1299. * with an address.
  1300. */
  1301. typedef int (*ZT_PathLookupFunction)(
  1302. ZT_Node *, /* Node */
  1303. void *, /* User ptr */
  1304. void *, /* Thread ptr */
  1305. uint64_t, /* ZeroTier address (40 bits) */
  1306. int, /* Desired ss_family or -1 for any */
  1307. struct sockaddr_storage *); /* Result buffer */
  1308. /****************************************************************************/
  1309. /* C Node API */
  1310. /****************************************************************************/
  1311. /**
  1312. * Structure for configuring ZeroTier core callback functions
  1313. */
  1314. struct ZT_Node_Callbacks
  1315. {
  1316. /**
  1317. * Struct version -- must currently be 0
  1318. */
  1319. long version;
  1320. /**
  1321. * REQUIRED: Function to store and/or replicate state objects
  1322. */
  1323. ZT_StatePutFunction statePutFunction;
  1324. /**
  1325. * REQUIRED: Function to retrieve state objects from an object store
  1326. */
  1327. ZT_StateGetFunction stateGetFunction;
  1328. /**
  1329. * REQUIRED: Function to send packets over the physical wire
  1330. */
  1331. ZT_WirePacketSendFunction wirePacketSendFunction;
  1332. /**
  1333. * REQUIRED: Function to inject frames into a virtual network's TAP
  1334. */
  1335. ZT_VirtualNetworkFrameFunction virtualNetworkFrameFunction;
  1336. /**
  1337. * REQUIRED: Function to be called when virtual networks are configured or changed
  1338. */
  1339. ZT_VirtualNetworkConfigFunction virtualNetworkConfigFunction;
  1340. /**
  1341. * REQUIRED: Function to be called to notify external code of important events
  1342. */
  1343. ZT_EventCallback eventCallback;
  1344. /**
  1345. * OPTIONAL: Function to check whether a given physical path should be used
  1346. */
  1347. ZT_PathCheckFunction pathCheckFunction;
  1348. /**
  1349. * OPTIONAL: Function to get hints to physical paths to ZeroTier addresses
  1350. */
  1351. ZT_PathLookupFunction pathLookupFunction;
  1352. };
  1353. /**
  1354. * Create a new ZeroTier node
  1355. *
  1356. * This will attempt to load its identity via the state get function in the
  1357. * callback struct. If that fails it will generate a new identity and store
  1358. * it. Identity generation can take anywhere from a few hundred milliseconds
  1359. * to a few seconds depending on your CPU speed.
  1360. *
  1361. * @param node Result: pointer is set to new node instance on success
  1362. * @param uptr User pointer to pass to functions/callbacks
  1363. * @param tptr Thread pointer to pass to functions/callbacks resulting from this call
  1364. * @param callbacks Callback function configuration
  1365. * @param now Current clock in milliseconds
  1366. * @return OK (0) or error code if a fatal error condition has occurred
  1367. */
  1368. ZT_SDK_API enum ZT_ResultCode ZT_Node_new(ZT_Node **node,void *uptr,void *tptr,const struct ZT_Node_Callbacks *callbacks,uint64_t now);
  1369. /**
  1370. * Delete a node and free all resources it consumes
  1371. *
  1372. * If you are using multiple threads, all other threads must be shut down
  1373. * first. This can crash if processXXX() methods are in progress.
  1374. *
  1375. * @param node Node to delete
  1376. */
  1377. ZT_SDK_API void ZT_Node_delete(ZT_Node *node);
  1378. /**
  1379. * Process a packet received from the physical wire
  1380. *
  1381. * @param node Node instance
  1382. * @param tptr Thread pointer to pass to functions/callbacks resulting from this call
  1383. * @param now Current clock in milliseconds
  1384. * @param localSocket Local socket (you can use 0 if only one local socket is bound and ignore this)
  1385. * @param remoteAddress Origin of packet
  1386. * @param packetData Packet data
  1387. * @param packetLength Packet length
  1388. * @param nextBackgroundTaskDeadline Value/result: set to deadline for next call to processBackgroundTasks()
  1389. * @return OK (0) or error code if a fatal error condition has occurred
  1390. */
  1391. ZT_SDK_API enum ZT_ResultCode ZT_Node_processWirePacket(
  1392. ZT_Node *node,
  1393. void *tptr,
  1394. uint64_t now,
  1395. int64_t localSocket,
  1396. const struct sockaddr_storage *remoteAddress,
  1397. const void *packetData,
  1398. unsigned int packetLength,
  1399. volatile uint64_t *nextBackgroundTaskDeadline);
  1400. /**
  1401. * Process a frame from a virtual network port (tap)
  1402. *
  1403. * @param node Node instance
  1404. * @param tptr Thread pointer to pass to functions/callbacks resulting from this call
  1405. * @param now Current clock in milliseconds
  1406. * @param nwid ZeroTier 64-bit virtual network ID
  1407. * @param sourceMac Source MAC address (least significant 48 bits)
  1408. * @param destMac Destination MAC address (least significant 48 bits)
  1409. * @param etherType 16-bit Ethernet frame type
  1410. * @param vlanId 10-bit VLAN ID or 0 if none
  1411. * @param frameData Frame payload data
  1412. * @param frameLength Frame payload length
  1413. * @param nextBackgroundTaskDeadline Value/result: set to deadline for next call to processBackgroundTasks()
  1414. * @return OK (0) or error code if a fatal error condition has occurred
  1415. */
  1416. ZT_SDK_API enum ZT_ResultCode ZT_Node_processVirtualNetworkFrame(
  1417. ZT_Node *node,
  1418. void *tptr,
  1419. uint64_t now,
  1420. uint64_t nwid,
  1421. uint64_t sourceMac,
  1422. uint64_t destMac,
  1423. unsigned int etherType,
  1424. unsigned int vlanId,
  1425. const void *frameData,
  1426. unsigned int frameLength,
  1427. volatile uint64_t *nextBackgroundTaskDeadline);
  1428. /**
  1429. * Perform periodic background operations
  1430. *
  1431. * @param node Node instance
  1432. * @param tptr Thread pointer to pass to functions/callbacks resulting from this call
  1433. * @param now Current clock in milliseconds
  1434. * @param nextBackgroundTaskDeadline Value/result: set to deadline for next call to processBackgroundTasks()
  1435. * @return OK (0) or error code if a fatal error condition has occurred
  1436. */
  1437. ZT_SDK_API enum ZT_ResultCode ZT_Node_processBackgroundTasks(ZT_Node *node,void *tptr,uint64_t now,volatile uint64_t *nextBackgroundTaskDeadline);
  1438. /**
  1439. * Join a network
  1440. *
  1441. * This may generate calls to the port config callback before it returns,
  1442. * or these may be deffered if a netconf is not available yet.
  1443. *
  1444. * If we are already a member of the network, nothing is done and OK is
  1445. * returned.
  1446. *
  1447. * @param node Node instance
  1448. * @param nwid 64-bit ZeroTier network ID
  1449. * @param uptr An arbitrary pointer to associate with this network (default: NULL)
  1450. * @return OK (0) or error code if a fatal error condition has occurred
  1451. */
  1452. ZT_SDK_API enum ZT_ResultCode ZT_Node_join(ZT_Node *node,uint64_t nwid,void *uptr,void *tptr);
  1453. /**
  1454. * Leave a network
  1455. *
  1456. * If a port has been configured for this network this will generate a call
  1457. * to the port config callback with a NULL second parameter to indicate that
  1458. * the port is now deleted.
  1459. *
  1460. * The uptr parameter is optional and is NULL by default. If it is not NULL,
  1461. * the pointer it points to is set to this network's uptr on success.
  1462. *
  1463. * @param node Node instance
  1464. * @param nwid 64-bit network ID
  1465. * @param uptr Target pointer is set to uptr (if not NULL)
  1466. * @return OK (0) or error code if a fatal error condition has occurred
  1467. */
  1468. ZT_SDK_API enum ZT_ResultCode ZT_Node_leave(ZT_Node *node,uint64_t nwid,void **uptr,void *tptr);
  1469. /**
  1470. * Subscribe to an Ethernet multicast group
  1471. *
  1472. * ADI stands for additional distinguishing information. This defaults to zero
  1473. * and is rarely used. Right now its only use is to enable IPv4 ARP to scale,
  1474. * and this must be done.
  1475. *
  1476. * For IPv4 ARP, the implementation must subscribe to 0xffffffffffff (the
  1477. * broadcast address) but with an ADI equal to each IPv4 address in host
  1478. * byte order. This converts ARP from a non-scalable broadcast protocol to
  1479. * a scalable multicast protocol with perfect address specificity.
  1480. *
  1481. * If this is not done, ARP will not work reliably.
  1482. *
  1483. * Multiple calls to subscribe to the same multicast address will have no
  1484. * effect. It is perfectly safe to do this.
  1485. *
  1486. * This does not generate an update call to networkConfigCallback().
  1487. *
  1488. * @param node Node instance
  1489. * @param tptr Thread pointer to pass to functions/callbacks resulting from this call
  1490. * @param nwid 64-bit network ID
  1491. * @param multicastGroup Ethernet multicast or broadcast MAC (least significant 48 bits)
  1492. * @param multicastAdi Multicast ADI (least significant 32 bits only, use 0 if not needed)
  1493. * @return OK (0) or error code if a fatal error condition has occurred
  1494. */
  1495. ZT_SDK_API enum ZT_ResultCode ZT_Node_multicastSubscribe(ZT_Node *node,void *tptr,uint64_t nwid,uint64_t multicastGroup,unsigned long multicastAdi);
  1496. /**
  1497. * Unsubscribe from an Ethernet multicast group (or all groups)
  1498. *
  1499. * If multicastGroup is zero (0), this will unsubscribe from all groups. If
  1500. * you are not subscribed to a group this has no effect.
  1501. *
  1502. * This does not generate an update call to networkConfigCallback().
  1503. *
  1504. * @param node Node instance
  1505. * @param nwid 64-bit network ID
  1506. * @param multicastGroup Ethernet multicast or broadcast MAC (least significant 48 bits)
  1507. * @param multicastAdi Multicast ADI (least significant 32 bits only, use 0 if not needed)
  1508. * @return OK (0) or error code if a fatal error condition has occurred
  1509. */
  1510. ZT_SDK_API enum ZT_ResultCode ZT_Node_multicastUnsubscribe(ZT_Node *node,uint64_t nwid,uint64_t multicastGroup,unsigned long multicastAdi);
  1511. /**
  1512. * Add or update a moon
  1513. *
  1514. * Moons are persisted in the data store in moons.d/, so this can persist
  1515. * across invocations if the contents of moon.d are scanned and orbit is
  1516. * called for each on startup.
  1517. *
  1518. * @param node Node instance
  1519. * @param tptr Thread pointer to pass to functions/callbacks resulting from this call
  1520. * @param moonWorldId Moon's world ID
  1521. * @param moonSeed If non-zero, the ZeroTier address of any member of the moon to query for moon definition
  1522. * @param len Length of moonWorld in bytes
  1523. * @return Error if moon was invalid or failed to be added
  1524. */
  1525. ZT_SDK_API enum ZT_ResultCode ZT_Node_orbit(ZT_Node *node,void *tptr,uint64_t moonWorldId,uint64_t moonSeed);
  1526. /**
  1527. * Remove a moon (does nothing if not present)
  1528. *
  1529. * @param node Node instance
  1530. * @param tptr Thread pointer to pass to functions/callbacks resulting from this call
  1531. * @param moonWorldId World ID of moon to remove
  1532. * @return Error if anything bad happened
  1533. */
  1534. ZT_SDK_API enum ZT_ResultCode ZT_Node_deorbit(ZT_Node *node,void *tptr,uint64_t moonWorldId);
  1535. /**
  1536. * Get this node's 40-bit ZeroTier address
  1537. *
  1538. * @param node Node instance
  1539. * @return ZeroTier address (least significant 40 bits of 64-bit int)
  1540. */
  1541. ZT_SDK_API uint64_t ZT_Node_address(ZT_Node *node);
  1542. /**
  1543. * Get the status of this node
  1544. *
  1545. * @param node Node instance
  1546. * @param status Buffer to fill with current node status
  1547. */
  1548. ZT_SDK_API void ZT_Node_status(ZT_Node *node,ZT_NodeStatus *status);
  1549. /**
  1550. * Get a list of known peer nodes
  1551. *
  1552. * The pointer returned here must be freed with freeQueryResult()
  1553. * when you are done with it.
  1554. *
  1555. * @param node Node instance
  1556. * @return List of known peers or NULL on failure
  1557. */
  1558. ZT_SDK_API ZT_PeerList *ZT_Node_peers(ZT_Node *node);
  1559. /**
  1560. * Get the status of a virtual network
  1561. *
  1562. * The pointer returned here must be freed with freeQueryResult()
  1563. * when you are done with it.
  1564. *
  1565. * @param node Node instance
  1566. * @param nwid 64-bit network ID
  1567. * @return Network configuration or NULL if we are not a member of this network
  1568. */
  1569. ZT_SDK_API ZT_VirtualNetworkConfig *ZT_Node_networkConfig(ZT_Node *node,uint64_t nwid);
  1570. /**
  1571. * Enumerate and get status of all networks
  1572. *
  1573. * @param node Node instance
  1574. * @return List of networks or NULL on failure
  1575. */
  1576. ZT_SDK_API ZT_VirtualNetworkList *ZT_Node_networks(ZT_Node *node);
  1577. /**
  1578. * Free a query result buffer
  1579. *
  1580. * Use this to free the return values of listNetworks(), listPeers(), etc.
  1581. *
  1582. * @param node Node instance
  1583. * @param qr Query result buffer
  1584. */
  1585. ZT_SDK_API void ZT_Node_freeQueryResult(ZT_Node *node,void *qr);
  1586. /**
  1587. * Add a local interface address
  1588. *
  1589. * This is used to make ZeroTier aware of those local interface addresses
  1590. * that you wish to use for ZeroTier communication. This is optional, and if
  1591. * it is not used ZeroTier will rely upon upstream peers (and roots) to
  1592. * perform empirical address discovery and NAT traversal. But the use of this
  1593. * method is recommended as it improves peer discovery when both peers are
  1594. * on the same LAN.
  1595. *
  1596. * It is the responsibility of the caller to take care that these are never
  1597. * ZeroTier interface addresses, whether these are assigned by ZeroTier or
  1598. * are otherwise assigned to an interface managed by this ZeroTier instance.
  1599. * This can cause recursion or other undesirable behavior.
  1600. *
  1601. * This returns a boolean indicating whether or not the address was
  1602. * accepted. ZeroTier will only communicate over certain address types
  1603. * and (for IP) address classes.
  1604. *
  1605. * @param addr Local interface address
  1606. * @return Boolean: non-zero if address was accepted and added
  1607. */
  1608. ZT_SDK_API int ZT_Node_addLocalInterfaceAddress(ZT_Node *node,const struct sockaddr_storage *addr);
  1609. /**
  1610. * Clear local interface addresses
  1611. */
  1612. ZT_SDK_API void ZT_Node_clearLocalInterfaceAddresses(ZT_Node *node);
  1613. /**
  1614. * Send a VERB_USER_MESSAGE to another ZeroTier node
  1615. *
  1616. * There is no delivery guarantee here. Failure can occur if the message is
  1617. * too large or if dest is not a valid ZeroTier address.
  1618. *
  1619. * @param node Node instance
  1620. * @param tptr Thread pointer to pass to functions/callbacks resulting from this call
  1621. * @param dest Destination ZeroTier address
  1622. * @param typeId VERB_USER_MESSAGE type ID
  1623. * @param data Payload data to attach to user message
  1624. * @param len Length of data in bytes
  1625. * @return Boolean: non-zero on success, zero on failure
  1626. */
  1627. ZT_SDK_API int ZT_Node_sendUserMessage(ZT_Node *node,void *tptr,uint64_t dest,uint64_t typeId,const void *data,unsigned int len);
  1628. /**
  1629. * Set a network configuration master instance for this node
  1630. *
  1631. * Normal nodes should not need to use this. This is for nodes with
  1632. * special compiled-in support for acting as network configuration
  1633. * masters / controllers.
  1634. *
  1635. * The supplied instance must be a C++ object that inherits from the
  1636. * NetworkConfigMaster base class in node/. No type checking is performed,
  1637. * so a pointer to anything else will result in a crash.
  1638. *
  1639. * @param node ZertTier One node
  1640. * @param networkConfigMasterInstance Instance of NetworkConfigMaster C++ class or NULL to disable
  1641. * @return OK (0) or error code if a fatal error condition has occurred
  1642. */
  1643. ZT_SDK_API void ZT_Node_setNetconfMaster(ZT_Node *node,void *networkConfigMasterInstance);
  1644. /**
  1645. * Set trusted paths
  1646. *
  1647. * A trusted path is a physical network (network/bits) over which both
  1648. * encryption and authentication can be skipped to improve performance.
  1649. * Each trusted path must have a non-zero unique ID that is the same across
  1650. * all participating nodes.
  1651. *
  1652. * We don't recommend using trusted paths at all unless you really *need*
  1653. * near-bare-metal performance. Even on a LAN authentication and encryption
  1654. * are never a bad thing, and anything that introduces an "escape hatch"
  1655. * for encryption should be treated with the utmost care.
  1656. *
  1657. * Calling with NULL pointers for networks and ids and a count of zero clears
  1658. * all trusted paths.
  1659. *
  1660. * @param node Node instance
  1661. * @param networks Array of [count] networks
  1662. * @param ids Array of [count] corresponding non-zero path IDs (zero path IDs are ignored)
  1663. * @param count Number of trusted paths-- values greater than ZT_MAX_TRUSTED_PATHS are clipped
  1664. */
  1665. ZT_SDK_API void ZT_Node_setTrustedPaths(ZT_Node *node,const struct sockaddr_storage *networks,const uint64_t *ids,unsigned int count);
  1666. /**
  1667. * Get ZeroTier One version
  1668. *
  1669. * @param major Result: major version
  1670. * @param minor Result: minor version
  1671. * @param revision Result: revision
  1672. */
  1673. ZT_SDK_API void ZT_version(int *major,int *minor,int *revision);
  1674. #ifdef __cplusplus
  1675. }
  1676. #endif
  1677. #endif