oob_probe.hpp

Go to the documentation of this file.

//    OpenVPN -- An application to securely tunnel IP networks
//               over a single port, with support for SSL/TLS-based
//               session authentication and key exchange,
//               packet encryption, packet authentication, and
//               packet compression.
//
//    Copyright (C) 2026- OpenVPN Inc.
//
//    SPDX-License-Identifier: MPL-2.0 OR AGPL-3.0-only WITH openvpn3-openssl-exception
//
 
#ifndef OPENVPN_SSL_OOB_PROBE_H
#define OPENVPN_SSL_OOB_PROBE_H
 
#include <cstdint>
#include <cstring>
#include <optional>
 
#include <openvpn/buffer/buffer.hpp>
#include <openvpn/buffer/bufbe.hpp>
#include <openvpn/ssl/psid.hpp>
 
namespace openvpn::oob {
 
// big-endian integer read/write on a Buffer (shared helpers)
using BufferBE::read_u16;
using BufferBE::read_u32;
using BufferBE::read_u64;
using BufferBE::write_u16;
using BufferBE::write_u32;
using BufferBE::write_u64;
 
enum : std::uint16_t
{
    MSG_SERVER_PROBE = 0x100,
    MSG_PROBE_REPLY = 0x101,
};
 
enum : std::uint16_t
{
    TLV_OPTIONAL_FLAG = 0x8000,
    TLV_TYPE_MASK = 0x7fff,
    TLV_PROBE_PARAMETER = 0x200,
    TLV_PROBE_REPLY = 0x201,
};
 
enum : std::uint32_t
{
    REPLY_FLAG_RESEND_WKC = 0x1,
};
 
// ---- message + TLV headers ----------------------------------------------------
 
inline bool msg_write_header(Buffer &buf, std::uint16_t msg_type)
{
    return write_u16(buf, msg_type);
}
 
inline bool msg_read_header(Buffer &buf, std::uint16_t expected_msg_type)
{
    std::uint16_t msg_type;
    return read_u16(buf, msg_type) && msg_type == expected_msg_type;
}
 
struct TlvHeader
{
    std::uint16_t type;      
    bool optional;           
    std::uint16_t value_len; 
};
 
inline bool tlv_write_header(Buffer &buf, std::uint16_t type, bool optional, std::uint16_t value_len)
{
    std::uint16_t field = type & TLV_TYPE_MASK;
    if (optional)
        field |= TLV_OPTIONAL_FLAG;
    return write_u16(buf, field) && write_u16(buf, value_len);
}
 
inline std::optional<TlvHeader> tlv_read_header(Buffer &buf)
{
    std::uint16_t field, value_len;
    if (!read_u16(buf, field) || !read_u16(buf, value_len))
        return std::nullopt;
    return TlvHeader{.type = static_cast<std::uint16_t>(field & TLV_TYPE_MASK),
                     .optional = (field & TLV_OPTIONAL_FLAG) != 0,
                     .value_len = value_len};
}
 
inline bool skip_trailing(Buffer &buf, std::uint16_t value_len, std::size_t consumed)
{
    if (value_len < consumed)
        return false;
    const std::size_t rest = value_len - consumed;
    if (buf.size() < rest)
        return false;
    buf.advance(rest);
    return true;
}
 
inline std::optional<std::uint16_t> find_tlv(Buffer &buf, std::uint16_t wanted_type)
{
    while (buf.size() >= 4) // a TLV header is 4 bytes
    {
        const auto hdr = tlv_read_header(buf);
        if (!hdr)
            return std::nullopt;
        if (hdr->type == wanted_type)
            return hdr->value_len;
        // Only an optional TLV may be ignored when we do not understand it. A
        // mandatory one carries something the sender requires us to act on, so
        // the message as a whole is not ours to interpret.
        if (!hdr->optional)
            return std::nullopt;
        if (buf.size() < hdr->value_len)
            return std::nullopt;
        buf.advance(hdr->value_len); // optional and unknown: skip its value
    }
    return std::nullopt;
}
 
// ---- probe_parameter / probe_reply TLVs -----------------------------------------
 
struct ProbeParameter
{
    static constexpr std::size_t WIRE_LEN = 12;
 
