diff options
Diffstat (limited to 'include')
| -rw-r--r-- | include/ZeroTierOne.h | 424 |
1 files changed, 229 insertions, 195 deletions
diff --git a/include/ZeroTierOne.h b/include/ZeroTierOne.h index 8d7b0cd4..98413a21 100644 --- a/include/ZeroTierOne.h +++ b/include/ZeroTierOne.h @@ -137,6 +137,11 @@ extern "C" { #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 @@ -175,6 +180,11 @@ extern "C" { #define ZT_CLUSTER_MAX_MESSAGE_LENGTH (1500 - 48) /** + * Maximum value for link quality (min is 0) + */ +#define ZT_PATH_LINK_QUALITY_MAX 0xff + +/** * Packet characteristics flag: packet direction, 1 if inbound 0 if outbound */ #define ZT_RULE_PACKET_CHARACTERISTICS_INBOUND 0x8000000000000000ULL @@ -190,6 +200,16 @@ extern "C" { #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 @@ -393,28 +413,54 @@ enum ZT_Event * * Meta-data: C string, TRACE message */ - ZT_EVENT_TRACE = 5 + 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 }; /** - * Current node status + * User message used with ZT_EVENT_USER_MESSAGE */ typedef struct { /** - * 40-bit ZeroTier address of this node + * ZeroTier address of sender (least significant 40 bits) */ - uint64_t address; + uint64_t origin; + + /** + * User message type ID + */ + uint64_t typeId; + + /** + * User message data (not including type ID) + */ + const void *data; /** - * Current world ID + * Length of data in bytes */ - uint64_t worldId; + unsigned int length; +} ZT_UserMessage; +/** + * Current node status + */ +typedef struct +{ /** - * Current world revision/timestamp + * 40-bit ZeroTier address of this node */ - uint64_t worldTimestamp; + uint64_t address; /** * Public identity in string-serialized form (safe to send to others) @@ -491,15 +537,15 @@ enum ZT_VirtualNetworkType /** * The type of a virtual network rules table entry * - * These must range from 0 to 127 (0x7f) because the most significant bit - * is reserved as a NOT flag. + * 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 31 reserved for actions + // 0 to 15 reserved for actions /** * Drop frame @@ -527,146 +573,49 @@ enum ZT_VirtualNetworkRuleType ZT_NETWORK_RULE_ACTION_REDIRECT = 4, /** - * Log if match and if rule debugging is enabled in the build, otherwise does nothing (for developers) + * Stop evaluating rule set (drops unless there are capabilities, etc.) */ - ZT_NETWORK_RULE_ACTION_DEBUG_LOG = 5, + ZT_NETWORK_RULE_ACTION_BREAK = 5, /** * Maximum ID for an ACTION, anything higher is a MATCH */ - ZT_NETWORK_RULE_ACTION__MAX_ID = 31, - - // 32 to 127 reserved for match criteria - - /** - * Source ZeroTier address -- analogous to an Ethernet port ID on a switch - */ - ZT_NETWORK_RULE_MATCH_SOURCE_ZEROTIER_ADDRESS = 32, - - /** - * Destination ZeroTier address -- analogous to an Ethernet port ID on a switch - */ - ZT_NETWORK_RULE_MATCH_DEST_ZEROTIER_ADDRESS = 33, - - /** - * Ethernet VLAN ID - */ - ZT_NETWORK_RULE_MATCH_VLAN_ID = 34, - - /** - * Ethernet VLAN PCP - */ - ZT_NETWORK_RULE_MATCH_VLAN_PCP = 35, - - /** - * Ethernet VLAN DEI - */ - ZT_NETWORK_RULE_MATCH_VLAN_DEI = 36, - - /** - * Ethernet frame type - */ + 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, - - /** - * Source Ethernet MAC address - */ - ZT_NETWORK_RULE_MATCH_MAC_SOURCE = 38, - - /** - * Destination Ethernet MAC address - */ - ZT_NETWORK_RULE_MATCH_MAC_DEST = 39, - - /** - * Source IPv4 address - */ - ZT_NETWORK_RULE_MATCH_IPV4_SOURCE = 40, - - /** - * Destination IPv4 address - */ - ZT_NETWORK_RULE_MATCH_IPV4_DEST = 41, - - /** - * Source IPv6 address - */ - ZT_NETWORK_RULE_MATCH_IPV6_SOURCE = 42, - - /** - * Destination IPv6 address - */ - ZT_NETWORK_RULE_MATCH_IPV6_DEST = 43, - - /** - * IP TOS (type of service) - */ - ZT_NETWORK_RULE_MATCH_IP_TOS = 44, - - /** - * IP protocol - */ - ZT_NETWORK_RULE_MATCH_IP_PROTOCOL = 45, - - /** - * ICMP type and possibly code (does not match if not ICMP) - */ - ZT_NETWORK_RULE_MATCH_ICMP = 46, - - /** - * IP source port range (start-end, inclusive) - */ - ZT_NETWORK_RULE_MATCH_IP_SOURCE_PORT_RANGE = 47, - - /** - * IP destination port range (start-end, inclusive) - */ - ZT_NETWORK_RULE_MATCH_IP_DEST_PORT_RANGE = 48, - - /** - * Packet characteristics (set of flags) - */ - ZT_NETWORK_RULE_MATCH_CHARACTERISTICS = 49, - - /** - * Frame size range (start-end, inclusive) - */ - ZT_NETWORK_RULE_MATCH_FRAME_SIZE_RANGE = 50, - - /** - * Random match with selectable probability - */ - ZT_NETWORK_RULE_MATCH_RANDOM = 51, - - /** - * Match if local and remote tags differ by no more than value, use 0 to check for equality - */ - ZT_NETWORK_RULE_MATCH_TAGS_DIFFERENCE = 52, - - /** - * Match if local and remote tags ANDed together equal value. - */ - ZT_NETWORK_RULE_MATCH_TAGS_BITWISE_AND = 53, - - /** - * Match if local and remote tags ANDed together equal value. - */ - ZT_NETWORK_RULE_MATCH_TAGS_BITWISE_OR = 54, - - /** - * Match if local and remote tags XORed together equal value. - */ - ZT_NETWORK_RULE_MATCH_TAGS_BITWISE_XOR = 55, - - /** - * Match if local and remote tags both equal a value - */ - ZT_NETWORK_RULE_MATCH_TAGS_EQUAL = 56, + 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, /** * Maximum ID allowed for a MATCH entry in the rules table */ - ZT_NETWORK_RULE_MATCH__MAX_ID = 127 + ZT_NETWORK_RULE_MATCH__MAX_ID = 63 }; /** @@ -683,15 +632,15 @@ enum ZT_VirtualNetworkRuleType typedef struct { /** - * Least significant 7 bits: ZT_VirtualNetworkRuleType, most significant 1 bit is NOT bit + * Type and flags * - * If the NOT bit is set, then matches will be interpreted as "does not - * match." The NOT bit has no effect on actions. + * Bits are: NOTTTTTT * - * Use "& 0x7f" to get the enum and "& 0x80" to get the NOT flag. + * 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 * - * The union 'v' is a variant type, and this selects which field in 'v' is - * actually used and valid. + * AND with 0x3f to get type, 0x80 to get NOT bit, and 0x40 to get OR bit. */ uint8_t t; @@ -768,7 +717,10 @@ typedef struct /** * IP type of service a.k.a. DSCP field */ - uint8_t ipTos; + struct { + uint8_t mask; + uint8_t value[2]; + } ipTos; /** * Ethernet packet size in host byte order (start-end, inclusive) @@ -890,21 +842,14 @@ enum ZT_VirtualNetworkConfigOperation ZT_VIRTUAL_NETWORK_CONFIG_OPERATION_DESTROY = 4 }; -enum ZT_RelayPolicy -{ - ZT_RELAY_POLICY_NEVER = 0, - ZT_RELAY_POLICY_TRUSTED = 1, - ZT_RELAY_POLICY_ALWAYS = 2 -}; - /** * What trust hierarchy role does this peer have? */ enum ZT_PeerRole { - ZT_PEER_ROLE_LEAF = 0, // ordinary node - ZT_PEER_ROLE_UPSTREAM = 1, // upstream node - ZT_PEER_ROLE_ROOT = 2 // global root + ZT_PEER_ROLE_LEAF = 0, // ordinary node + ZT_PEER_ROLE_MOON = 1, // moon root + ZT_PEER_ROLE_PLANET = 2 // planetary root }; /** @@ -1097,6 +1042,11 @@ typedef struct uint64_t trustedPathId; /** + * Path link quality from 0 to 255 (always 255 if peer does not support) + */ + int linkQuality; + + /** * Is path expired? */ int expired; @@ -1118,16 +1068,6 @@ typedef struct uint64_t address; /** - * Time we last received a unicast frame from this peer - */ - uint64_t lastUnicastFrame; - - /** - * Time we last received a multicast rame from this peer - */ - uint64_t lastMulticastFrame; - - /** * Remote major version or -1 if not known */ int versionMajor; @@ -1331,6 +1271,11 @@ typedef struct { struct sockaddr_storage receivedFromRemoteAddress; /** + * Path link quality of physical path over which test was received + */ + int receivedFromLinkQuality; + + /** * Next hops to which packets are being or will be sent by the reporter * * In addition to reporting back, the reporter may send the test on if @@ -1596,8 +1541,9 @@ typedef int (*ZT_WirePacketSendFunction)( * Paramters: * (1) Node * (2) User pointer - * (3) Local interface address - * (4) Remote address + * (3) ZeroTier address or 0 for none/any + * (4) Local interface address + * (5) Remote address * * This function must return nonzero (true) if the path should be used. * @@ -1616,14 +1562,88 @@ typedef int (*ZT_WirePacketSendFunction)( typedef int (*ZT_PathCheckFunction)( ZT_Node *, /* Node */ void *, /* User ptr */ + uint64_t, /* ZeroTier address */ const struct sockaddr_storage *, /* Local address */ 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) Desried 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 */ + 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 get objects from persistent storage + */ + ZT_DataStoreGetFunction dataStoreGetFunction; + + /** + * REQUIRED: Function to store objects in persistent storage + */ + ZT_DataStorePutFunction dataStorePutFunction; + + /** + * 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 One node * * Note that this can take a few seconds the first time it's called, as it @@ -1634,25 +1654,11 @@ typedef int (*ZT_PathCheckFunction)( * * @param node Result: pointer is set to new node instance on success * @param uptr User pointer to pass to functions/callbacks + * @param callbacks Callback function configuration * @param now Current clock in milliseconds - * @param dataStoreGetFunction Function called to get objects from persistent storage - * @param dataStorePutFunction Function called to put objects in persistent storage - * @param virtualNetworkConfigFunction Function to be called when virtual LANs are created, deleted, or their config parameters change - * @param pathCheckFunction A function to check whether a path should be used for ZeroTier traffic, or NULL to allow any path - * @param eventCallback Function to receive status updates and non-fatal error notices * @return OK (0) or error code if a fatal error condition has occurred */ -enum ZT_ResultCode ZT_Node_new( - ZT_Node **node, - void *uptr, - uint64_t now, - ZT_DataStoreGetFunction dataStoreGetFunction, - ZT_DataStorePutFunction dataStorePutFunction, - ZT_WirePacketSendFunction wirePacketSendFunction, - ZT_VirtualNetworkFrameFunction virtualNetworkFrameFunction, - ZT_VirtualNetworkConfigFunction virtualNetworkConfigFunction, - ZT_PathCheckFunction pathCheckFunction, - ZT_EventCallback eventCallback); +enum ZT_ResultCode ZT_Node_new(ZT_Node **node,void *uptr,const struct ZT_Node_Callbacks *callbacks,uint64_t now); /** * Delete a node and free all resources it consumes @@ -1723,15 +1729,6 @@ enum ZT_ResultCode ZT_Node_processVirtualNetworkFrame( enum ZT_ResultCode ZT_Node_processBackgroundTasks(ZT_Node *node,uint64_t now,volatile uint64_t *nextBackgroundTaskDeadline); /** - * Set node's relay policy - * - * @param node Node instance - * @param rp New relay policy - * @return OK(0) or error code - */ -enum ZT_ResultCode ZT_Node_setRelayPolicy(ZT_Node *node,enum ZT_RelayPolicy rp); - -/** * Join a network * * This may generate calls to the port config callback before it returns, @@ -1808,6 +1805,29 @@ enum ZT_ResultCode ZT_Node_multicastSubscribe(ZT_Node *node,uint64_t nwid,uint64 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 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 + */ +enum ZT_ResultCode ZT_Node_orbit(ZT_Node *node,uint64_t moonWorldId,uint64_t moonSeed); + +/** + * Remove a moon (does nothing if not present) + * + * @param node Node instance + * @param moonWorldId World ID of moon to remove + * @return Error if anything bad happened + */ +enum ZT_ResultCode ZT_Node_deorbit(ZT_Node *node,uint64_t moonWorldId); + +/** * Get this node's 40-bit ZeroTier address * * @param node Node instance @@ -1894,6 +1914,20 @@ int ZT_Node_addLocalInterfaceAddress(ZT_Node *node,const struct sockaddr_storage 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 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 + */ +int ZT_Node_sendUserMessage(ZT_Node *node,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 |