/* * Copyright (c)2019 ZeroTier, Inc. * * Use of this software is governed by the Business Source License included * in the LICENSE.TXT file in the project's root directory. * * Change Date: 2025-01-01 * * On the date above, in accordance with the Business Source License, use * of this software will be governed by version 2.0 of the Apache License. */ /****/ /* * This defines the external C API for ZeroTier's core network virtualization * engine. */ #ifndef ZT_ZEROTIER_API_H #define ZT_ZEROTIER_API_H #include // For the struct sockaddr_storage structure #if defined(_WIN32) || defined(_WIN64) #include #include #include #else /* not Windows */ #include #include #include #include #endif /* Windows or not */ #if defined (_MSC_VER) #ifdef ZT_EXPORT #define ZT_SDK_API __declspec(dllexport) #else #define ZT_SDK_API __declspec(dllimport) #if !defined(ZT_SDK) #ifdef _DEBUG #ifdef _WIN64 #pragma comment(lib, "ZeroTierOne_x64d.lib") #else #pragma comment(lib, "ZeroTierOne_x86d.lib") #endif #else #ifdef _WIN64 #pragma comment(lib, "ZeroTierOne_x64.lib") #else #pragma comment(lib, "ZeroTierOne_x86.lib") #endif #endif #endif #endif #else #define ZT_SDK_API #endif #ifdef __cplusplus extern "C" { #endif /****************************************************************************/ /* Core constants */ /****************************************************************************/ /** * Default UDP port for devices running a ZeroTier endpoint */ #define ZT_DEFAULT_PORT 9993 /** * Minimum MTU, which is the minimum allowed by IPv6 and several specs */ #define ZT_MIN_MTU 1280 /** * Maximum MTU for ZeroTier virtual networks */ #define ZT_MAX_MTU 10000 /** * Minimum UDP payload size allowed */ #define ZT_MIN_PHYSMTU 1400 /** * Default UDP payload size (physical path MTU) not including UDP and IP overhead * * This is small enough for PPPoE and for Google Cloud's bizarrely tiny MTUs. * A 2800 byte payload still fits into two packets, so this should not impact * real world throughput at all vs the previous default of 1444. */ #define ZT_DEFAULT_PHYSMTU 1432 /** * Maximum physical UDP payload */ #define ZT_MAX_PHYSPAYLOAD 10100 /** * Headroom for max physical MTU */ #define ZT_MAX_HEADROOM 224 /** * Maximum payload MTU for UDP packets */ #define ZT_MAX_PHYSMTU (ZT_MAX_PHYSPAYLOAD + ZT_MAX_HEADROOM) /** * Maximum size of a remote trace message's serialized Dictionary */ #define ZT_MAX_REMOTE_TRACE_SIZE 10000 /** * Maximum length of network short name */ #define ZT_MAX_NETWORK_SHORT_NAME_LENGTH 127 /** * Maximum number of pushed routes on a network */ #define ZT_MAX_NETWORK_ROUTES 32 /** * Maximum number of statically assigned IP addresses per network endpoint using ZT address management (not DHCP) */ #define ZT_MAX_ZT_ASSIGNED_ADDRESSES 16 /** * Maximum number of "specialists" on a network -- bridges, relays, etc. */ #define ZT_MAX_NETWORK_SPECIALISTS 256 /** * Maximum number of multicast group subscriptions per network */ #define ZT_MAX_NETWORK_MULTICAST_SUBSCRIPTIONS 4096 /** * Rules engine revision ID, which specifies rules engine capabilities */ #define ZT_RULES_ENGINE_REVISION 1 /** * Maximum number of base (non-capability) network rules */ #define ZT_MAX_NETWORK_RULES 1024 /** * Maximum number of per-member capabilities per network */ #define ZT_MAX_NETWORK_CAPABILITIES 128 /** * Maximum number of per-member tags per network */ #define ZT_MAX_NETWORK_TAGS 128 /** * Maximum number of direct network paths to a given peer */ #define ZT_MAX_PEER_NETWORK_PATHS 16 /** * Maximum number of path configurations that can be set */ #define ZT_MAX_CONFIGURABLE_PATHS 32 /** * Maximum number of rules per capability */ #define ZT_MAX_CAPABILITY_RULES 64 /** * Maximum number of certificates of ownership to assign to a single network member */ #define ZT_MAX_CERTIFICATES_OF_OWNERSHIP 4 /** * Global maximum length for capability chain of custody (including initial issue) */ #define ZT_MAX_CAPABILITY_CUSTODY_CHAIN_LENGTH 7 /** * Maximum number of multicast groups a device / network interface can be subscribed to at once */ #define ZT_MAX_MULTICAST_SUBSCRIPTIONS 1024 /** * Maximum value for link quality (min is 0) */ #define ZT_PATH_LINK_QUALITY_MAX 0xff /** * Maximum number of DNS servers per domain */ #define ZT_MAX_DNS_SERVERS 4 /** * Packet characteristics flag: packet direction, 1 if inbound 0 if outbound */ #define ZT_RULE_PACKET_CHARACTERISTICS_INBOUND 0x8000000000000000ULL /** * Packet characteristics flag: multicast or broadcast destination MAC */ #define ZT_RULE_PACKET_CHARACTERISTICS_MULTICAST 0x4000000000000000ULL /** * Packet characteristics flag: broadcast destination MAC */ #define ZT_RULE_PACKET_CHARACTERISTICS_BROADCAST 0x2000000000000000ULL /** * Packet characteristics flag: sending IP address has a certificate of ownership */ #define ZT_RULE_PACKET_CHARACTERISTICS_SENDER_IP_AUTHENTICATED 0x1000000000000000ULL /** * Packet characteristics flag: sending MAC address has a certificate of ownership */ #define ZT_RULE_PACKET_CHARACTERISTICS_SENDER_MAC_AUTHENTICATED 0x0800000000000000ULL /** * Packet characteristics flag: TCP left-most reserved bit */ #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_RESERVED_0 0x0000000000000800ULL /** * Packet characteristics flag: TCP middle reserved bit */ #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_RESERVED_1 0x0000000000000400ULL /** * Packet characteristics flag: TCP right-most reserved bit */ #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_RESERVED_2 0x0000000000000200ULL /** * Packet characteristics flag: TCP NS flag */ #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_NS 0x0000000000000100ULL /** * Packet characteristics flag: TCP CWR flag */ #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_CWR 0x0000000000000080ULL /** * Packet characteristics flag: TCP ECE flag */ #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_ECE 0x0000000000000040ULL /** * Packet characteristics flag: TCP URG flag */ #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_URG 0x0000000000000020ULL /** * Packet characteristics flag: TCP ACK flag */ #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_ACK 0x0000000000000010ULL /** * Packet characteristics flag: TCP PSH flag */ #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_PSH 0x0000000000000008ULL /** * Packet characteristics flag: TCP RST flag */ #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_RST 0x0000000000000004ULL /** * Packet characteristics flag: TCP SYN flag */ #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_SYN 0x0000000000000002ULL /** * Packet characteristics flag: TCP FIN flag */ #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_FIN 0x0000000000000001ULL // Fields in remote trace dictionaries #define ZT_REMOTE_TRACE_FIELD__EVENT "event" #define ZT_REMOTE_TRACE_FIELD__NODE_ID "nodeId" #define ZT_REMOTE_TRACE_FIELD__PACKET_ID "packetId" #define ZT_REMOTE_TRACE_FIELD__PACKET_VERB "packetVerb" #define ZT_REMOTE_TRACE_FIELD__PACKET_TRUSTED_PATH_ID "packetTrustedPathId" #define ZT_REMOTE_TRACE_FIELD__PACKET_TRUSTED_PATH_APPROVED "packetTrustedPathApproved" #define ZT_REMOTE_TRACE_FIELD__PACKET_HOPS "packetHops" #define ZT_REMOTE_TRACE_FIELD__REMOTE_ZTADDR "remoteZtAddr" #define ZT_REMOTE_TRACE_FIELD__REMOTE_PHYADDR "remotePhyAddr" #define ZT_REMOTE_TRACE_FIELD__LOCAL_ZTADDR "localZtAddr" #define ZT_REMOTE_TRACE_FIELD__LOCAL_PHYADDR "localPhyAddr" #define ZT_REMOTE_TRACE_FIELD__LOCAL_SOCKET "localSocket" #define ZT_REMOTE_TRACE_FIELD__IP_SCOPE "phyAddrIpScope" #define ZT_REMOTE_TRACE_FIELD__NETWORK_ID "networkId" #define ZT_REMOTE_TRACE_FIELD__SOURCE_ZTADDR "sourceZtAddr" #define ZT_REMOTE_TRACE_FIELD__DEST_ZTADDR "destZtAddr" #define ZT_REMOTE_TRACE_FIELD__SOURCE_MAC "sourceMac" #define ZT_REMOTE_TRACE_FIELD__DEST_MAC "destMac" #define ZT_REMOTE_TRACE_FIELD__ETHERTYPE "etherType" #define ZT_REMOTE_TRACE_FIELD__VLAN_ID "vlanId" #define ZT_REMOTE_TRACE_FIELD__FRAME_LENGTH "frameLength" #define ZT_REMOTE_TRACE_FIELD__FRAME_DATA "frameData" #define ZT_REMOTE_TRACE_FIELD__FILTER_FLAG_NOTEE "filterNoTee" #define ZT_REMOTE_TRACE_FIELD__FILTER_FLAG_INBOUND "filterInbound" #define ZT_REMOTE_TRACE_FIELD__FILTER_RESULT "filterResult" #define ZT_REMOTE_TRACE_FIELD__FILTER_BASE_RULE_LOG "filterBaseRuleLog" #define ZT_REMOTE_TRACE_FIELD__FILTER_CAP_RULE_LOG "filterCapRuleLog" #define ZT_REMOTE_TRACE_FIELD__FILTER_CAP_ID "filterMatchingCapId" #define ZT_REMOTE_TRACE_FIELD__CREDENTIAL_TYPE "credType" #define ZT_REMOTE_TRACE_FIELD__CREDENTIAL_ID "credId" #define ZT_REMOTE_TRACE_FIELD__CREDENTIAL_TIMESTAMP "credTs" #define ZT_REMOTE_TRACE_FIELD__CREDENTIAL_INFO "credInfo" #define ZT_REMOTE_TRACE_FIELD__CREDENTIAL_ISSUED_TO "credIssuedTo" #define ZT_REMOTE_TRACE_FIELD__CREDENTIAL_REVOCATION_TARGET "credRevocationTarget" #define ZT_REMOTE_TRACE_FIELD__REASON "reason" #define ZT_REMOTE_TRACE_FIELD__NETWORK_CONTROLLER_ID "networkControllerId" // Event types in remote traces #define ZT_REMOTE_TRACE_EVENT__RESETTING_PATHS_IN_SCOPE 0x1000 #define ZT_REMOTE_TRACE_EVENT__PEER_CONFIRMING_UNKNOWN_PATH 0x1001 #define ZT_REMOTE_TRACE_EVENT__PEER_LEARNED_NEW_PATH 0x1002 #define ZT_REMOTE_TRACE_EVENT__PEER_REDIRECTED 0x1003 #define ZT_REMOTE_TRACE_EVENT__PACKET_MAC_FAILURE 0x1004 #define ZT_REMOTE_TRACE_EVENT__PACKET_INVALID 0x1005 #define ZT_REMOTE_TRACE_EVENT__DROPPED_HELLO 0x1006 #define ZT_REMOTE_TRACE_EVENT__OUTGOING_NETWORK_FRAME_DROPPED 0x2000 #define ZT_REMOTE_TRACE_EVENT__INCOMING_NETWORK_ACCESS_DENIED 0x2001 #define ZT_REMOTE_TRACE_EVENT__INCOMING_NETWORK_FRAME_DROPPED 0x2002 #define ZT_REMOTE_TRACE_EVENT__CREDENTIAL_REJECTED 0x2003 #define ZT_REMOTE_TRACE_EVENT__CREDENTIAL_ACCEPTED 0x2004 #define ZT_REMOTE_TRACE_EVENT__NETWORK_CONFIG_REQUEST_SENT 0x2005 #define ZT_REMOTE_TRACE_EVENT__NETWORK_FILTER_TRACE 0x2006 // Event types in remote traces in hex string form #define ZT_REMOTE_TRACE_EVENT__RESETTING_PATHS_IN_SCOPE_S "1000" #define ZT_REMOTE_TRACE_EVENT__PEER_CONFIRMING_UNKNOWN_PATH_S "1001" #define ZT_REMOTE_TRACE_EVENT__PEER_LEARNED_NEW_PATH_S "1002" #define ZT_REMOTE_TRACE_EVENT__PEER_REDIRECTED_S "1003" #define ZT_REMOTE_TRACE_EVENT__PACKET_MAC_FAILURE_S "1004" #define ZT_REMOTE_TRACE_EVENT__PACKET_INVALID_S "1005" #define ZT_REMOTE_TRACE_EVENT__DROPPED_HELLO_S "1006" #define ZT_REMOTE_TRACE_EVENT__OUTGOING_NETWORK_FRAME_DROPPED_S "2000" #define ZT_REMOTE_TRACE_EVENT__INCOMING_NETWORK_ACCESS_DENIED_S "2001" #define ZT_REMOTE_TRACE_EVENT__INCOMING_NETWORK_FRAME_DROPPED_S "2002" #define ZT_REMOTE_TRACE_EVENT__CREDENTIAL_REJECTED_S "2003" #define ZT_REMOTE_TRACE_EVENT__CREDENTIAL_ACCEPTED_S "2004" #define ZT_REMOTE_TRACE_EVENT__NETWORK_CONFIG_REQUEST_SENT_S "2005" #define ZT_REMOTE_TRACE_EVENT__NETWORK_FILTER_TRACE_S "2006" /****************************************************************************/ /* Structures and other types */ /****************************************************************************/ /** * Function return code: OK (0) or error results * * Use ZT_ResultCode_isFatal() to check for a fatal error. If a fatal error * occurs, the node should be considered to not be working correctly. These * indicate serious problems like an inaccessible data store or a compile * problem. */ enum ZT_ResultCode { /** * Operation completed normally */ ZT_RESULT_OK = 0, /** * Call produced no error but no action was taken */ ZT_RESULT_OK_IGNORED = 1, // Fatal errors (>100, <1000) /** * Ran out of memory */ ZT_RESULT_FATAL_ERROR_OUT_OF_MEMORY = 100, /** * Data store is not writable or has failed */ ZT_RESULT_FATAL_ERROR_DATA_STORE_FAILED = 101, /** * Internal error (e.g. unexpected exception indicating bug or build problem) */ ZT_RESULT_FATAL_ERROR_INTERNAL = 102, // Non-fatal errors (>1000) /** * Network ID not valid */ ZT_RESULT_ERROR_NETWORK_NOT_FOUND = 1000, /** * The requested operation is not supported on this version or build */ ZT_RESULT_ERROR_UNSUPPORTED_OPERATION = 1001, /** * The requested operation was given a bad parameter or was called in an invalid state */ ZT_RESULT_ERROR_BAD_PARAMETER = 1002 }; /** * @param x Result code * @return True if result code indicates a fatal error */ #define ZT_ResultCode_isFatal(x) ((((int)(x)) >= 100)&&(((int)(x)) < 1000)) /** * Multipath bonding policy */ enum ZT_MultipathBondingPolicy { /** * Normal operation. No fault tolerance, no load balancing */ ZT_BONDING_POLICY_NONE = 0, /** * Sends traffic out on only one path at a time. Configurable immediate * fail-over. */ ZT_BONDING_POLICY_ACTIVE_BACKUP = 1, /** * Sends traffic out on all paths */ ZT_BONDING_POLICY_BROADCAST = 2, /** * Stripes packets across all paths */ ZT_BONDING_POLICY_BALANCE_RR = 3, /** * Packets destined for specific peers will always be sent over the same * path. */ ZT_BONDING_POLICY_BALANCE_XOR = 4, /** * Balances flows among all paths according to path performance */ ZT_BONDING_POLICY_BALANCE_AWARE = 5 }; /** * Multipath active re-selection policy (linkSelectMethod) */ enum ZT_MultipathLinkSelectMethod { /** * Primary link regains status as active link whenever it comes back up * (default when links are explicitly specified) */ ZT_MULTIPATH_RESELECTION_POLICY_ALWAYS = 0, /** * Primary link regains status as active link when it comes back up and * (if) it is better than the currently-active link. */ ZT_MULTIPATH_RESELECTION_POLICY_BETTER = 1, /** * Primary link regains status as active link only if the currently-active * link fails. */ ZT_MULTIPATH_RESELECTION_POLICY_FAILURE = 2, /** * The primary link can change if a superior path is detected. * (default if user provides no fail-over guidance) */ ZT_MULTIPATH_RESELECTION_POLICY_OPTIMIZE = 3 }; /** * Mode of multipath link interface */ enum ZT_MultipathLinkMode { ZT_MULTIPATH_SLAVE_MODE_PRIMARY = 0, ZT_MULTIPATH_SLAVE_MODE_SPARE = 1 }; /** * Strategy for path monitoring */ enum ZT_MultipathMonitorStrategy { /** * Use bonding policy's default strategy */ ZT_MULTIPATH_SLAVE_MONITOR_STRATEGY_DEFAULT = 0, /** * Does not actively send probes to judge aliveness, will rely * on conventional traffic and summary statistics. */ ZT_MULTIPATH_SLAVE_MONITOR_STRATEGY_PASSIVE = 1, /** * Sends probes at a constant rate to judge aliveness. */ ZT_MULTIPATH_SLAVE_MONITOR_STRATEGY_ACTIVE = 2, /** * Sends probes at varying rates which correlate to native * traffic loads to judge aliveness. */ ZT_MULTIPATH_SLAVE_MONITOR_STRATEGY_DYNAMIC = 3 }; /** * Strategy for re-balancing protocol flows */ enum ZT_MultipathFlowRebalanceStrategy { /** * Flows will only be re-balanced among links during * assignment or failover. This minimizes the possibility * of sequence reordering and is thus the default setting. */ ZT_MULTIPATH_FLOW_REBALANCE_STRATEGY_PASSIVE = 0, /** * Flows that are active may be re-assigned to a new more * suitable link if it can be done without disrupting the flow. * This setting can sometimes cause sequence re-ordering. */ ZT_MULTIPATH_FLOW_REBALANCE_STRATEGY_OPPORTUNISTIC = 0, /** * Flows will be continuously re-assigned the most suitable link * in order to maximize "balance". This can often cause sequence * reordering and is thus only reccomended for protocols like UDP. */ ZT_MULTIPATH_FLOW_REBALANCE_STRATEGY_AGGRESSIVE = 2 }; /** * Indices for the path quality weight vector */ enum ZT_MultipathQualityWeightIndex { ZT_QOS_LAT_IDX, ZT_QOS_LTM_IDX, ZT_QOS_PDV_IDX, ZT_QOS_PLR_IDX, ZT_QOS_PER_IDX, ZT_QOS_THR_IDX, ZT_QOS_THM_IDX, ZT_QOS_THV_IDX, ZT_QOS_AGE_IDX, ZT_QOS_SCP_IDX, ZT_QOS_WEIGHT_SIZE }; /** * Status codes sent to status update callback when things happen */ enum ZT_Event { /** * Node has been initialized * * This is the first event generated, and is always sent. It may occur * before Node's constructor returns. * * Meta-data: none */ ZT_EVENT_UP = 0, /** * Node is offline -- network does not seem to be reachable by any available strategy * * Meta-data: none */ ZT_EVENT_OFFLINE = 1, /** * Node is online -- at least one upstream node appears reachable * * Meta-data: none */ ZT_EVENT_ONLINE = 2, /** * Node is shutting down * * This is generated within Node's destructor when it is being shut down. * It's done for convenience, since cleaning up other state in the event * handler may appear more idiomatic. * * Meta-data: none */ ZT_EVENT_DOWN = 3, /** * Your identity has collided with another node's ZeroTier address * * This happens if two different public keys both hash (via the algorithm * in Identity::generate()) to the same 40-bit ZeroTier address. * * This is something you should "never" see, where "never" is defined as * once per 2^39 new node initializations / identity creations. If you do * see it, you're going to see it very soon after a node is first * initialized. * * This is reported as an event rather than a return code since it's * detected asynchronously via error messages from authoritative nodes. * * If this occurs, you must shut down and delete the node, delete the * identity.secret record/file from the data store, and restart to generate * a new identity. If you don't do this, you will not be able to communicate * with other nodes. * * We'd automate this process, but we don't think silently deleting * private keys or changing our address without telling the calling code * is good form. It violates the principle of least surprise. * * You can technically get away with not handling this, but we recommend * doing so in a mature reliable application. Besides, handling this * condition is a good way to make sure it never arises. It's like how * umbrellas prevent rain and smoke detectors prevent fires. They do, right? * * Meta-data: none */ ZT_EVENT_FATAL_ERROR_IDENTITY_COLLISION = 4, /** * Trace (debugging) message * * These events are only generated if this is a TRACE-enabled build. * * Meta-data: C string, TRACE message */ ZT_EVENT_TRACE = 5, /** * VERB_USER_MESSAGE received * * These are generated when a VERB_USER_MESSAGE packet is received via * ZeroTier VL1. * * Meta-data: ZT_UserMessage structure */ ZT_EVENT_USER_MESSAGE = 6, /** * Remote trace received * * These are generated when a VERB_REMOTE_TRACE is received. Note * that any node can fling one of these at us. It is your responsibility * to filter and determine if it's worth paying attention to. If it's * not just drop it. Most nodes that are not active controllers ignore * these, and controllers only save them if they pertain to networks * with remote tracing enabled. * * Meta-data: ZT_RemoteTrace structure */ ZT_EVENT_REMOTE_TRACE = 7 }; /** * Payload of REMOTE_TRACE event */ typedef struct { /** * ZeroTier address of sender */ uint64_t origin; /** * Null-terminated Dictionary containing key/value pairs sent by origin * * This *should* be a dictionary, but the implementation only checks * that it is a valid non-empty C-style null-terminated string. Be very * careful to use a well-tested parser to parse this as it represents * data received from a potentially un-trusted peer on the network. * Invalid payloads should be dropped. * * The contents of data[] may be modified. */ char *data; /** * Length of dict[] in bytes, including terminating null */ unsigned int len; } ZT_RemoteTrace; /** * User message used with ZT_EVENT_USER_MESSAGE * * These are direct VL1 P2P messages for application use. Encryption and * authentication in the ZeroTier protocol will guarantee the origin * address and message content, but you are responsible for any other * levels of authentication or access control that are required. Any node * in the world can send you a user message! (Unless your network is air * gapped.) */ typedef struct { /** * ZeroTier address of sender (least significant 40 bits) */ uint64_t origin; /** * User message type ID */ uint64_t typeId; /** * User message data (not including type ID) */ const void *data; /** * Length of data in bytes */ unsigned int length; } ZT_UserMessage; /** * Current node status */ typedef struct { /** * 40-bit ZeroTier address of this node */ uint64_t address; /** * Public identity in string-serialized form (safe to send to others) * * This pointer will remain valid as long as the node exists. */ const char *publicIdentity; /** * Full identity including secret key in string-serialized form * * This pointer will remain valid as long as the node exists. */ const char *secretIdentity; /** * True if some kind of connectivity appears available */ int online; } ZT_NodeStatus; /** * Internal node statistics * * This structure is subject to change between versions. */ typedef struct { /** * Number of each protocol verb (possible verbs 0..31) received */ uint64_t inVerbCounts[32]; /** * Number of bytes for each protocol verb received */ uint64_t inVerbBytes[32]; } ZT_NodeStatistics; /** * Virtual network status codes */ enum ZT_VirtualNetworkStatus { /** * Waiting for network configuration (also means revision == 0) */ ZT_NETWORK_STATUS_REQUESTING_CONFIGURATION = 0, /** * Configuration received and we are authorized */ ZT_NETWORK_STATUS_OK = 1, /** * Netconf master told us 'nope' */ ZT_NETWORK_STATUS_ACCESS_DENIED = 2, /** * Netconf master exists, but this virtual network does not */ ZT_NETWORK_STATUS_NOT_FOUND = 3, /** * Initialization of network failed or other internal error */ ZT_NETWORK_STATUS_PORT_ERROR = 4, /** * ZeroTier core version too old */ ZT_NETWORK_STATUS_CLIENT_TOO_OLD = 5 }; /** * Virtual network type codes */ enum ZT_VirtualNetworkType { /** * Private networks are authorized via certificates of membership */ ZT_NETWORK_TYPE_PRIVATE = 0, /** * Public networks have no access control -- they'll always be AUTHORIZED */ ZT_NETWORK_TYPE_PUBLIC = 1 }; /** * The type of a virtual network rules table entry * * These must be from 0 to 63 since the most significant two bits of each * rule type are NOT (MSB) and AND/OR. * * Each rule is composed of zero or more MATCHes followed by an ACTION. * An ACTION with no MATCHes is always taken. */ enum ZT_VirtualNetworkRuleType { // 0 to 15 reserved for actions /** * Drop frame */ ZT_NETWORK_RULE_ACTION_DROP = 0, /** * Accept and pass frame */ ZT_NETWORK_RULE_ACTION_ACCEPT = 1, /** * Forward a copy of this frame to an observer (by ZT address) */ ZT_NETWORK_RULE_ACTION_TEE = 2, /** * Exactly like TEE but mandates ACKs from observer */ ZT_NETWORK_RULE_ACTION_WATCH = 3, /** * Drop and redirect this frame to another node (by ZT address) */ ZT_NETWORK_RULE_ACTION_REDIRECT = 4, /** * Stop evaluating rule set (drops unless there are capabilities, etc.) */ ZT_NETWORK_RULE_ACTION_BREAK = 5, /** * Place a matching frame in the specified QoS bucket */ ZT_NETWORK_RULE_ACTION_PRIORITY = 6, /** * Maximum ID for an ACTION, anything higher is a MATCH */ ZT_NETWORK_RULE_ACTION__MAX_ID = 15, // 16 to 63 reserved for match criteria ZT_NETWORK_RULE_MATCH_SOURCE_ZEROTIER_ADDRESS = 24, ZT_NETWORK_RULE_MATCH_DEST_ZEROTIER_ADDRESS = 25, ZT_NETWORK_RULE_MATCH_VLAN_ID = 26, ZT_NETWORK_RULE_MATCH_VLAN_PCP = 27, ZT_NETWORK_RULE_MATCH_VLAN_DEI = 28, ZT_NETWORK_RULE_MATCH_MAC_SOURCE = 29, ZT_NETWORK_RULE_MATCH_MAC_DEST = 30, ZT_NETWORK_RULE_MATCH_IPV4_SOURCE = 31, ZT_NETWORK_RULE_MATCH_IPV4_DEST = 32, ZT_NETWORK_RULE_MATCH_IPV6_SOURCE = 33, ZT_NETWORK_RULE_MATCH_IPV6_DEST = 34, ZT_NETWORK_RULE_MATCH_IP_TOS = 35, ZT_NETWORK_RULE_MATCH_IP_PROTOCOL = 36, ZT_NETWORK_RULE_MATCH_ETHERTYPE = 37, ZT_NETWORK_RULE_MATCH_ICMP = 38, ZT_NETWORK_RULE_MATCH_IP_SOURCE_PORT_RANGE = 39, ZT_NETWORK_RULE_MATCH_IP_DEST_PORT_RANGE = 40, ZT_NETWORK_RULE_MATCH_CHARACTERISTICS = 41, ZT_NETWORK_RULE_MATCH_FRAME_SIZE_RANGE = 42, ZT_NETWORK_RULE_MATCH_RANDOM = 43, ZT_NETWORK_RULE_MATCH_TAGS_DIFFERENCE = 44, ZT_NETWORK_RULE_MATCH_TAGS_BITWISE_AND = 45, ZT_NETWORK_RULE_MATCH_TAGS_BITWISE_OR = 46, ZT_NETWORK_RULE_MATCH_TAGS_BITWISE_XOR = 47, ZT_NETWORK_RULE_MATCH_TAGS_EQUAL = 48, ZT_NETWORK_RULE_MATCH_TAG_SENDER = 49, ZT_NETWORK_RULE_MATCH_TAG_RECEIVER = 50, ZT_NETWORK_RULE_MATCH_INTEGER_RANGE = 51, /** * Maximum ID allowed for a MATCH entry in the rules table */ ZT_NETWORK_RULE_MATCH__MAX_ID = 63 }; /** * Network flow rule * * Rules are stored in a table in which one or more match entries is followed * by an action. If more than one match precedes an action, the rule is * the AND of all matches. An action with no match is always taken since it * matches anything. If nothing matches, the default action is DROP. * * This is designed to be a more memory-efficient way of storing rules than * a wide table, yet still fast and simple to access in code. */ typedef struct { /** * Type and flags * * Bits are: NOTTTTTT * * N - If true, sense of match is inverted (no effect on actions) * O - If true, result is ORed with previous instead of ANDed (no effect on actions) * T - Rule or action type * * AND with 0x3f to get type, 0x80 to get NOT bit, and 0x40 to get OR bit. */ uint8_t t; /** * Union containing the value of this rule -- which field is used depends on 't' */ union { /** * IPv6 address in big-endian / network byte order and netmask bits */ struct { uint8_t ip[16]; uint8_t mask; } ipv6; /** * IPv4 address in big-endian / network byte order */ struct { uint32_t ip; uint8_t mask; } ipv4; /** * Integer range match in packet payload * * This allows matching of ranges of integers up to 64 bits wide where * the range is +/- INT32_MAX. It's packed this way so it fits in 16 * bytes and doesn't enlarge the overall size of this union. */ struct { uint64_t start; // integer range start uint32_t end; // end of integer range (relative to start, inclusive, 0 for equality w/start) uint16_t idx; // index in packet of integer uint8_t format; // bits in integer (range 1-64, ((format&63)+1)) and endianness (MSB 1 for little, 0 for big) } intRange; /** * Packet characteristic flags being matched */ uint64_t characteristics; /** * IP port range -- start-end inclusive -- host byte order */ uint16_t port[2]; /** * 40-bit ZeroTier address (in least significant bits, host byte order) */ uint64_t zt; /** * 0 = never, UINT32_MAX = always */ uint32_t randomProbability; /** * 48-bit Ethernet MAC address in big-endian order */ uint8_t mac[6]; /** * VLAN ID in host byte order */ uint16_t vlanId; /** * VLAN PCP (least significant 3 bits) */ uint8_t vlanPcp; /** * VLAN DEI (single bit / boolean) */ uint8_t vlanDei; /** * Ethernet type in host byte order */ uint16_t etherType; /** * IP protocol */ uint8_t ipProtocol; /** * IP type of service a.k.a. DSCP field */ struct { uint8_t mask; uint8_t value[2]; } ipTos; /** * Ethernet packet size in host byte order (start-end, inclusive) */ uint16_t frameSize[2]; /** * ICMP type and code */ struct { uint8_t type; // ICMP type, always matched uint8_t code; // ICMP code if matched uint8_t flags; // flag 0x01 means also match code, otherwise only match type } icmp; /** * For tag-related rules */ struct { uint32_t id; uint32_t value; } tag; /** * Destinations for TEE and REDIRECT */ struct { uint64_t address; uint32_t flags; uint16_t length; } fwd; /** * Quality of Service (QoS) bucket we want a frame to be placed in */ uint8_t qosBucket; } v; } ZT_VirtualNetworkRule; /** * A route to be pushed on a virtual network */ typedef struct { /** * Target network / netmask bits (in port field) or NULL or 0.0.0.0/0 for default */ struct sockaddr_storage target; /** * Gateway IP address (port ignored) or NULL (family == 0) for LAN-local (no gateway) */ struct sockaddr_storage via; /** * Route flags */ uint16_t flags; /** * Route metric (not currently used) */ uint16_t metric; } ZT_VirtualNetworkRoute; /** * DNS configuration to be pushed on a virtual network */ typedef struct { char domain[128]; struct sockaddr_storage server_addr[ZT_MAX_DNS_SERVERS]; } ZT_VirtualNetworkDNS; /** * An Ethernet multicast group */ typedef struct { /** * MAC address (least significant 48 bits) */ uint64_t mac; /** * Additional distinguishing information (usually zero) */ unsigned long adi; } ZT_MulticastGroup; /** * Virtual network configuration update type */ enum ZT_VirtualNetworkConfigOperation { /** * Network is coming up (either for the first time or after service restart) */ ZT_VIRTUAL_NETWORK_CONFIG_OPERATION_UP = 1, /** * Network configuration has been updated */ ZT_VIRTUAL_NETWORK_CONFIG_OPERATION_CONFIG_UPDATE = 2, /** * Network is going down (not permanently) */ ZT_VIRTUAL_NETWORK_CONFIG_OPERATION_DOWN = 3, /** * Network is going down permanently (leave/delete) */ ZT_VIRTUAL_NETWORK_CONFIG_OPERATION_DESTROY = 4 }; /** * What trust hierarchy role does this peer have? */ enum ZT_PeerRole { ZT_PEER_ROLE_LEAF = 0, // ordinary node ZT_PEER_ROLE_MOON = 1, // moon root ZT_PEER_ROLE_PLANET = 2 // planetary root }; /** * Vendor ID */ enum ZT_Vendor { ZT_VENDOR_UNSPECIFIED = 0, ZT_VENDOR_ZEROTIER = 1 }; /** * Platform type */ enum ZT_Platform { ZT_PLATFORM_UNSPECIFIED = 0, ZT_PLATFORM_LINUX = 1, ZT_PLATFORM_WINDOWS = 2, ZT_PLATFORM_MACOS = 3, ZT_PLATFORM_ANDROID = 4, ZT_PLATFORM_IOS = 5, ZT_PLATFORM_SOLARIS_SMARTOS = 6, ZT_PLATFORM_FREEBSD = 7, ZT_PLATFORM_NETBSD = 8, ZT_PLATFORM_OPENBSD = 9, ZT_PLATFORM_RISCOS = 10, ZT_PLATFORM_VXWORKS = 11, ZT_PLATFORM_FREERTOS = 12, ZT_PLATFORM_SYSBIOS = 13, ZT_PLATFORM_HURD = 14, ZT_PLATFORM_WEB = 15 }; /** * Architecture type */ enum ZT_Architecture { ZT_ARCHITECTURE_UNSPECIFIED = 0, ZT_ARCHITECTURE_X86 = 1, ZT_ARCHITECTURE_X64 = 2, ZT_ARCHITECTURE_ARM32 = 3, ZT_ARCHITECTURE_ARM64 = 4, ZT_ARCHITECTURE_MIPS32 = 5, ZT_ARCHITECTURE_MIPS64 = 6, ZT_ARCHITECTURE_POWER32 = 7, ZT_ARCHITECTURE_POWER64 = 8, ZT_ARCHITECTURE_OPENRISC32 = 9, ZT_ARCHITECTURE_OPENRISC64 = 10, ZT_ARCHITECTURE_SPARC32 = 11, ZT_ARCHITECTURE_SPARC64 = 12, ZT_ARCHITECTURE_DOTNET_CLR = 13, ZT_ARCHITECTURE_JAVA_JVM = 14, ZT_ARCHITECTURE_WEB = 15, ZT_ARCHITECTURE_S390X = 16 }; /** * Virtual network configuration */ typedef struct { /** * 64-bit ZeroTier network ID */ uint64_t nwid; /** * Ethernet MAC (48 bits) that should be assigned to port */ uint64_t mac; /** * Network name (from network configuration master) */ char name[ZT_MAX_NETWORK_SHORT_NAME_LENGTH + 1]; /** * Network configuration request status */ enum ZT_VirtualNetworkStatus status; /** * Network type */ enum ZT_VirtualNetworkType type; /** * Maximum interface MTU */ unsigned int mtu; /** * If nonzero, the network this port belongs to indicates DHCP availability * * This is a suggestion. The underlying implementation is free to ignore it * for security or other reasons. This is simply a netconf parameter that * means 'DHCP is available on this network.' */ int dhcp; /** * If nonzero, this port is allowed to bridge to other networks * * This is informational. If this is false (0), bridged packets will simply * be dropped and bridging won't work. */ int bridge; /** * If nonzero, this network supports and allows broadcast (ff:ff:ff:ff:ff:ff) traffic */ int broadcastEnabled; /** * If the network is in PORT_ERROR state, this is the (negative) error code most recently reported */ int portError; /** * Revision number as reported by controller or 0 if still waiting for config */ unsigned long netconfRevision; /** * Number of assigned addresses */ unsigned int assignedAddressCount; /** * ZeroTier-assigned addresses (in sockaddr_storage structures) * * For IP, the port number of the sockaddr_XX structure contains the number * of bits in the address netmask. Only the IP address and port are used. * Other fields like interface number can be ignored. * * This is only used for ZeroTier-managed address assignments sent by the * virtual network's configuration master. */ struct sockaddr_storage assignedAddresses[ZT_MAX_ZT_ASSIGNED_ADDRESSES]; /** * Number of ZT-pushed routes */ unsigned int routeCount; /** * Routes (excluding those implied by assigned addresses and their masks) */ ZT_VirtualNetworkRoute routes[ZT_MAX_NETWORK_ROUTES]; /** * Number of multicast groups subscribed */ unsigned int multicastSubscriptionCount; /** * Multicast groups to which this network's device is subscribed */ struct { uint64_t mac; /* MAC in lower 48 bits */ uint32_t adi; /* Additional distinguishing information, usually zero except for IPv4 ARP groups */ } multicastSubscriptions[ZT_MAX_MULTICAST_SUBSCRIPTIONS]; /** * Network specific DNS configuration */ ZT_VirtualNetworkDNS dns; } ZT_VirtualNetworkConfig; /** * A list of networks */ typedef struct { ZT_VirtualNetworkConfig *networks; unsigned long networkCount; } ZT_VirtualNetworkList; /** * Physical path configuration */ typedef struct { /** * If non-zero set this physical network path to be trusted to disable encryption and authentication */ uint64_t trustedPathId; /** * Physical path MTU from ZT_MIN_PHYSMTU and ZT_MAX_PHYSMTU or <= 0 to use default */ int mtu; } ZT_PhysicalPathConfiguration; /** * Physical network path to a peer */ typedef struct { /** * Address of endpoint */ struct sockaddr_storage address; /** * Time of last send in milliseconds or 0 for never */ uint64_t lastSend; /** * Time of last receive in milliseconds or 0 for never */ uint64_t lastReceive; /** * Is this a trusted path? If so this will be its nonzero ID. */ uint64_t trustedPathId; /** * Mean latency */ float latencyMean; /** * Maximum observed latency */ float latencyMax; /** * Variance of latency */ float latencyVariance; /** * Packet loss ratio */ float packetLossRatio; /** * Packet error ratio */ float packetErrorRatio; /** * Mean throughput */ uint64_t throughputMean; /** * Maximum observed throughput */ float throughputMax; /** * Throughput variance */ float throughputVariance; /** * Address scope */ uint8_t scope; /** * Percentage of traffic allocated to this path */ float allocation; /** * Name of physical interface (for monitoring) */ char ifname[32]; uint64_t localSocket; /** * Is path expired? */ int expired; /** * Is path preferred? */ int preferred; } ZT_PeerPhysicalPath; /** * Peer status result buffer */ typedef struct { /** * ZeroTier address (40 bits) */ uint64_t address; /** * Remote major version or -1 if not known */ int versionMajor; /** * Remote minor version or -1 if not known */ int versionMinor; /** * Remote revision or -1 if not known */ int versionRev; /** * Last measured latency in milliseconds or -1 if unknown */ int latency; /** * What trust hierarchy role does this device have? */ enum ZT_PeerRole role; /** * Whether a multi-link bond has formed */ bool isBonded; /** * The bonding policy used to bond to this peer */ int bondingPolicy; /** * The health status of the bond to this peer */ bool isHealthy; /** * The number of links that comprise the bond to this peer that are considered alive */ int numAliveLinks; /** * The number of links that comprise the bond to this peer */ int numTotalLinks; /** * The user-specified bond template name */ char customBondName[32]; /** * Number of paths (size of paths[]) */ unsigned int pathCount; /** * Known network paths to peer */ ZT_PeerPhysicalPath paths[ZT_MAX_PEER_NETWORK_PATHS]; } ZT_Peer; /** * List of peers */ typedef struct { ZT_Peer *peers; unsigned long peerCount; } ZT_PeerList; /** * ZeroTier core state objects */ enum ZT_StateObjectType { /** * Null object -- ignored */ ZT_STATE_OBJECT_NULL = 0, /** * Public address and public key * * Object ID: this node's address if known, or 0 if unknown (first query) * Canonical path: /identity.public * Persistence: required */ ZT_STATE_OBJECT_IDENTITY_PUBLIC = 1, /** * Full identity with secret key * * Object ID: this node's address if known, or 0 if unknown (first query) * Canonical path: /identity.secret * Persistence: required, should be stored with restricted permissions e.g. mode 0600 on *nix */ ZT_STATE_OBJECT_IDENTITY_SECRET = 2, /** * The planet (there is only one per... well... planet!) * * Object ID: world ID of planet, or 0 if unknown (first query) * Canonical path: /planet * Persistence: recommended */ ZT_STATE_OBJECT_PLANET = 3, /** * A moon (federated root set) * * Object ID: world ID of moon * Canonical path: /moons.d/.moon (16-digit hex ID) * Persistence: required if moon memberships should persist */ ZT_STATE_OBJECT_MOON = 4, /** * Peer and related state * * Object ID: peer address * Canonical path: /peers.d/ (10-digit address * Persistence: optional, can be cleared at any time */ ZT_STATE_OBJECT_PEER = 5, /** * Network configuration * * Object ID: peer address * Canonical path: /networks.d/.conf (16-digit hex ID) * Persistence: required if network memberships should persist */ ZT_STATE_OBJECT_NETWORK_CONFIG = 6 }; /** * An instance of a ZeroTier One node (opaque) */ typedef void ZT_Node; /****************************************************************************/ /* Callbacks used by Node API */ /****************************************************************************/ /** * Callback called to update virtual network port configuration * * This can be called at any time to update the configuration of a virtual * network port. The parameter after the network ID specifies whether this * port is being brought up, updated, brought down, or permanently deleted. * * This in turn should be used by the underlying implementation to create * and configure tap devices at the OS (or virtual network stack) layer. * * The supplied config pointer is not guaranteed to remain valid, so make * a copy if you want one. * * This should not call multicastSubscribe() or other network-modifying * methods, as this could cause a deadlock in multithreaded or interrupt * driven environments. * * This must return 0 on success. It can return any OS-dependent error code * on failure, and this results in the network being placed into the * PORT_ERROR state. */ typedef int (*ZT_VirtualNetworkConfigFunction)( ZT_Node *, /* Node */ void *, /* User ptr */ void *, /* Thread ptr */ uint64_t, /* Network ID */ void **, /* Modifiable network user PTR */ enum ZT_VirtualNetworkConfigOperation, /* Config operation */ const ZT_VirtualNetworkConfig *); /* Network configuration */ /** * Function to send a frame out to a virtual network port * * Parameters: (1) node, (2) user ptr, (3) network ID, (4) source MAC, * (5) destination MAC, (6) ethertype, (7) VLAN ID, (8) frame data, * (9) frame length. */ typedef void (*ZT_VirtualNetworkFrameFunction)( ZT_Node *, /* Node */ void *, /* User ptr */ void *, /* Thread ptr */ uint64_t, /* Network ID */ void **, /* Modifiable network user PTR */ uint64_t, /* Source MAC */ uint64_t, /* Destination MAC */ unsigned int, /* Ethernet type */ unsigned int, /* VLAN ID (0 for none) */ const void *, /* Frame data */ unsigned int); /* Frame length */ /** * Callback for events * * Events are generated when the node's status changes in a significant way * and on certain non-fatal errors and events of interest. The final void * parameter points to event meta-data. The type of event meta-data (and * whether it is present at all) is event type dependent. See the comments * in the definition of ZT_Event. */ typedef void (*ZT_EventCallback)( ZT_Node *, /* Node */ void *, /* User ptr */ void *, /* Thread ptr */ enum ZT_Event, /* Event type */ const void *); /* Event payload (if applicable) */ /** * Callback for storing and/or publishing state information * * See ZT_StateObjectType docs for information about each state object type * and when and if it needs to be persisted. * * An object of length -1 is sent to indicate that an object should be * deleted. */ typedef void (*ZT_StatePutFunction)( ZT_Node *, /* Node */ void *, /* User ptr */ void *, /* Thread ptr */ enum ZT_StateObjectType, /* State object type */ const uint64_t [2], /* State object ID (if applicable) */ const void *, /* State object data */ int); /* Length of data or -1 to delete */ /** * Callback for retrieving stored state information * * This function should return the number of bytes actually stored to the * buffer or -1 if the state object was not found or the buffer was too * small to store it. */ typedef int (*ZT_StateGetFunction)( ZT_Node *, /* Node */ void *, /* User ptr */ void *, /* Thread ptr */ enum ZT_StateObjectType, /* State object type */ const uint64_t [2], /* State object ID (if applicable) */ void *, /* Buffer to store state object data */ unsigned int); /* Length of data buffer in bytes */ /** * Function to send a ZeroTier packet out over the physical wire (L2/L3) * * Parameters: * (1) Node * (2) User pointer * (3) Local socket or -1 for "all" or "any" * (4) Remote address * (5) Packet data * (6) Packet length * (7) Desired IP TTL or 0 to use default * * If there is only one local socket, the local socket can be ignored. * If the local socket is -1, the packet should be sent out from all * bound local sockets or a random bound local socket. * * If TTL is nonzero, packets should have their IP TTL value set to this * value if possible. If this is not possible it is acceptable to ignore * this value and send anyway with normal or default TTL. * * The function must return zero on success and may return any error code * on failure. Note that success does not (of course) guarantee packet * delivery. It only means that the packet appears to have been sent. */ typedef int (*ZT_WirePacketSendFunction)( ZT_Node *, /* Node */ void *, /* User ptr */ void *, /* Thread ptr */ int64_t, /* Local socket */ const struct sockaddr_storage *, /* Remote address */ const void *, /* Packet data */ unsigned int, /* Packet length */ unsigned int); /* TTL or 0 to use default */ /** * Function to check whether a path should be used for ZeroTier traffic * * Parameters: * (1) Node * (2) User pointer * (3) ZeroTier address or 0 for none/any * (4) Local socket or -1 if unknown * (5) Remote address * * This function must return nonzero (true) if the path should be used. * * If no path check function is specified, ZeroTier will still exclude paths * that overlap with ZeroTier-assigned and managed IP address blocks. But the * use of a path check function is recommended to ensure that recursion does * not occur in cases where addresses are assigned by the OS or managed by * an out of band mechanism like DHCP. The path check function should examine * all configured ZeroTier interfaces and check to ensure that the supplied * addresses will not result in ZeroTier traffic being sent over a ZeroTier * interface (recursion). */ typedef int (*ZT_PathCheckFunction)( ZT_Node *, /* Node */ void *, /* User ptr */ void *, /* Thread ptr */ uint64_t, /* ZeroTier address */ int64_t, /* Local socket or -1 if unknown */ const struct sockaddr_storage *); /* Remote address */ /** * Function to get physical addresses for ZeroTier peers * * Parameters: * (1) Node * (2) User pointer * (3) ZeroTier address (least significant 40 bits) * (4) Desired address family or -1 for any * (5) Buffer to fill with result * * If provided this function will be occasionally called to get physical * addresses that might be tried to reach a ZeroTier address. It must * return a nonzero (true) value if the result buffer has been filled * with an address. */ typedef int (*ZT_PathLookupFunction)( ZT_Node *, /* Node */ void *, /* User ptr */ void *, /* Thread ptr */ uint64_t, /* ZeroTier address (40 bits) */ int, /* Desired ss_family or -1 for any */ struct sockaddr_storage *); /* Result buffer */ /****************************************************************************/ /* C Node API */ /****************************************************************************/ /** * Structure for configuring ZeroTier core callback functions */ struct ZT_Node_Callbacks { /** * Struct version -- must currently be 0 */ long version; /** * REQUIRED: Function to store and/or replicate state objects */ ZT_StatePutFunction statePutFunction; /** * REQUIRED: Function to retrieve state objects from an object store */ ZT_StateGetFunction stateGetFunction; /** * REQUIRED: Function to send packets over the physical wire */ ZT_WirePacketSendFunction wirePacketSendFunction; /** * REQUIRED: Function to inject frames into a virtual network's TAP */ ZT_VirtualNetworkFrameFunction virtualNetworkFrameFunction; /** * REQUIRED: Function to be called when virtual networks are configured or changed */ ZT_VirtualNetworkConfigFunction virtualNetworkConfigFunction; /** * REQUIRED: Function to be called to notify external code of important events */ ZT_EventCallback eventCallback; /** * OPTIONAL: Function to check whether a given physical path should be used */ ZT_PathCheckFunction pathCheckFunction; /** * OPTIONAL: Function to get hints to physical paths to ZeroTier addresses */ ZT_PathLookupFunction pathLookupFunction; }; /** * Create a new ZeroTier node * * This will attempt to load its identity via the state get function in the * callback struct. If that fails it will generate a new identity and store * it. Identity generation can take anywhere from a few hundred milliseconds * to a few seconds depending on your CPU speed. * * @param node Result: pointer is set to new node instance on success * @param uptr User pointer to pass to functions/callbacks * @param tptr Thread pointer to pass to functions/callbacks resulting from this call * @param callbacks Callback function configuration * @param now Current clock in milliseconds * @return OK (0) or error code if a fatal error condition has occurred */ ZT_SDK_API enum ZT_ResultCode ZT_Node_new(ZT_Node **node,void *uptr,void *tptr,const struct ZT_Node_Callbacks *callbacks,int64_t now); /** * Delete a node and free all resources it consumes * * If you are using multiple threads, all other threads must be shut down * first. This can crash if processXXX() methods are in progress. * * @param node Node to delete */ ZT_SDK_API void ZT_Node_delete(ZT_Node *node); /** * Process a packet received from the physical wire * * @param node Node instance * @param tptr Thread pointer to pass to functions/callbacks resulting from this call * @param now Current clock in milliseconds * @param localSocket Local socket (you can use 0 if only one local socket is bound and ignore this) * @param remoteAddress Origin of packet * @param packetData Packet data * @param packetLength Packet length * @param nextBackgroundTaskDeadline Value/result: set to deadline for next call to processBackgroundTasks() * @return OK (0) or error code if a fatal error condition has occurred */ ZT_SDK_API enum ZT_ResultCode ZT_Node_processWirePacket( ZT_Node *node, void *tptr, int64_t now, int64_t localSocket, const struct sockaddr_storage *remoteAddress, const void *packetData, unsigned int packetLength, volatile int64_t *nextBackgroundTaskDeadline); /** * Process a frame from a virtual network port (tap) * * @param node Node instance * @param tptr Thread pointer to pass to functions/callbacks resulting from this call * @param now Current clock in milliseconds * @param nwid ZeroTier 64-bit virtual network ID * @param sourceMac Source MAC address (least significant 48 bits) * @param destMac Destination MAC address (least significant 48 bits) * @param etherType 16-bit Ethernet frame type * @param vlanId 10-bit VLAN ID or 0 if none * @param frameData Frame payload data * @param frameLength Frame payload length * @param nextBackgroundTaskDeadline Value/result: set to deadline for next call to processBackgroundTasks() * @return OK (0) or error code if a fatal error condition has occurred */ ZT_SDK_API enum ZT_ResultCode ZT_Node_processVirtualNetworkFrame( ZT_Node *node, void *tptr, int64_t now, uint64_t nwid, uint64_t sourceMac, uint64_t destMac, unsigned int etherType, unsigned int vlanId, const void *frameData, unsigned int frameLength, volatile int64_t *nextBackgroundTaskDeadline); /** * Perform periodic background operations * * @param node Node instance * @param tptr Thread pointer to pass to functions/callbacks resulting from this call * @param now Current clock in milliseconds * @param nextBackgroundTaskDeadline Value/result: set to deadline for next call to processBackgroundTasks() * @return OK (0) or error code if a fatal error condition has occurred */ ZT_SDK_API enum ZT_ResultCode ZT_Node_processBackgroundTasks(ZT_Node *node,void *tptr,int64_t now,volatile int64_t *nextBackgroundTaskDeadline); /** * Join a network * * This may generate calls to the port config callback before it returns, * or these may be differed if a netconf is not available yet. * * If we are already a member of the network, nothing is done and OK is * returned. * * @param node Node instance * @param nwid 64-bit ZeroTier network ID * @param uptr An arbitrary pointer to associate with this network (default: NULL) * @return OK (0) or error code if a fatal error condition has occurred */ ZT_SDK_API enum ZT_ResultCode ZT_Node_join(ZT_Node *node,uint64_t nwid,void *uptr,void *tptr); /** * Leave a network * * If a port has been configured for this network this will generate a call * to the port config callback with a NULL second parameter to indicate that * the port is now deleted. * * The uptr parameter is optional and is NULL by default. If it is not NULL, * the pointer it points to is set to this network's uptr on success. * * @param node Node instance * @param nwid 64-bit network ID * @param uptr Target pointer is set to uptr (if not NULL) * @return OK (0) or error code if a fatal error condition has occurred */ ZT_SDK_API enum ZT_ResultCode ZT_Node_leave(ZT_Node *node,uint64_t nwid,void **uptr,void *tptr); /** * Subscribe to an Ethernet multicast group * * ADI stands for additional distinguishing information. This defaults to zero * and is rarely used. Right now its only use is to enable IPv4 ARP to scale, * and this must be done. * * For IPv4 ARP, the implementation must subscribe to 0xffffffffffff (the * broadcast address) but with an ADI equal to each IPv4 address in host * byte order. This converts ARP from a non-scalable broadcast protocol to * a scalable multicast protocol with perfect address specificity. * * If this is not done, ARP will not work reliably. * * Multiple calls to subscribe to the same multicast address will have no * effect. It is perfectly safe to do this. * * This does not generate an update call to networkConfigCallback(). * * @param node Node instance * @param tptr Thread pointer to pass to functions/callbacks resulting from this call * @param nwid 64-bit network ID * @param multicastGroup Ethernet multicast or broadcast MAC (least significant 48 bits) * @param multicastAdi Multicast ADI (least significant 32 bits only, use 0 if not needed) * @return OK (0) or error code if a fatal error condition has occurred */ ZT_SDK_API enum ZT_ResultCode ZT_Node_multicastSubscribe(ZT_Node *node,void *tptr,uint64_t nwid,uint64_t multicastGroup,unsigned long multicastAdi); /** * Unsubscribe from an Ethernet multicast group (or all groups) * * If multicastGroup is zero (0), this will unsubscribe from all groups. If * you are not subscribed to a group this has no effect. * * This does not generate an update call to networkConfigCallback(). * * @param node Node instance * @param nwid 64-bit network ID * @param multicastGroup Ethernet multicast or broadcast MAC (least significant 48 bits) * @param multicastAdi Multicast ADI (least significant 32 bits only, use 0 if not needed) * @return OK (0) or error code if a fatal error condition has occurred */ ZT_SDK_API enum ZT_ResultCode ZT_Node_multicastUnsubscribe(ZT_Node *node,uint64_t nwid,uint64_t multicastGroup,unsigned long multicastAdi); /** * Add or update a moon * * Moons are persisted in the data store in moons.d/, so this can persist * across invocations if the contents of moon.d are scanned and orbit is * called for each on startup. * * @param node Node instance * @param tptr Thread pointer to pass to functions/callbacks resulting from this call * @param moonWorldId Moon's world ID * @param moonSeed If non-zero, the ZeroTier address of any member of the moon to query for moon definition * @param len Length of moonWorld in bytes * @return Error if moon was invalid or failed to be added */ ZT_SDK_API enum ZT_ResultCode ZT_Node_orbit(ZT_Node *node,void *tptr,uint64_t moonWorldId,uint64_t moonSeed); /** * Remove a moon (does nothing if not present) * * @param node Node instance * @param tptr Thread pointer to pass to functions/callbacks resulting from this call * @param moonWorldId World ID of moon to remove * @return Error if anything bad happened */ ZT_SDK_API enum ZT_ResultCode ZT_Node_deorbit(ZT_Node *node,void *tptr,uint64_t moonWorldId); /** * Get this node's 40-bit ZeroTier address * * @param node Node instance * @return ZeroTier address (least significant 40 bits of 64-bit int) */ ZT_SDK_API uint64_t ZT_Node_address(ZT_Node *node); /** * Get the status of this node * * @param node Node instance * @param status Buffer to fill with current node status */ ZT_SDK_API void ZT_Node_status(ZT_Node *node,ZT_NodeStatus *status); /** * Get a list of known peer nodes * * The pointer returned here must be freed with freeQueryResult() * when you are done with it. * * @param node Node instance * @return List of known peers or NULL on failure */ ZT_SDK_API ZT_PeerList *ZT_Node_peers(ZT_Node *node); /** * Get the status of a virtual network * * The pointer returned here must be freed with freeQueryResult() * when you are done with it. * * @param node Node instance * @param nwid 64-bit network ID * @return Network configuration or NULL if we are not a member of this network */ ZT_SDK_API ZT_VirtualNetworkConfig *ZT_Node_networkConfig(ZT_Node *node,uint64_t nwid); /** * Enumerate and get status of all networks * * @param node Node instance * @return List of networks or NULL on failure */ ZT_SDK_API ZT_VirtualNetworkList *ZT_Node_networks(ZT_Node *node); /** * Free a query result buffer * * Use this to free the return values of listNetworks(), listPeers(), etc. * * @param node Node instance * @param qr Query result buffer */ ZT_SDK_API void ZT_Node_freeQueryResult(ZT_Node *node,void *qr); /** * Add a local interface address * * This is used to make ZeroTier aware of those local interface addresses * that you wish to use for ZeroTier communication. This is optional, and if * it is not used ZeroTier will rely upon upstream peers (and roots) to * perform empirical address discovery and NAT traversal. But the use of this * method is recommended as it improves peer discovery when both peers are * on the same LAN. * * It is the responsibility of the caller to take care that these are never * ZeroTier interface addresses, whether these are assigned by ZeroTier or * are otherwise assigned to an interface managed by this ZeroTier instance. * This can cause recursion or other undesirable behavior. * * This returns a boolean indicating whether or not the address was * accepted. ZeroTier will only communicate over certain address types * and (for IP) address classes. * * @param addr Local interface address * @return Boolean: non-zero if address was accepted and added */ ZT_SDK_API int ZT_Node_addLocalInterfaceAddress(ZT_Node *node,const struct sockaddr_storage *addr); /** * Clear local interface addresses */ ZT_SDK_API void ZT_Node_clearLocalInterfaceAddresses(ZT_Node *node); /** * Send a VERB_USER_MESSAGE to another ZeroTier node * * There is no delivery guarantee here. Failure can occur if the message is * too large or if dest is not a valid ZeroTier address. * * @param node Node instance * @param tptr Thread pointer to pass to functions/callbacks resulting from this call * @param dest Destination ZeroTier address * @param typeId VERB_USER_MESSAGE type ID * @param data Payload data to attach to user message * @param len Length of data in bytes * @return Boolean: non-zero on success, zero on failure */ ZT_SDK_API int ZT_Node_sendUserMessage(ZT_Node *node,void *tptr,uint64_t dest,uint64_t typeId,const void *data,unsigned int len); /** * Set a network configuration master instance for this node * * Normal nodes should not need to use this. This is for nodes with * special compiled-in support for acting as network configuration * masters / controllers. * * The supplied instance must be a C++ object that inherits from the * NetworkConfigMaster base class in node/. No type checking is performed, * so a pointer to anything else will result in a crash. * * @param node ZertTier One node * @param networkConfigMasterInstance Instance of NetworkConfigMaster C++ class or NULL to disable * @return OK (0) or error code if a fatal error condition has occurred */ ZT_SDK_API void ZT_Node_setNetconfMaster(ZT_Node *node,void *networkConfigMasterInstance); /** * Set configuration for a given physical path * * @param node Node instance * @param pathNetwork Network/CIDR of path or NULL to clear the cache and reset all paths to default * @param pathConfig Path configuration or NULL to erase this entry and therefore reset it to NULL * @return OK or error code */ ZT_SDK_API enum ZT_ResultCode ZT_Node_setPhysicalPathConfiguration(ZT_Node *node,const struct sockaddr_storage *pathNetwork,const ZT_PhysicalPathConfiguration *pathConfig); /** * Get ZeroTier One version * * @param major Result: major version * @param minor Result: minor version * @param revision Result: revision */ ZT_SDK_API void ZT_version(int *major,int *minor,int *revision); #ifdef __cplusplus } #endif #endif