    std::uint64_t timestamp = 0; 
    std::uint32_t flags = 0;     
 
    bool write(Buffer &buf) const
    {
        return tlv_write_header(buf, TLV_PROBE_PARAMETER, false, WIRE_LEN)
               && write_u64(buf, timestamp)
               && write_u32(buf, flags);
    }
 
    static std::optional<ProbeParameter> read(Buffer &buf, std::uint16_t value_len)
    {
        if (value_len < WIRE_LEN)
            return std::nullopt;
        ProbeParameter p;
        if (!read_u64(buf, p.timestamp) || !read_u32(buf, p.flags))
            return std::nullopt;
        if (!skip_trailing(buf, value_len, WIRE_LEN))
            return std::nullopt;
        return p;
    }
};
 
struct ProbeReply
{
    static constexpr std::size_t WIRE_LEN = 20;
 
    ProtoSessionID peer_session_id;     
    std::uint16_t priority = 0;         
    std::uint16_t weight = 0;           
    std::uint16_t max_latency_diff = 0; 
    std::uint16_t connect_lifetime = 0; 
    std::uint32_t flags = 0;            
 
    bool write(Buffer &buf) const
    {
        if (!tlv_write_header(buf, TLV_PROBE_REPLY, false, WIRE_LEN))
            return false;
        if (buf.remaining() < ProtoSessionID::SIZE)
            return false;
        peer_session_id.write(buf);
        return write_u16(buf, priority)
               && write_u16(buf, weight)
               && write_u16(buf, max_latency_diff)
               && write_u16(buf, connect_lifetime)
               && write_u32(buf, flags);
    }
 
    static std::optional<ProbeReply> read(Buffer &buf, std::uint16_t value_len)
    {
        if (value_len < WIRE_LEN)
            return std::nullopt;
        if (buf.size() < ProtoSessionID::SIZE)
            return std::nullopt;
        ProbeReply r;
        r.peer_session_id.read(buf);
        if (!read_u16(buf, r.priority) || !read_u16(buf, r.weight) || !read_u16(buf, r.max_latency_diff)
            || !read_u16(buf, r.connect_lifetime) || !read_u32(buf, r.flags))
            return std::nullopt;
        if (!skip_trailing(buf, value_len, WIRE_LEN))
            return std::nullopt;
        return r;
    }
};
 
// ---- full SERVER_PROBE / PROBE_REPLY messages ---------------------------------
 
inline bool server_probe_write(Buffer &buf, const ProbeParameter &param)
{
    return msg_write_header(buf, MSG_SERVER_PROBE) && param.write(buf);
}
 
inline std::optional<ProbeParameter> server_probe_read(Buffer &buf)
{
    if (!msg_read_header(buf, MSG_SERVER_PROBE))
        return std::nullopt;
    const auto value_len = find_tlv(buf, TLV_PROBE_PARAMETER);
    if (!value_len)
        return std::nullopt;
    return ProbeParameter::read(buf, *value_len);
}
 
inline bool client_reply_write(Buffer &buf, const ProbeReply &reply)
{
    return msg_write_header(buf, MSG_PROBE_REPLY) && reply.write(buf);
}
 
inline std::optional<ProbeReply> client_reply_read(Buffer &buf)
{
    if (!msg_read_header(buf, MSG_PROBE_REPLY))
        return std::nullopt;
    const auto value_len = find_tlv(buf, TLV_PROBE_REPLY);
    if (!value_len)
        return std::nullopt;
    return ProbeReply::read(buf, *value_len);
}
 
} // namespace openvpn::oob
 
#endif