TunnelForge.WinTun 10.1.1

TunnelForge.WinTun (v10.1.1)

Поддерживаемые языки / Supported languages / Unterstützte Sprachen / 支持的语言:

• Русский
• English
• Deutsch
• 简体中文

Русский

TunnelForge.WinTun — это обёртка на C# для взаимодействия с нативным драйвером Wintun (Microsoft), который предоставляет высокопроизводительные виртуальные TUN-интерфейсы в Windows. Библиотека позволяет создавать адаптеры, открывать сессии для передачи сетевых пакетов и управлять их жизненным циклом с помощью удобного и низкоуровневого API.

Установка

dotnet add package TunnelForge.WinTun --version 10.1.1

Поддерживаемые платформы

Основные возможности

• Создание и открытие адаптеров Wintun.
• Управление сессиями чтения и записи сетевых пакетов.
• Настройка логгирования нативных вызовов.
• Получение событий готовности к чтению.
• Полный контроль над памятью пакетов для минимизации копирований.

Быстрый старт

Создание адаптера и сессии

using System;
using System.Runtime.InteropServices;
using TunnelForge.WinTun;
using TunnelForge.WinTun.Structs;

var adapterName = "MyTunnel";
var tunnelType = "TunnelForge";
var guid = new GUID(); // пустой GUID — система назначит автоматически

// Создание адаптера
var adapter = WinTunNative.WintunCreateAdapter(adapterName, tunnelType, ref guid);
if (adapter == IntPtr.Zero)
    throw new Exception("Не удалось создать адаптер");

// Запуск сессии (буфер 4 МБ, должен быть степенью двойки от 128 КБ до 64 МБ)
var session = WinTunNative.WintunStartSession(adapter, 0x400000);
if (session == IntPtr.Zero)
{
    WinTunNative.WintunCloseAdapter(adapter);
    throw new Exception("Не удалось запустить сессию");
}

Получение пакетов

var waitEvent = WinTunNative.WintunGetReadWaitEvent(session);

var packetPtr = WinTunNative.WintunReceivePacket(session, out uint packetSize);
if (packetPtr != IntPtr.Zero)
{
    // Чтение данных пакета
    byte[] data = new byte[packetSize];
    Marshal.Copy(packetPtr, data, 0, (int)packetSize);

    // Обязательно освободить буфер после обработки
    WinTunNative.WintunReleaseReceivePacket(session, packetPtr);
}

Отправка пакетов

byte[] payload = /* данные IP-пакета */;

var sendPtr = WinTunNative.WintunAllocateSendPacket(session, (uint)payload.Length);
if (sendPtr != IntPtr.Zero)
{
    Marshal.Copy(payload, 0, sendPtr, payload.Length);
    WinTunNative.WintunSendPacket(session, sendPtr);
}

Настройка логгирования

WinTunNative.WintunSetLogger((WINTUN_LOGGER_LEVEL level, ulong timestamp, string message) =>
{
    Console.WriteLine($"[WinTun {level}] {message}");
});

// Отключение логгирования
WinTunNative.WintunSetLogger(null);

Получение информации об адаптере

// LUID адаптера (для идентификации интерфейса в системе)
WinTunNative.WintunGetAdapterLUID(adapter, out NET_LUID luid);

// Версия драйвера
uint version = WinTunNative.WintunGetRunningDriverVersion();

Очистка ресурсов

WinTunNative.WintunEndSession(session);
WinTunNative.WintunCloseAdapter(adapter);

// Удалить драйвер, если больше нет активных адаптеров
WinTunNative.WintunDeleteDriver();

Важные замечания

• Работает только на Windows.
• Требуются права администратора для создания адаптеров.
• Буфер сессии должен быть степенью двойки в диапазоне от 128 КБ до 64 МБ.
• Указатель пакета из WintunReceivePacket обязательно нужно вернуть через WintunReleaseReceivePacket.
• Не забывайте закрывать сессии и адаптеры при завершении работы.

English

TunnelForge.WinTun is a C# wrapper for the native Wintun driver (by Microsoft), providing high-performance virtual TUN interfaces on Windows. This library allows creating adapters, opening sessions for packet transmission, and managing their lifecycle through a simple low-level API.

Installation

dotnet add package TunnelForge.WinTun --version 10.1.1

Supported Platforms

Key Features

• Create and open Wintun adapters.
• Manage read/write sessions for network packets.
• Configure native logging callbacks.
• Obtain read wait events for efficient async I/O.
• Full control of packet memory to minimize copying.

Quick Start

Create adapter and session

using System;
using System.Runtime.InteropServices;
using TunnelForge.WinTun;
using TunnelForge.WinTun.Structs;

string adapterName = "MyTunnel";
string tunnelType = "TunnelForge";
var guid = new GUID(); // empty GUID — system will assign automatically

