1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
# [Wintun Network Adapter](https://www.wintun.net/)
### TUN Device Driver for Windows
This is a layer 3 TUN driver for Windows 7, 8, 8.1, and 10. Originally created for [WireGuard](https://www.wireguard.com/), 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](https://visualstudio.microsoft.com/downloads/)
- [Windows Driver Kit for Windows 10](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk)
- [WiX Toolset 3.11.1](http://wixtoolset.org/releases/)
## 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
<?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 `msbuild` 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, only for release configurations.
- `DVL`: Runs the `SDV`, and creates a Driver Verification Log, only for release configurations.
- `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](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/setupapi), open `\\.\Device\WINTUN%d` as Local System, where `%d` is the [LUID](https://docs.microsoft.com/en-us/windows/desktop/api/ifdef/ns-ifdef-_net_luid_lh) index (`NetLuidIndex` member) of the network device. You may then [`ReadFile`](https://docs.microsoft.com/en-us/windows/desktop/api/fileapi/nf-fileapi-readfile) and [`WriteFile`](https://docs.microsoft.com/en-us/windows/desktop/api/fileapi/nf-fileapi-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](https://docs.microsoft.com/en-us/windows/desktop/sync/synchronization-and-overlapped-input-and-output) for this. If using blocking I/O instead, it may be desirable to open separate handles for reading and writing.
|
