ZeroTierOne/node/Network.hpp

/*
 * 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: 2026-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.
 */
/****/

#ifndef ZT_NETWORK_HPP
#define ZT_NETWORK_HPP

#include "../include/ZeroTierOne.h"
#include "Address.hpp"
#include "AtomicCounter.hpp"
#include "CertificateOfMembership.hpp"
#include "Constants.hpp"
#include "Dictionary.hpp"
#include "Hashtable.hpp"
#include "MAC.hpp"
#include "Membership.hpp"
#include "Metrics.hpp"
#include "MulticastGroup.hpp"
#include "Multicaster.hpp"
#include "Mutex.hpp"
#include "NetworkConfig.hpp"
#include "SharedPtr.hpp"

#include <algorithm>
#include <map>
#include <stdexcept>
#include <stdint.h>
#include <string>
#include <vector>

#define ZT_NETWORK_MAX_INCOMING_UPDATES 3
#define ZT_NETWORK_MAX_UPDATE_CHUNKS    ((ZT_NETWORKCONFIG_DICT_CAPACITY / 1024) + 1)

namespace ZeroTier {

class RuntimeEnvironment;
class Peer;

/**
 * A virtual LAN
 */
class Network {
    friend class SharedPtr<Network>;

  public:
    /**
     * Broadcast multicast group: ff:ff:ff:ff:ff:ff / 0
     */
    static const MulticastGroup BROADCAST;

    /**
     * Compute primary controller device ID from network ID
     */
    static inline Address controllerFor(uint64_t nwid)
    {
        return Address(nwid >> 24);
    }

    /**
     * Construct a new network
     *
     * Note that init() should be called immediately after the network is
     * constructed to actually configure the port.
     *
     * @param renv Runtime environment
     * @param tPtr Thread pointer to be handed through to any callbacks called as a result of this call
     * @param nwid Network ID
     * @param uptr Arbitrary pointer used by externally-facing API (for user use)
     * @param nconf Network config, if known
     */
    Network(const RuntimeEnvironment* renv, void* tPtr, uint64_t nwid, void* uptr, const NetworkConfig* nconf);

    ~Network();

    inline uint64_t id() const
    {
        return _id;
    }
    inline Address controller() const
    {
        return Address(_id >> 24);
    }
    inline bool multicastEnabled() const
    {
        return (_config.multicastLimit > 0);
    }
    inline bool hasConfig() const
    {
        return (_config);
    }
    inline uint64_t lastConfigUpdate() const
    {
        return _lastConfigUpdate;
    }
    inline ZT_VirtualNetworkStatus status() const
    {
        Mutex::Lock _l(_lock);
        return _status();
    }
    inline const NetworkConfig& config() const
    {
        return _config;
    }
    inline const MAC& mac() const
    {
        return _mac;
    }

    /**
     * Apply filters to an outgoing packet
     *
     * This applies filters from our network config and, if that doesn't match,
     * our capabilities in ascending order of capability ID. Additional actions
     * such as TEE may be taken, and credentials may be pushed, so this is not
     * side-effect-free. It's basically step one in sending something over VL2.
     *
     * @param tPtr Thread pointer to be handed through to any callbacks called as a result of this call
     * @param noTee If true, do not TEE anything anywhere (for two-pass filtering as done with multicast and bridging)
     * @param ztSource Source ZeroTier address
     * @param ztDest Destination ZeroTier address
     * @param macSource Ethernet layer source address
     * @param macDest Ethernet layer destination address
     * @param frameData Ethernet frame data
     * @param frameLen Ethernet frame payload length
     * @param etherType 16-bit ethernet type ID
     * @param vlanId 16-bit VLAN ID
     * @return True if packet should be sent, false if dropped or redirected
     */
    bool filterOutgoingPacket(
        void* tPtr,
        const bool noTee,
        const Address& ztSource,
        const Address& ztDest,
        const MAC& macSource,
        const MAC& macDest,
        const uint8_t* frameData,
        const unsigned int frameLen,
        const unsigned int etherType,
        const unsigned int vlanId,
        uint8_t& qosBucket);

