Go to file
Simon Rozman a979361217 MSM: Install driver files to C:\Program Files\Wintun
This is temporary until we figure out how to use WiX's Difx to install
driver without leaving staged driver files behind.

Signed-off-by: Simon Rozman <simon@rozman.si>
2019-04-19 21:24:08 +02:00
.editorconfig Switch from NMake to MSBuild 2019-04-19 15:25:44 +02:00
.gitignore Move MSM files to a distribution folder 2019-04-18 15:32:09 +02:00
COPYING Initial commit 2019-03-22 16:52:31 -06:00
README.md Switch from NMake to MSBuild 2019-04-19 15:25:44 +02:00
wintun.c Revise OID request return statuses 2019-04-12 15:35:39 +02:00
wintun.inf Fix driver service name 2019-03-28 14:30:44 +01:00
wintun.proj Add missing dependencies 2019-04-19 21:24:08 +02:00
wintun.props Switch from NMake to MSBuild 2019-04-19 15:25:44 +02:00
wintun.rc Preset version to 0.1 2019-04-18 15:32:09 +02:00
wintun.vcxproj Switch from NMake to MSBuild 2019-04-19 15:25:44 +02:00
wintun.vcxproj.filters Add documentation files to the .vcxproj 2019-03-28 14:30:44 +01:00
wintun.wixproj MSM: Install driver files to C:\Program Files\Wintun 2019-04-19 21:24:08 +02:00
wintun.wxs MSM: Install driver files to C:\Program Files\Wintun 2019-04-19 21:24:08 +02:00

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>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.