/*
 * Copyright (c)2013-2020 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: 2024-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_PROTOCOL_HPP
#define ZT_PROTOCOL_HPP

#include "Constants.hpp"
#include "AES.hpp"
#include "Salsa20.hpp"
#include "Poly1305.hpp"
#include "LZ4.hpp"
#include "Buf.hpp"

/**
 * Protocol version -- incremented only for major changes
 *
 * 1  - 0.2.0 ... 0.2.5
 * 2  - 0.3.0 ... 0.4.5
 *    + Added signature and originating peer to multicast frame
 *    + Double size of multicast frame bloom filter
 * 3  - 0.5.0 ... 0.6.0
 *    + Yet another multicast redesign
 *    + New crypto completely changes key agreement cipher
 * 4  - 0.6.0 ... 1.0.6
 *    + BREAKING CHANGE: New identity format based on hashcash design
 * 5  - 1.1.0 ... 1.1.5
 *    + Supports echo
 *    + Supports in-band world (root server definition) updates
 *    + Clustering! (Though this will work with protocol v4 clients.)
 *    + Otherwise backward compatible with protocol v4
 * 6  - 1.1.5 ... 1.1.10
 *    + Network configuration format revisions including binary values
 * 7  - 1.1.10 ... 1.1.17
 *    + Introduce trusted paths for local SDN use
 * 8  - 1.1.17 ... 1.2.0
 *    + Multipart network configurations for large network configs
 *    + Tags and Capabilities
 *    + inline push of CertificateOfMembership deprecated
 * 9  - 1.2.0 ... 1.2.14
 * 10 - 1.4.0 ... 1.6.0
 *    + Multipath capability and load balancing
 * 11 - 2.0.0 ... CURRENT
 *    + Peer-to-peer multicast replication
 *    + Old planet/moon stuff is DEAD!
 *    + AES encryption support
 *    + NIST P-384 (type 1) identities
 *    + Ephemeral keys
 */
#define ZT_PROTO_VERSION 11

/**
 * Packet buffer size (can be changed)
 */
#define ZT_PROTO_MAX_PACKET_LENGTH (ZT_MAX_PACKET_FRAGMENTS * ZT_DEFAULT_PHYSMTU)

/**
 * Minimum viable packet length (a.k.a. header length)
 */
#define ZT_PROTO_MIN_PACKET_LENGTH 28

/**
 * Index at which the encrypted section of a packet begins
 */
#define ZT_PROTO_PACKET_ENCRYPTED_SECTION_START 27


/**
 * Index at which packet payload begins (after verb)
 */
#define ZT_PROTO_PACKET_PAYLOAD_START 28

/**
 * Maximum hop count allowed by packet structure (3 bits, 0-7)
 *
 * This is a protocol constant. It's the maximum allowed by the length
 * of the hop counter -- three bits. See node/Constants.hpp for the
 * pragmatic forwarding limit, which is typically lower.
 */
#define ZT_PROTO_MAX_HOPS 7

/**
 * NONE/Poly1305 (using Salsa20/12 to generate poly1305 key)
 */
#define ZT_PROTO_CIPHER_SUITE__POLY1305_NONE 0

/**
 * Salsa2012/Poly1305
 */
#define ZT_PROTO_CIPHER_SUITE__POLY1305_SALSA2012 1

/**
 * No encryption or authentication at all
 *
 * For trusted paths the MAC field is the trusted path ID.
 */
#define ZT_PROTO_CIPHER_SUITE__NONE 2

/**
 * AES-GCM with AES-256
 */
#define ZT_PROTO_CIPHER_SUITE__AES_GCM 3

/**
 * Magic number indicating a fragment
 */
#define ZT_PACKET_FRAGMENT_INDICATOR 0xff

/**
 * Minimum viable fragment length
 */
#define ZT_PROTO_MIN_FRAGMENT_LENGTH 16

/**
 * Index at which packet fragment payload starts
 */
#define ZT_PROTO_PACKET_FRAGMENT_PAYLOAD_START_AT 16

/**
 * Header flag indicating that a packet is fragmented and more fragments should be expected
 */
#define ZT_PROTO_FLAG_FRAGMENTED 0x40

/**
 * Verb flag indicating payload is compressed with LZ4
 */