    /**
     * Apply filters to an incoming packet
     *
     * This applies filters from our network config and, if that doesn't match,
     * the peer's capabilities in ascending order of capability ID. If there is
     * a match certain actions may be taken such as sending a copy of the packet
     * to a TEE or REDIRECT target.
     *
     * @param tPtr Thread pointer to be handed through to any callbacks called as a result of this call
     * @param sourcePeer Source Peer
     * @param ztDest Destination ZeroTier address
     * @param macSource Ethernet layer source address
     * @param macDest Ethernet layer destination address
     * @param frameData Ethernet frame data
     * @param frameLen Ethernet frame payload length
     * @param etherType 16-bit ethernet type ID
     * @param vlanId 16-bit VLAN ID
     * @return 0 == drop, 1 == accept, 2 == accept even if bridged
     */
    int filterIncomingPacket(
        void* tPtr,
        const SharedPtr<Peer>& sourcePeer,
        const Address& ztDest,
        const MAC& macSource,
        const MAC& macDest,
        const uint8_t* frameData,
        const unsigned int frameLen,
        const unsigned int etherType,
        const unsigned int vlanId);

    /**
     * Check whether we are subscribed to a multicast group
     *
     * @param mg Multicast group
     * @param includeBridgedGroups If true, also check groups we've learned via bridging
     * @return True if this network endpoint / peer is a member
     */
    bool subscribedToMulticastGroup(const MulticastGroup& mg, bool includeBridgedGroups) const;

    /**
     * Subscribe to a multicast group
     *
     * @param tPtr Thread pointer to be handed through to any callbacks called as a result of this call
     * @param mg New multicast group
     */
    void multicastSubscribe(void* tPtr, const MulticastGroup& mg);

    /**
     * Unsubscribe from a multicast group
     *
     * @param mg Multicast group
     */
    void multicastUnsubscribe(const MulticastGroup& mg);

    /**
     * Handle an inbound network config chunk
     *
     * This is called from IncomingPacket to handle incoming network config
     * chunks via OK(NETWORK_CONFIG_REQUEST) or NETWORK_CONFIG. It verifies
     * each chunk and once assembled applies the configuration.
     *
     * @param tPtr Thread pointer to be handed through to any callbacks called as a result of this call
     * @param packetId Packet ID or 0 if none (e.g. via cluster path)
     * @param source Address of sender of chunk or NULL if none (e.g. via cluster path)
     * @param chunk Buffer containing chunk
     * @param ptr Index of chunk and related fields in packet
     * @return Update ID if update was fully assembled and accepted or 0 otherwise
     */
    uint64_t handleConfigChunk(void* tPtr, const uint64_t packetId, const Address& source, const Buffer<ZT_PROTO_MAX_PACKET_LENGTH>& chunk, unsigned int ptr);

    /**
     * Set network configuration
     *
     * @param tPtr Thread pointer to be handed through to any callbacks called as a result of this call
     * @param nconf Network configuration
     * @param saveToDisk Save to disk? Used during loading, should usually be true otherwise.
     * @return 0 == bad, 1 == accepted but duplicate/unchanged, 2 == accepted and new
     */
    int setConfiguration(void* tPtr, const NetworkConfig& nconf, bool saveToDisk);

    /**
     * Set netconf failure to 'access denied' -- called in IncomingPacket when controller reports this
     */
    inline void setAccessDenied(void* tPtr)
    {
        Mutex::Lock _l(_lock);
        _netconfFailure = NETCONF_FAILURE_ACCESS_DENIED;

        _sendUpdateEvent(tPtr);
    }

    /**
     * Set netconf failure to 'not found' -- called by IncomingPacket when controller reports this
     */
    inline void setNotFound(void* tPtr)
    {
        Mutex::Lock _l(_lock);
        _netconfFailure = NETCONF_FAILURE_NOT_FOUND;

        _sendUpdateEvent(tPtr);
    }

    /**
     * Set netconf failure to 'authentication required' possibly with an authorization URL
     */
    inline void setAuthenticationRequired(void* tPtr, const char* url)
    {
        Mutex::Lock _l(_lock);
        _netconfFailure = NETCONF_FAILURE_AUTHENTICATION_REQUIRED;
        _authenticationURL = (url) ? url : "";
        _config.ssoEnabled = true;
        _config.ssoVersion = 0;
        _sendUpdateEvent(tPtr);
    }

    /**
     * set netconf failure to 'authentication required' along with info needed
     * for sso full flow authentication.
     */
    void setAuthenticationRequired(void* tPtr, const char* issuerURL, const char* centralEndpoint, const char* clientID, const char* ssoProvider, const char* nonce, const char* state);

    /**
     * Causes this network to request an updated configuration from its master node now
     *
     * @param tPtr Thread pointer to be handed through to any callbacks called as a result of this call
     */
    void requestConfiguration(void* tPtr);

