b9d0b301b8
The NDIS reason why TunCheckForPause() reported the adapter unavailable, might not make much sense to a client. In case adapter is paused or in low power state, the STATUS_CANCELLED (ERROR_OPERATION_ABORTED) is returned. Exchange buffer size overflow - total TUN_EXCH_MAX_IP_PACKET_SIZE or individual packet - rejects entire exchange buffer now. Exchange buffers containing non-IPv4 or non-IPv6 packets are now rejected as a whole. Allocation errors while preparing NBLs from the exchange buffer are now considered fatal. Ensure write buffer has at least sizeof(TUN_PACKET) left, or reject entire exchange buffer. Signed-off-by: Simon Rozman <simon@rozman.si> |
||
---|---|---|
.editorconfig | ||
.gitignore | ||
COPYING | ||
README.md | ||
undocumented.h | ||
wintun.c | ||
wintun.inf | ||
wintun.proj | ||
wintun.props | ||
wintun.rc | ||
wintun.vcxproj | ||
wintun.vcxproj.filters | ||
wintun.wixproj | ||
wintun.wxs |
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.
Build Requirements
Digital Signing
Digital signing is integral part of the build process. By default, the driver will be test-signed using a certificate that the WDK should automatically generate. To subsequently load the driver, you will need to put your computer into test mode by executing as Administrator bcdedit /set testsigning on
.
If you possess an EV certificate for kernel mode code signing you should switch TUN driver digital signing from test-signing to production-signing by authoring your wintun.vcxproj.user
file to look something like this:
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<SignMode>ProductionSign</SignMode>
<CrossCertificateFile>$(WDKContentRoot)CrossCertificates\DigiCert_High_Assurance_EV_Root_CA.crt</CrossCertificateFile>
<ProductionCertificate>DF98E075A012ED8C86FBCF14854B8F9555CB3D45</ProductionCertificate>
<TimestampServer>http://timestamp.digicert.com</TimestampServer>
</PropertyGroup>
</Project>
Modify the <CrossCertificateFile>
to contain the full path to the cross-signing certificate of CA that issued your certificate. You should be able to find its .crt
file in C:\Program Files (x86)\Windows Kits\10\CrossCertificates
. Note that the $(WDKContentRoot)
expands to C:\Program Files (x86)\Windows Kits\10\
.
If you already have wintun.vcxproj.user
file, just add the <PropertyGroup>
section.
Building from Command Line
Open Developer Command Prompt for VS 2019 and use the msbuild
command:
msbuild wintun.proj [/t:<target>]
Targets
-
Build
: Builds the driver release configurations of all supported platforms. This is the default target. -
Clean
: Deletes all intermediate and output files. -
Rebuild
: Alias forClean
followed byBuild
. -
SDV
: Runs Static Driver Verifier, which includes a clean driver build, only for AMD64 release configuration. -
DVL
: Runs theSDV
, and creates a Driver Verification Log, only for AMD64 release configurations. -
MSM
: Builds Microsoft Installer Merge Modules in<output folder>\wintun-<platform>-<version>.msm
. Requires WHQL signed driver.
The driver output folders are:
Platform and Configuration | Folder |
---|---|
x86 Debug | x86\Debug\wintun |
x86 Release | x86\Release\wintun |
AMD64 Debug | amd64\Debug\wintun |
AMD64 Release | amd64\Release\wintun |
ARM64 Debug | arm64\Debug\wintun |
ARM64 Release | arm64\Release\wintun |
Building Microsoft Installer Merge Modules
msbuild wintun.proj /t:DVL;Build
.- Perform Windows Hardware Lab Kit tests.
- Submit submission package to Microsoft.
- Copy WHQL-signed driver to
x86\Release\whql\
andamd64\Release\whql\
subfolders. msbuild wintun.proj /t:MSM
- MSM files are placed in
dist
subfolder.
Note: due to the use of SHA256 signatures throughout, Windows 7 users who would like a prompt-less installation generally need to have the KB2921916 hotfix installed, which can be obtained from these mirrors: amd64 and x86.
Usage
After loading the driver and creating a network interface the typical way using SetupAPI, open \\.\Device\WINTUN%d
as Local System, where %d
is the LUID index (NetLuidIndex
member) of the network device. You may then ReadFile
and WriteFile
bundles of packets of the following format:
+------------------------------+
| size_0 |
| 4 bytes, native endian |
+------------------------------+
| |
| padding |
| 12 bytes, all zero |
| |
+------------------------------+
| |
| packet_0 |
| size_0 bytes |
| |
~ ~
| |
+------------------------------+
| padding |
| 16-(size_0&15) bytes, |
| all zero |
+------------------------------+
| size_1 |
| 4 bytes, native endian |
+------------------------------+
| |
| padding |
| 12 bytes, all zero |
| |
+------------------------------+
| |
| packet_1 |
| size_1 bytes |
| |
~ ~
Each packet segment should contain a layer 3 IPv4 or IPv6 packet. Up to 256 packets may be read or written during each call to ReadFile
or WriteFile
.
It is advisable to use overlapped I/O for this. If using blocking I/O instead, it may be desirable to open separate handles for reading and writing.