#define ZT_PROTO_VERB_FLAG_COMPRESSED 0x80

/**
 * Signed locator for this node
 */
#define ZT_PROTO_HELLO_NODE_META_LOCATOR "l"

/**
 * Ephemeral C25519 public key
 */
#define ZT_PROTO_HELLO_NODE_META_EPHEMERAL_KEY_C25519 "e0"

/**
 * Ephemeral NIST P-384 public key
 */
#define ZT_PROTO_HELLO_NODE_META_EPHEMERAL_KEY_P384 "e1"

/**
 * Addresses of ZeroTier nodes to whom this node will relay or one entry for 0000000000 if promiscuous.
 */
#define ZT_PROTO_HELLO_NODE_META_WILL_RELAY_TO "r"

/**
 * X coordinate of your node (sent in OK(HELLO))
 */
#define ZT_PROTO_HELLO_NODE_META_LOCATION_X "gX"

/**
 * Y coordinate of your node (sent in OK(HELLO))
 */
#define ZT_PROTO_HELLO_NODE_META_LOCATION_Y "gY"

/**
 * Z coordinate of your node (sent in OK(HELLO))
 */
#define ZT_PROTO_HELLO_NODE_META_LOCATION_Z "gZ"

/****************************************************************************/

/*
 * Packet format:
 *   <[8] 64-bit packet ID / crypto IV>
 *   <[5] destination ZT address>
 *   <[5] source ZT address>
 *   <[1] flags/cipher/hops>
 *   <[8] 64-bit MAC (or trusted path ID in trusted path mode)>
 *   [... -- begin encryption envelope -- ...]
 *   <[1] encrypted flags (MS 3 bits) and verb (LS 5 bits)>
 *   [... verb-specific payload ...]
 *
 * Packets smaller than 28 bytes are invalid and silently discarded.
 *
 * The flags/cipher/hops bit field is: FFCCCHHH where C is a 3-bit cipher
 * selection allowing up to 7 cipher suites, F is outside-envelope flags,
 * and H is hop count.
 *
 * The three-bit hop count is the only part of a packet that is mutable in
 * transit without invalidating the MAC. All other bits in the packet are
 * immutable. This is because intermediate nodes can increment the hop
 * count up to 7 (protocol max).
 *
 * For unencrypted packets, MAC is computed on plaintext. Only HELLO is ever
 * sent in the clear, as it's the "here is my public key" message.
 *
 * Fragments are sent if a packet is larger than UDP MTU. The first fragment
 * is sent with its normal header with the fragmented flag set. Remaining
 * fragments are sent this way.
 *
 * The fragmented bit indicates that there is at least one fragment. Fragments
 * themselves contain the total, so the receiver must "learn" this from the
 * first fragment it receives.
 *
 * Fragments are sent with the following format:
 *   <[8] packet ID of packet whose fragment this belongs to>
 *   <[5] destination ZT address>
 *   <[1] 0xff, a reserved address, signals that this isn't a normal packet>
 *   <[1] total fragments (most significant 4 bits), fragment no (LS 4 bits)>
 *   <[1] ZT hop count (top 5 bits unused and must be zero)>
 *   <[...] fragment data>
 *
 * The protocol supports a maximum of 16 fragments. If a fragment is received
 * before its main packet header, it should be cached for a brief period of
 * time to see if its parent arrives. Loss of any fragment constitutes packet
 * loss; there is no retransmission mechanism. The receiver must wait for full
 * receipt to authenticate and decrypt; there is no per-fragment MAC. (But if
 * fragments are corrupt, the MAC will fail for the whole assembled packet.)
 */

namespace ZeroTier {
namespace Protocol {

/**
 * Packet verb (message type)
 */
enum Verb
{
	VERB_NOP = 0x00,