    /**
     * Determine whether this peer is permitted to communicate on this network
     *
     * @param tPtr Thread pointer to be handed through to any callbacks called as a result of this call
     * @param peer Peer to check
     */
    bool gate(void* tPtr, const SharedPtr<Peer>& peer);

    /**
     * Check whether a given peer has recently had an association with this network
     *
     * This checks whether a peer has communicated with us recently about this
     * network and has possessed a valid certificate of membership. This may return
     * true even if the peer has been offline for a while or no longer has a valid
     * certificate of membership but had one recently.
     *
     * @param addr Peer address
     * @return True if peer has recently associated
     */
    bool recentlyAssociatedWith(const Address& addr);

    /**
     * Do periodic cleanup and housekeeping tasks
     */
    void clean();

    /**
     * Push state to members such as multicast group memberships and latest COM (if needed)
     *
     * @param tPtr Thread pointer to be handed through to any callbacks called as a result of this call
     */
    inline void sendUpdatesToMembers(void* tPtr)
    {
        Mutex::Lock _l(_lock);
        _sendUpdatesToMembers(tPtr, (const MulticastGroup*)0);
    }

    /**
     * Find the node on this network that has this MAC behind it (if any)
     *
     * @param mac MAC address
     * @return ZeroTier address of bridge to this MAC
     */
    inline Address findBridgeTo(const MAC& mac) const
    {
        Mutex::Lock _l(_lock);
        const Address* const br = _remoteBridgeRoutes.get(mac);
        return ((br) ? *br : Address());
    }

    /**
     * @return True if QoS is in effect for this network
     */
    inline bool qosEnabled()
    {
        return false;
    }

    /**
     * Set a bridge route
     *
     * @param mac MAC address of destination
     * @param addr Bridge this MAC is reachable behind
     */
    void learnBridgeRoute(const MAC& mac, const Address& addr);

    /**
     * Learn a multicast group that is bridged to our tap device
     *
     * @param tPtr Thread pointer to be handed through to any callbacks called as a result of this call
     * @param mg Multicast group
     * @param now Current time
     */
    void learnBridgedMulticastGroup(void* tPtr, const MulticastGroup& mg, int64_t now);

    /**
     * Validate a credential and learn it if it passes certificate and other checks
     */
    Membership::AddCredentialResult addCredential(void* tPtr, const CertificateOfMembership& com);

    /**
     * Validate a credential and learn it if it passes certificate and other checks
     */
    inline Membership::AddCredentialResult addCredential(void* tPtr, const Capability& cap)
    {
        if (cap.networkId() != _id) {
            return Membership::ADD_REJECTED;
        }
        Mutex::Lock _l(_lock);
        return _membership(cap.issuedTo()).addCredential(RR, tPtr, _config, cap);
    }

    /**
     * Validate a credential and learn it if it passes certificate and other checks
     */
    inline Membership::AddCredentialResult addCredential(void* tPtr, const Tag& tag)
    {
        if (tag.networkId() != _id) {
            return Membership::ADD_REJECTED;
        }
        Mutex::Lock _l(_lock);
        return _membership(tag.issuedTo()).addCredential(RR, tPtr, _config, tag);
    }

    /**
     * Validate a credential and learn it if it passes certificate and other checks
     */
    Membership::AddCredentialResult addCredential(void* tPtr, const Address& sentFrom, const Revocation& rev);

    /**
     * Validate a credential and learn it if it passes certificate and other checks
     */
    inline Membership::AddCredentialResult addCredential(void* tPtr, const CertificateOfOwnership& coo)
    {
        if (coo.networkId() != _id) {
            return Membership::ADD_REJECTED;
        }
        Mutex::Lock _l(_lock);
        return _membership(coo.issuedTo()).addCredential(RR, tPtr, _config, coo);
    }

    /**
     * Force push credentials (COM, etc.) to a peer now
     *
     * @param tPtr Thread pointer to be handed through to any callbacks called as a result of this call
     * @param to Destination peer address
     * @param now Current time
     */
    inline void peerRequestedCredentials(void* tPtr, const Address& to, const int64_t now)
    {
        Mutex::Lock _l(_lock);
        Membership& m = _membership(to);
        const int64_t lastPushed = m.lastPushedCredentials();
        if ((lastPushed < _lastConfigUpdate) || ((now - lastPushed) > ZT_PEER_CREDENTIALS_REQUEST_RATE_LIMIT)) {
            m.pushCredentials(RR, tPtr, now, to, _config);
        }
    }

