82c41bdb4b
Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com> |
||
---|---|---|
api | ||
example | ||
.clang-format | ||
.editorconfig | ||
.gitignore | ||
COPYING | ||
README.md | ||
undocumented.h | ||
wintun.c | ||
wintun.inf | ||
wintun.proj | ||
wintun.props | ||
wintun.rc | ||
wintun.sln | ||
wintun.vcxproj | ||
wintun.vcxproj.filters |
Wintun Network Adapter
TUN Device Driver for Windows
This is a layer 3 TUN driver for Windows 7, 8, 8.1, and 10. Originally created for WireGuard, it is intended to be useful to a wide variety of projects that require layer 3 tunneling devices with implementations primarily in userspace.
Installation
Wintun is deployed as a platform-specific wintun.dll
file. Install the wintun.dll
file side-by-side with your application. Download the dll from wintun.net, alongside the header file for your application described below.
Usage
Include the wintun.h
file in your project simply by copying it there and dynamically load the wintun.dll
using LoadLibraryEx()
and GetProcAddress()
to resolve each function, using the typedefs provided in the header file. The InitializeWintun
function in the example.c code provides this in a function that you can simply copy and paste.
With the library setup, Wintun can then be used by first creating an adapter, and then starting a tunnel session on that adapter. Adapters have names (e.g. "OfficeNet"), and each one belongs to a pool (e.g. "WireGuard"). So, for example, the WireGuard application app creates multiple tunnels all inside of its "WireGuard" pool:
WINTUN_ADAPTER_HANDLE Adapter1 = WintunCreateAdapter(L"WireGuard", L"OfficeNet", &SomeFixedGUID1, NULL);
WINTUN_ADAPTER_HANDLE Adapter2 = WintunCreateAdapter(L"WireGuard", L"HomeNet", &SomeFixedGUID2, NULL);
WINTUN_ADAPTER_HANDLE Adapter3 = WintunCreateAdapter(L"WireGuard", L"Data Center", &SomeFixedGUID3, NULL);
After creating an adapter, we can use it by starting a session:
WINTUN_SESSION_HANDLE Session = WintunStartSession(Adapter2, 0x40000);
Then, the WintunAllocateSendPacket
and WintunSendPacket
functions can be used for sending packets (used by SendPackets
in the example.c code):
BYTE *OutgoingPacket = WintunAllocateSendPacket(Session, PacketDataSize);
if (OutgoingPacket)
{
memcpy(OutgoingPacket, PacketData, PacketDataSize);
WintunSendPacket(Session, OutgoingPacket);
}
else if (GetLastError() != ERROR_BUFFER_OVERFLOW) // Silently drop packets if the ring is full
Log(L"Packet write failed");
And the WintunReceivePacket
and WintunReleaseReceivePacket
functions can be used for receiving packets (used by ReceivePackets
in the example.c code):
for (;;)
{
DWORD IncomingPacketSize;
BYTE *IncomingPacket = WintunReceivePacket(Session, &IncomingPacketSize);
if (IncomingPacket)
{
DoSomethingWithPacket(IncomingPacket, IncomingPacketSize);
WintunReleaseReceivePacket(Session, IncomingPacket);
}
else if (GetLastError() == ERROR_NO_MORE_ITEMS)
WaitForSingleObject(WintunGetReadWaitEvent(Session), INFINITE);
else
{
Log(L"Packet read failed");
break;
}
}
Some high performance use cases may want to spin on WintunReceivePackets
for a number of cycles before falling back to waiting on the read-wait event.
You are highly encouraged to read the example.c short example to see how to put together a simple userspace network tunnel.
The various functions and definitions are documented in the reference below.
Reference
Macro Definitions
WINTUN_MAX_POOL
#define WINTUN_MAX_POOL 256
Maximum pool name length including zero terminator
WINTUN_MIN_RING_CAPACITY
#define WINTUN_MIN_RING_CAPACITY 0x20000 /* 128kiB */
Minimum ring capacity.
WINTUN_MAX_RING_CAPACITY
#define WINTUN_MAX_RING_CAPACITY 0x4000000 /* 64MiB */
Maximum ring capacity.
WINTUN_MAX_IP_PACKET_SIZE
#define WINTUN_MAX_IP_PACKET_SIZE 0xFFFF
Maximum IP packet size
Typedefs
WINTUN_ADAPTER_HANDLE
typedef void* WINTUN_ADAPTER_HANDLE
A handle representing Wintun adapter
WINTUN_ENUM_CALLBACK
typedef BOOL(* WINTUN_ENUM_CALLBACK) (WINTUN_ADAPTER_HANDLE Adapter, LPARAM Param)
Called by WintunEnumAdapters for each adapter in the pool.
Parameters
- Adapter: Adapter handle, which will be freed when this function returns.
- Param: An application-defined value passed to the WintunEnumAdapters.
Returns
Non-zero to continue iterating adapters; zero to stop.
WINTUN_LOGGER_CALLBACK
typedef BOOL(* WINTUN_LOGGER_CALLBACK) (WINTUN_LOGGER_LEVEL Level, const WCHAR *Message)
Called by internal logger to report diagnostic messages
Parameters
- Level: Message level.
- Message: Message text.
Returns
Anything - return value is ignored.
WINTUN_SESSION_HANDLE
typedef void* WINTUN_SESSION_HANDLE
A handle representing Wintun session
Enumeration Types
WINTUN_LOGGER_LEVEL
enum WINTUN_LOGGER_LEVEL
Determines the level of logging, passed to WINTUN_LOGGER_CALLBACK.
- WINTUN_LOG_INFO: Informational
- WINTUN_LOG_WARN: Warning
- WINTUN_LOG_ERR: Error
Enumerator
Functions
WintunCreateAdapter()
WINTUN_ADAPTER_HANDLE WintunCreateAdapter (const WCHAR * Pool, const WCHAR * Name, const GUID * RequestedGUID, BOOL * RebootRequired)
Creates a new Wintun adapter.
Parameters
- Pool: Name of the adapter pool. Zero-terminated string of up to WINTUN_MAX_POOL-1 characters.
- Name: The requested name of the adapter. Zero-terminated string of up to MAX_ADAPTER_NAME-1 characters.
- RequestedGUID: The GUID of the created network adapter, which then influences NLA generation deterministically. If it is set to NULL, the GUID is chosen by the system at random, and hence a new NLA entry is created for each new adapter. It is called "requested" GUID because the API it uses is completely undocumented, and so there could be minor interesting complications with its usage.
- RebootRequired: Optional pointer to a boolean flag to be set to TRUE in case SetupAPI suggests a reboot.
Returns
If the function succeeds, the return value is the adapter handle. Must be released with WintunFreeAdapter. If the function fails, the return value is NULL. To get extended error information, call GetLastError.
WintunOpenAdapter()
WINTUN_ADAPTER_HANDLE WintunOpenAdapter (const WCHAR * Pool, const WCHAR * Name)
Opens an existing Wintun adapter.
Parameters
- Pool: Name of the adapter pool. Zero-terminated string of up to WINTUN_MAX_POOL-1 characters.
- Name: Adapter name. Zero-terminated string of up to MAX_ADAPTER_NAME-1 characters.
Returns
If the function succeeds, the return value is adapter handle. Must be released with WintunFreeAdapter. If the function fails, the return value is NULL. To get extended error information, call GetLastError. Possible errors include the following: ERROR_FILE_NOT_FOUND if adapter with given name is not found; ERROR_ALREADY_EXISTS if adapter is found but not a Wintun-class or not a member of the pool
WintunDeleteAdapter()
BOOL WintunDeleteAdapter (WINTUN_ADAPTER_HANDLE Adapter, BOOL ForceCloseSessions, BOOL * RebootRequired)
Deletes a Wintun adapter.
Parameters
- Adapter: Adapter handle obtained with WintunOpenAdapter or WintunCreateAdapter.
- ForceCloseSessions: Force close adapter handles that may be in use by other processes. Only set this to TRUE with extreme care, as this is resource intensive and may put processes into an undefined or unpredictable state. Most users should set this to FALSE.
- RebootRequired: Optional pointer to a boolean flag to be set to TRUE in case SetupAPI suggests a reboot.
Returns
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
WintunEnumAdapters()
BOOL WintunEnumAdapters (const WCHAR * Pool, WINTUN_ENUM_CALLBACK Callback, LPARAM Param)
Enumerates all Wintun adapters.
Parameters
- Pool: Name of the adapter pool. Zero-terminated string of up to WINTUN_MAX_POOL-1 characters.
- Callback: Callback function. To continue enumeration, the callback function must return TRUE; to stop enumeration, it must return FALSE.
- Param: An application-defined value to be passed to the callback function.
Returns
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
WintunFreeAdapter()
void WintunFreeAdapter (WINTUN_ADAPTER_HANDLE Adapter)
Releases Wintun adapter resources.
Parameters
- Adapter: Adapter handle obtained with WintunOpenAdapter or WintunCreateAdapter.
WintunDeletePoolDriver()
BOOL WintunDeletePoolDriver (const WCHAR * Pool, BOOL * RebootRequired)
Deletes all Wintun adapters in a pool and if there are no more adapters in any other pools, also removes Wintun from the driver store, usually called by uninstallers.
Parameters
- Pool: Name of the adapter pool. Zero-terminated string of up to WINTUN_MAX_POOL-1 characters.
- RebootRequired: Optional pointer to a boolean flag to be set to TRUE in case SetupAPI suggests a reboot.
Returns
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
WintunOpenAdapterDeviceObject()
HANDLE WintunOpenAdapterDeviceObject (WINTUN_ADAPTER_HANDLE Adapter)
Returns a handle to the adapter device object.
Parameters
- Adapter: Adapter handle obtained with WintunOpenAdapter or WintunCreateAdapter.
Returns
If the function succeeds, the return value is adapter device object handle. Must be released with CloseHandle. If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.
WintunGetAdapterLuid()
void WintunGetAdapterLuid (WINTUN_ADAPTER_HANDLE Adapter, NET_LUID * Luid)
Returns the LUID of the adapter.
Parameters
- Adapter: Adapter handle obtained with WintunOpenAdapter or WintunCreateAdapter
- Luid: Pointer to LUID to receive adapter LUID.
WintunGetAdapterName()
BOOL WintunGetAdapterName (WINTUN_ADAPTER_HANDLE Adapter, WCHAR * Name)
Returns the name of the Wintun adapter.
Parameters
- Adapter: Adapter handle obtained with WintunOpenAdapter or WintunCreateAdapter
- Name: Pointer to a string to receive adapter name
Returns
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
WintunSetAdapterName()
BOOL WintunSetAdapterName (WINTUN_ADAPTER_HANDLE Adapter, const WCHAR * Name)
Sets name of the Wintun adapter.
Parameters
- Adapter: Adapter handle obtained with WintunOpenAdapter or WintunCreateAdapter
- Name: Adapter name. Zero-terminated string of up to MAX_ADAPTER_NAME-1 characters.
Returns
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
WintunGetRunningDriverVersion()
DWORD WintunGetRunningDriverVersion (void )
Determines the version of the Wintun driver currently loaded.
Returns
If the function succeeds, the return value is the version number. If the function fails, the return value is zero. To get extended error information, call GetLastError. Possible errors include the following: ERROR_FILE_NOT_FOUND Wintun not loaded
WintunSetLogger()
void WintunSetLogger (WINTUN_LOGGER_CALLBACK NewLogger)
Sets logger callback function.
Parameters
- NewLogger: Pointer to callback function to use as a new global logger. NewLogger may be called from various threads concurrently. Should the logging require serialization, you must handle serialization in NewLogger. Set to NULL to disable.
WintunStartSession()
WINTUN_SESSION_HANDLE WintunStartSession (WINTUN_ADAPTER_HANDLE Adapter, DWORD Capacity)
Starts Wintun session.
Parameters
- Adapter: Adapter handle obtained with WintunOpenAdapter or WintunCreateAdapter
- Capacity: Rings capacity. Must be between WINTUN_MIN_RING_CAPACITY and WINTUN_MAX_RING_CAPACITY (incl.) Must be a power of two.
Returns
Wintun session handle. Must be released with WintunEndSession. If the function fails, the return value is NULL. To get extended error information, call GetLastError.
WintunEndSession()
void WintunEndSession (WINTUN_SESSION_HANDLE Session)
Ends Wintun session.
Parameters
- Session: Wintun session handle obtained with WintunStartSession
WintunGetReadWaitEvent()
HANDLE WintunGetReadWaitEvent (WINTUN_SESSION_HANDLE Session)
Gets Wintun session's read-wait event handle.
Parameters
- Session: Wintun session handle obtained with WintunStartSession
Returns
Pointer to receive event handle to wait for available data when reading. Should WintunReceivePackets return ERROR_NO_MORE_ITEMS (after spinning on it for a while under heavy load), wait for this event to become signaled before retrying WintunReceivePackets. Do not call CloseHandle on this event - it is managed by the session.
WintunReceivePacket()
BYTE* WintunReceivePacket (WINTUN_SESSION_HANDLE Session, DWORD * PacketSize)
Retrieves one or packet. After the packet content is consumed, call WintunReleaseReceivePacket with Packet returned from this function to release internal buffer. This function is thread-safe.
Parameters
- Session: Wintun session handle obtained with WintunStartSession
- PacketSize: Pointer to receive packet size.
Returns
Pointer to layer 3 IPv4 or IPv6 packet. Client may modify its content at will. If the function fails, the return value is NULL. To get extended error information, call GetLastError. Possible errors include the following: ERROR_HANDLE_EOF Wintun adapter is terminating; ERROR_NO_MORE_ITEMS Wintun buffer is exhausted; ERROR_INVALID_DATA Wintun buffer is corrupt
WintunReleaseReceivePacket()
void WintunReleaseReceivePacket (WINTUN_SESSION_HANDLE Session, const BYTE * Packet)
Releases internal buffer after the received packet has been processed by the client. This function is thread-safe.
Parameters
- Session: Wintun session handle obtained with WintunStartSession
- Packet: Packet obtained with WintunReceivePacket
WintunAllocateSendPacket()
BYTE* WintunAllocateSendPacket (WINTUN_SESSION_HANDLE Session, DWORD PacketSize)
Allocates memory for a packet to send. After the memory is filled with packet data, call WintunSendPacket to send and release internal buffer. WintunAllocateSendPacket is thread-safe and the WintunAllocateSendPacket order of calls define the packet sending order.
Parameters
- Session: Wintun session handle obtained with WintunStartSession
- PacketSize: Exact packet size. Must be less or equal to WINTUN_MAX_IP_PACKET_SIZE.
Returns
Returns pointer to memory where to prepare layer 3 IPv4 or IPv6 packet for sending. If the function fails, the return value is NULL. To get extended error information, call GetLastError. Possible errors include the following: ERROR_HANDLE_EOF Wintun adapter is terminating; ERROR_BUFFER_OVERFLOW Wintun buffer is full;
WintunSendPacket()
void WintunSendPacket (WINTUN_SESSION_HANDLE Session, const BYTE * Packet)
Sends the packet and releases internal buffer. WintunSendPacket is thread-safe, but the WintunAllocateSendPacket order of calls define the packet sending order. This means the packet is not guaranteed to be sent in the WintunSendPacket yet.
Parameters
- Session: Wintun session handle obtained with WintunStartSession
- Packet: Packet obtained with WintunAllocateSendPacket
Building
Do not distribute drivers or files named "Wintun", as they will most certainly clash with official deployments. Instead distribute wintun.dll
as downloaded from wintun.net.
General requirements:
wintun.sln
may be opened in Visual Studio for development and building. Be sure to run bcdedit /set testsigning on
before to enable unsigned driver loading. The default run sequence (F5) in Visual Studio will build the example project.
License
The entire contents of this repository, including all documentation code, is "Copyright © 2018-2020 WireGuard LLC. All Rights Reserved." and is licensed under the GPLv2.