	/**
	 * Announcement of a node's existence and vitals:
	 *   <[1] protocol version>
	 *   <[1] software major version>
	 *   <[1] software minor version>
	 *   <[2] software revision>
	 *   <[8] timestamp for determining latency>
	 *   <[...] binary serialized identity>
	 *   <[...] physical destination address of packet>
	 *   [... begin encrypted region ...]
	 *   <[2] 16-bit reserved (legacy) field, always 0>
	 *   <[2] 16-bit length of meta-data dictionary>
	 *   <[...] meta-data dictionary>
	 *   [... end encrypted region ...]
	 *   <[48] HMAC-SHA384 of all fields to this point (as plaintext)>
	 *
	 * HELLO is sent with authentication but without the usual encryption so
	 * that peers can exchange identities.
	 *
	 * Destination address is the actual wire address to which the packet
	 * was sent. See InetAddress::serialize() for format.
	 *
	 * Starting at "begin encrypted section" the reset of the packet is
	 * encrypted with Salsa20/12. This is not the normal packet encryption
	 * and is technically not necessary as nothing in HELLO is secret. It
	 * exists merely to shield meta-data info from passive listeners to
	 * slightly improve privacy, and for backward compatibility with older
	 * nodes that required it.
	 *
	 * HELLO (and its OK response) ends with a large 384-bit HMAC to allow
	 * identity exchanges to be authenticated with additional strength beyond
	 * ordinary packet authentication.
	 *
	 * OK payload:
	 *   <[8] HELLO timestamp field echo>
	 *   <[1] protocol version>
	 *   <[1] software major version>
	 *   <[1] software minor version>
	 *   <[2] software revision>
	 *   <[...] physical destination address of packet>
	 *   <[2] 16-bit reserved (legacy) field, always 0>
	 *   <[2] 16-bit length of meta-data dictionary>
	 *   <[...] meta-data dictionary>
	 *   <[48] HMAC-SHA384 of all fields to this point (as plaintext)>
	 *
	 * With the exception of the timestamp, the other fields pertain to the
	 * respondent who is sending OK and are not echoes.
	 *
	 * ERROR has no payload.
	 */
	VERB_HELLO = 0x01,

	/**
	 * Error response:
	 *   <[1] in-re verb>
	 *   <[8] in-re packet ID>
	 *   <[1] error code>
	 *   <[...] error-dependent payload>
	 *
	 * If this is not in response to a single packet then verb can be
	 * NOP and packet ID can be zero.
	 */
	VERB_ERROR = 0x02,

	/**
	 * Success response:
	 *   <[1] in-re verb>
	 *   <[8] in-re packet ID>
	 *   <[...] request-specific payload>
	 */
	VERB_OK = 0x03,

	/**
	 * Query an identity by address:
	 *   <[5] address to look up>
	 *   [<[...] additional addresses to look up>
	 *
	 * OK response payload:
	 *   <[...] identity>
	 *   <[...] locator>
	 *   [... additional identity/locator pairs]
	 *
	 * If the address is not found, no response is generated. The semantics
	 * of WHOIS is similar to ARP and NDP in that persistent retrying can
	 * be performed.
	 *
	 * It is possible for an identity but a null/empty locator to be returned
	 * if no locator is known for a node. Older versions will also send no
	 * locator field at all.
	 */
	VERB_WHOIS = 0x04,

	/**
	 * Relay-mediated NAT traversal or firewall punching initiation:
	 *   <[1] flags (unused, currently 0)>
	 *   <[5] ZeroTier address of peer that might be found at this address>
	 *   <[2] 16-bit protocol address port>
	 *   <[1] protocol address length (4 for IPv4, 16 for IPv6)>
	 *   <[...] protocol address (network byte order)>
	 *
	 * An upstream node can send this to inform both sides of a relay of
	 * information they might use to establish a direct connection.
	 *
	 * Upon receipt a peer sends HELLO to establish a direct link.
	 *
	 * No OK or ERROR is generated.
	 */
	VERB_RENDEZVOUS = 0x05,

	/**
	 * ZT-to-ZT unicast ethernet frame (shortened EXT_FRAME):
	 *   <[8] 64-bit network ID>
	 *   <[2] 16-bit ethertype>
	 *   <[...] ethernet payload>
	 *
	 * MAC addresses are derived from the packet's source and destination
	 * ZeroTier addresses. This is a shortened EXT_FRAME that elides full
	 * Ethernet framing and other optional flags and features when they
	 * are not necessary.
	 *
	 * ERROR may be generated if a membership certificate is needed for a
	 * closed network. Payload will be network ID.
	 */
	VERB_FRAME = 0x06,

