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

• Visual Studio 2017
• Windows Driver Kit for Windows 10
• WiX Toolset 3.11.1

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>CN=WireGuard LLC, O=WireGuard LLC, L=Boulder, S=Colorado, C=US, SERIALNUMBER=4227913, OID.2.5.4.15=Private Organization, OID.1.3.6.1.4.1.311.60.2.1.2=Ohio, OID.1.3.6.1.4.1.311.60.2.1.3=US | DF98E075A012ED8C86FBCF14854B8F9555CB3D45</ProductionCertificate>
  </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 2017 and use the nmake command:

msbuild wintun.proj [/t:<target>] [/p:Configuration=<configuration>] [/p:Platform=<platform>]

Targets

• Build: Builds the driver. This is the default target.

• Clean: Deletes all intermediate and output files.

• Rebuild: Alias for Clean followed by Build.

• SDV: Runs Static Driver Verifier, which includes a clean driver build. Release configurations only.

• DVL: Runs the SDV, and creates a Driver Verification Log in wintun.DVL.XML file. Release configurations only. When you are ready to test your driver using the Windows Hardware Certification Kit (HCK), you need to copy the wintun.DVL.XML file to the %SystemDrive%\DVL directory on the test computer.

• MSM: Builds Microsoft Installer Merge Module in <output folder>\wintun-<platform>-<version>.msm.

The driver output folder is:

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

Properties

Properties may be defined as environment variables, or specified on the msbuild command line.

• Configuration: Specifies configuration to build or clean. May be Debug or Release (default).

• Platform: Specifies driver platform to build. May be x86 or amd64 (default), or arm64.

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-((4+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.