    /**
     * Push credentials if we haven't done so in a very long time
     *
     * @param tPtr Thread pointer to be handed through to any callbacks called as a result of this call
     * @param to Destination peer address
     * @param now Current time
     */
    inline void pushCredentialsIfNeeded(void* tPtr, const Address& to, const int64_t now)
    {
        Mutex::Lock _l(_lock);
        Membership& m = _membership(to);
        const int64_t lastPushed = m.lastPushedCredentials();
        if ((lastPushed < _lastConfigUpdate) || ((now - lastPushed) > ZT_PEER_ACTIVITY_TIMEOUT)) {
            m.pushCredentials(RR, tPtr, now, to, _config);
        }
    }

    /**
     * Destroy this network
     *
     * This sets the network to completely remove itself on delete. This also prevents the
     * call of the normal port shutdown event on delete.
     */
    void destroy();

    /**
     * Get this network's config for export via the ZT core API
     *
     * @param ec Buffer to fill with externally-visible network configuration
     */
    inline void externalConfig(ZT_VirtualNetworkConfig* ec) const
    {
        Mutex::Lock _l(_lock);
        _externalConfig(ec);
    }

    /**
     * @return Externally usable pointer-to-pointer exported via the core API
     */
    inline void** userPtr()
    {
        return &_uPtr;
    }

  private:
    ZT_VirtualNetworkStatus _status() const;
    void _externalConfig(ZT_VirtualNetworkConfig* ec) const;   // assumes _lock is locked
    bool _gate(const SharedPtr<Peer>& peer);
    void _sendUpdatesToMembers(void* tPtr, const MulticastGroup* const newMulticastGroup);
    void _announceMulticastGroupsTo(void* tPtr, const Address& peer, const std::vector<MulticastGroup>& allMulticastGroups);
    std::vector<MulticastGroup> _allMulticastGroups() const;
    Membership& _membership(const Address& a);
    void _sendUpdateEvent(void* tPtr);

    const RuntimeEnvironment* const RR;
    void* _uPtr;
    const uint64_t _id;
    std::string _nwidStr;
    uint64_t _lastAnnouncedMulticastGroupsUpstream;
    MAC _mac;   // local MAC address
    bool _portInitialized;

    std::vector<MulticastGroup> _myMulticastGroups;                 // multicast groups that we belong to (according to tap)
    Hashtable<MulticastGroup, uint64_t> _multicastGroupsBehindMe;   // multicast groups that seem to be behind us and when we last saw them (if we are a bridge)
    Hashtable<MAC, Address> _remoteBridgeRoutes;                    // remote addresses where given MACs are reachable (for tracking devices behind remote bridges)

    NetworkConfig _config;
    int64_t _lastConfigUpdate;

    struct _IncomingConfigChunk {
        _IncomingConfigChunk()
        {
            memset(this, 0, sizeof(_IncomingConfigChunk));
        }
        uint64_t ts;
        uint64_t updateId;
        uint64_t haveChunkIds[ZT_NETWORK_MAX_UPDATE_CHUNKS];
        unsigned long haveChunks;
        unsigned long haveBytes;
        Dictionary<ZT_NETWORKCONFIG_DICT_CAPACITY> data;
    };
    _IncomingConfigChunk _incomingConfigChunks[ZT_NETWORK_MAX_INCOMING_UPDATES];

    bool _destroyed;

    enum { NETCONF_FAILURE_NONE, NETCONF_FAILURE_ACCESS_DENIED, NETCONF_FAILURE_NOT_FOUND, NETCONF_FAILURE_INIT_FAILED, NETCONF_FAILURE_AUTHENTICATION_REQUIRED } _netconfFailure;
    int _portError;   // return value from port config callback
    std::string _authenticationURL;

    Hashtable<Address, Membership> _memberships;

    Mutex _lock;

    AtomicCounter __refCount;

    prometheus::simpleapi::gauge_metric_t _num_multicast_groups;
    prometheus::simpleapi::counter_metric_t _incoming_packets_accepted;
    prometheus::simpleapi::counter_metric_t _incoming_packets_dropped;
    prometheus::simpleapi::counter_metric_t _outgoing_packets_accepted;
    prometheus::simpleapi::counter_metric_t _outgoing_packets_dropped;
};

}   // namespace ZeroTier

#endif