	/**
	 * Full Ethernet frame with MAC addressing and optional fields:
	 *   <[8] 64-bit network ID>
	 *   <[1] flags>
	 *   <[6] destination MAC or all zero for destination node>
	 *   <[6] source MAC or all zero for node of origin>
	 *   <[2] 16-bit ethertype>
	 *   <[...] ethernet payload>
	 *
	 * Flags:
	 *   0x01 - Certificate of network membership attached (DEPRECATED)
	 *   0x02 - Most significant bit of subtype (see below)
	 *   0x04 - Middle bit of subtype (see below)
	 *   0x08 - Least significant bit of subtype (see below)
	 *   0x10 - ACK requested in the form of OK(EXT_FRAME)
	 *
	 * Subtypes (0..7):
	 *   0x0 - Normal frame (bridging can be determined by checking MAC)
	 *   0x1 - TEEd outbound frame
	 *   0x2 - REDIRECTed outbound frame
	 *   0x3 - WATCHed outbound frame (TEE with ACK, ACK bit also set)
	 *   0x4 - TEEd inbound frame
	 *   0x5 - REDIRECTed inbound frame
	 *   0x6 - WATCHed inbound frame
	 *   0x7 - (reserved for future use)
	 *
	 * An extended frame carries full MAC addressing, making it a
	 * superset of VERB_FRAME. If 0x20 is set then p2p or hub and
	 * spoke multicast propagation is requested.
	 *
	 * OK payload (if ACK flag is set):
	 *   <[8] 64-bit network ID>
	 *   <[1] flags>
	 *   <[6] destination MAC or all zero for destination node>
	 *   <[6] source MAC or all zero for node of origin>
	 *   <[2] 16-bit ethertype>
	 */
	VERB_EXT_FRAME = 0x07,

	/**
	 * ECHO request (a.k.a. ping):
	 *   <[...] arbitrary payload>
	 *
	 * This generates OK with a copy of the transmitted payload. No ERROR
	 * is generated. Response to ECHO requests is optional and ECHO may be
	 * ignored if a node detects a possible flood.
	 */
	VERB_ECHO = 0x08,

	/**
	 * Announce interest in multicast group(s):
	 *   <[8] 64-bit network ID>
	 *   <[6] multicast Ethernet address>
	 *   <[4] multicast additional distinguishing information (ADI)>
	 *   [... additional tuples of network/address/adi ...]
	 *
	 * LIKEs may be sent to any peer, though a good implementation should
	 * restrict them to peers on the same network they're for and to network
	 * controllers and root servers. In the current network, root servers
	 * will provide the service of final multicast cache.
	 */
	VERB_MULTICAST_LIKE = 0x09,

	/**
	 * Network credentials push:
	 *   [<[...] one or more certificates of membership>]
	 *   <[1] 0x00, null byte marking end of COM array>
	 *   <[2] 16-bit number of capabilities>
	 *   <[...] one or more serialized Capability>
	 *   <[2] 16-bit number of tags>
	 *   <[...] one or more serialized Tags>
	 *   <[2] 16-bit number of revocations>
	 *   <[...] one or more serialized Revocations>
	 *   <[2] 16-bit number of certificates of ownership>
	 *   <[...] one or more serialized CertificateOfOwnership>
	 *
	 * This can be sent by anyone at any time to push network credentials.
	 * These will of course only be accepted if they are properly signed.
	 * Credentials can be for any number of networks.
	 *
	 * The use of a zero byte to terminate the COM section is for legacy
	 * backward compatibility. Newer fields are prefixed with a length.
	 *
	 * OK/ERROR are not generated.
	 */
	VERB_NETWORK_CREDENTIALS = 0x0a,