// Create adapter
var adapter = WinTunNative.WintunCreateAdapter(adapterName, tunnelType, ref guid);
if (adapter == IntPtr.Zero)
    throw new Exception("Failed to create adapter");

// Start session (4 MB buffer, must be power of two between 128 KB and 64 MB)
var session = WinTunNative.WintunStartSession(adapter, 0x400000);
if (session == IntPtr.Zero)
{
    WinTunNative.WintunCloseAdapter(adapter);
    throw new Exception("Failed to start session");
}

Receive packets

var waitEvent = WinTunNative.WintunGetReadWaitEvent(session);

var packetPtr = WinTunNative.WintunReceivePacket(session, out uint packetSize);
if (packetPtr != IntPtr.Zero)
{
    byte[] data = new byte[packetSize];
    Marshal.Copy(packetPtr, data, 0, (int)packetSize);

    // Must release the buffer after processing
    WinTunNative.WintunReleaseReceivePacket(session, packetPtr);
}

Send packets

byte[] payload = /* IP packet data */;

var sendPtr = WinTunNative.WintunAllocateSendPacket(session, (uint)payload.Length);
if (sendPtr != IntPtr.Zero)
{
    Marshal.Copy(payload, 0, sendPtr, payload.Length);
    WinTunNative.WintunSendPacket(session, sendPtr);
}

Configure logging

WinTunNative.WintunSetLogger((WINTUN_LOGGER_LEVEL level, ulong timestamp, string message) =>
{
    Console.WriteLine($"[WinTun {level}] {message}");
});

// Disable logging
WinTunNative.WintunSetLogger(null);

Get adapter info

// Adapter LUID (for system interface identification)
WinTunNative.WintunGetAdapterLUID(adapter, out NET_LUID luid);

// Driver version
uint version = WinTunNative.WintunGetRunningDriverVersion();

Cleanup

WinTunNative.WintunEndSession(session);
WinTunNative.WintunCloseAdapter(adapter);

// Remove the driver if no adapters remain
WinTunNative.WintunDeleteDriver();

Important Notes

• Windows only.
• Administrator privileges required to create adapters.
• Session buffer must be a power of two between 128 KB and 64 MB.
• Packet pointer from WintunReceivePacket must be returned via WintunReleaseReceivePacket.
• Always close sessions and adapters on shutdown.

Deutsch

TunnelForge.WinTun ist eine C#-Wrapper-Bibliothek für den nativen Wintun-Treiber (von Microsoft), die leistungsstarke virtuelle TUN-Schnittstellen unter Windows bereitstellt. Die Bibliothek ermöglicht das Erstellen von Adaptern, das Öffnen von Sessions für die Paketübertragung und die Verwaltung des Lebenszyklus über eine einfache Low-Level-API.

Installation

dotnet add package TunnelForge.WinTun --version 10.1.1

Unterstützte Plattformen

Hauptfunktionen

• Erstellung und Öffnung von Wintun-Adaptern.
• Verwaltung von Lese- und Schreib-Sessions für Netzwerkpakete.
• Konfiguration von nativen Logger-Callbacks.
• Empfang von Warte-Events für effizientes asynchrones IO.
• Volle Kontrolle über Paket-Speicher zur Minimierung von Kopien.

Schnellstart

Adapter und Session erstellen

using System;
using System.Runtime.InteropServices;
using TunnelForge.WinTun;
using TunnelForge.WinTun.Structs;

string adapterName = "MeinTunnel";
string tunnelType = "TunnelForge";
var guid = new GUID(); // Leerer GUID — System vergibt automatisch

// Adapter erstellen
var adapter = WinTunNative.WintunCreateAdapter(adapterName, tunnelType, ref guid);
if (adapter == IntPtr.Zero)
    throw new Exception("Adapter konnte nicht erstellt werden");

// Session mit 4 MB Puffer starten (Zweierpotenz zwischen 128 KB und 64 MB)
var session = WinTunNative.WintunStartSession(adapter, 0x400000);
if (session == IntPtr.Zero)
{
    WinTunNative.WintunCloseAdapter(adapter);
    throw new Exception("Session konnte nicht gestartet werden");
}

Pakete empfangen

var waitEvent = WinTunNative.WintunGetReadWaitEvent(session);

var packetPtr = WinTunNative.WintunReceivePacket(session, out uint packetSize);
if (packetPtr != IntPtr.Zero)
{
    byte[] data = new byte[packetSize];
    Marshal.Copy(packetPtr, data, 0, (int)packetSize);

    // Puffer muss nach der Verarbeitung freigegeben werden
    WinTunNative.WintunReleaseReceivePacket(session, packetPtr);
}

Pakete senden

byte[] payload = /* IP-Paketdaten */;

