ZeroTierOne/node/Buffer.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_BUFFER_HPP
#define ZT_BUFFER_HPP

#include "Constants.hpp"
#include "Utils.hpp"

#include <algorithm>
#include <stdexcept>
#include <stdint.h>
#include <string.h>
#include <string>
#include <utility>

#if defined(__GNUC__) && (! defined(ZT_NO_TYPE_PUNNING))
#define ZT_VAR_MAY_ALIAS __attribute__((__may_alias__))
#else
#define ZT_VAR_MAY_ALIAS
#endif

namespace ZeroTier {

/**
 * A variable length but statically allocated buffer
 *
 * Bounds-checking is done everywhere, since this is used in security
 * critical code. This supports construction and assignment from buffers
 * of differing capacities, provided the data actually in them fits.
 * It throws std::out_of_range on any boundary violation.
 *
 * The at(), append(), etc. methods encode integers larger than 8-bit in
 * big-endian (network) byte order.
 *
 * @tparam C Total capacity
 */
template <unsigned int C> class Buffer {
    // I love me!
    template <unsigned int C2> friend class Buffer;

  public:
    // STL container idioms
    typedef unsigned char value_type;
    typedef unsigned char* pointer;
    typedef const char* const_pointer;
    typedef char& reference;
    typedef const char& const_reference;
    typedef char* iterator;
    typedef const char* const_iterator;
    typedef unsigned int size_type;
    typedef int difference_type;
    typedef std::reverse_iterator<iterator> reverse_iterator;
    typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
    inline iterator begin()
    {
        return _b;
    }
    inline iterator end()
    {
        return (_b + _l);
    }
    inline const_iterator begin() const
    {
        return _b;
    }
    inline const_iterator end() const
    {
        return (_b + _l);
    }
    inline reverse_iterator rbegin()
    {
        return reverse_iterator(begin());
    }
    inline reverse_iterator rend()
    {
        return reverse_iterator(end());
    }
    inline const_reverse_iterator rbegin() const
    {
        return const_reverse_iterator(begin());
    }
    inline const_reverse_iterator rend() const
    {
        return const_reverse_iterator(end());
    }

    Buffer() : _l(0)
    {
    }

    Buffer(unsigned int l)
    {
        if (l > C) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
        _l = l;
    }

    template <unsigned int C2> Buffer(const Buffer<C2>& b)
    {
        *this = b;
    }

    Buffer(const void* b, unsigned int l)
    {
        copyFrom(b, l);
    }

    template <unsigned int C2> inline Buffer& operator=(const Buffer<C2>& b)
    {
        if (unlikely(b._l > C)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
        if (C2 == C) {
            memcpy(this, &b, sizeof(Buffer<C>));
        }
        else {
            memcpy(_b, b._b, _l = b._l);
        }
        return *this;
    }

    inline void copyFrom(const void* b, unsigned int l)
    {
        if (unlikely(l > C)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
        memcpy(_b, b, l);
        _l = l;
    }

    unsigned char operator[](const unsigned int i) const
    {
        if (unlikely(i >= _l)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
        return (unsigned char)_b[i];
    }

    unsigned char& operator[](const unsigned int i)
    {
        if (unlikely(i >= _l)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
        return ((unsigned char*)_b)[i];
    }

    /**
     * Get a raw pointer to a field with bounds checking
     *
     * This isn't perfectly safe in that the caller could still overflow
     * the pointer, but its use provides both a sanity check and
     * documentation / reminder to the calling code to treat the returned
     * pointer as being of size [l].
     *
     * @param i Index of field in buffer
     * @param l Length of field in bytes
     * @return Pointer to field data
     * @throws std::out_of_range Field extends beyond data size
     */
    unsigned char* field(unsigned int i, unsigned int l)
    {
        if (unlikely((i + l) > _l)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
        return (unsigned char*)(_b + i);
    }
    const unsigned char* field(unsigned int i, unsigned int l) const
    {
        if (unlikely((i + l) > _l)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
        return (const unsigned char*)(_b + i);
    }

    /**
     * Place a primitive integer value at a given position
     *
     * @param i Index to place value
     * @param v Value
     * @tparam T Integer type (e.g. uint16_t, int64_t)
     */
    template <typename T> inline void setAt(unsigned int i, const T v)
    {
        if (unlikely((i + sizeof(T)) > _l)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
#ifdef ZT_NO_TYPE_PUNNING
        uint8_t* p = reinterpret_cast<uint8_t*>(_b + i);
        for (unsigned int x = 1; x <= sizeof(T); ++x) {
            *(p++) = (uint8_t)(v >> (8 * (sizeof(T) - x)));
        }
#else
        T* const ZT_VAR_MAY_ALIAS p = reinterpret_cast<T*>(_b + i);
        *p = Utils::hton(v);
#endif
    }

    /**
     * Get a primitive integer value at a given position
     *
     * @param i Index to get integer
     * @tparam T Integer type (e.g. uint16_t, int64_t)
     * @return Integer value
     */
    template <typename T> inline T at(unsigned int i) const
    {
        if (unlikely((i + sizeof(T)) > _l)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
#ifdef ZT_NO_TYPE_PUNNING
        T v = 0;
        const uint8_t* p = reinterpret_cast<const uint8_t*>(_b + i);
        for (unsigned int x = 0; x < sizeof(T); ++x) {
            v <<= 8;
            v |= (T) * (p++);
        }
        return v;
#else
        const T* const ZT_VAR_MAY_ALIAS p = reinterpret_cast<const T*>(_b + i);
        return Utils::ntoh(*p);
#endif
    }

    /**
     * Append an integer type to this buffer
     *
     * @param v Value to append
     * @tparam T Integer type (e.g. uint16_t, int64_t)
     * @throws std::out_of_range Attempt to append beyond capacity
     */
    template <typename T> inline void append(const T v)
    {
        if (unlikely((_l + sizeof(T)) > C)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
#ifdef ZT_NO_TYPE_PUNNING
        uint8_t* p = reinterpret_cast<uint8_t*>(_b + _l);
        for (unsigned int x = 1; x <= sizeof(T); ++x) {
            *(p++) = (uint8_t)(v >> (8 * (sizeof(T) - x)));
        }
#else
        T* const ZT_VAR_MAY_ALIAS p = reinterpret_cast<T*>(_b + _l);
        *p = Utils::hton(v);
#endif
        _l += sizeof(T);
    }

    /**
     * Append a run of bytes
     *
     * @param c Character value to append
     * @param n Number of times to append
     * @throws std::out_of_range Attempt to append beyond capacity
     */
    inline void append(unsigned char c, unsigned int n)
    {
        if (unlikely((_l + n) > C)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
        for (unsigned int i = 0; i < n; ++i) {
            _b[_l++] = (char)c;
        }
    }

    /**
     * Append secure random bytes
     *
     * @param n Number of random bytes to append
     */
    inline void appendRandom(unsigned int n)
    {
        if (unlikely((_l + n) > C)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
        Utils::getSecureRandom(_b + _l, n);
        _l += n;
    }

    /**
     * Append a C-array of bytes
     *
     * @param b Data
     * @param l Length
     * @throws std::out_of_range Attempt to append beyond capacity
     */
    inline void append(const void* b, unsigned int l)
    {
        if (unlikely((_l + l) > C)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
        memcpy(_b + _l, b, l);
        _l += l;
    }

    /**
     * Append a C string including null termination byte
     *
     * @param s C string
     * @throws std::out_of_range Attempt to append beyond capacity
     */
    inline void appendCString(const char* s)
    {
        for (;;) {
            if (unlikely(_l >= C)) {
                throw ZT_EXCEPTION_OUT_OF_BOUNDS;
            }
            if (! (_b[_l++] = *(s++))) {
                break;
            }
        }
    }

    /**
     * Append a buffer
     *
     * @param b Buffer to append
     * @tparam C2 Capacity of second buffer (typically inferred)
     * @throws std::out_of_range Attempt to append beyond capacity
     */
    template <unsigned int C2> inline void append(const Buffer<C2>& b)
    {
        append(b._b, b._l);
    }

    /**
     * Increment size and return pointer to field of specified size
     *
     * Nothing is actually written to the memory. This is a shortcut
     * for addSize() followed by field() to reference the previous
     * position and the new size.
     *
     * @param l Length of field to append
     * @return Pointer to beginning of appended field of length 'l'
     */
    inline char* appendField(unsigned int l)
    {
        if (unlikely((_l + l) > C)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
        char* r = _b + _l;
        _l += l;
        return r;
    }

    /**
     * Increment size by a given number of bytes
     *
     * The contents of new space are undefined.
     *
     * @param i Bytes to increment
     * @throws std::out_of_range Capacity exceeded
     */
    inline void addSize(unsigned int i)
    {
        if (unlikely((i + _l) > C)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
        _l += i;
    }

    /**
     * Set size of data in buffer
     *
     * The contents of new space are undefined.
     *
     * @param i New size
     * @throws std::out_of_range Size larger than capacity
     */
    inline void setSize(const unsigned int i)
    {
        if (unlikely(i > C)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
        _l = i;
    }

    /**
     * Move everything after 'at' to the buffer's front and truncate
     *
     * @param at Truncate before this position
     * @throws std::out_of_range Position is beyond size of buffer
     */
    inline void behead(const unsigned int at)
    {
        if (! at) {
            return;
        }
        if (unlikely(at > _l)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
        ::memmove(_b, _b + at, _l -= at);
    }

    /**
     * Erase something from the middle of the buffer
     *
     * @param start Starting position
     * @param length Length of block to erase
     * @throws std::out_of_range Position plus length is beyond size of buffer
     */
    inline void erase(const unsigned int at, const unsigned int length)
    {
        const unsigned int endr = at + length;
        if (unlikely(endr > _l)) {
            throw ZT_EXCEPTION_OUT_OF_BOUNDS;
        }
        ::memmove(_b + at, _b + endr, _l - endr);
        _l -= length;
    }

    /**
     * Set buffer data length to zero
     */
    inline void clear()
    {
        _l = 0;
    }

    /**
     * Zero buffer up to size()
     */
    inline void zero()
    {
        memset(_b, 0, _l);
    }

    /**
     * Zero unused capacity area
     */
    inline void zeroUnused()
    {
        memset(_b + _l, 0, C - _l);
    }

    /**
     * Unconditionally and securely zero buffer's underlying memory
     */
    inline void burn()
    {
        Utils::burn(_b, sizeof(_b));
    }

    /**
     * @return Constant pointer to data in buffer
     */
    inline const void* data() const
    {
        return _b;
    }

    /**
     * @return Non-constant pointer to data in buffer
     */
    inline void* unsafeData()
    {
        return _b;
    }

    /**
     * @return Size of data in buffer
     */
    inline unsigned int size() const
    {
        return _l;
    }

    /**
     * @return Capacity of buffer
     */
    inline unsigned int capacity() const
    {
        return C;
    }

    template <unsigned int C2> inline bool operator==(const Buffer<C2>& b) const
    {
        return ((_l == b._l) && (! memcmp(_b, b._b, _l)));
    }
    template <unsigned int C2> inline bool operator!=(const Buffer<C2>& b) const
    {
        return ((_l != b._l) || (memcmp(_b, b._b, _l)));
    }
    template <unsigned int C2> inline bool operator<(const Buffer<C2>& b) const
    {
        return (memcmp(_b, b._b, std::min(_l, b._l)) < 0);
    }
    template <unsigned int C2> inline bool operator>(const Buffer<C2>& b) const
    {
        return (b < *this);
    }
    template <unsigned int C2> inline bool operator<=(const Buffer<C2>& b) const
    {
        return ! (b < *this);
    }
    template <unsigned int C2> inline bool operator>=(const Buffer<C2>& b) const
    {
        return ! (*this < b);
    }

  private:
    char ZT_VAR_MAY_ALIAS _b[C];
    unsigned int _l;
};

}   // namespace ZeroTier

#endif