	/**
	 * Network configuration request:
	 *   <[8] 64-bit network ID>
	 *   <[2] 16-bit length of request meta-data dictionary>
	 *   <[...] string-serialized request meta-data>
	 *   <[8] 64-bit revision of netconf we currently have>
	 *   <[8] 64-bit timestamp of netconf we currently have>
	 *
	 * This message requests network configuration from a node capable of
	 * providing it.
	 *
	 * Responses to this are always whole configs intended for the recipient.
	 * For patches and other updates a NETWORK_CONFIG is sent instead.
	 *
	 * It would be valid and correct as of 1.2.0 to use NETWORK_CONFIG always,
	 * but OK(NETWORK_CONFIG_REQUEST) should be sent for compatibility.
	 *
	 * OK response payload:
	 *   <[8] 64-bit network ID>
	 *   <[2] 16-bit length of network configuration dictionary chunk>
	 *   <[...] network configuration dictionary (may be incomplete)>
	 *   [ ... end of legacy single chunk response ... ]
	 *   <[1] 8-bit flags>
	 *   <[8] 64-bit config update ID (should never be 0)>
	 *   <[4] 32-bit total length of assembled dictionary>
	 *   <[4] 32-bit index of chunk>
	 *   [ ... end signed portion ... ]
	 *   <[1] 8-bit chunk signature type>
	 *   <[2] 16-bit length of chunk signature>
	 *   <[...] chunk signature>
	 *
	 * The chunk signature signs the entire payload of the OK response.
	 * Currently only one signature type is supported: ed25519 (1).
	 *
	 * Each config chunk is signed to prevent memory exhaustion or
	 * traffic crowding DOS attacks against config fragment assembly.
	 *
	 * If the packet is from the network controller it is permitted to end
	 * before the config update ID or other chunking related or signature
	 * fields. This is to support older controllers that don't include
	 * these fields and may be removed in the future.
	 *
	 * ERROR response payload:
	 *   <[8] 64-bit network ID>
	 */
	VERB_NETWORK_CONFIG_REQUEST = 0x0b,

	/**
	 * Network configuration data push:
	 *   <[8] 64-bit network ID>
	 *   <[2] 16-bit length of network configuration dictionary chunk>
	 *   <[...] network configuration dictionary (may be incomplete)>
	 *   <[1] 8-bit flags>
	 *   <[8] 64-bit config update ID (should never be 0)>
	 *   <[4] 32-bit total length of assembled dictionary>
	 *   <[4] 32-bit index of chunk>
	 *   [ ... end signed portion ... ]
	 *   <[1] 8-bit chunk signature type>
	 *   <[2] 16-bit length of chunk signature>
	 *   <[...] chunk signature>
	 *
	 * This is a direct push variant for network config updates. It otherwise
	 * carries the same payload as OK(NETWORK_CONFIG_REQUEST) and has the same
	 * semantics.
	 *
	 * The legacy mode missing the additional chunking fields is not supported
	 * here.
	 *
	 * Flags:
	 *   0x01 - Use fast propagation
	 *
	 * An OK should be sent if the config is successfully received and
	 * accepted.
	 *
	 * OK payload:
	 *   <[8] 64-bit network ID>
	 *   <[8] 64-bit config update ID>
	 */
	VERB_NETWORK_CONFIG = 0x0c,

	/**
	 * Request endpoints for multicast distribution:
	 *   <[8] 64-bit network ID>
	 *   <[1] flags>
	 *   <[6] MAC address of multicast group being queried>
	 *   <[4] 32-bit ADI for multicast group being queried>
	 *   <[4] 32-bit requested max number of multicast peers>
	 *
	 * This message asks a peer for additional known endpoints that have
	 * LIKEd a given multicast group. It's sent when the sender wishes
	 * to send multicast but does not have the desired number of recipient
	 * peers.
	 *
	 * OK response payload: (multiple OKs can be generated)
	 *   <[8] 64-bit network ID>
	 *   <[6] MAC address of multicast group being queried>
	 *   <[4] 32-bit ADI for multicast group being queried>
	 *   <[4] 32-bit total number of known members in this multicast group>
	 *   <[2] 16-bit number of members enumerated in this packet>
	 *   <[...] series of 5-byte ZeroTier addresses of enumerated members>
	 *
	 * ERROR is not generated; queries that return no response are dropped.
	 */
	VERB_MULTICAST_GATHER = 0x0d,