var sendPtr = WinTunNative.WintunAllocateSendPacket(session, (uint)payload.Length);
if (sendPtr != IntPtr.Zero)
{
    Marshal.Copy(payload, 0, sendPtr, payload.Length);
    WinTunNative.WintunSendPacket(session, sendPtr);
}

Logging konfigurieren

WinTunNative.WintunSetLogger((WINTUN_LOGGER_LEVEL level, ulong timestamp, string message) =>
{
    Console.WriteLine($"[WinTun {level}] {message}");
});

// Logging deaktivieren
WinTunNative.WintunSetLogger(null);

Adapter-Informationen abrufen

// Adapter-LUID (zur Identifikation der Schnittstelle im System)
WinTunNative.WintunGetAdapterLUID(adapter, out NET_LUID luid);

// Treiberversion
uint version = WinTunNative.WintunGetRunningDriverVersion();

Aufräumen

WinTunNative.WintunEndSession(session);
WinTunNative.WintunCloseAdapter(adapter);

// Treiber entfernen, wenn keine Adapter mehr vorhanden
WinTunNative.WintunDeleteDriver();

Wichtige Hinweise

• Nur Windows wird unterstützt.
• Administratorrechte sind zum Erstellen von Adaptern erforderlich.
• Session-Puffer muss eine Zweierpotenz zwischen 128 KB und 64 MB sein.
• Der Paketzeiger von WintunReceivePacket muss über WintunReleaseReceivePacket zurückgegeben werden.
• Sessions und Adapter immer beim Beenden schließen.

简体中文

TunnelForge.WinTun 是微软 Wintun 驱动的 C# 封装库，提供高性能的虚拟 TUN 网络接口，仅限 Windows 平台。此库允许创建适配器、打开会话进行数据包传输，并通过简单的低级 API 管理其生命周期。

安装

dotnet add package TunnelForge.WinTun --version 10.1.1

支持的平台

主要功能

• 创建和打开 Wintun 适配器。
• 管理网络数据包的读写会话。
• 配置本地日志回调。
• 获取读取等待事件，实现高效异步 IO。
• 完全控制数据包内存，减少拷贝。

快速开始

创建适配器和会话

using System;
using System.Runtime.InteropServices;
using TunnelForge.WinTun;
using TunnelForge.WinTun.Structs;

string adapterName = "MyTunnel";
string tunnelType = "TunnelForge";
var guid = new GUID(); // 空 GUID — 系统将自动分配

// 创建适配器
var adapter = WinTunNative.WintunCreateAdapter(adapterName, tunnelType, ref guid);
if (adapter == IntPtr.Zero)
    throw new Exception("创建适配器失败");

// 启动会话（4 MB 缓冲区，必须是 128 KB 到 64 MB 之间的 2 的幂）
var session = WinTunNative.WintunStartSession(adapter, 0x400000);
if (session == IntPtr.Zero)
{
    WinTunNative.WintunCloseAdapter(adapter);
    throw new Exception("启动会话失败");
}

接收数据包

var waitEvent = WinTunNative.WintunGetReadWaitEvent(session);

var packetPtr = WinTunNative.WintunReceivePacket(session, out uint packetSize);
if (packetPtr != IntPtr.Zero)
{
    byte[] data = new byte[packetSize];
    Marshal.Copy(packetPtr, data, 0, (int)packetSize);

    // 处理后必须释放缓冲区
    WinTunNative.WintunReleaseReceivePacket(session, packetPtr);
}

发送数据包

byte[] payload = /* IP 数据包数据 */;

var sendPtr = WinTunNative.WintunAllocateSendPacket(session, (uint)payload.Length);
if (sendPtr != IntPtr.Zero)
{
    Marshal.Copy(payload, 0, sendPtr, payload.Length);
    WinTunNative.WintunSendPacket(session, sendPtr);
}

配置日志

WinTunNative.WintunSetLogger((WINTUN_LOGGER_LEVEL level, ulong timestamp, string message) =>
{
    Console.WriteLine($"[WinTun {level}] {message}");
});

// 禁用日志
WinTunNative.WintunSetLogger(null);

获取适配器信息

// 适配器 LUID（用于系统中接口标识）
WinTunNative.WintunGetAdapterLUID(adapter, out NET_LUID luid);

// 驱动程序版本
uint version = WinTunNative.WintunGetRunningDriverVersion();

清理资源

WinTunNative.WintunEndSession(session);
WinTunNative.WintunCloseAdapter(adapter);

// 如果没有剩余适配器则删除驱动程序
WinTunNative.WintunDeleteDriver();

重要提示

• 仅支持 Windows。
• 创建适配器需要管理员权限。
• 会话缓冲区必须是 128 KB 到 64 MB 之间的 2 的幂。
• 来自 WintunReceivePacket 的数据包指针必须通过 WintunReleaseReceivePacket 释放。
• 关闭时务必清理会话和适配器。