ZeroTierOne/include/ZeroTierOne.h

854 lines
24 KiB
C
Raw Normal View History

/*
* ZeroTier One - Network Virtualization Everywhere
* Copyright (C) 2011-2015 ZeroTier, Inc.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* --
*
* ZeroTier may be used and distributed under the terms of the GPLv3, which
* are available at: http://www.gnu.org/licenses/gpl-3.0.html
*
* If you would like to embed ZeroTier into a commercial application or
* redistribute it in a modified binary form, please contact ZeroTier Networks
* LLC. Start here: http://www.zerotier.com/
*/
/*
* This defines the external C API for ZeroTier One, the core network
* virtualization engine.
*/
#ifndef ZT_ZEROTIERONE_H
#define ZT_ZEROTIERONE_H
#include <stdint.h>
// For the struct sockaddr_storage structure
#if defined(_WIN32) || defined(_WIN64)
#include <WinSock2.h>
#include <WS2tcpip.h>
#include <Windows.h>
#else /* not Windows */
#include <arpa/inet.h>
#include <netinet/in.h>
#endif /* Windows or not */
#ifdef __cplusplus
extern "C" {
#endif
/****************************************************************************/
/* Core constants */
/****************************************************************************/
/**
* Maximum MTU for ZeroTier virtual networks
*
* This is pretty much an unchangeable global constant. To make it change
* across nodes would require logic to send ICMP packet too big messages,
* which would complicate things. 1500 has been good enough on most LANs
* for ages, so a larger MTU should be fine for the forseeable future. This
* typically results in two UDP packets per single large frame. Experimental
* results seem to show that this is good. Larger MTUs resulting in more
* fragments seemed too brittle on slow/crummy links for no benefit.
*
* If this does change, also change it in tap.h in the tuntaposx code under
* mac-tap.
*
* Overhead for a normal frame split into two packets:
*
* 1414 = 1444 (typical UDP MTU) - 28 (packet header) - 2 (ethertype)
* 1428 = 1444 (typical UDP MTU) - 16 (fragment header)
* SUM: 2842
*
* We use 2800, which leaves some room for other payload in other types of
* messages such as multicast propagation or future support for bridging.
*/
#define ZT1_MAX_MTU 2800
/**
* Feature flag: this is an official ZeroTier, Inc. binary build (built with ZT_OFFICIAL_RELEASE)
*/
#define ZT1_FEATURE_FLAG_OFFICIAL 0x00000001
/**
* Feature flag: ZeroTier One was built to be thread-safe -- concurrent processXXX() calls are okay
*/
#define ZT1_FEATURE_FLAG_THREAD_SAFE 0x00000002
/**
* Feature flag: FIPS compliant build (not available yet, but reserved for future use if we ever do this)
*/
#define ZT1_FEATURE_FLAG_FIPS 0x00000004
/****************************************************************************/
/* Structures and other types */
/****************************************************************************/
/**
* Function return code: OK (0) or error results
*
* Fatal errors should be interpreted to mean that the node is no longer
* working correctly. They indicate serious problems such as build problems,
* an inaccessible data store, system configuration issues, or out of
* memory.
*/
enum ZT1_ResultCode
{
/**
* Operation completed normally
*/
ZT1_RESULT_OK = 0,
// Fatal errors (>0, <1000)
/**
* Ran out of memory
*/
ZT1_RESULT_FATAL_ERROR_OUT_OF_MEMORY = 1,
/**
* Data store is not writable or has failed
*/
ZT1_RESULT_FATAL_ERROR_DATA_STORE_FAILED = 2,
2015-04-01 23:27:14 +00:00
/**
* Internal error (e.g. unexpected exception, build problem, link problem, etc.)
*/
ZT1_RESULT_FATAL_ERROR_INTERNAL = 3,
// Non-fatal errors (>1000)
2015-04-01 23:27:14 +00:00
/**
* Invalid packet or failed authentication
*/
ZT1_RESULT_ERROR_PACKET_INVALID = 1000
};
/**
* Status codes sent to status update callback when things happen
*/
enum ZT1_Event
{
/**
* Node has been initialized
*
* This is the first event generated, and is always sent. It may occur
* before Node's constructor returns.
*/
ZT1_EVENT_UP = 0,
/**
* Node is offline -- network does not seem to be reachable by any available strategy
*/
ZT1_EVENT_OFFLINE = 1,
/**
* Node is online -- at least one upstream node appears reachable
*/
ZT1_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.
*/
ZT1_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?
*/
ZT1_EVENT_FATAL_ERROR_IDENTITY_COLLISION = 4,
/**
* A more recent version was observed on the network
*
* Right now this is only triggered if a hub or supernode reports a
* more recent version, and only once. It can be used to trigger a
* software update check.
*/
ZT1_EVENT_SAW_MORE_RECENT_VERSION = 5
};
/**
* 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;
/**
* Current maximum link desperation metric
*/
unsigned int desperation;
} ZT1_NodeStatus;
/**
* Virtual network status codes
*/
enum ZT1_VirtualNetworkStatus
{
/**
* Waiting for network configuration (also means revision == 0)
*/
ZT1_NETWORK_STATUS_WAITING = 0,
/**
* Configuration received and we are authorized
*/
ZT1_NETWORK_STATUS_AUTHORIZED = 1,
/**
* Netconf master told us 'nope'
*/
ZT1_NETWORK_STATUS_ACCESS_DENIED = 2,
/**
* Netconf master exists, but this virtual network does not
*/
ZT1_NETWORK_STATUS_NOT_FOUND = 3
};
/**
* Virtual network type codes
*/
enum ZT1_VirtualNetworkType
{
/**
* Private networks are authorized via certificates of membership
*/
ZT1_NETWORK_TYPE_PRIVATE = 0,
/**
* Public networks have no access control -- they'll always be AUTHORIZED
*/
ZT1_NETWORK_TYPE_PUBLIC = 1
};
/**
* An Ethernet multicast group
*/
typedef struct
{
/**
* MAC address (least significant 48 bits)
*/
uint64_t mac;
/**
* Additional distinguishing information (usually zero)
*/
unsigned long adi;
} ZT1_MulticastGroup;
/**
* Virtual LAN configuration
*/
typedef struct
{
/**
* 64-bit ZeroTier network ID
*/
uint64_t nwid;
/**
* Ethernet MAC (40 bits) that should be assigned to port
*/
uint64_t mac;
/**
* Network configuration request status
*/
enum ZT1_VirtualNetworkStatus status;
/**
* Network type
*/
enum ZT1_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;
/**
* Network config revision as reported by netconf master
*
* If this is zero, it means we're still waiting for our netconf.
*/
unsigned long netconfRevision;
/**
* 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.
*/
const struct sockaddr_storage *assignedAddresses;
/**
* Number of assigned addresses
*/
unsigned int assignedAddressCount;
/**
* Multicast group subscriptions
*/
ZT1_MulticastGroup *multicastSubscriptions;
/**
* Number of multicast group subscriptions
*/
unsigned int multicastSubscriptionCount;
/**
* Network name (from network configuration master)
*/
const char *networkName;
} ZT1_VirtualNetworkConfig;
/**
* A list of networks
*/
typedef struct
{
ZT1_VirtualNetworkConfig *networks;
unsigned long networkCount;
} ZT1_VirtualNetworkList;
2014-10-19 19:56:39 +00:00
/**
* Physical network path to a peer
*/
typedef struct
{
/**
* Address of endpoint
*/
struct sockaddr_storage address;
/**
* Time since last send in milliseconds or -1 for never
*/
long lastSend;
/**
* Time since last receive in milliseconds or -1 for never
*/
long lastReceive;
/**
* Time since last ping sent in milliseconds or -1 for never
*/
long lastPing;
2014-10-19 19:56:39 +00:00
/**
* Time since last firewall opener sent in milliseconds or -1 for never
*/
long lastFirewallOpener;
/**
* Total bytes sent
*/
uint64_t bytesSent;
/**
* Total bytes received
*/
uint64_t bytesReceived;
/**
* Is path fixed? (i.e. not learned, static)
*/
int fixed;
} ZT1_PeerPhysicalPath;
2014-10-19 19:56:39 +00:00
/**
* What trust hierarchy role does this peer have?
2014-10-19 19:56:39 +00:00
*/
enum ZT1_PeerRole {
2015-04-03 20:14:37 +00:00
ZT1_PEER_ROLE_NODE = 0, // ordinary node
ZT1_PEER_ROLE_HUB = 1, // locally federated hub
ZT1_PEER_ROLE_SUPERNODE = 2 // planetary supernode
2014-10-19 19:56:39 +00:00
};
/**
* Peer status result buffer
*/
typedef struct
{
/**
* ZeroTier binary 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 zero if unknown
*/
unsigned int latency;
2014-10-13 18:47:14 +00:00
/**
* What trust hierarchy role does this device have?
*/
enum ZT1_PeerRole role;
2014-10-13 18:47:14 +00:00
/**
* Array of network paths to peer
*/
ZT1_PeerPhysicalPath *paths;
/**
* Number of paths (size of paths[])
*/
unsigned long pathCount;
} ZT1_Peer;
/**
* List of peers
*/
typedef struct
{
ZT1_Peer *peers;
unsigned long peerCount;
} ZT1_PeerList;
2014-10-19 19:56:39 +00:00
/**
* An instance of a ZeroTier One node (opaque)
2014-10-19 19:56:39 +00:00
*/
typedef void ZT1_Node;
/****************************************************************************/
/* Callbacks used by Node API */
/****************************************************************************/
2014-10-19 19:56:39 +00:00
/**
* Callback called to update virtual port configuration
*
* This can be called at any time to update the configuration of a virtual
* network port. If a port is deleted (via leave() or otherwise) this is
* called with a NULL config parameter.
*
* This in turn should be used by the underlying implementation to create
* and configure tap devices to handle frames, etc.
*
* The supplied config pointer is not guaranteed to remain valid, so make
* a copy if you want one.
*/
typedef void (*ZT1_VirtualNetworkConfigCallback)(ZT1_Node *,uint64_t,const ZT1_VirtualNetworkConfig *);
/**
* Callback for status messages
*
* This is called whenever the node's status changes in some significant way.
*/
typedef void (*ZT1_StatusCallback)(ZT1_Node *,enum ZT1_Event);
/**
* Function to get an object from the data store
*
* Parameters: (1) object name, (2) buffer to fill, (3) size of buffer, (4)
* index in object to start reading, (5) result parameter that must be set
* to the actual size of the object if it exists.
*
* Object names can contain forward slash (/) path separators. They will
* never contain .. or backslash (\), so this is safe to map as a Unix-style
* path if the underlying storage permits. For security reasons we recommend
* returning errors if .. or \ are used.
*
* The function must return the actual number of bytes read. If the object
* doesn't exist, it should return -1. -2 should be returned on other errors
* such as errors accessing underlying storage.
*
* If the read doesn't fit in the buffer, the max number of bytes should be
* read. The caller may call the function multiple times to read the whole
* object.
*/
typedef long (*ZT1_DataStoreGetFunction)(ZT1_Node *,const char *,void *,unsigned long,unsigned long,unsigned long *);
/**
* Function to store an object in the data store
*
* Parameters: (1) node, (2) object name, (3) object data, (4) object size,
* and (5) secure? (bool). If secure is true, the file should be set readable
* and writable only to the user running ZeroTier One. What this means is
* platform-specific.
*
* Name semantics are the same as the get function. This must return zero on
* success. You can return any OS-specific error code on failure, as these
* may be visible in logs or error messages and might aid in debugging.
*
* A call to write 0 bytes with a null data pointer should be interpreted
* as a delete operation. The secure flag is not meaningful in this case.
*/
typedef int (*ZT1_DataStorePutFunction)(ZT1_Node *,const char *,const void *,unsigned long,int);
/**
* Function to send a ZeroTier packet out over the wire
*
2015-04-03 20:14:37 +00:00
* Parameters: (1) node, (2) address, (3) link desperation,
* (4) packet data, (5) packet data length.
*
* 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 (*ZT1_WirePacketSendFunction)(ZT1_Node *,const struct sockaddr_storage *,unsigned int,const void *,unsigned int);
/**
* Function to send a frame out to a virtual network port
*
* Parameters: (1) node, (2) network ID, (3) source MAC, (4) destination MAC,
* (5) ethertype, (6) VLAN ID, (7) frame data, (8) frame length.
*/
typedef void (*ZT1_VirtualNetworkFrameFunction)(ZT1_Node *,uint64_t,uint64_t,uint64_t,unsigned int,unsigned int,const void *,unsigned int);
/****************************************************************************/
/* C Node API */
/****************************************************************************/
/**
* Create a new ZeroTier One node
*
* Note that this can take a few seconds the first time it's called, as it
* will generate an identity.
*
* @param node Result: pointer is set to new node instance on success
* @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
2015-04-01 23:27:14 +00:00
* @param virtualNetworkConfigCallback Function to be called when virtual LANs are created, deleted, or their config parameters change
* @param statusCallback Function to receive status updates and non-fatal error notices
* @return OK (0) or error code if a fatal error condition has occurred
*/
enum ZT1_ResultCode ZT1_Node_new(
ZT1_Node **node,
uint64_t now,
2015-04-03 20:14:37 +00:00
ZT1_DataStoreGetFunction dataStoreGetFunction,
ZT1_DataStorePutFunction dataStorePutFunction,
ZT1_WirePacketSendFunction wirePacketSendFunction,
ZT1_VirtualNetworkFrameFunction virtualNetworkFrameFunction,
ZT1_VirtualNetworkConfigCallback virtualNetworkConfigCallback,
ZT1_StatusCallback statusCallback);
/**
* 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
*/
void ZT1_Node_delete(ZT1_Node *node);
/**
* Process a packet received from the physical wire
*
* @param node Node instance
* @param now Current clock in milliseconds
* @param remoteAddress Origin of packet
* @param linkDesperation Link desperation metric for link or protocol over which packet arrived
* @param packetData Packet data
* @param packetLength Packet length
* @param nextCallDeadline Result: set to deadline for next call to one of the three processXXX() methods
* @return OK (0) or error code if a fatal error condition has occurred
*/
enum ZT1_ResultCode ZT1_Node_processWirePacket(
ZT1_Node *node,
uint64_t now,
const struct sockaddr_storage *remoteAddress,
unsigned int linkDesperation,
const void *packetData,
unsigned int packetLength,
uint64_t *nextCallDeadline);
/**
* Process a frame from a virtual network port (tap)
*
* @param node Node instance
* @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 nextCallDeadline Result: set to deadline for next call to one of the three processXXX() methods
* @return OK (0) or error code if a fatal error condition has occurred
*/
enum ZT1_ResultCode ZT1_Node_processVirtualNetworkFrame(
ZT1_Node *node,
uint64_t now,
uint64_t nwid,
uint64_t sourceMac,
uint64_t destMac,
unsigned int etherType,
unsigned int vlanId,
const void *frameData,
unsigned int frameLength,
uint64_t *nextCallDeadline);
/**
* Perform required periodic operations even if no new frames or packets have arrived
*
* If the nextCallDeadline arrives and nothing has happened, call this method
* to do required background tasks like pinging and cleanup.
*
* @param node Node instance
* @param now Current clock in milliseconds
* @param nextCallDeadline Result: set to deadline for next call to one of the three processXXX() methods
* @return OK (0) or error code if a fatal error condition has occurred
*/
enum ZT1_ResultCode ZT1_Node_processNothing(ZT1_Node *node,uint64_t now,uint64_t *nextCallDeadline);
/**
* Join a network
*
* This may generate calls to the port config callback before it returns,
* or these may be deffered if a netconf is not available yet.
*
* @param node Node instance
* @param nwid 64-bit ZeroTier network ID
* @return OK (0) or error code if a fatal error condition has occurred
*/
enum ZT1_ResultCode ZT1_Node_join(ZT1_Node *node,uint64_t nwid);
/**
* 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.
*
* @param node Node instance
* @param nwid 64-bit network ID
* @return OK (0) or error code if a fatal error condition has occurred
*/
enum ZT1_ResultCode ZT1_Node_leave(ZT1_Node *node,uint64_t nwid);
/**
* 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.
*
* 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, default: 0)
* @return OK (0) or error code if a fatal error condition has occurred
*/
enum ZT1_ResultCode ZT1_Node_multicastSubscribe(ZT1_Node *node,uint64_t nwid,uint64_t multicastGroup,unsigned long multicastAdi = 0);
/**
* 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, default: 0)
* @return OK (0) or error code if a fatal error condition has occurred
*/
enum ZT1_ResultCode ZT1_Node_multicastUnsubscribe(ZT1_Node *node,uint64_t nwid,uint64_t multicastGroup,unsigned long multicastAdi = 0);
/**
* Get the status of this node
*
* @param node Node instance
* @param status Buffer to fill with current node status
*/
void ZT1_Node_status(ZT1_Node *node,ZT1_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
*/
ZT1_PeerList *ZT1_Node_peers(ZT1_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
*/
ZT1_VirtualNetworkConfig *ZT1_Node_networkConfig(ZT1_Node *node,uint64_t nwid);
/**
* Enumerate and get status of all networks
*
* @param node Node instance
* @return List of networks or NULL on failure
*/
ZT1_VirtualNetworkList *ZT1_Node_listNetworks(ZT1_Node *node);
/**
* Free a query result buffer
*
* Use this to free the return values of listNetworks(), listPeers(), etc.
*
2015-04-01 23:27:14 +00:00
* @param node Node instance
* @param qr Query result buffer
*/
2015-04-01 23:27:14 +00:00
void ZT1_Node_freeQueryResult(ZT1_Node *node,void *qr);
/**
* 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
*/
2015-04-01 01:17:11 +00:00
void ZT1_Node_setNetconfMaster(ZT1_Node *node,void *networkConfigMasterInstance);
/**
* Get ZeroTier One version
*
* @param major Result: major version
* @param minor Result: minor version
* @param revision Result: revision
* @param featureFlags: Result: feature flag bitmap
*/
void ZT1_version(int *major,int *minor,int *revision,unsigned long *featureFlags);
#ifdef __cplusplus
}
#endif
#endif