	/** *** DEPRECATED ***
	 * Multicast frame:
	 *   <[8] 64-bit network ID>
	 *   <[1] flags>
	 *  [<[4] 32-bit implicit gather limit>]
	 *  [<[6] source MAC>]
	 *   <[6] destination MAC (multicast address)>
	 *   <[4] 32-bit multicast ADI (multicast address extension)>
	 *   <[2] 16-bit ethertype>
	 *   <[...] ethernet payload>
	 *
	 * Flags:
	 *   0x01 - Network certificate of membership attached (DEPRECATED)
	 *   0x02 - Implicit gather limit field is present
	 *   0x04 - Source MAC is specified -- otherwise it's computed from sender
	 *   0x08 - Please replicate (sent to multicast replicators)
	 *
	 * OK and ERROR responses are optional. OK may be generated if there are
	 * implicit gather results or if the recipient wants to send its own
	 * updated certificate of network membership to the sender. ERROR may be
	 * generated if a certificate is needed or if multicasts to this group
	 * are no longer wanted (multicast unsubscribe).
	 *
	 * OK response payload:
	 *   <[8] 64-bit network ID>
	 *   <[6] MAC address of multicast group>
	 *   <[4] 32-bit ADI for multicast group>
	 *   <[1] flags>
	 *  [<[...] network certificate of membership (DEPRECATED)>]
	 *  [<[...] implicit gather results if flag 0x01 is set>]
	 *
	 * OK flags (same bits as request flags):
	 *   0x01 - OK includes certificate of network membership (DEPRECATED)
	 *   0x02 - OK includes implicit gather results
	 *
	 * ERROR response payload:
	 *   <[8] 64-bit network ID>
	 *   <[6] multicast group MAC>
	 *   <[4] 32-bit multicast group ADI>
	 */
	VERB_MULTICAST_FRAME_deprecated = 0x0e,

	/**
	 * Push of potential endpoints for direct communication:
	 *   <[2] 16-bit number of paths>
	 *   <[...] paths>
	 *
	 * Path record format:
	 *   <[1] 8-bit path flags (always 0, currently unused)>
	 *   <[2] length of extended path characteristics or 0 for none>
	 *   <[...] extended path characteristics>
	 *   <[1] address type>
	 *   <[1] address length in bytes>
	 *   <[...] address>
	 *
	 * The receiver may, upon receiving a push, attempt to establish a
	 * direct link to one or more of the indicated addresses. It is the
	 * responsibility of the sender to limit which peers it pushes direct
	 * paths to to those with whom it has a trust relationship. The receiver
	 * must obey any restrictions provided such as exclusivity or blacklists.
	 * OK responses to this message are optional.
	 *
	 * Note that a direct path push does not imply that learned paths can't
	 * be used unless they are blacklisted explicitly or unless flag 0x01
	 * is set.
	 *
	 * OK and ERROR are not generated.
	 */
	VERB_PUSH_DIRECT_PATHS = 0x10,

	/**
	 * A message with arbitrary user-definable content:
	 *   <[8] 64-bit arbitrary message type ID>
	 *  [<[...] message payload>]
	 *
	 * This can be used to send arbitrary messages over VL1. It generates no
	 * OK or ERROR and has no special semantics outside of whatever the user
	 * (via the ZeroTier core API) chooses to give it.
	 *
	 * Message type IDs less than or equal to 65535 are reserved for use by
	 * ZeroTier, Inc. itself. We recommend making up random ones for your own
	 * implementations.
	 */
	VERB_USER_MESSAGE = 0x14,

	/**
	 * Encapsulate a ZeroTier packet for multicast distribution:
	 *   [... begin signed portion ...]
	 *   <[1] 8-bit flags>
	 *   <[5] 40-bit ZeroTier address of sender>
	 *   <[2] 16-bit length of inner payload>
	 *   <[1] inner payload verb>
	 *   <[...] inner payload data>
	 *   [... end signed portion ...]
	 *   <[2] 16-bit length of signature or 0 if un-signed>
	 *  [<[...] optional signature of multicast>]
	 *   <[...] address (min prefix) list>
	 */
	VERB_MULTICAST = 0x16,

	/**
	 * Encapsulate a full ZeroTier packet in another:
	 *   <[...] raw encapsulated packet>
	 *
	 * Encapsulation exists to enable secure relaying as opposed to the usual
	 * "dumb" relaying. The latter is faster but secure relaying has roles
	 * where endpoint privacy is desired. Multiply nested ENCAP packets
	 * could allow ZeroTier to act as an onion router.
	 *
	 * When encapsulated packets are forwarded they do have their hop count
	 * field incremented.
	 */
	VERB_ENCAP = 0x17

	// protocol max: 0x1f
};

/**
 * Error codes used in ERROR packets.
 */
enum ErrorCode
{
	/* Invalid request */
	ERROR_INVALID_REQUEST = 0x01,

	/* Bad/unsupported protocol version */
	ERROR_BAD_PROTOCOL_VERSION = 0x02,

	/* Unknown object queried */
	ERROR_OBJ_NOT_FOUND = 0x03,

	/* Verb or use case not supported/enabled by this node */
	ERROR_UNSUPPORTED_OPERATION = 0x05,

	/* Network access denied; updated credentials needed */
	ERROR_NEED_MEMBERSHIP_CERTIFICATE = 0x06,

	/* Tried to join network, but you're not a member */
	ERROR_NETWORK_ACCESS_DENIED_ = 0x07, /* extra _ at end to avoid Windows name conflict */

	/* Cannot deliver a forwarded ZeroTier packet (e.g. hops exceeded, no routes) */
	ERROR_CANNOT_DELIVER = 0x09
};

/**
 * EXT_FRAME subtypes, which are packed into three bits in the flags field.
 */
enum ExtFrameSubtype
{
	EXT_FRAME_SUBTYPE_NORMAL = 0x0,
	EXT_FRAME_SUBTYPE_TEE_OUTBOUND = 0x1,
	EXT_FRAME_SUBTYPE_REDIRECT_OUTBOUND = 0x2,
	EXT_FRAME_SUBTYPE_WATCH_OUTBOUND = 0x3,
	EXT_FRAME_SUBTYPE_TEE_INBOUND = 0x4,
	EXT_FRAME_SUBTYPE_REDIRECT_INBOUND = 0x5,
	EXT_FRAME_SUBTYPE_WATCH_INBOUND = 0x6
};

/**
 * EXT_FRAME flags
 */
enum ExtFrameFlag
{
	EXT_FRAME_FLAG_COM_ATTACHED_deprecated = 0x01,
	// bits 0x02, 0x04, and 0x08 are occupied by the ExtFrameSubtype
	EXT_FRAME_FLAG_ACK_REQUESTED = 0x10
};

/****************************************************************************/

/*
 * These are bit-packed structures for rapid parsing of packets or at least
 * the fixed size headers thereof. Not all packet types have these as some
 * are full of variable length fields are are more easily parsed through
 * incremental decoding.
 *
 * All fields larger than one byte are in big-endian byte order on the wire.
 */

ZT_PACKED_STRUCT(struct HELLO {
	uint8_t versionProtocol;
	uint8_t versionMajor;
	uint8_t versionMinor;
	uint16_t versionRev;
	uint64_t timestamp;
});

ZT_PACKED_STRUCT(struct RENDEZVOUS {
	uint8_t flags;
	uint8_t peerAddress[5];
	uint16_t port;
	uint8_t addressLength;
	uint8_t address[16];
});

ZT_PACKED_STRUCT(struct FRAME {
	uint64_t networkId;
	uint16_t etherType;
	uint8_t data[];
});

ZT_PACKED_STRUCT(struct EXT_FRAME {
	uint64_t networkId;
	uint8_t flags;
	uint8_t destMac[6];
	uint8_t sourceMac[6];
	uint16_t etherType;
	uint8_t data[];
});

ZT_PACKED_STRUCT(struct MULTICAST_LIKE_Entry {
	uint64_t networkId;
	uint8_t mac[6];
	uint32_t adi;
});

ZT_PACKED_STRUCT(struct MULTICAST_LIKE {
	MULTICAST_LIKE_Entry groups[];
});

namespace OK {

ZT_PACKED_STRUCT(struct HELLO {
	uint64_t timestampEcho;
	uint8_t versionProtocol;
	uint8_t versionMajor;
	uint8_t versionMinor;
	uint16_t versionRev;
});

ZT_PACKED_STRUCT(struct EXT_FRAME {
	uint64_t networkId;
	uint8_t flags;
	uint8_t destMac[6];
	uint8_t sourceMac[6];
	uint16_t etherType;
});

/**
 * OK response header
 *
 * The OK header comes after the packet header but before type-specific payloads.
 *
 * @tparam PT OK payload type (default: uint8_t[])
 */
template<typename PT = uint8_t[]>
ZT_PACKED_STRUCT(struct Header {
	uint8_t inReVerb;
	uint64_t inRePacketId;
	PT p;
});

} // namespace OK

namespace ERROR {

/**
 * Error header
 *
 * The error header comes after the packet header but before type-specific payloads.
 *
 * @tparam PT Error payload type (default: uint8_t[])
 */
template<typename PT = uint8_t[]>
ZT_PACKED_STRUCT(struct Header {
	uint8_t inReVerb;
	uint64_t inRePacketId;
	uint8_t error;
	PT p;
});

} // namespace ERROR

/**
 * Normal packet header
 *
 * @tparam PT Packet payload type (default: uint8_t[])
 */
template<typename PT = uint8_t[]>
ZT_PACKED_STRUCT(struct Header {
	uint64_t packetId;
	uint8_t destination[5];
	uint8_t source[5];
	uint8_t flags;
	uint64_t mac;
	// --- begin encrypted envelope ---
	uint8_t verb;
	PT p;
});

/**
 * Packet fragment header
 */
ZT_PACKED_STRUCT(struct FragmentHeader {
	uint64_t packetId;
	uint8_t destination[5];
	uint8_t fragmentIndicator; // always 0xff for fragments
	uint8_t counts; // total: most significant four bits, number: least significant four bits
	uint8_t hops; // top 5 bits unused and must be zero
	uint8_t p[];
});

/****************************************************************************/

/**
 * Increment the 3-bit hops field embedded in the packet flags field
 *
 * @return New hop count (can be greater than allowed if there is an overflow)
 */
template<typename X>
ZT_ALWAYS_INLINE unsigned int incrementPacketHops(Buf< Header<X> > &packet)
{
	uint8_t f = packet.data.fields.flags;
	uint8_t h = f;
	f &= 0xf8U;
	++h;
	packet.data.fields.flags = f | (h & 0x07U);
	return h;
}

/**
 * @return 3-bit hops field embedded in packet flags field
 */
template<typename X>
ZT_ALWAYS_INLINE unsigned int packetHops(Buf< Header<X> > &packet) const { return (packet.data.fields.flags & 0x07U); }

/**
 * Armor a packet for transport
 *
 * @param packet Packet to armor
 * @param packetSize Size of data in packet (must be at least the minimum packet size)
 * @param key 256-bit symmetric key
 * @param cipherSuite Cipher suite to apply
 */
void armor(Buf< Header<> > &packet,unsigned int packetSize,const uint8_t key[ZT_PEER_SECRET_KEY_LENGTH],uint8_t cipherSuite);

/**
 * Dearmor a packet and check message authentication code
 *
 * If the packet is valid and MAC (if indicated) passes, the cipher suite
 * is returned. Otherwise -1 is returned to indicate a MAC failure.
 *
 * @param packet Packet to dearmor
 * @param packetSize Size of data in packet (must be at least the minimum packet size)
 * @param key 256-bit symmetric key
 * @return Cipher suite or -1 if MAC validation failed
 */
int dearmor(Buf< Header<> > &packet,unsigned int packetSize,const uint8_t key[ZT_PEER_SECRET_KEY_LENGTH]);

/**
 * Compress packet payload
 *
 * @param packet Packet to compress
 * @param packetSize Original packet size
 * @return New packet size (returns original size of compression didn't help, in which case packet is unmodified)
 */
unsigned int compress(Buf< Header<> > &packet,unsigned int packetSize);

/**
 * Uncompress packet payload (if compressed)
 *
 * @param packet Packet to uncompress
 * @param packetSize Original packet size
 * @return New packet size or -1 on decompression error (returns original packet size if packet wasn't compressed)
 */
int uncompress(Buf< Header<> > &packet,unsigned int packetSize);

/**
 * Get a sequential non-repeating packet ID for the next packet (thread-safe)
 *
 * @return Next packet ID / cryptographic nonce
 */
uint64_t getPacketId();

} // namespace Protocol
} // namespace ZeroTier

#endif